/*************************************************************************** * pofflib.h * Interfaces to the POFF library * * Copyright (C) 2008 Gregory Nutt. All rights reserved. * Author: Gregory Nutt * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * 3. Neither the name NuttX nor the names of its contributors may be * used to endorse or promote products derived from this software * without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * ***************************************************************************/ #ifndef __POFFLIB_H #define __POFFLIB_H /*************************************************************************** * Compilation Switches ***************************************************************************/ /*************************************************************************** * Included Files ***************************************************************************/ #include "keywords.h" #include "poff.h" /*************************************************************************** * Definitions ***************************************************************************/ /*************************************************************************** * Public Types ***************************************************************************/ /* The internal form of the POFF data structures are hidden from the caller * in these "handles" */ typedef void *poffHandle_t; typedef void *poffProgHandle_t; typedef void *poffSymHandle_t; /* This is a externally visible form of a symbol table entry that is * not entangled in the POFF internal string table logic. */ struct poffLibSymbol_s { /* type is the type of symbol described by this entry. * See the STT_ definitions in poff.h. */ ubyte type; /* For data section symbols, the following provides the required * data space alignment for the symbol memory representation. For * procedures and functions, this value is ignored. See the STT_ * definitions in poff.h */ ubyte align; /* These flags describe the characteristics of the symbol. See the * STF_ definitions above. */ ubyte flags; /* name is a reference to the symbol name in the string table * section data. */ const char *name; /* value is the value associated with symbol. For defined data * section symbols, this is the offset into the initialized data * section data; for defined procedures and functions, this the * offset into program section data. For undefined symbols, this * valid can be used as as addend. */ uint32 value; /* For data section symbols, this is the size of the initialized * data region associated with the symbol. */ uint32 size; }; typedef struct poffLibSymbol_s poffLibSymbol_t; /* The externally visible form of a line number structure. Line numbers * are associated with executable program data sections. */ struct poffLibLineNumber_s { /* This is the source file line number */ uint32 lineno; /* This is the full filename of the file containing the line number. */ const char *filename; /* This is an offset to the beginning code in the program data section * associated with this line number. */ uint32 offset; }; typedef struct poffLibLineNumber_s poffLibLineNumber_t; /* The externally visible form of a debug function info structure. */ struct poffLibDebugFuncInfo_s { /* For use outside of libpoff so that the allocated debug * information can be retained in a list. */ struct poffLibDebugFuncInfo_s *next; /* This is the address or label of the function/procedure entry * point. */ uint32 value; /* This is the size of the value returned by the function in * bytes (zero for procedures). */ uint32 retsize; /* This is the number of parameters accepted by the function/ * procedure. */ uint32 nparms; /* This is the beginning of a table of input parameter sizes * the actually allocate size will be nparms entries. */ uint32 argsize[1]; }; typedef struct poffLibDebugFuncInfo_s poffLibDebugFuncInfo_t; #define SIZEOFDEBUFINFO(n) (sizeof(poffLibDebugFuncInfo_t) + ((n)-1)*sizeof(uint32)) /*************************************************************************** * Public Variables ***************************************************************************/ /*************************************************************************** * Public Function Prototypes ***************************************************************************/ /* Functions to create/destroy a handle to POFF file data */ extern poffHandle_t poffCreateHandle(void); extern void poffDestroyHandle(poffHandle_t handle); extern void poffResetAccess(poffHandle_t handle); /* Functions to manage writing a POFF file */ extern void poffSetFileType(poffHandle_t handle, ubyte fh_type, uint16 nfiles, const char *name); extern void poffSetArchitecture(poffHandle_t handle, ubyte fh_arch); extern void poffSetEntryPoint(poffHandle_t handle, uint32 entryPoint); extern sint32 poffFindString(poffHandle_t handle, const char *string); extern uint32 poffAddString(poffHandle_t handle, const char *string); extern uint32 poffAddFileName(poffHandle_t handle, const char *name); extern void poffAddProgByte(poffHandle_t handle, ubyte progByte); #if 0 /* not used */ extern uint32 poffAddRoDataByte(poffHandle_t handle, ubyte dataByte); #endif extern uint32 poffAddRoDataString(poffHandle_t handle, const char *string); extern uint32 poffAddSymbol(poffHandle_t handle, poffLibSymbol_t *symbol); extern uint32 poffAddLineNumber(poffHandle_t handle, uint16 lineNumber, uint16 fileNumber, uint32 progSectionDataOffset); extern uint32 poffAddDebugFuncInfo(poffHandle_t handle, poffLibDebugFuncInfo_t *pContainer); extern uint32 poffAddRelocation(poffHandle_t handle, ubyte relocType, uint32 symIndex, uint32 sectionDataOffset); extern void poffWriteFile(poffHandle_t handle, FILE *poffFile); /* Functions to manage reading a POFF file */ extern uint16 poffReadFile(poffHandle_t handle, FILE *poffFile); extern ubyte poffGetFileType(poffHandle_t handle); extern ubyte poffGetArchitecture(poffHandle_t handle); extern uint32 poffGetEntryPoint(poffHandle_t handle); extern const char *poffGetFileHdrName(poffHandle_t handle); extern uint32 poffGetRoDataSize(poffHandle_t handle); extern sint32 poffGetFileName(poffHandle_t handle, const char **fname); extern int poffGetProgByte(poffHandle_t handle); extern sint32 poffGetSymbol(poffHandle_t handle, poffLibSymbol_t *symbol); extern const char *poffGetString(poffHandle_t handle, uint32 index); extern sint32 poffGetLineNumber(poffHandle_t handle, poffLibLineNumber_t *lineno); extern sint32 poffGetRawLineNumber(poffHandle_t handle, poffLineNumber_t *lineno); extern sint32 poffGetRawRelocation(poffHandle_t handle, poffRelocation_t *reloc); extern poffLibDebugFuncInfo_t *poffGetDebugFuncInfo(poffHandle_t handle); extern poffLibDebugFuncInfo_t *poffCreateDebugInfoContainer(uint32 nparms); extern void poffReleaseDebugFuncContainer(poffLibDebugFuncInfo_t *pDebugFuncInfo); extern void poffDiscardDebugFuncInfo(poffHandle_t handle); extern sint32 poffProgTell(poffHandle_t handle); extern int poffProgSeek(poffHandle_t handle, uint32 offset); extern uint32 poffGetProgSize(poffHandle_t handle); extern void poffReleaseProgData(poffHandle_t handle); /* Functions used to manage modifications to a POFF file using a * temporary container for the new program data. */ extern poffProgHandle_t poffCreateProgHandle(void); extern void poffDestroyProgHandle(poffProgHandle_t handle); extern void poffResetProgHandle(poffProgHandle_t handle); extern uint16 poffAddTmpProgByte(poffProgHandle_t handle, ubyte progByte); extern uint16 poffWriteTmpProgBytes(ubyte *buffer, uint32 nbyte, poffProgHandle_t handle); extern void poffReplaceProgData(poffHandle_t handle, poffProgHandle_t progHandle); /* Functions used to manage modifications to a POFF file using a * temporary container for the new symbol data. */ extern poffSymHandle_t poffCreateSymHandle(void); extern void poffDestroySymHandle(poffSymHandle_t handle); extern void poffResetSymHandle(poffSymHandle_t handle); extern uint32 poffAddTmpSymbol(poffHandle_t handle, poffSymHandle_t symHandle, poffLibSymbol_t *symbol); extern void poffReplaceSymbolTable(poffHandle_t handle, poffSymHandle_t symHandle); /* Functions used to extract/insert whole data sections from/into a POFF * file container */ extern uint32 poffExtractProgramData(poffHandle_t handle, ubyte **progData); extern void poffInsertProgramData(poffHandle_t handle, ubyte *progData, uint32 progSize); extern uint32 poffExtractRoData(poffHandle_t handle, ubyte **roData); extern void poffAppendRoData(poffHandle_t handle, ubyte *roData, uint32 roDataSize); /* Functions to manage printing of the POFF file content */ extern void poffDumpFileHeader(poffHandle_t handle, FILE *outFile); extern void poffDumpSectionHeaders(poffHandle_t handle, FILE *outFile); extern void poffDumpSymbolTable(poffHandle_t handle, FILE *outFile); extern void poffDumpRelocTable(poffHandle_t handle, FILE *outFile); /* Helper functions to manage resolution of labels in POFF files. These * just store and retrieve information by label number. */ extern void poffAddToDefinedLabelTable(uint32 label, uint32 pc); extern void poffAddToUndefinedLabelTable(uint32 label, uint32 symIndex); extern int poffGetSymIndexForUndefinedLabel(uint32 label); extern int poffGetPcForDefinedLabel(uint32 label); extern void poffReleaseLabelReferences(void); /* Helper functions for line numbers */ extern void poffReadLineNumberTable(poffHandle_t handle); extern poffLibLineNumber_t *poffFindLineNumber(uint32 offset); extern void poffReleaseLineNumberTable(void); /* Helper functions for debug information */ extern void poffReadDebugFuncInfoTable(poffHandle_t handle); extern poffLibDebugFuncInfo_t *poffFindDebugFuncInfo(uint32 offset); extern void poffReplaceDebugFuncInfo(poffHandle_t handle); extern void poffReleaseDebugFuncInfoTable(void); #endif /* __POFFLIB_H */