drivers/staging/tidspbridge/include/dspbridge/dbdcd.h

   1 /*
   2  * dbdcd.h
   3  *
   4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
   5  *
   6  * Defines the DSP/BIOS Bridge Configuration Database (DCD) API.
   7  *
   8  * Copyright (C) 2008 Texas Instruments, Inc.
   9  *
  10  * This package is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License version 2 as
  12  * published by the Free Software Foundation.
  13  *
  14  * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  15  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  16  * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  17  */
  18
  19 #ifndef DBDCD_
  20 #define DBDCD_
  21
  22 #include <dspbridge/dbdcddef.h>
  23 #include <dspbridge/host_os.h>
  24 #include <dspbridge/nldrdefs.h>
  25
  26 /*
  27  *  ======== dcd_auto_register ========
  28  *  Purpose:
  29  *      This function automatically registers DCD objects specified in a
  30  *      special COFF section called ".dcd_register"
  31  *  Parameters:
  32  *      hdcd_mgr:                A DCD manager handle.
  33  *      sz_coff_path:           Pointer to name of COFF file containing DCD
  34  *                              objects to be registered.
  35  *  Returns:
  36  *      0:                Success.
  37  *      -EACCES: Unable to find auto-registration/read/load section.
  38  *      -EFAULT:            Invalid DCD_HMANAGER handle..
  39  *  Requires:
  40  *      DCD initialized.
  41  *  Ensures:
  42  *  Note:
  43  *      Due to the DCD database construction, it is essential for a DCD-enabled
  44  *      COFF file to contain the right COFF sections, especially
  45  *      ".dcd_register", which is used for auto registration.
  46  */
  47 extern int dcd_auto_register(struct dcd_manager *hdcd_mgr,
  48                                     char *sz_coff_path);
  49
  50 /*
  51  *  ======== dcd_auto_unregister ========
  52  *  Purpose:
  53  *      This function automatically unregisters DCD objects specified in a
  54  *      special COFF section called ".dcd_register"
  55  *  Parameters:
  56  *      hdcd_mgr:                A DCD manager handle.
  57  *      sz_coff_path:           Pointer to name of COFF file containing
  58  *                              DCD objects to be unregistered.
  59  *  Returns:
  60  *      0:                Success.
  61  *      -EACCES: Unable to find auto-registration/read/load section.
  62  *      -EFAULT:            Invalid DCD_HMANAGER handle..
  63  *  Requires:
  64  *      DCD initialized.
  65  *  Ensures:
  66  *  Note:
  67  *      Due to the DCD database construction, it is essential for a DCD-enabled
  68  *      COFF file to contain the right COFF sections, especially
  69  *      ".dcd_register", which is used for auto unregistration.
  70  */
  71 extern int dcd_auto_unregister(struct dcd_manager *hdcd_mgr,
  72                                       char *sz_coff_path);
  73
  74 /*
  75  *  ======== dcd_create_manager ========
  76  *  Purpose:
  77  *      This function creates a DCD module manager.
  78  *  Parameters:
  79  *      sz_zl_dll_name: Pointer to a DLL name string.
  80  *      dcd_mgr:        A pointer to a DCD manager handle.
  81  *  Returns:
  82  *      0:        Success.
  83  *      -ENOMEM:    Unable to allocate memory for DCD manager handle.
  84  *      -EPERM:      General failure.
  85  *  Requires:
  86  *      DCD initialized.
  87  *      sz_zl_dll_name is non-NULL.
  88  *      dcd_mgr is non-NULL.
  89  *  Ensures:
  90  *      A DCD manager handle is created.
  91  */
  92 extern int dcd_create_manager(char *sz_zl_dll_name,
  93                                      struct dcd_manager **dcd_mgr);
  94
  95 /*
  96  *  ======== dcd_destroy_manager ========
  97  *  Purpose:
  98  *      This function destroys a DCD module manager.
  99  *  Parameters:
 100  *      hdcd_mgr:        A DCD manager handle.
 101  *  Returns:
 102  *      0:        Success.
 103  *      -EFAULT:    Invalid DCD manager handle.
 104  *  Requires:
 105  *      DCD initialized.
 106  *  Ensures:
 107  */
 108 extern int dcd_destroy_manager(struct dcd_manager *hdcd_mgr);
 109
 110 /*
 111  *  ======== dcd_enumerate_object ========
 112  *  Purpose:
 113  *      This function enumerates currently visible DSP/BIOS Bridge objects
 114  *      and returns the UUID and type of each enumerated object.
 115  *  Parameters:
 116  *      index:              The object enumeration index.
 117  *      obj_type:            Type of object to enumerate.
 118  *      uuid_obj:              Pointer to a dsp_uuid object.
 119  *  Returns:
 120  *      0:            Success.
 121  *      -EPERM:          Unable to enumerate through the DCD database.
 122  *      ENODATA:  Enumeration completed. This is not an error code.
 123  *  Requires:
 124  *      DCD initialized.
 125  *      uuid_obj is a valid pointer.
 126  *  Ensures:
 127  *  Details:
 128  *      This function can be used in conjunction with dcd_get_object_def to
 129  *      retrieve object properties.
 130  */
 131 extern int dcd_enumerate_object(s32 index,
 132                                        enum dsp_dcdobjtype obj_type,
 133                                        struct dsp_uuid *uuid_obj);
 134
 135 /*
 136  *  ======== dcd_exit ========
 137  *  Purpose:
 138  *      This function cleans up the DCD module.
 139  *  Parameters:
 140  *  Returns:
 141  *  Requires:
 142  *      DCD initialized.
 143  *  Ensures:
 144  */
 145 extern void dcd_exit(void);
 146
 147 /*
 148  *  ======== dcd_get_dep_libs ========
 149  *  Purpose:
 150  *      Given the uuid of a library and size of array of uuids, this function
 151  *      fills the array with the uuids of all dependent libraries of the input
 152  *      library.
 153  *  Parameters:
 154  *      hdcd_mgr: A DCD manager handle.
 155  *      uuid_obj: Pointer to a dsp_uuid for a library.
 156  *      num_libs: Size of uuid array (number of library uuids).
 157  *      dep_lib_uuids: Array of dependent library uuids to be filled in.
 158  *      prstnt_dep_libs:    Array indicating if corresponding lib is persistent.
 159  *      phase: phase to obtain correct input library
 160  *  Returns:
 161  *      0: Success.
 162  *      -ENOMEM: Memory allocation failure.
 163  *      -EACCES: Failure to read section containing library info.
 164  *      -EPERM: General failure.
 165  *  Requires:
 166  *      DCD initialized.
 167  *      Valid hdcd_mgr.
 168  *      uuid_obj != NULL
 169  *      dep_lib_uuids != NULL.
 170  *  Ensures:
 171  */
 172 extern int dcd_get_dep_libs(struct dcd_manager *hdcd_mgr,
 173                                    struct dsp_uuid *uuid_obj,
 174                                    u16 num_libs,
 175                                    struct dsp_uuid *dep_lib_uuids,
 176                                    bool *prstnt_dep_libs,
 177                                    enum nldr_phase phase);
 178
 179 /*
 180  *  ======== dcd_get_num_dep_libs ========
 181  *  Purpose:
 182  *      Given the uuid of a library, determine its number of dependent
 183  *      libraries.
 184  *  Parameters:
 185  *      hdcd_mgr:        A DCD manager handle.
 186  *      uuid_obj:          Pointer to a dsp_uuid for a library.
 187  *      num_libs:       Size of uuid array (number of library uuids).
 188  *      num_pers_libs:  number of persistent dependent library.
 189  *      phase:          Phase to obtain correct input library
 190  *  Returns:
 191  *      0: Success.
 192  *      -ENOMEM: Memory allocation failure.
 193  *      -EACCES: Failure to read section containing library info.
 194  *      -EPERM: General failure.
 195  *  Requires:
 196  *      DCD initialized.
 197  *      Valid hdcd_mgr.
 198  *      uuid_obj != NULL
 199  *      num_libs != NULL.
 200  *  Ensures:
 201  */
 202 extern int dcd_get_num_dep_libs(struct dcd_manager *hdcd_mgr,
 203                                        struct dsp_uuid *uuid_obj,
 204                                        u16 *num_libs,
 205                                        u16 *num_pers_libs,
 206                                        enum nldr_phase phase);
 207
 208 /*
 209  *  ======== dcd_get_library_name ========
 210  *  Purpose:
 211  *      This function returns the name of a (dynamic) library for a given
 212  *      UUID.
 213  *  Parameters:
 214  *      hdcd_mgr: A DCD manager handle.
 215  *      uuid_obj:       Pointer to a dsp_uuid that represents a unique DSP/BIOS
 216  *                      Bridge object.
 217  *      str_lib_name: Buffer to hold library name.
 218  *      buff_size: Contains buffer size. Set to string size on output.
 219  *      phase:          Which phase to load
 220  *      phase_split:    Are phases in multiple libraries
 221  *  Returns:
 222  *      0: Success.
 223  *      -EPERM: General failure.
 224  *  Requires:
 225  *      DCD initialized.
 226  *      Valid hdcd_mgr.
 227  *      str_lib_name != NULL.
 228  *      uuid_obj != NULL
 229  *      buff_size != NULL.
 230  *  Ensures:
 231  */
 232 extern int dcd_get_library_name(struct dcd_manager *hdcd_mgr,
 233                                        struct dsp_uuid *uuid_obj,
 234                                        char *str_lib_name,
 235                                        u32 *buff_size,
 236                                        enum nldr_phase phase,
 237                                        bool *phase_split);
 238
 239 /*
 240  *  ======== dcd_get_object_def ========
 241  *  Purpose:
 242  *      This function returns the properties/attributes of a DSP/BIOS Bridge
 243  *      object.
 244  *  Parameters:
 245  *      hdcd_mgr:            A DCD manager handle.
 246  *      uuid_obj:              Pointer to a dsp_uuid that represents a unique
 247  *                          DSP/BIOS Bridge object.
 248  *      obj_type:            The type of DSP/BIOS Bridge object to be
 249  *                          referenced (node, processor, etc).
 250  *      obj_def:            Pointer to an object definition structure. A
 251  *                          union of various possible DCD object types.
 252  *  Returns:
 253  *      0: Success.
 254  *      -EACCES: Unable to access/read/parse/load content of object code
 255  *               section.
 256  *      -EPERM:          General failure.
 257  *      -EFAULT:        Invalid DCD_HMANAGER handle.
 258  *  Requires:
 259  *      DCD initialized.
 260  *      obj_uuid is non-NULL.
 261  *      obj_def is non-NULL.
 262  *  Ensures:
 263  */
 264 extern int dcd_get_object_def(struct dcd_manager *hdcd_mgr,
 265                                      struct dsp_uuid *obj_uuid,
 266                                      enum dsp_dcdobjtype obj_type,
 267                                      struct dcd_genericobj *obj_def);
 268
 269 /*
 270  *  ======== dcd_get_objects ========
 271  *  Purpose:
 272  *      This function finds all DCD objects specified in a special
 273  *      COFF section called ".dcd_register", and for each object,
 274  *      call a "register" function.  The "register" function may perform
 275  *      various actions, such as 1) register nodes in the node database, 2)
 276  *      unregister nodes from the node database, and 3) add overlay nodes.
 277  *  Parameters:
 278  *      hdcd_mgr:                A DCD manager handle.
 279  *      sz_coff_path:           Pointer to name of COFF file containing DCD
 280  *                              objects.
 281  *      register_fxn:           Callback fxn to be applied on each located
 282  *                              DCD object.
 283  *      handle:                 Handle to pass to callback.
 284  *  Returns:
 285  *      0:                Success.
 286  *      -EACCES: Unable to access/read/parse/load content of object code
 287  *               section.
 288  *      -EFAULT:            Invalid DCD_HMANAGER handle..
 289  *  Requires:
 290  *      DCD initialized.
 291  *  Ensures:
 292  *  Note:
 293  *      Due to the DCD database construction, it is essential for a DCD-enabled
 294  *      COFF file to contain the right COFF sections, especially
 295  *      ".dcd_register", which is used for auto registration.
 296  */
 297 extern int dcd_get_objects(struct dcd_manager *hdcd_mgr,
 298                                   char *sz_coff_path,
 299                                   dcd_registerfxn register_fxn, void *handle);
 300
 301 /*
 302  *  ======== dcd_init ========
 303  *  Purpose:
 304  *      This function initializes DCD.
 305  *  Parameters:
 306  *  Returns:
 307  *      FALSE:  Initialization failed.
 308  *      TRUE:   Initialization succeeded.
 309  *  Requires:
 310  *  Ensures:
 311  *      DCD initialized.
 312  */
 313 extern bool dcd_init(void);
 314
 315 /*
 316  *  ======== dcd_register_object ========
 317  *  Purpose:
 318  *      This function registers a DSP/BIOS Bridge object in the DCD database.
 319  *  Parameters:
 320  *      uuid_obj:          Pointer to a dsp_uuid that identifies a DSP/BIOS
 321  *                      Bridge object.
 322  *      obj_type:        Type of object.
 323  *      psz_path_name:    Path to the object's COFF file.
 324  *  Returns:
 325  *      0:        Success.
 326  *      -EPERM:      Failed to register object.
 327  *  Requires:
 328  *      DCD initialized.
 329  *      uuid_obj and szPathName are non-NULL values.
 330  *      obj_type is a valid type value.
 331  *  Ensures:
 332  */
 333 extern int dcd_register_object(struct dsp_uuid *uuid_obj,
 334                                       enum dsp_dcdobjtype obj_type,
 335                                       char *psz_path_name);
 336
 337 /*
 338  *  ======== dcd_unregister_object ========
 339  *  Purpose:
 340  *      This function de-registers a valid DSP/BIOS Bridge object from the DCD
 341  *      database.
 342  *  Parameters:
 343  *      uuid_obj:      Pointer to a dsp_uuid that identifies a DSP/BIOS Bridge
 344  *                  object.
 345  *      obj_type:    Type of object.
 346  *  Returns:
 347  *      0:    Success.
 348  *      -EPERM:  Unable to de-register the specified object.
 349  *  Requires:
 350  *      DCD initialized.
 351  *      uuid_obj is a non-NULL value.
 352  *      obj_type is a valid type value.
 353  *  Ensures:
 354  */
 355 extern int dcd_unregister_object(struct dsp_uuid *uuid_obj,
 356                                         enum dsp_dcdobjtype obj_type);
 357
 358 #endif /* _DBDCD_H */