Home | History | Annotate | Download | only in inc
      1 /*
      2  *  Copyright 2001-2008 Texas Instruments - http://www.ti.com/
      3  *
      4  *  Licensed under the Apache License, Version 2.0 (the "License");
      5  *  you may not use this file except in compliance with the License.
      6  *  You may obtain a copy of the License at
      7  *
      8  *     http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  *  Unless required by applicable law or agreed to in writing, software
     11  *  distributed under the License is distributed on an "AS IS" BASIS,
     12  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  *  See the License for the specific language governing permissions and
     14  *  limitations under the License.
     15  */
     16 
     17 
     18 
     19 /*
     20  *  ======== nldrdefs.h ========
     21  *  DSP-BIOS Bridge driver support functions for TI OMAP processors.
     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