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  *  ======== dbdcd.h ========
     19  *  DSP-BIOS Bridge driver support functions for TI OMAP processors.
     20  *  Description:
     21  *      Defines the DSP/BIOS Bridge Configuration Database (DCD) API.
     22  *
     23  *! Revision History
     24  *! ================
     25  *! 03-Dec-2003 map Changed DCD_OBJTYPE to DSP_DCDOBJTYPE
     26  *! 24-Feb-2003 kc  Updated DCD_AutoUnregister and DCD_GetObjects to simplify
     27  *!                 DCD implementation.
     28  *! 05-Aug-2002 jeh Added DCD_GetObjects().
     29  *! 11-Jul-2002 jeh Added DCD_GetDepLibs(), DCD_GetNumDepLibs().
     30  *! 22-Apr-2002 jeh Added DCD_GetLibraryName().
     31  *! 03-Apr-2001 sg  Changed error names to have DCD_E* format.
     32  *! 13-Feb-2001 kc  Name changed from dcdbs.h to dbdcd.h.
     33  *! 12-Dec-2000 kc  Added DCD_AutoUnregister.
     34  *! 09-Nov-2000 kc  Updated usage of DCD_EnumerateObject.
     35  *! 30-Oct-2000 kc  Added DCD_AutoRegister. Updated error DCD error codes.
     36  *! 29-Sep-2000 kc  Incorporated code review comments. See
     37  *!                 /src/reviews/dcd_review.txt.
     38  *! 26-Jul-2000 kc  Created.
     39  *!
     40  */
     41 
     42 #ifndef DBDCD_
     43 #define DBDCD_
     44 
     45 #ifdef __cplusplus
     46 extern "C" {
     47 #endif
     48 
     49 #include <dbdcddef.h>
     50 #include <nldrdefs.h>
     51 
     52 /*
     53  *  ======== DCD_AutoRegister ========
     54  *  Purpose:
     55  *      This function automatically registers DCD objects specified in a
     56  *      special COFF section called ".dcd_register"
     57  *  Parameters:
     58  *      hDcdMgr:                A DCD manager handle.
     59  *      pszCoffPath:            Pointer to name of COFF file containing DCD
     60  *                              objects to be registered.
     61  *  Returns:
     62  *      DSP_SOK:                Success.
     63  *      DSP_EDCDNOAUTOREGISTER: Unable to find auto-registration section.
     64  *      DSP_EDCDREADSECT:       Unable to read object code section.
     65  *      DSP_EDCDLOADBASE:       Unable to load code base.
     66  *      DSP_EHANDLE:            Invalid DCD_HMANAGER handle..
     67  *  Requires:
     68  *      DCD initialized.
     69  *  Ensures:
     70  *  Note:
     71  *      Due to the DCD database construction, it is essential for a DCD-enabled
     72  *      COFF file to contain the right COFF sections, especially
     73  *      ".dcd_register", which is used for auto registration.
     74  */
     75 	extern DSP_STATUS DCD_AutoRegister(IN struct DCD_MANAGER* hDcdMgr,
     76 					   IN CHAR * pszCoffPath);
     77 
     78 /*
     79  *  ======== DCD_AutoUnregister ========
     80  *  Purpose:
     81  *      This function automatically unregisters DCD objects specified in a
     82  *      special COFF section called ".dcd_register"
     83  *  Parameters:
     84  *      hDcdMgr:                A DCD manager handle.
     85  *      pszCoffPath:            Pointer to name of COFF file containing
     86  *                              DCD objects to be unregistered.
     87  *  Returns:
     88  *      DSP_SOK:                Success.
     89  *      DSP_EDCDNOAUTOREGISTER: Unable to find auto-registration section.
     90  *      DSP_EDCDREADSECT:       Unable to read object code section.
     91  *      DSP_EDCDLOADBASE:       Unable to load code base.
     92  *      DSP_EHANDLE:            Invalid DCD_HMANAGER handle..
     93  *  Requires:
     94  *      DCD initialized.
     95  *  Ensures:
     96  *  Note:
     97  *      Due to the DCD database construction, it is essential for a DCD-enabled
     98  *      COFF file to contain the right COFF sections, especially
     99  *      ".dcd_register", which is used for auto unregistration.
    100  */
    101 	extern DSP_STATUS DCD_AutoUnregister(IN struct DCD_MANAGER* hDcdMgr,
    102 					     IN CHAR * pszCoffPath);
    103 
    104 /*
    105  *  ======== DCD_CreateManager ========
    106  *  Purpose:
    107  *      This function creates a DCD module manager.
    108  *  Parameters:
    109  *      pszZlDllName:   Pointer to a DLL name string.
    110  *      phDcdMgr:       A pointer to a DCD manager handle.
    111  *  Returns:
    112  *      DSP_SOK:        Success.
    113  *      DSP_EMEMORY:    Unable to allocate memory for DCD manager handle.
    114  *      DSP_EFAIL:      General failure.
    115  *  Requires:
    116  *      DCD initialized.
    117  *      pszZlDllName is non-NULL.
    118  *      phDcdMgr is non-NULL.
    119  *  Ensures:
    120  *      A DCD manager handle is created.
    121  */
    122 	extern DSP_STATUS DCD_CreateManager(IN CHAR * pszZlDllName,
    123 					    OUT struct DCD_MANAGER* * phDcdMgr);
    124 
    125 /*
    126  *  ======== DCD_DestroyManager ========
    127  *  Purpose:
    128  *      This function destroys a DCD module manager.
    129  *  Parameters:
    130  *      hDcdMgr:        A DCD manager handle.
    131  *  Returns:
    132  *      DSP_SOK:        Success.
    133  *      DSP_EHANDLE:    Invalid DCD manager handle.
    134  *  Requires:
    135  *      DCD initialized.
    136  *  Ensures:
    137  */
    138 	extern DSP_STATUS DCD_DestroyManager(IN struct DCD_MANAGER* hDcdMgr);
    139 
    140 /*
    141  *  ======== DCD_EnumerateObject ========
    142  *  Purpose:
    143  *      This function enumerates currently visible DSP/BIOS Bridge objects
    144  *      and returns the UUID and type of each enumerated object.
    145  *  Parameters:
    146  *      cIndex:             The object enumeration index.
    147  *      objType:            Type of object to enumerate.
    148  *      pUuid:              Pointer to a DSP_UUID object.
    149  *  Returns:
    150  *      DSP_SOK:            Success.
    151  *      DSP_EFAIL:          Unable to enumerate through the DCD database.
    152  *      DSP_SENUMCOMPLETE:  Enumeration completed. This is not an error code.
    153  *  Requires:
    154  *      DCD initialized.
    155  *      pUuid is a valid pointer.
    156  *  Ensures:
    157  *  Details:
    158  *      This function can be used in conjunction with DCD_GetObjectDef to
    159  *      retrieve object properties.
    160  */
    161 	extern DSP_STATUS DCD_EnumerateObject(IN INT cIndex,
    162 					      IN DSP_DCDOBJTYPE objType,
    163 					      OUT struct DSP_UUID * pUuid);
    164 
    165 /*
    166  *  ======== DCD_Exit ========
    167  *  Purpose:
    168  *      This function cleans up the DCD module.
    169  *  Parameters:
    170  *  Returns:
    171  *  Requires:
    172  *      DCD initialized.
    173  *  Ensures:
    174  */
    175 	extern VOID DCD_Exit();
    176 
    177 /*
    178  *  ======== DCD_GetDepLibs ========
    179  *  Purpose:
    180  *      Given the uuid of a library and size of array of uuids, this function
    181  *      fills the array with the uuids of all dependent libraries of the input
    182  *      library.
    183  *  Parameters:
    184  *      hDcdMgr: A DCD manager handle.
    185  *      pUuid: Pointer to a DSP_UUID for a library.
    186  *      numLibs: Size of uuid array (number of library uuids).
    187  *      pDepLibUuids: Array of dependent library uuids to be filled in.
    188  *      pPersistentDepLibs: Array indicating if corresponding lib is persistent.
    189  *      phase: phase to obtain correct input library
    190  *  Returns:
    191  *      DSP_SOK: Success.
    192  *      DSP_EMEMORY: Memory allocation failure.
    193  *      DSP_EDCDREADSECT: Failure to read section containing library info.
    194  *      DSP_EFAIL: General failure.
    195  *  Requires:
    196  *      DCD initialized.
    197  *      Valid hDcdMgr.
    198  *      pUuid != NULL
    199  *      pDepLibUuids != NULL.
    200  *  Ensures:
    201  */
    202 	extern DSP_STATUS DCD_GetDepLibs(IN struct DCD_MANAGER* hDcdMgr,
    203 					 IN struct DSP_UUID * pUuid,
    204 					 USHORT numLibs,
    205 					 OUT struct DSP_UUID * pDepLibUuids,
    206 					 OUT bool * pPersistentDepLibs,
    207 					 IN NLDR_PHASE phase);
    208 
    209 /*
    210  *  ======== DCD_GetNumDepLibs ========
    211  *  Purpose:
    212  *      Given the uuid of a library, determine its number of dependent
    213  *      libraries.
    214  *  Parameters:
    215  *      hDcdMgr:        A DCD manager handle.
    216  *      pUuid:          Pointer to a DSP_UUID for a library.
    217  *      pNumLibs:       Size of uuid array (number of library uuids).
    218  *      pNumPersLibs:   number of persistent dependent library.
    219  *      phase:          Phase to obtain correct input library
    220  *  Returns:
    221  *      DSP_SOK: Success.
    222  *      DSP_EMEMORY: Memory allocation failure.
    223  *      DSP_EDCDREADSECT: Failure to read section containing library info.
    224  *      DSP_EFAIL: General failure.
    225  *  Requires:
    226  *      DCD initialized.
    227  *      Valid hDcdMgr.
    228  *      pUuid != NULL
    229  *      pNumLibs != NULL.
    230  *  Ensures:
    231  */
    232 	extern DSP_STATUS DCD_GetNumDepLibs(IN struct DCD_MANAGER* hDcdMgr,
    233 					    IN struct DSP_UUID * pUuid,
    234 					    OUT USHORT * pNumLibs,
    235 					    OUT USHORT * pNumPersLibs,
    236 					    IN NLDR_PHASE phase);
    237 
    238 /*
    239  *  ======== DCD_GetLibraryName ========
    240  *  Purpose:
    241  *      This function returns the name of a (dynamic) library for a given
    242  *      UUID.
    243  *  Parameters:
    244  *      hDcdMgr: A DCD manager handle.
    245  *      pUuid:          Pointer to a DSP_UUID that represents a unique DSP/BIOS
    246  *                      Bridge object.
    247  *      pstrLibName: Buffer to hold library name.
    248  *      pdwSize: Contains buffer size. Set to string size on output.
    249  *      phase:          Which phase to load
    250  *      fPhaseSplit:    Are phases in multiple libraries
    251  *  Returns:
    252  *      DSP_SOK: Success.
    253  *      DSP_EFAIL: General failure.
    254  *  Requires:
    255  *      DCD initialized.
    256  *      Valid hDcdMgr.
    257  *      pstrLibName != NULL.
    258  *      pUuid != NULL
    259  *      pdwSize != NULL.
    260  *  Ensures:
    261  */
    262 	extern DSP_STATUS DCD_GetLibraryName(IN struct DCD_MANAGER* hDcdMgr,
    263 					     IN struct DSP_UUID * pUuid,
    264 					     IN OUT PSTR pstrLibName,
    265 					     IN OUT DWORD * pdwSize,
    266 					     IN NLDR_PHASE phase,
    267 					     OUT bool * fPhaseSplit);
    268 
    269 /*
    270  *  ======== DCD_GetObjectDef ========
    271  *  Purpose:
    272  *      This function returns the properties/attributes of a DSP/BIOS Bridge
    273  *      object.
    274  *  Parameters:
    275  *      hDcdMgr:            A DCD manager handle.
    276  *      pUuid:              Pointer to a DSP_UUID that represents a unique
    277  *                          DSP/BIOS Bridge object.
    278  *      objType:            The type of DSP/BIOS Bridge object to be
    279  *                          referenced (node, processor, etc).
    280  *      pObjDef:            Pointer to an object definition structure. A
    281  *                          union of various possible DCD object types.
    282  *  Returns:
    283  *      DSP_SOK: Success.
    284  *      DSP_EDCDPARSESECT:  Unable to parse content of object code section.
    285  *      DSP_EDCDREADSECT:   Unable to read object code section.
    286  *      DSP_EDCDGETSECT:    Unable to access object code section.
    287  *      DSP_EDCDLOADBASE:   Unable to load code base.
    288  *      DSP_EFAIL:          General failure.
    289  *      DSP_EHANDLE:        Invalid DCD_HMANAGER handle.
    290  *  Requires:
    291  *      DCD initialized.
    292  *      pObjUuid is non-NULL.
    293  *      pObjDef is non-NULL.
    294  *  Ensures:
    295  */
    296 	extern DSP_STATUS DCD_GetObjectDef(IN struct DCD_MANAGER* hDcdMgr,
    297 					   IN struct DSP_UUID * pObjUuid,
    298 					   IN DSP_DCDOBJTYPE objType,
    299 					   OUT struct DCD_GENERICOBJ *pObjDef);
    300 
    301 /*
    302  *  ======== DCD_GetObjects ========
    303  *  Purpose:
    304  *      This function finds all DCD objects specified in a special
    305  *      COFF section called ".dcd_register", and for each object,
    306  *      call a "register" function.  The "register" function may perform
    307  *      various actions, such as 1) register nodes in the node database, 2)
    308  *      unregister nodes from the node database, and 3) add overlay nodes.
    309  *  Parameters:
    310  *      hDcdMgr:                A DCD manager handle.
    311  *      pszCoffPath:            Pointer to name of COFF file containing DCD
    312  *                              objects.
    313  *      registerFxn:            Callback fxn to be applied on each located
    314  *                              DCD object.
    315  *      handle:                 Handle to pass to callback.
    316  *  Returns:
    317  *      DSP_SOK:                Success.
    318  *      DSP_EDCDNOAUTOREGISTER: Unable to find .dcd_register section.
    319  *      DSP_EDCDREADSECT:       Unable to read object code section.
    320  *      DSP_EDCDLOADBASE:       Unable to load code base.
    321  *      DSP_EHANDLE:            Invalid DCD_HMANAGER handle..
    322  *  Requires:
    323  *      DCD initialized.
    324  *  Ensures:
    325  *  Note:
    326  *      Due to the DCD database construction, it is essential for a DCD-enabled
    327  *      COFF file to contain the right COFF sections, especially
    328  *      ".dcd_register", which is used for auto registration.
    329  */
    330 	extern DSP_STATUS DCD_GetObjects(IN struct DCD_MANAGER* hDcdMgr,
    331 					 IN CHAR * pszCoffPath,
    332 					 DCD_REGISTERFXN registerFxn,
    333 					 PVOID handle);
    334 
    335 /*
    336  *  ======== DCD_Init ========
    337  *  Purpose:
    338  *      This function initializes DCD.
    339  *  Parameters:
    340  *  Returns:
    341  *      FALSE:  Initialization failed.
    342  *      TRUE:   Initialization succeeded.
    343  *  Requires:
    344  *  Ensures:
    345  *      DCD initialized.
    346  */
    347 	extern bool DCD_Init();
    348 
    349 /*
    350  *  ======== DCD_RegisterObject ========
    351  *  Purpose:
    352  *      This function registers a DSP/BIOS Bridge object in the DCD database.
    353  *  Parameters:
    354  *      pUuid:          Pointer to a DSP_UUID that identifies a DSP/BIOS
    355  *                      Bridge object.
    356  *      objType:        Type of object.
    357  *      pszPathName:    Path to the object's COFF file.
    358  *  Returns:
    359  *      DSP_SOK:        Success.
    360  *      DSP_EFAIL:      Failed to register object.
    361  *  Requires:
    362  *      DCD initialized.
    363  *      pUuid and szPathName are non-NULL values.
    364  *      objType is a valid type value.
    365  *  Ensures:
    366  */
    367 	extern DSP_STATUS DCD_RegisterObject(IN struct DSP_UUID * pUuid,
    368 					     IN DSP_DCDOBJTYPE objType,
    369 					     IN CHAR * pszPathName);
    370 
    371 /*
    372  *  ======== DCD_UnregisterObject ========
    373  *  Purpose:
    374  *      This function de-registers a valid DSP/BIOS Bridge object from the DCD
    375  *      database.
    376  *  Parameters:
    377  *      pUuid:      Pointer to a DSP_UUID that identifies a DSP/BIOS Bridge
    378  *                  object.
    379  *      objType:    Type of object.
    380  *  Returns:
    381  *      DSP_SOK:    Success.
    382  *      DSP_EFAIL:  Unable to de-register the specified object.
    383  *  Requires:
    384  *      DCD initialized.
    385  *      pUuid is a non-NULL value.
    386  *      objType is a valid type value.
    387  *  Ensures:
    388  */
    389 	extern DSP_STATUS DCD_UnregisterObject(IN struct DSP_UUID * pUuid,
    390 					       IN DSP_DCDOBJTYPE objType);
    391 
    392 #ifdef __cplusplus
    393 }
    394 #endif
    395 #endif				/* _DBDCD_H */
    396