1 /* 2 * dspbridge/mpu_api/inc/nldrdefs.h 3 * 4 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 5 * 6 * Copyright (C) 2007 Texas Instruments, Inc. 7 * 8 * This program is free software; you can redistribute it and/or modify it 9 * under the terms of the GNU Lesser General Public License as published 10 * by the Free Software Foundation version 2.1 of the License. 11 * 12 * This program is distributed .as is. WITHOUT ANY WARRANTY of any kind, 13 * whether express or implied; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 */ 17 18 19 20 /* 21 * ======== nldrdefs.h ======== 22 * Description: 23 * Global Dynamic + static/overlay Node loader (NLDR) constants and types. 24 * 25 *! Revision History 26 *! ================ 27 *! 07-Apr-2003 map Consolidated dldrdefs.h into nldrdefs.h 28 *! 05-Aug-2002 jeh Created. 29 */ 30 31 #ifndef NLDRDEFS_ 32 #define NLDRDEFS_ 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 #include <dbdcddef.h> 39 #include <devdefs.h> 40 41 #define NLDR_MAXPATHLENGTH 255 42 /* NLDR Objects: */ 43 struct NLDR_OBJECT; 44 /*typedef struct NLDR_OBJECT *NLDR_HOBJECT;*/ 45 struct NLDR_NODEOBJECT; 46 /*typedef struct NLDR_NODEOBJECT *NLDR_HNODE;*/ 47 48 /* 49 * ======== NLDR_LOADTYPE ======== 50 * Load types for a node. Must match values in node.h55. 51 */ 52 typedef enum NLDR_LOADTYPE { 53 NLDR_STATICLOAD, /* Linked in base image, not overlay */ 54 NLDR_DYNAMICLOAD, /* Dynamically loaded node */ 55 NLDR_OVLYLOAD /* Linked in base image, overlay node */ 56 } NLDR_LOADTYPE; 57 58 /* 59 * ======== NLDR_OVLYFXN ======== 60 * Causes code or data to be copied from load address to run address. This 61 * is the "COD_WRITEFXN" that gets passed to the DBLL_Library and is used as 62 * the ZL write function. 63 * 64 * Parameters: 65 * pPrivRef: Handle to identify the node. 66 * ulDspRunAddr: Run address of code or data. 67 * ulDspLoadAddr: Load address of code or data. 68 * ulNumBytes: Number of (GPP) bytes to copy. 69 * nMemSpace: RMS_CODE or RMS_DATA. 70 * Returns: 71 * ulNumBytes: Success. 72 * 0: Failure. 73 * Requires: 74 * Ensures: 75 */ 76 typedef ULONG(CDECL * NLDR_OVLYFXN) (PVOID pPrivRef, ULONG ulDspRunAddr, 77 ULONG ulDspLoadAddr, 78 ULONG ulNumBytes, UINT nMemSpace); 79 80 /* 81 * ======== NLDR_WRITEFXN ======== 82 * Write memory function. Used for dynamic load writes. 83 * Parameters: 84 * pPrivRef: Handle to identify the node. 85 * ulDspAddr: Address of code or data. 86 * pBuf: Code or data to be written 87 * ulNumBytes: Number of (GPP) bytes to write. 88 * nMemSpace: DBLL_DATA or DBLL_CODE. 89 * Returns: 90 * ulNumBytes: Success. 91 * 0: Failure. 92 * Requires: 93 * Ensures: 94 */ 95 typedef ULONG(CDECL * NLDR_WRITEFXN) (PVOID pPrivRef, 96 ULONG ulDspAddr, PVOID pBuf, 97 ULONG ulNumBytes, UINT nMemSpace); 98 99 /* 100 * ======== NLDR_ATTRS ======== 101 * Attributes passed to NLDR_Create function. 102 */ 103 struct NLDR_ATTRS { 104 NLDR_OVLYFXN pfnOvly; 105 NLDR_WRITEFXN pfnWrite; 106 USHORT usDSPWordSize; 107 USHORT usDSPMauSize; 108 } ; 109 110 /* 111 * ======== NLDR_PHASE ======== 112 * Indicates node create, delete, or execute phase function. 113 */ 114 typedef enum { 115 NLDR_CREATE, 116 NLDR_DELETE, 117 NLDR_EXECUTE, 118 NLDR_NOPHASE 119 } NLDR_PHASE; 120 121 /* 122 * Typedefs of loader functions imported from a DLL, or defined in a 123 * function table. 124 */ 125 126 /* 127 * ======== NLDR_Allocate ======== 128 * Allocate resources to manage the loading of a node on the DSP. 129 * 130 * Parameters: 131 * hNldr: Handle of loader that will load the node. 132 * pPrivRef: Handle to identify the node. 133 * pNodeProps: Pointer to a DCD_NODEPROPS for the node. 134 * phNldrNode: Location to store node handle on output. This handle 135 * will be passed to NLDR_Load/NLDR_Unload. 136 * pfPhaseSplit: pointer to boolean variable referenced in node.c 137 * Returns: 138 * DSP_SOK: Success. 139 * DSP_EMEMORY: Insufficient memory on GPP. 140 * Requires: 141 * NLDR_Init() called. 142 * Valid hNldr. 143 * pNodeProps != NULL. 144 * phNldrNode != NULL. 145 * Ensures: 146 * DSP_SOK: IsValidNode(*phNldrNode). 147 * error: *phNldrNode == NULL. 148 */ 149 typedef DSP_STATUS(*NLDR_ALLOCATEFXN) (struct NLDR_OBJECT* hNldr, 150 PVOID pPrivRef, 151 IN CONST struct DCD_NODEPROPS *pNodeProps, 152 OUT struct NLDR_NODEOBJECT* * phNldrNode, 153 OUT bool * pfPhaseSplit); 154 155 /* 156 * ======== NLDR_Create ======== 157 * Create a loader object. This object handles the loading and unloading of 158 * create, delete, and execute phase functions of nodes on the DSP target. 159 * 160 * Parameters: 161 * phNldr: Location to store loader handle on output. 162 * hDevObject: Device for this processor. 163 * pAttrs: Loader attributes. 164 * Returns: 165 * DSP_SOK: Success; 166 * DSP_EMEMORY: Insufficient memory for requested resources. 167 * Requires: 168 * NLDR_Init() called. 169 * phNldr != NULL. 170 * hDevObject != NULL. 171 * pAttrs != NULL. 172 * Ensures: 173 * DSP_SOK: Valid *phNldr. 174 * error: *phNldr == NULL. 175 */ 176 typedef DSP_STATUS(*NLDR_CREATEFXN) (OUT struct NLDR_OBJECT* * phNldr, 177 struct DEV_OBJECT* hDevObject, 178 IN CONST struct NLDR_ATTRS * pAttrs); 179 180 /* 181 * ======== NLDR_Delete ======== 182 * Delete the NLDR loader. 183 * 184 * Parameters: 185 * hNldr: Node manager object. 186 * Returns: 187 * Requires: 188 * NLDR_Init() called. 189 * Valid hNldr. 190 * Ensures: 191 * hNldr invalid 192 */ 193 typedef VOID(*NLDR_DELETEFXN) (struct NLDR_OBJECT* hNldr); 194 195 /* 196 * ======== NLDR_Exit ======== 197 * Discontinue usage of NLDR module. 198 * 199 * Parameters: 200 * Returns: 201 * Requires: 202 * NLDR_Init() successfully called before. 203 * Ensures: 204 * Any resources acquired in NLDR_Init() will be freed when last NLDR 205 * client calls NLDR_Exit(). 206 */ 207 typedef VOID(*NLDR_EXITFXN) (); 208 209 /* 210 * ======== NLDR_Free ======== 211 * Free resources allocated in NLDR_Allocate. 212 * 213 * Parameters: 214 * hNldrNode: Handle returned from NLDR_Allocate(). 215 * Returns: 216 * Requires: 217 * NLDR_Init() called. 218 * Valid hNldrNode. 219 * Ensures: 220 */ 221 typedef VOID(*NLDR_FREEFXN) (struct NLDR_NODEOBJECT* hNldrNode); 222 223 /* 224 * ======== NLDR_GetFxnAddr ======== 225 * Get address of create, delete, or execute phase function of a node on 226 * the DSP. 227 * 228 * Parameters: 229 * hNldrNode: Handle returned from NLDR_Allocate(). 230 * pstrFxn: Name of function. 231 * pulAddr: Location to store function address. 232 * Returns: 233 * DSP_SOK: Success. 234 * DSP_ESYMBOL: Address of function not found. 235 * Requires: 236 * NLDR_Init() called. 237 * Valid hNldrNode. 238 * pulAddr != NULL; 239 * pstrFxn != NULL; 240 * Ensures: 241 */ 242 typedef DSP_STATUS(*NLDR_GETFXNADDRFXN) (struct NLDR_NODEOBJECT* hNldrNode, 243 PSTR pstrFxn, ULONG * pulAddr); 244 245 /* 246 * ======== NLDR_Init ======== 247 * Initialize the NLDR module. 248 * 249 * Parameters: 250 * Returns: 251 * TRUE if initialization succeeded, FALSE otherwise. 252 * Ensures: 253 */ 254 typedef bool(*NLDR_INITFXN) (); 255 256 /* 257 * ======== NLDR_Load ======== 258 * Load create, delete, or execute phase function of a node on the DSP. 259 * 260 * Parameters: 261 * hNldrNode: Handle returned from NLDR_Allocate(). 262 * phase: Type of function to load (create, delete, or execute). 263 * Returns: 264 * DSP_SOK: Success. 265 * DSP_EMEMORY: Insufficient memory on GPP. 266 * DSP_EOVERLAYMEMORY: Can't overlay phase because overlay memory 267 * is already in use. 268 * DSP_EDYNLOAD: Failure in dynamic loader library. 269 * DSP_EFWRITE: Failed to write phase's code or date to target. 270 * Requires: 271 * NLDR_Init() called. 272 * Valid hNldrNode. 273 * Ensures: 274 */ 275 typedef DSP_STATUS(*NLDR_LOADFXN) (struct NLDR_NODEOBJECT* hNldrNode, 276 NLDR_PHASE phase); 277 278 /* 279 * ======== NLDR_Unload ======== 280 * Unload create, delete, or execute phase function of a node on the DSP. 281 * 282 * Parameters: 283 * hNldrNode: Handle returned from NLDR_Allocate(). 284 * phase: Node function to unload (create, delete, or execute). 285 * Returns: 286 * DSP_SOK: Success. 287 * DSP_EMEMORY: Insufficient memory on GPP. 288 * Requires: 289 * NLDR_Init() called. 290 * Valid hNldrNode. 291 * Ensures: 292 */ 293 typedef DSP_STATUS(*NLDR_UNLOADFXN) (struct NLDR_NODEOBJECT* hNldrNode, 294 NLDR_PHASE phase); 295 296 /* 297 * ======== NLDR_FXNS ======== 298 */ 299 struct NLDR_FXNS { 300 NLDR_ALLOCATEFXN pfnAllocate; 301 NLDR_CREATEFXN pfnCreate; 302 NLDR_DELETEFXN pfnDelete; 303 NLDR_EXITFXN pfnExit; 304 NLDR_FREEFXN pfnFree; 305 NLDR_GETFXNADDRFXN pfnGetFxnAddr; 306 NLDR_INITFXN pfnInit; 307 NLDR_LOADFXN pfnLoad; 308 NLDR_UNLOADFXN pfnUnload; 309 } ; 310 311 #ifdef __cplusplus 312 } 313 #endif 314 #endif /* NLDRDEFS_ */ 315
