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

   1 /*
   2  * nldrdefs.h
   3  *
   4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
   5  *
   6  * Global Dynamic + static/overlay Node loader (NLDR) constants and types.
   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 NLDRDEFS_
  20 #define NLDRDEFS_
  21
  22 #include <dspbridge/dbdcddef.h>
  23 #include <dspbridge/devdefs.h>
  24
  25 #define NLDR_MAXPATHLENGTH       255
  26 /* NLDR Objects: */
  27 struct nldr_object;
  28 struct nldr_nodeobject;
  29
  30 /*
  31  *  ======== nldr_loadtype ========
  32  *  Load types for a node. Must match values in node.h55.
  33  */
  34 enum nldr_loadtype {
  35         NLDR_STATICLOAD,        /* Linked in base image, not overlay */
  36         NLDR_DYNAMICLOAD,       /* Dynamically loaded node */
  37         NLDR_OVLYLOAD           /* Linked in base image, overlay node */
  38 };
  39
  40 /*
  41  *  ======== nldr_ovlyfxn ========
  42  *  Causes code or data to be copied from load address to run address. This
  43  *  is the "cod_writefxn" that gets passed to the DBLL_Library and is used as
  44  *  the ZL write function.
  45  *
  46  *  Parameters:
  47  *      priv_ref:       Handle to identify the node.
  48  *      dsp_run_addr:   Run address of code or data.
  49  *      dsp_load_addr:  Load address of code or data.
  50  *      ul_num_bytes:     Number of (GPP) bytes to copy.
  51  *      mem_space:      RMS_CODE or RMS_DATA.
  52  *  Returns:
  53  *      ul_num_bytes:     Success.
  54  *      0:              Failure.
  55  *  Requires:
  56  *  Ensures:
  57  */
  58 typedef u32(*nldr_ovlyfxn) (void *priv_ref, u32 dsp_run_addr,
  59                             u32 dsp_load_addr, u32 ul_num_bytes, u32 mem_space);
  60
  61 /*
  62  *  ======== nldr_writefxn ========
  63  *  Write memory function. Used for dynamic load writes.
  64  *  Parameters:
  65  *      priv_ref:       Handle to identify the node.
  66  *      dsp_add:        Address of code or data.
  67  *      pbuf:           Code or data to be written
  68  *      ul_num_bytes:     Number of (GPP) bytes to write.
  69  *      mem_space:      DBLL_DATA or DBLL_CODE.
  70  *  Returns:
  71  *      ul_num_bytes:     Success.
  72  *      0:              Failure.
  73  *  Requires:
  74  *  Ensures:
  75  */
  76 typedef u32(*nldr_writefxn) (void *priv_ref,
  77                              u32 dsp_add, void *pbuf,
  78                              u32 ul_num_bytes, u32 mem_space);
  79
  80 /*
  81  *  ======== nldr_attrs ========
  82  *  Attributes passed to nldr_create function.
  83  */
  84 struct nldr_attrs {
  85         nldr_ovlyfxn pfn_ovly;
  86         nldr_writefxn pfn_write;
  87         u16 us_dsp_word_size;
  88         u16 us_dsp_mau_size;
  89 };
  90
  91 /*
  92  *  ======== nldr_phase ========
  93  *  Indicates node create, delete, or execute phase function.
  94  */
  95 enum nldr_phase {
  96         NLDR_CREATE,
  97         NLDR_DELETE,
  98         NLDR_EXECUTE,
  99         NLDR_NOPHASE
 100 };
 101
 102 /*
 103  *  Typedefs of loader functions imported from a DLL, or defined in a
 104  *  function table.
 105  */
 106
 107 /*
 108  *  ======== nldr_allocate ========
 109  *  Allocate resources to manage the loading of a node on the DSP.
 110  *
 111  *  Parameters:
 112  *      nldr_obj:          Handle of loader that will load the node.
 113  *      priv_ref:       Handle to identify the node.
 114  *      node_props:     Pointer to a dcd_nodeprops for the node.
 115  *      nldr_nodeobj:   Location to store node handle on output. This handle
 116  *                      will be passed to nldr_load/nldr_unload.
 117  *      pf_phase_split:   pointer to int variable referenced in node.c
 118  *  Returns:
 119  *      0:        Success.
 120  *      -ENOMEM:    Insufficient memory on GPP.
 121  *  Requires:
 122  *      nldr_init(void) called.
 123  *      Valid nldr_obj.
 124  *      node_props != NULL.
 125  *      nldr_nodeobj != NULL.
 126  *  Ensures:
 127  *      0:        IsValidNode(*nldr_nodeobj).
 128  *      error:          *nldr_nodeobj == NULL.
 129  */
 130 typedef int(*nldr_allocatefxn) (struct nldr_object *nldr_obj,
 131                                        void *priv_ref,
 132                                        IN const struct dcd_nodeprops
 133                                        * node_props,
 134                                        OUT struct nldr_nodeobject
 135                                        **nldr_nodeobj,
 136                                        OUT bool *pf_phase_split);
 137
 138 /*
 139  *  ======== nldr_create ========
 140  *  Create a loader object. This object handles the loading and unloading of
 141  *  create, delete, and execute phase functions of nodes on the DSP target.
 142  *
 143  *  Parameters:
 144  *      nldr:           Location to store loader handle on output.
 145  *      hdev_obj:     Device for this processor.
 146  *      pattrs:         Loader attributes.
 147  *  Returns:
 148  *      0:        Success;
 149  *      -ENOMEM:    Insufficient memory for requested resources.
 150  *  Requires:
 151  *      nldr_init(void) called.
 152  *      nldr != NULL.
 153  *      hdev_obj != NULL.
 154  *      pattrs != NULL.
 155  *  Ensures:
 156  *      0:        Valid *nldr.
 157  *      error:          *nldr == NULL.
 158  */
 159 typedef int(*nldr_createfxn) (OUT struct nldr_object **nldr,
 160                                      struct dev_object *hdev_obj,
 161                                      IN const struct nldr_attrs *pattrs);
 162
 163 /*
 164  *  ======== nldr_delete ========
 165  *  Delete the NLDR loader.
 166  *
 167  *  Parameters:
 168  *      nldr_obj:          Node manager object.
 169  *  Returns:
 170  *  Requires:
 171  *      nldr_init(void) called.
 172  *      Valid nldr_obj.
 173  *  Ensures:
 174  *      nldr_obj invalid
 175  */
 176 typedef void (*nldr_deletefxn) (struct nldr_object *nldr_obj);
 177
 178 /*
 179  *  ======== nldr_exit ========
 180  *  Discontinue usage of NLDR module.
 181  *
 182  *  Parameters:
 183  *  Returns:
 184  *  Requires:
 185  *      nldr_init(void) successfully called before.
 186  *  Ensures:
 187  *      Any resources acquired in nldr_init(void) will be freed when last NLDR
 188  *      client calls nldr_exit(void).
 189  */
 190 typedef void (*nldr_exitfxn) (void);
 191
 192 /*
 193  *  ======== NLDR_Free ========
 194  *  Free resources allocated in nldr_allocate.
 195  *
 196  *  Parameters:
 197  *      nldr_node_obj:      Handle returned from nldr_allocate().
 198  *  Returns:
 199  *  Requires:
 200  *      nldr_init(void) called.
 201  *      Valid nldr_node_obj.
 202  *  Ensures:
 203  */
 204 typedef void (*nldr_freefxn) (struct nldr_nodeobject *nldr_node_obj);
 205
 206 /*
 207  *  ======== nldr_get_fxn_addr ========
 208  *  Get address of create, delete, or execute phase function of a node on
 209  *  the DSP.
 210  *
 211  *  Parameters:
 212  *      nldr_node_obj:      Handle returned from nldr_allocate().
 213  *      str_fxn:        Name of function.
 214  *      addr:           Location to store function address.
 215  *  Returns:
 216  *      0:        Success.
 217  *      -ESPIPE:    Address of function not found.
 218  *  Requires:
 219  *      nldr_init(void) called.
 220  *      Valid nldr_node_obj.
 221  *      addr != NULL;
 222  *      str_fxn != NULL;
 223  *  Ensures:
 224  */
 225 typedef int(*nldr_getfxnaddrfxn) (struct nldr_nodeobject
 226                                          * nldr_node_obj,
 227                                          char *str_fxn, u32 * addr);
 228
 229 /*
 230  *  ======== nldr_init ========
 231  *  Initialize the NLDR module.
 232  *
 233  *  Parameters:
 234  *  Returns:
 235  *      TRUE if initialization succeeded, FALSE otherwise.
 236  *  Ensures:
 237  */
 238 typedef bool(*nldr_initfxn) (void);
 239
 240 /*
 241  *  ======== nldr_load ========
 242  *  Load create, delete, or execute phase function of a node on the DSP.
 243  *
 244  *  Parameters:
 245  *      nldr_node_obj:      Handle returned from nldr_allocate().
 246  *      phase:          Type of function to load (create, delete, or execute).
 247  *  Returns:
 248  *      0:                Success.
 249  *      -ENOMEM:            Insufficient memory on GPP.
 250  *      -ENXIO:     Can't overlay phase because overlay memory
 251  *                              is already in use.
 252  *      -EILSEQ:           Failure in dynamic loader library.
 253  *  Requires:
 254  *      nldr_init(void) called.
 255  *      Valid nldr_node_obj.
 256  *  Ensures:
 257  */
 258 typedef int(*nldr_loadfxn) (struct nldr_nodeobject *nldr_node_obj,
 259                                    enum nldr_phase phase);
 260
 261 /*
 262  *  ======== nldr_unload ========
 263  *  Unload create, delete, or execute phase function of a node on the DSP.
 264  *
 265  *  Parameters:
 266  *      nldr_node_obj:      Handle returned from nldr_allocate().
 267  *      phase:          Node function to unload (create, delete, or execute).
 268  *  Returns:
 269  *      0:        Success.
 270  *      -ENOMEM:    Insufficient memory on GPP.
 271  *  Requires:
 272  *      nldr_init(void) called.
 273  *      Valid nldr_node_obj.
 274  *  Ensures:
 275  */
 276 typedef int(*nldr_unloadfxn) (struct nldr_nodeobject *nldr_node_obj,
 277                                      enum nldr_phase phase);
 278
 279 /*
 280  *  ======== node_ldr_fxns ========
 281  */
 282 struct node_ldr_fxns {
 283         nldr_allocatefxn pfn_allocate;
 284         nldr_createfxn pfn_create;
 285         nldr_deletefxn pfn_delete;
 286         nldr_exitfxn pfn_exit;
 287         nldr_getfxnaddrfxn pfn_get_fxn_addr;
 288         nldr_initfxn pfn_init;
 289         nldr_loadfxn pfn_load;
 290         nldr_unloadfxn pfn_unload;
 291 };
 292
 293 #endif /* NLDRDEFS_ */