1 /* 2 * nldrdefs.h 3 * 4 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 5 * 6 * Global Dynamic + static/overlay Node loader (NLDR) constants and types. 7 * 8 * Copyright (C) 2008 Texas Instruments, Inc. 9 * 10 * This package is free software; you can redistribute it and/or modify 11 * it under the terms of the GNU General Public License version 2 as 12 * published by the Free Software Foundation. 13 * 14 * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR 15 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED 16 * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. 17 */ 18 19 #ifndef NLDRDEFS_ 20 #define NLDRDEFS_ 21 22 #include <dspbridge/dbdcddef.h> 23 #include <dspbridge/devdefs.h> 24 25 #define NLDR_MAXPATHLENGTH 255 26 /* NLDR Objects: */ 27 struct nldr_object; 28 struct nldr_nodeobject; 29 30 /* 31 * ======== nldr_loadtype ======== 32 * Load types for a node. Must match values in node.h55. 33 */ 34 enum nldr_loadtype { 35 NLDR_STATICLOAD, /* Linked in base image, not overlay */ 36 NLDR_DYNAMICLOAD, /* Dynamically loaded node */ 37 NLDR_OVLYLOAD /* Linked in base image, overlay node */ 38 }; 39 40 /* 41 * ======== nldr_ovlyfxn ======== 42 * Causes code or data to be copied from load address to run address. This 43 * is the "cod_writefxn" that gets passed to the DBLL_Library and is used as 44 * the ZL write function. 45 * 46 * Parameters: 47 * priv_ref: Handle to identify the node. 48 * dsp_run_addr: Run address of code or data. 49 * dsp_load_addr: Load address of code or data. 50 * ul_num_bytes: Number of (GPP) bytes to copy. 51 * mem_space: RMS_CODE or RMS_DATA. 52 * Returns: 53 * ul_num_bytes: Success. 54 * 0: Failure. 55 * Requires: 56 * Ensures: 57 */ 58 typedef u32(*nldr_ovlyfxn) (void *priv_ref, u32 dsp_run_addr, 59 u32 dsp_load_addr, u32 ul_num_bytes, u32 mem_space); 60 61 /* 62 * ======== nldr_writefxn ======== 63 * Write memory function. Used for dynamic load writes. 64 * Parameters: 65 * priv_ref: Handle to identify the node. 66 * dsp_add: Address of code or data. 67 * pbuf: Code or data to be written 68 * ul_num_bytes: Number of (GPP) bytes to write. 69 * mem_space: DBLL_DATA or DBLL_CODE. 70 * Returns: 71 * ul_num_bytes: Success. 72 * 0: Failure. 73 * Requires: 74 * Ensures: 75 */ 76 typedef u32(*nldr_writefxn) (void *priv_ref, 77 u32 dsp_add, void *pbuf, 78 u32 ul_num_bytes, u32 mem_space); 79 80 /* 81 * ======== nldr_attrs ======== 82 * Attributes passed to nldr_create function. 83 */ 84 struct nldr_attrs { 85 nldr_ovlyfxn ovly; 86 nldr_writefxn write; 87 u16 dsp_word_size; 88 u16 dsp_mau_size; 89 }; 90 91 /* 92 * ======== nldr_phase ======== 93 * Indicates node create, delete, or execute phase function. 94 */ 95 enum nldr_phase { 96 NLDR_CREATE, 97 NLDR_DELETE, 98 NLDR_EXECUTE, 99 NLDR_NOPHASE 100 }; 101 102 /* 103 * Typedefs of loader functions imported from a DLL, or defined in a 104 * function table. 105 */ 106 107 /* 108 * ======== nldr_allocate ======== 109 * Allocate resources to manage the loading of a node on the DSP. 110 * 111 * Parameters: 112 * nldr_obj: Handle of loader that will load the node. 113 * priv_ref: Handle to identify the node. 114 * node_props: Pointer to a dcd_nodeprops for the node. 115 * nldr_nodeobj: Location to store node handle on output. This handle 116 * will be passed to nldr_load/nldr_unload. 117 * pf_phase_split: pointer to int variable referenced in node.c 118 * Returns: 119 * 0: Success. 120 * -ENOMEM: Insufficient memory on GPP. 121 * Requires: 122 * Valid nldr_obj. 123 * node_props != NULL. 124 * nldr_nodeobj != NULL. 125 * Ensures: 126 * 0: IsValidNode(*nldr_nodeobj). 127 * error: *nldr_nodeobj == NULL. 128 */ 129 typedef int(*nldr_allocatefxn) (struct nldr_object *nldr_obj, 130 void *priv_ref, 131 const struct dcd_nodeprops 132 * node_props, 133 struct nldr_nodeobject 134 **nldr_nodeobj, 135 bool *pf_phase_split); 136 137 /* 138 * ======== nldr_create ======== 139 * Create a loader object. This object handles the loading and unloading of 140 * create, delete, and execute phase functions of nodes on the DSP target. 141 * 142 * Parameters: 143 * nldr: Location to store loader handle on output. 144 * hdev_obj: Device for this processor. 145 * pattrs: Loader attributes. 146 * Returns: 147 * 0: Success; 148 * -ENOMEM: Insufficient memory for requested resources. 149 * Requires: 150 * nldr != NULL. 151 * hdev_obj != NULL. 152 * pattrs != NULL. 153 * Ensures: 154 * 0: Valid *nldr. 155 * error: *nldr == NULL. 156 */ 157 typedef int(*nldr_createfxn) (struct nldr_object **nldr, 158 struct dev_object *hdev_obj, 159 const struct nldr_attrs *pattrs); 160 161 /* 162 * ======== nldr_delete ======== 163 * Delete the NLDR loader. 164 * 165 * Parameters: 166 * nldr_obj: Node manager object. 167 * Returns: 168 * Requires: 169 * Valid nldr_obj. 170 * Ensures: 171 * nldr_obj invalid 172 */ 173 typedef void (*nldr_deletefxn) (struct nldr_object *nldr_obj); 174 175 /* 176 * ======== NLDR_Free ======== 177 * Free resources allocated in nldr_allocate. 178 * 179 * Parameters: 180 * nldr_node_obj: Handle returned from nldr_allocate(). 181 * Returns: 182 * Requires: 183 * Valid nldr_node_obj. 184 * Ensures: 185 */ 186 typedef void (*nldr_freefxn) (struct nldr_nodeobject *nldr_node_obj); 187 188 /* 189 * ======== nldr_get_fxn_addr ======== 190 * Get address of create, delete, or execute phase function of a node on 191 * the DSP. 192 * 193 * Parameters: 194 * nldr_node_obj: Handle returned from nldr_allocate(). 195 * str_fxn: Name of function. 196 * addr: Location to store function address. 197 * Returns: 198 * 0: Success. 199 * -ESPIPE: Address of function not found. 200 * Requires: 201 * Valid nldr_node_obj. 202 * addr != NULL; 203 * str_fxn != NULL; 204 * Ensures: 205 */ 206 typedef int(*nldr_getfxnaddrfxn) (struct nldr_nodeobject 207 * nldr_node_obj, 208 char *str_fxn, u32 * addr); 209 210 /* 211 * ======== nldr_load ======== 212 * Load create, delete, or execute phase function of a node on the DSP. 213 * 214 * Parameters: 215 * nldr_node_obj: Handle returned from nldr_allocate(). 216 * phase: Type of function to load (create, delete, or execute). 217 * Returns: 218 * 0: Success. 219 * -ENOMEM: Insufficient memory on GPP. 220 * -ENXIO: Can't overlay phase because overlay memory 221 * is already in use. 222 * -EILSEQ: Failure in dynamic loader library. 223 * Requires: 224 * Valid nldr_node_obj. 225 * Ensures: 226 */ 227 typedef int(*nldr_loadfxn) (struct nldr_nodeobject *nldr_node_obj, 228 enum nldr_phase phase); 229 230 /* 231 * ======== nldr_unload ======== 232 * Unload create, delete, or execute phase function of a node on the DSP. 233 * 234 * Parameters: 235 * nldr_node_obj: Handle returned from nldr_allocate(). 236 * phase: Node function to unload (create, delete, or execute). 237 * Returns: 238 * 0: Success. 239 * -ENOMEM: Insufficient memory on GPP. 240 * Requires: 241 * Valid nldr_node_obj. 242 * Ensures: 243 */ 244 typedef int(*nldr_unloadfxn) (struct nldr_nodeobject *nldr_node_obj, 245 enum nldr_phase phase); 246 247 /* 248 * ======== node_ldr_fxns ======== 249 */ 250 struct node_ldr_fxns { 251 nldr_allocatefxn allocate; 252 nldr_createfxn create; 253 nldr_deletefxn delete; 254 nldr_getfxnaddrfxn get_fxn_addr; 255 nldr_loadfxn load; 256 nldr_unloadfxn unload; 257 }; 258 259 #endif /* NLDRDEFS_ */ 260