359 lines
12 KiB
C
359 lines
12 KiB
C
/*
|
|
* 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 */
|