/*************************************************************************** * pofflib.h * Interfaces to the POFF library * * Copyright (C) 2008-2009 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 /*************************************************************************** * Included Files ***************************************************************************/ #include #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. */ uint8_t 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 */ uint8_t align; /* These flags describe the characteristics of the symbol. See the * STF_ definitions above. */ uint8_t 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_t value; /* For data section symbols, this is the size of the initialized * data region associated with the symbol. */ uint32_t 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_t 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_t 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_t value; /* This is the size of the value returned by the function in * bytes (zero for procedures). */ uint32_t retsize; /* This is the number of parameters accepted by the function/ * procedure. */ uint32_t nparms; /* This is the beginning of a table of input parameter sizes * the actually allocate size will be nparms entries. */ uint32_t argsize[1]; }; typedef struct poffLibDebugFuncInfo_s poffLibDebugFuncInfo_t; #define SIZEOFDEBUFINFO(n) (sizeof(poffLibDebugFuncInfo_t) + ((n)-1)*sizeof(uint32_t)) /*************************************************************************** * 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, uint8_t fh_type, uint16_t nfiles, const char *name); extern void poffSetArchitecture(poffHandle_t handle, uint8_t fh_arch); extern void poffSetEntryPoint(poffHandle_t handle, uint32_t entryPoint); extern int32_t poffFindString(poffHandle_t handle, const char *string); extern uint32_t poffAddString(poffHandle_t handle, const char *string); extern uint32_t poffAddFileName(poffHandle_t handle, const char *name); extern void poffAddProgByte(poffHandle_t handle, uint8_t progByte); #if 0 /* not used */ extern uint32_t poffAddRoDataByte(poffHandle_t handle, uint8_t dataByte); #endif extern uint32_t poffAddRoDataString(poffHandle_t handle, const char *string); extern uint32_t poffAddSymbol(poffHandle_t handle, poffLibSymbol_t *symbol); extern uint32_t poffAddLineNumber(poffHandle_t handle, uint16_t lineNumber, uint16_t fileNumber, uint32_t progSectionDataOffset); extern uint32_t poffAddDebugFuncInfo(poffHandle_t handle, poffLibDebugFuncInfo_t *pContainer); extern uint32_t poffAddRelocation(poffHandle_t handle, uint8_t relocType, uint32_t symIndex, uint32_t sectionDataOffset); extern void poffWriteFile(poffHandle_t handle, FILE *poffFile); /* Functions to manage reading a POFF file */ extern uint16_t poffReadFile(poffHandle_t handle, FILE *poffFile); extern uint8_t poffGetFileType(poffHandle_t handle); extern uint8_t poffGetArchitecture(poffHandle_t handle); extern uint32_t poffGetEntryPoint(poffHandle_t handle); extern const char *poffGetFileHdrName(poffHandle_t handle); extern uint32_t poffGetRoDataSize(poffHandle_t handle); extern int32_t poffGetFileName(poffHandle_t handle, const char **fname); extern int poffGetProgByte(poffHandle_t handle); extern int32_t poffGetSymbol(poffHandle_t handle, poffLibSymbol_t *symbol); extern const char *poffGetString(poffHandle_t handle, uint32_t index); extern int32_t poffGetLineNumber(poffHandle_t handle, poffLibLineNumber_t *lineno); extern int32_t poffGetRawLineNumber(poffHandle_t handle, poffLineNumber_t *lineno); extern int32_t poffGetRawRelocation(poffHandle_t handle, poffRelocation_t *reloc); extern poffLibDebugFuncInfo_t *poffGetDebugFuncInfo(poffHandle_t handle); extern poffLibDebugFuncInfo_t *poffCreateDebugInfoContainer(uint32_t nparms); extern void poffReleaseDebugFuncContainer(poffLibDebugFuncInfo_t *pDebugFuncInfo); extern void poffDiscardDebugFuncInfo(poffHandle_t handle); extern int32_t poffProgTell(poffHandle_t handle); extern int poffProgSeek(poffHandle_t handle, uint32_t offset); extern uint32_t 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_t poffAddTmpProgByte(poffProgHandle_t handle, uint8_t progByte); extern uint16_t poffWriteTmpProgBytes(uint8_t *buffer, uint32_t 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_t 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_t poffExtractProgramData(poffHandle_t handle, uint8_t **progData); extern void poffInsertProgramData(poffHandle_t handle, uint8_t *progData, uint32_t progSize); extern uint32_t poffExtractRoData(poffHandle_t handle, uint8_t **roData); extern void poffAppendRoData(poffHandle_t handle, uint8_t *roData, uint32_t 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_t label, uint32_t pc); extern void poffAddToUndefinedLabelTable(uint32_t label, uint32_t symIndex); extern int poffGetSymIndexForUndefinedLabel(uint32_t label); extern int poffGetPcForDefinedLabel(uint32_t label); extern void poffReleaseLabelReferences(void); /* Helper functions for line numbers */ extern void poffReadLineNumberTable(poffHandle_t handle); extern poffLibLineNumber_t *poffFindLineNumber(uint32_t offset); extern void poffReleaseLineNumberTable(void); /* Helper functions for debug information */ extern void poffReadDebugFuncInfoTable(poffHandle_t handle); extern poffLibDebugFuncInfo_t *poffFindDebugFuncInfo(uint32_t offset); extern void poffReplaceDebugFuncInfo(poffHandle_t handle); extern void poffReleaseDebugFuncInfoTable(void); #endif /* __POFFLIB_H */