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: */ 27struct nldr_object; 28struct nldr_nodeobject; 29 30/* 31 * ======== nldr_loadtype ======== 32 * Load types for a node. Must match values in node.h55. 33 */ 34enum 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 */ 58typedef 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 */ 76typedef 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 */ 84struct 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 */ 95enum 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 */ 130typedef int(*nldr_allocatefxn) (struct nldr_object *nldr_obj, 131 void *priv_ref, 132 const struct dcd_nodeprops 133 * node_props, 134 struct nldr_nodeobject 135 **nldr_nodeobj, 136 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 */ 159typedef int(*nldr_createfxn) (struct nldr_object **nldr, 160 struct dev_object *hdev_obj, 161 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 */ 176typedef 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 */ 190typedef 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 */ 204typedef 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 */ 225typedef 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 */ 238typedef 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 */ 258typedef 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 */ 276typedef int(*nldr_unloadfxn) (struct nldr_nodeobject *nldr_node_obj, 277 enum nldr_phase phase); 278 279/* 280 * ======== node_ldr_fxns ======== 281 */ 282struct 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_ */ 294