| /* |
| * cod.h |
| * |
| * DSP-BIOS Bridge driver support functions for TI OMAP processors. |
| * |
| * Code management module for DSPs. This module provides an interface |
| * interface for loading both static and dynamic code objects onto DSP |
| * systems. |
| * |
| * Copyright (C) 2005-2006 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 COD_ |
| #define COD_ |
| |
| #include <dspbridge/dblldefs.h> |
| |
| #define COD_MAXPATHLENGTH 255 |
| #define COD_TRACEBEG "SYS_PUTCBEG" |
| #define COD_TRACEEND "SYS_PUTCEND" |
| #define COD_TRACECURPOS "BRIDGE_SYS_PUTC_current" |
| #define COD_TRACESECT "trace" |
| #define COD_TRACEBEGOLD "PUTCBEG" |
| #define COD_TRACEENDOLD "PUTCEND" |
| |
| #define COD_NOLOAD DBLL_NOLOAD |
| #define COD_SYMB DBLL_SYMB |
| |
| /* COD code manager handle */ |
| struct cod_manager; |
| |
| /* COD library handle */ |
| struct cod_libraryobj; |
| |
| /* COD attributes */ |
| struct cod_attrs { |
| u32 ul_reserved; |
| }; |
| |
| /* |
| * Function prototypes for writing memory to a DSP system, allocating |
| * and freeing DSP memory. |
| */ |
| typedef u32(*cod_writefxn) (void *priv_ref, u32 dsp_add, |
| void *pbuf, u32 ul_num_bytes, u32 mem_space); |
| |
| /* |
| * ======== cod_close ======== |
| * Purpose: |
| * Close a library opened with cod_open(). |
| * Parameters: |
| * lib - Library handle returned by cod_open(). |
| * Returns: |
| * None. |
| * Requires: |
| * COD module initialized. |
| * valid lib. |
| * Ensures: |
| * |
| */ |
| extern void cod_close(struct cod_libraryobj *lib); |
| |
| /* |
| * ======== cod_create ======== |
| * Purpose: |
| * Create an object to manage code on a DSP system. This object can be |
| * used to load an initial program image with arguments that can later |
| * be expanded with dynamically loaded object files. |
| * Symbol table information is managed by this object and can be retrieved |
| * using the cod_get_sym_value() function. |
| * Parameters: |
| * manager: created manager object |
| * str_zl_file: ZL DLL filename, of length < COD_MAXPATHLENGTH. |
| * attrs: attributes to be used by this object. A NULL value |
| * will cause default attrs to be used. |
| * Returns: |
| * 0: Success. |
| * -ESPIPE: ZL_Create failed. |
| * -ENOSYS: attrs was not NULL. We don't yet support |
| * non default values of attrs. |
| * Requires: |
| * COD module initialized. |
| * str_zl_file != NULL |
| * Ensures: |
| */ |
| extern int cod_create(struct cod_manager **mgr, |
| char *str_zl_file, |
| const struct cod_attrs *attrs); |
| |
| /* |
| * ======== cod_delete ======== |
| * Purpose: |
| * Delete a code manager object. |
| * Parameters: |
| * cod_mgr_obj: handle of manager to be deleted |
| * Returns: |
| * None. |
| * Requires: |
| * COD module initialized. |
| * valid cod_mgr_obj. |
| * Ensures: |
| */ |
| extern void cod_delete(struct cod_manager *cod_mgr_obj); |
| |
| /* |
| * ======== cod_exit ======== |
| * Purpose: |
| * Discontinue usage of the COD module. |
| * Parameters: |
| * None. |
| * Returns: |
| * None. |
| * Requires: |
| * COD initialized. |
| * Ensures: |
| * Resources acquired in cod_init(void) are freed. |
| */ |
| extern void cod_exit(void); |
| |
| /* |
| * ======== cod_get_base_lib ======== |
| * Purpose: |
| * Get handle to the base image DBL library. |
| * Parameters: |
| * cod_mgr_obj: handle of manager to be deleted |
| * plib: location to store library handle on output. |
| * Returns: |
| * 0: Success. |
| * Requires: |
| * COD module initialized. |
| * valid cod_mgr_obj. |
| * plib != NULL. |
| * Ensures: |
| */ |
| extern int cod_get_base_lib(struct cod_manager *cod_mgr_obj, |
| struct dbll_library_obj **plib); |
| |
| /* |
| * ======== cod_get_base_name ======== |
| * Purpose: |
| * Get the name of the base image DBL library. |
| * Parameters: |
| * cod_mgr_obj: handle of manager to be deleted |
| * sz_name: location to store library name on output. |
| * usize: size of name buffer. |
| * Returns: |
| * 0: Success. |
| * -EPERM: Buffer too small. |
| * Requires: |
| * COD module initialized. |
| * valid cod_mgr_obj. |
| * sz_name != NULL. |
| * Ensures: |
| */ |
| extern int cod_get_base_name(struct cod_manager *cod_mgr_obj, |
| char *sz_name, u32 usize); |
| |
| /* |
| * ======== cod_get_entry ======== |
| * Purpose: |
| * Retrieve the entry point of a loaded DSP program image |
| * Parameters: |
| * cod_mgr_obj: handle of manager to be deleted |
| * entry_pt: pointer to location for entry point |
| * Returns: |
| * 0: Success. |
| * Requires: |
| * COD module initialized. |
| * valid cod_mgr_obj. |
| * entry_pt != NULL. |
| * Ensures: |
| */ |
| extern int cod_get_entry(struct cod_manager *cod_mgr_obj, |
| u32 *entry_pt); |
| |
| /* |
| * ======== cod_get_loader ======== |
| * Purpose: |
| * Get handle to the DBL loader. |
| * Parameters: |
| * cod_mgr_obj: handle of manager to be deleted |
| * loader: location to store loader handle on output. |
| * Returns: |
| * 0: Success. |
| * Requires: |
| * COD module initialized. |
| * valid cod_mgr_obj. |
| * loader != NULL. |
| * Ensures: |
| */ |
| extern int cod_get_loader(struct cod_manager *cod_mgr_obj, |
| struct dbll_tar_obj **loader); |
| |
| /* |
| * ======== cod_get_section ======== |
| * Purpose: |
| * Retrieve the starting address and length of a section in the COFF file |
| * given the section name. |
| * Parameters: |
| * lib Library handle returned from cod_open(). |
| * str_sect: name of the section, with or without leading "." |
| * addr: Location to store address. |
| * len: Location to store length. |
| * Returns: |
| * 0: Success |
| * -ESPIPE: Symbols could not be found or have not been loaded onto |
| * the board. |
| * Requires: |
| * COD module initialized. |
| * valid cod_mgr_obj. |
| * str_sect != NULL; |
| * addr != NULL; |
| * len != NULL; |
| * Ensures: |
| * 0: *addr and *len contain the address and length of the |
| * section. |
| * else: *addr == 0 and *len == 0; |
| * |
| */ |
| extern int cod_get_section(struct cod_libraryobj *lib, |
| char *str_sect, |
| u32 *addr, u32 *len); |
| |
| /* |
| * ======== cod_get_sym_value ======== |
| * Purpose: |
| * Retrieve the value for the specified symbol. The symbol is first |
| * searched for literally and then, if not found, searched for as a |
| * C symbol. |
| * Parameters: |
| * lib: library handle returned from cod_open(). |
| * pstrSymbol: name of the symbol |
| * value: value of the symbol |
| * Returns: |
| * 0: Success. |
| * -ESPIPE: Symbols could not be found or have not been loaded onto |
| * the board. |
| * Requires: |
| * COD module initialized. |
| * Valid cod_mgr_obj. |
| * str_sym != NULL. |
| * pul_value != NULL. |
| * Ensures: |
| */ |
| extern int cod_get_sym_value(struct cod_manager *cod_mgr_obj, |
| char *str_sym, u32 * pul_value); |
| |
| /* |
| * ======== cod_init ======== |
| * Purpose: |
| * Initialize the COD module's private state. |
| * Parameters: |
| * None. |
| * Returns: |
| * TRUE if initialized; FALSE if error occured. |
| * Requires: |
| * Ensures: |
| * A requirement for each of the other public COD functions. |
| */ |
| extern bool cod_init(void); |
| |
| /* |
| * ======== cod_load_base ======== |
| * Purpose: |
| * Load the initial program image, optionally with command-line arguments, |
| * on the DSP system managed by the supplied handle. The program to be |
| * loaded must be the first element of the args array and must be a fully |
| * qualified pathname. |
| * Parameters: |
| * hmgr: manager to load the code with |
| * num_argc: number of arguments in the args array |
| * args: array of strings for arguments to DSP program |
| * write_fxn: board-specific function to write data to DSP system |
| * arb: arbitrary pointer to be passed as first arg to write_fxn |
| * envp: array of environment strings for DSP exec. |
| * Returns: |
| * 0: Success. |
| * -EBADF: Failed to open target code. |
| * Requires: |
| * COD module initialized. |
| * hmgr is valid. |
| * num_argc > 0. |
| * args != NULL. |
| * args[0] != NULL. |
| * pfn_write != NULL. |
| * Ensures: |
| */ |
| extern int cod_load_base(struct cod_manager *cod_mgr_obj, |
| u32 num_argc, char *args[], |
| cod_writefxn pfn_write, void *arb, |
| char *envp[]); |
| |
| /* |
| * ======== cod_open ======== |
| * Purpose: |
| * Open a library for reading sections. Does not load or set the base. |
| * Parameters: |
| * hmgr: manager to load the code with |
| * sz_coff_path: Coff file to open. |
| * flags: COD_NOLOAD (don't load symbols) or COD_SYMB (load |
| * symbols). |
| * lib_obj: Handle returned that can be used in calls to cod_close |
| * and cod_get_section. |
| * Returns: |
| * S_OK: Success. |
| * -EBADF: Failed to open target code. |
| * Requires: |
| * COD module initialized. |
| * hmgr is valid. |
| * flags == COD_NOLOAD || flags == COD_SYMB. |
| * sz_coff_path != NULL. |
| * Ensures: |
| */ |
| extern int cod_open(struct cod_manager *hmgr, |
| char *sz_coff_path, |
| u32 flags, struct cod_libraryobj **lib_obj); |
| |
| /* |
| * ======== cod_open_base ======== |
| * Purpose: |
| * Open base image for reading sections. Does not load the base. |
| * Parameters: |
| * hmgr: manager to load the code with |
| * sz_coff_path: Coff file to open. |
| * flags: Specifies whether to load symbols. |
| * Returns: |
| * 0: Success. |
| * -EBADF: Failed to open target code. |
| * Requires: |
| * COD module initialized. |
| * hmgr is valid. |
| * sz_coff_path != NULL. |
| * Ensures: |
| */ |
| extern int cod_open_base(struct cod_manager *hmgr, char *sz_coff_path, |
| dbll_flags flags); |
| |
| /* |
| * ======== cod_read_section ======== |
| * Purpose: |
| * Retrieve the content of a code section given the section name. |
| * Parameters: |
| * cod_mgr_obj - manager in which to search for the symbol |
| * str_sect - name of the section, with or without leading "." |
| * str_content - buffer to store content of the section. |
| * Returns: |
| * 0: on success, error code on failure |
| * -ESPIPE: Symbols have not been loaded onto the board. |
| * Requires: |
| * COD module initialized. |
| * valid cod_mgr_obj. |
| * str_sect != NULL; |
| * str_content != NULL; |
| * Ensures: |
| * 0: *str_content stores the content of the named section. |
| */ |
| extern int cod_read_section(struct cod_libraryobj *lib, |
| char *str_sect, |
| char *str_content, u32 content_size); |
| |
| #endif /* COD_ */ |
