| /* |
| * dbdcd.h |
| * |
| * DSP-BIOS Bridge driver support functions for TI OMAP processors. |
| * |
| * Defines the DSP/BIOS Bridge Configuration Database (DCD) API. |
| * |
| * Copyright (C) 2008 Texas Instruments, Inc. |
| * |
| * This package is free software; you can redistribute it and/or modify |
| * it under the terms of the GNU General Public License version 2 as |
| * published by the Free Software Foundation. |
| * |
| * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR |
| * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED |
| * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| */ |
| |
| #ifndef DBDCD_ |
| #define DBDCD_ |
| |
| #include <dspbridge/dbdcddef.h> |
| #include <dspbridge/host_os.h> |
| #include <dspbridge/nldrdefs.h> |
| |
| /* |
| * ======== dcd_auto_register ======== |
| * Purpose: |
| * This function automatically registers DCD objects specified in a |
| * special COFF section called ".dcd_register" |
| * Parameters: |
| * hdcd_mgr: A DCD manager handle. |
| * sz_coff_path: Pointer to name of COFF file containing DCD |
| * objects to be registered. |
| * Returns: |
| * 0: Success. |
| * -EACCES: Unable to find auto-registration/read/load section. |
| * -EFAULT: Invalid DCD_HMANAGER handle.. |
| * Requires: |
| * DCD initialized. |
| * Ensures: |
| * Note: |
| * Due to the DCD database construction, it is essential for a DCD-enabled |
| * COFF file to contain the right COFF sections, especially |
| * ".dcd_register", which is used for auto registration. |
| */ |
| extern int dcd_auto_register(struct dcd_manager *hdcd_mgr, |
| char *sz_coff_path); |
| |
| /* |
| * ======== dcd_auto_unregister ======== |
| * Purpose: |
| * This function automatically unregisters DCD objects specified in a |
| * special COFF section called ".dcd_register" |
| * Parameters: |
| * hdcd_mgr: A DCD manager handle. |
| * sz_coff_path: Pointer to name of COFF file containing |
| * DCD objects to be unregistered. |
| * Returns: |
| * 0: Success. |
| * -EACCES: Unable to find auto-registration/read/load section. |
| * -EFAULT: Invalid DCD_HMANAGER handle.. |
| * Requires: |
| * DCD initialized. |
| * Ensures: |
| * Note: |
| * Due to the DCD database construction, it is essential for a DCD-enabled |
| * COFF file to contain the right COFF sections, especially |
| * ".dcd_register", which is used for auto unregistration. |
| */ |
| extern int dcd_auto_unregister(struct dcd_manager *hdcd_mgr, |
| char *sz_coff_path); |
| |
| /* |
| * ======== dcd_create_manager ======== |
| * Purpose: |
| * This function creates a DCD module manager. |
| * Parameters: |
| * sz_zl_dll_name: Pointer to a DLL name string. |
| * dcd_mgr: A pointer to a DCD manager handle. |
| * Returns: |
| * 0: Success. |
| * -ENOMEM: Unable to allocate memory for DCD manager handle. |
| * -EPERM: General failure. |
| * Requires: |
| * DCD initialized. |
| * sz_zl_dll_name is non-NULL. |
| * dcd_mgr is non-NULL. |
| * Ensures: |
| * A DCD manager handle is created. |
| */ |
| extern int dcd_create_manager(char *sz_zl_dll_name, |
| struct dcd_manager **dcd_mgr); |
| |
| /* |
| * ======== dcd_destroy_manager ======== |
| * Purpose: |
| * This function destroys a DCD module manager. |
| * Parameters: |
| * hdcd_mgr: A DCD manager handle. |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid DCD manager handle. |
| * Requires: |
| * DCD initialized. |
| * Ensures: |
| */ |
| extern int dcd_destroy_manager(struct dcd_manager *hdcd_mgr); |
| |
| /* |
| * ======== dcd_enumerate_object ======== |
| * Purpose: |
| * This function enumerates currently visible DSP/BIOS Bridge objects |
| * and returns the UUID and type of each enumerated object. |
| * Parameters: |
| * index: The object enumeration index. |
| * obj_type: Type of object to enumerate. |
| * uuid_obj: Pointer to a dsp_uuid object. |
| * Returns: |
| * 0: Success. |
| * -EPERM: Unable to enumerate through the DCD database. |
| * ENODATA: Enumeration completed. This is not an error code. |
| * Requires: |
| * DCD initialized. |
| * uuid_obj is a valid pointer. |
| * Ensures: |
| * Details: |
| * This function can be used in conjunction with dcd_get_object_def to |
| * retrieve object properties. |
| */ |
| extern int dcd_enumerate_object(s32 index, |
| enum dsp_dcdobjtype obj_type, |
| struct dsp_uuid *uuid_obj); |
| |
| /* |
| * ======== dcd_exit ======== |
| * Purpose: |
| * This function cleans up the DCD module. |
| * Parameters: |
| * Returns: |
| * Requires: |
| * DCD initialized. |
| * Ensures: |
| */ |
| extern void dcd_exit(void); |
| |
| /* |
| * ======== dcd_get_dep_libs ======== |
| * Purpose: |
| * Given the uuid of a library and size of array of uuids, this function |
| * fills the array with the uuids of all dependent libraries of the input |
| * library. |
| * Parameters: |
| * hdcd_mgr: A DCD manager handle. |
| * uuid_obj: Pointer to a dsp_uuid for a library. |
| * num_libs: Size of uuid array (number of library uuids). |
| * dep_lib_uuids: Array of dependent library uuids to be filled in. |
| * prstnt_dep_libs: Array indicating if corresponding lib is persistent. |
| * phase: phase to obtain correct input library |
| * Returns: |
| * 0: Success. |
| * -ENOMEM: Memory allocation failure. |
| * -EACCES: Failure to read section containing library info. |
| * -EPERM: General failure. |
| * Requires: |
| * DCD initialized. |
| * Valid hdcd_mgr. |
| * uuid_obj != NULL |
| * dep_lib_uuids != NULL. |
| * Ensures: |
| */ |
| extern int dcd_get_dep_libs(struct dcd_manager *hdcd_mgr, |
| struct dsp_uuid *uuid_obj, |
| u16 num_libs, |
| struct dsp_uuid *dep_lib_uuids, |
| bool *prstnt_dep_libs, |
| enum nldr_phase phase); |
| |
| /* |
| * ======== dcd_get_num_dep_libs ======== |
| * Purpose: |
| * Given the uuid of a library, determine its number of dependent |
| * libraries. |
| * Parameters: |
| * hdcd_mgr: A DCD manager handle. |
| * uuid_obj: Pointer to a dsp_uuid for a library. |
| * num_libs: Size of uuid array (number of library uuids). |
| * num_pers_libs: number of persistent dependent library. |
| * phase: Phase to obtain correct input library |
| * Returns: |
| * 0: Success. |
| * -ENOMEM: Memory allocation failure. |
| * -EACCES: Failure to read section containing library info. |
| * -EPERM: General failure. |
| * Requires: |
| * DCD initialized. |
| * Valid hdcd_mgr. |
| * uuid_obj != NULL |
| * num_libs != NULL. |
| * Ensures: |
| */ |
| extern int dcd_get_num_dep_libs(struct dcd_manager *hdcd_mgr, |
| struct dsp_uuid *uuid_obj, |
| u16 *num_libs, |
| u16 *num_pers_libs, |
| enum nldr_phase phase); |
| |
| /* |
| * ======== dcd_get_library_name ======== |
| * Purpose: |
| * This function returns the name of a (dynamic) library for a given |
| * UUID. |
| * Parameters: |
| * hdcd_mgr: A DCD manager handle. |
| * uuid_obj: Pointer to a dsp_uuid that represents a unique DSP/BIOS |
| * Bridge object. |
| * str_lib_name: Buffer to hold library name. |
| * buff_size: Contains buffer size. Set to string size on output. |
| * phase: Which phase to load |
| * phase_split: Are phases in multiple libraries |
| * Returns: |
| * 0: Success. |
| * -EPERM: General failure. |
| * Requires: |
| * DCD initialized. |
| * Valid hdcd_mgr. |
| * str_lib_name != NULL. |
| * uuid_obj != NULL |
| * buff_size != NULL. |
| * Ensures: |
| */ |
| extern int dcd_get_library_name(struct dcd_manager *hdcd_mgr, |
| struct dsp_uuid *uuid_obj, |
| char *str_lib_name, |
| u32 *buff_size, |
| enum nldr_phase phase, |
| bool *phase_split); |
| |
| /* |
| * ======== dcd_get_object_def ======== |
| * Purpose: |
| * This function returns the properties/attributes of a DSP/BIOS Bridge |
| * object. |
| * Parameters: |
| * hdcd_mgr: A DCD manager handle. |
| * uuid_obj: Pointer to a dsp_uuid that represents a unique |
| * DSP/BIOS Bridge object. |
| * obj_type: The type of DSP/BIOS Bridge object to be |
| * referenced (node, processor, etc). |
| * obj_def: Pointer to an object definition structure. A |
| * union of various possible DCD object types. |
| * Returns: |
| * 0: Success. |
| * -EACCES: Unable to access/read/parse/load content of object code |
| * section. |
| * -EPERM: General failure. |
| * -EFAULT: Invalid DCD_HMANAGER handle. |
| * Requires: |
| * DCD initialized. |
| * obj_uuid is non-NULL. |
| * obj_def is non-NULL. |
| * Ensures: |
| */ |
| extern int dcd_get_object_def(struct dcd_manager *hdcd_mgr, |
| struct dsp_uuid *obj_uuid, |
| enum dsp_dcdobjtype obj_type, |
| struct dcd_genericobj *obj_def); |
| |
| /* |
| * ======== dcd_get_objects ======== |
| * Purpose: |
| * This function finds all DCD objects specified in a special |
| * COFF section called ".dcd_register", and for each object, |
| * call a "register" function. The "register" function may perform |
| * various actions, such as 1) register nodes in the node database, 2) |
| * unregister nodes from the node database, and 3) add overlay nodes. |
| * Parameters: |
| * hdcd_mgr: A DCD manager handle. |
| * sz_coff_path: Pointer to name of COFF file containing DCD |
| * objects. |
| * register_fxn: Callback fxn to be applied on each located |
| * DCD object. |
| * handle: Handle to pass to callback. |
| * Returns: |
| * 0: Success. |
| * -EACCES: Unable to access/read/parse/load content of object code |
| * section. |
| * -EFAULT: Invalid DCD_HMANAGER handle.. |
| * Requires: |
| * DCD initialized. |
| * Ensures: |
| * Note: |
| * Due to the DCD database construction, it is essential for a DCD-enabled |
| * COFF file to contain the right COFF sections, especially |
| * ".dcd_register", which is used for auto registration. |
| */ |
| extern int dcd_get_objects(struct dcd_manager *hdcd_mgr, |
| char *sz_coff_path, |
| dcd_registerfxn register_fxn, void *handle); |
| |
| /* |
| * ======== dcd_init ======== |
| * Purpose: |
| * This function initializes DCD. |
| * Parameters: |
| * Returns: |
| * FALSE: Initialization failed. |
| * TRUE: Initialization succeeded. |
| * Requires: |
| * Ensures: |
| * DCD initialized. |
| */ |
| extern bool dcd_init(void); |
| |
| /* |
| * ======== dcd_register_object ======== |
| * Purpose: |
| * This function registers a DSP/BIOS Bridge object in the DCD database. |
| * Parameters: |
| * uuid_obj: Pointer to a dsp_uuid that identifies a DSP/BIOS |
| * Bridge object. |
| * obj_type: Type of object. |
| * psz_path_name: Path to the object's COFF file. |
| * Returns: |
| * 0: Success. |
| * -EPERM: Failed to register object. |
| * Requires: |
| * DCD initialized. |
| * uuid_obj and szPathName are non-NULL values. |
| * obj_type is a valid type value. |
| * Ensures: |
| */ |
| extern int dcd_register_object(struct dsp_uuid *uuid_obj, |
| enum dsp_dcdobjtype obj_type, |
| char *psz_path_name); |
| |
| /* |
| * ======== dcd_unregister_object ======== |
| * Purpose: |
| * This function de-registers a valid DSP/BIOS Bridge object from the DCD |
| * database. |
| * Parameters: |
| * uuid_obj: Pointer to a dsp_uuid that identifies a DSP/BIOS Bridge |
| * object. |
| * obj_type: Type of object. |
| * Returns: |
| * 0: Success. |
| * -EPERM: Unable to de-register the specified object. |
| * Requires: |
| * DCD initialized. |
| * uuid_obj is a non-NULL value. |
| * obj_type is a valid type value. |
| * Ensures: |
| */ |
| extern int dcd_unregister_object(struct dsp_uuid *uuid_obj, |
| enum dsp_dcdobjtype obj_type); |
| |
| #endif /* _DBDCD_H */ |
