Andrew Scull | 5e1ddfa | 2018-08-14 10:06:54 +0100 | [diff] [blame] | 1 | /*===-- llvm-c/Object.h - Object Lib C Iface --------------------*- C++ -*-===*/ |
| 2 | /* */ |
Andrew Walbran | 16937d0 | 2019-10-22 13:54:20 +0100 | [diff] [blame] | 3 | /* Part of the LLVM Project, under the Apache License v2.0 with LLVM */ |
| 4 | /* Exceptions. */ |
| 5 | /* See https://llvm.org/LICENSE.txt for license information. */ |
| 6 | /* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception */ |
Andrew Scull | 5e1ddfa | 2018-08-14 10:06:54 +0100 | [diff] [blame] | 7 | /* */ |
| 8 | /*===----------------------------------------------------------------------===*/ |
| 9 | /* */ |
| 10 | /* This header declares the C interface to libLLVMObject.a, which */ |
| 11 | /* implements object file reading and writing. */ |
| 12 | /* */ |
| 13 | /* Many exotic languages can interoperate with C code but have a harder time */ |
| 14 | /* with C++ due to name mangling. So in addition to C, this interface enables */ |
| 15 | /* tools written in such languages. */ |
| 16 | /* */ |
| 17 | /*===----------------------------------------------------------------------===*/ |
| 18 | |
| 19 | #ifndef LLVM_C_OBJECT_H |
| 20 | #define LLVM_C_OBJECT_H |
| 21 | |
| 22 | #include "llvm-c/Types.h" |
| 23 | #include "llvm/Config/llvm-config.h" |
| 24 | |
| 25 | #ifdef __cplusplus |
| 26 | extern "C" { |
| 27 | #endif |
| 28 | |
| 29 | /** |
| 30 | * @defgroup LLVMCObject Object file reading and writing |
| 31 | * @ingroup LLVMC |
| 32 | * |
| 33 | * @{ |
| 34 | */ |
| 35 | |
| 36 | // Opaque type wrappers |
Andrew Scull | 5e1ddfa | 2018-08-14 10:06:54 +0100 | [diff] [blame] | 37 | typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef; |
| 38 | typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef; |
| 39 | typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef; |
| 40 | |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame^] | 41 | typedef enum { |
| 42 | LLVMBinaryTypeArchive, /**< Archive file. */ |
| 43 | LLVMBinaryTypeMachOUniversalBinary, /**< Mach-O Universal Binary file. */ |
| 44 | LLVMBinaryTypeCOFFImportFile, /**< COFF Import file. */ |
| 45 | LLVMBinaryTypeIR, /**< LLVM IR. */ |
| 46 | LLVMBinaryTypeWinRes, /**< Windows resource (.res) file. */ |
| 47 | LLVMBinaryTypeCOFF, /**< COFF Object file. */ |
| 48 | LLVMBinaryTypeELF32L, /**< ELF 32-bit, little endian. */ |
| 49 | LLVMBinaryTypeELF32B, /**< ELF 32-bit, big endian. */ |
| 50 | LLVMBinaryTypeELF64L, /**< ELF 64-bit, little endian. */ |
| 51 | LLVMBinaryTypeELF64B, /**< ELF 64-bit, big endian. */ |
| 52 | LLVMBinaryTypeMachO32L, /**< MachO 32-bit, little endian. */ |
| 53 | LLVMBinaryTypeMachO32B, /**< MachO 32-bit, big endian. */ |
| 54 | LLVMBinaryTypeMachO64L, /**< MachO 64-bit, little endian. */ |
| 55 | LLVMBinaryTypeMachO64B, /**< MachO 64-bit, big endian. */ |
| 56 | LLVMBinaryTypeWasm, /**< Web Assembly. */ |
| 57 | } LLVMBinaryType; |
Andrew Scull | 5e1ddfa | 2018-08-14 10:06:54 +0100 | [diff] [blame] | 58 | |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame^] | 59 | /** |
| 60 | * Create a binary file from the given memory buffer. |
| 61 | * |
| 62 | * The exact type of the binary file will be inferred automatically, and the |
| 63 | * appropriate implementation selected. The context may be NULL except if |
| 64 | * the resulting file is an LLVM IR file. |
| 65 | * |
| 66 | * The memory buffer is not consumed by this function. It is the responsibilty |
| 67 | * of the caller to free it with \c LLVMDisposeMemoryBuffer. |
| 68 | * |
| 69 | * If NULL is returned, the \p ErrorMessage parameter is populated with the |
| 70 | * error's description. It is then the caller's responsibility to free this |
| 71 | * message by calling \c LLVMDisposeMessage. |
| 72 | * |
| 73 | * @see llvm::object::createBinary |
| 74 | */ |
| 75 | LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf, |
| 76 | LLVMContextRef Context, |
| 77 | char **ErrorMessage); |
| 78 | |
| 79 | /** |
| 80 | * Dispose of a binary file. |
| 81 | * |
| 82 | * The binary file does not own its backing buffer. It is the responsibilty |
| 83 | * of the caller to free it with \c LLVMDisposeMemoryBuffer. |
| 84 | */ |
| 85 | void LLVMDisposeBinary(LLVMBinaryRef BR); |
| 86 | |
| 87 | /** |
| 88 | * Retrieves a copy of the memory buffer associated with this object file. |
| 89 | * |
| 90 | * The returned buffer is merely a shallow copy and does not own the actual |
| 91 | * backing buffer of the binary. Nevertheless, it is the responsibility of the |
| 92 | * caller to free it with \c LLVMDisposeMemoryBuffer. |
| 93 | * |
| 94 | * @see llvm::object::getMemoryBufferRef |
| 95 | */ |
| 96 | LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR); |
| 97 | |
| 98 | /** |
| 99 | * Retrieve the specific type of a binary. |
| 100 | * |
| 101 | * @see llvm::object::Binary::getType |
| 102 | */ |
| 103 | LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR); |
| 104 | |
| 105 | /* |
| 106 | * For a Mach-O universal binary file, retrieves the object file corresponding |
| 107 | * to the given architecture if it is present as a slice. |
| 108 | * |
| 109 | * If NULL is returned, the \p ErrorMessage parameter is populated with the |
| 110 | * error's description. It is then the caller's responsibility to free this |
| 111 | * message by calling \c LLVMDisposeMessage. |
| 112 | * |
| 113 | * It is the responsiblity of the caller to free the returned object file by |
| 114 | * calling \c LLVMDisposeBinary. |
| 115 | */ |
| 116 | LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(LLVMBinaryRef BR, |
| 117 | const char *Arch, |
| 118 | size_t ArchLen, |
| 119 | char **ErrorMessage); |
| 120 | |
| 121 | /** |
| 122 | * Retrieve a copy of the section iterator for this object file. |
| 123 | * |
| 124 | * If there are no sections, the result is NULL. |
| 125 | * |
| 126 | * The returned iterator is merely a shallow copy. Nevertheless, it is |
| 127 | * the responsibility of the caller to free it with |
| 128 | * \c LLVMDisposeSectionIterator. |
| 129 | * |
| 130 | * @see llvm::object::sections() |
| 131 | */ |
| 132 | LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR); |
| 133 | |
| 134 | /** |
| 135 | * Returns whether the given section iterator is at the end. |
| 136 | * |
| 137 | * @see llvm::object::section_end |
| 138 | */ |
| 139 | LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR, |
| 140 | LLVMSectionIteratorRef SI); |
| 141 | |
| 142 | /** |
| 143 | * Retrieve a copy of the symbol iterator for this object file. |
| 144 | * |
| 145 | * If there are no symbols, the result is NULL. |
| 146 | * |
| 147 | * The returned iterator is merely a shallow copy. Nevertheless, it is |
| 148 | * the responsibility of the caller to free it with |
| 149 | * \c LLVMDisposeSymbolIterator. |
| 150 | * |
| 151 | * @see llvm::object::symbols() |
| 152 | */ |
| 153 | LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR); |
| 154 | |
| 155 | /** |
| 156 | * Returns whether the given symbol iterator is at the end. |
| 157 | * |
| 158 | * @see llvm::object::symbol_end |
| 159 | */ |
| 160 | LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR, |
| 161 | LLVMSymbolIteratorRef SI); |
| 162 | |
Andrew Scull | 5e1ddfa | 2018-08-14 10:06:54 +0100 | [diff] [blame] | 163 | void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI); |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame^] | 164 | |
Andrew Scull | 5e1ddfa | 2018-08-14 10:06:54 +0100 | [diff] [blame] | 165 | void LLVMMoveToNextSection(LLVMSectionIteratorRef SI); |
| 166 | void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect, |
| 167 | LLVMSymbolIteratorRef Sym); |
| 168 | |
| 169 | // ObjectFile Symbol iterators |
Andrew Scull | 5e1ddfa | 2018-08-14 10:06:54 +0100 | [diff] [blame] | 170 | void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI); |
Andrew Scull | 5e1ddfa | 2018-08-14 10:06:54 +0100 | [diff] [blame] | 171 | void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI); |
| 172 | |
| 173 | // SectionRef accessors |
| 174 | const char *LLVMGetSectionName(LLVMSectionIteratorRef SI); |
| 175 | uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI); |
| 176 | const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI); |
| 177 | uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI); |
| 178 | LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI, |
| 179 | LLVMSymbolIteratorRef Sym); |
| 180 | |
| 181 | // Section Relocation iterators |
| 182 | LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section); |
| 183 | void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI); |
| 184 | LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section, |
| 185 | LLVMRelocationIteratorRef RI); |
| 186 | void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI); |
| 187 | |
| 188 | |
| 189 | // SymbolRef accessors |
| 190 | const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI); |
| 191 | uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI); |
| 192 | uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI); |
| 193 | |
| 194 | // RelocationRef accessors |
| 195 | uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI); |
| 196 | LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI); |
| 197 | uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI); |
| 198 | // NOTE: Caller takes ownership of returned string of the two |
| 199 | // following functions. |
| 200 | const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI); |
| 201 | const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI); |
| 202 | |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame^] | 203 | /** Deprecated: Use LLVMBinaryRef instead. */ |
| 204 | typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef; |
| 205 | |
| 206 | /** Deprecated: Use LLVMCreateBinary instead. */ |
| 207 | LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf); |
| 208 | |
| 209 | /** Deprecated: Use LLVMDisposeBinary instead. */ |
| 210 | void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile); |
| 211 | |
| 212 | /** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */ |
| 213 | LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile); |
| 214 | |
| 215 | /** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */ |
| 216 | LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile, |
| 217 | LLVMSectionIteratorRef SI); |
| 218 | |
| 219 | /** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */ |
| 220 | LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile); |
| 221 | |
| 222 | /** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */ |
| 223 | LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile, |
| 224 | LLVMSymbolIteratorRef SI); |
Andrew Scull | 5e1ddfa | 2018-08-14 10:06:54 +0100 | [diff] [blame] | 225 | /** |
| 226 | * @} |
| 227 | */ |
| 228 | |
| 229 | #ifdef __cplusplus |
| 230 | } |
| 231 | #endif /* defined(__cplusplus) */ |
| 232 | |
| 233 | #endif |