1 /* SPDX-License-Identifier: 0BSD */ 2 3 /** 4 * \file lzma/bcj.h 5 * \brief Branch/Call/Jump conversion filters 6 * \note Never include this file directly. Use <lzma.h> instead. 7 */ 8 9 /* 10 * Author: Lasse Collin 11 */ 12 13 #ifndef LZMA_H_INTERNAL 14 # error Never include this file directly. Use <lzma.h> instead. 15 #endif 16 17 18 /* Filter IDs for lzma_filter.id */ 19 20 /** 21 * \brief Filter for x86 binaries 22 */ 23 #define LZMA_FILTER_X86 LZMA_VLI_C(0x04) 24 25 /** 26 * \brief Filter for Big endian PowerPC binaries 27 */ 28 #define LZMA_FILTER_POWERPC LZMA_VLI_C(0x05) 29 30 /** 31 * \brief Filter for IA-64 (Itanium) binaries 32 */ 33 #define LZMA_FILTER_IA64 LZMA_VLI_C(0x06) 34 35 /** 36 * \brief Filter for ARM binaries 37 */ 38 #define LZMA_FILTER_ARM LZMA_VLI_C(0x07) 39 40 /** 41 * \brief Filter for ARM-Thumb binaries 42 */ 43 #define LZMA_FILTER_ARMTHUMB LZMA_VLI_C(0x08) 44 45 /** 46 * \brief Filter for SPARC binaries 47 */ 48 #define LZMA_FILTER_SPARC LZMA_VLI_C(0x09) 49 50 /** 51 * \brief Filter for ARM64 binaries 52 */ 53 #define LZMA_FILTER_ARM64 LZMA_VLI_C(0x0A) 54 55 /** 56 * \brief Filter for RISC-V binaries 57 */ 58 #define LZMA_FILTER_RISCV LZMA_VLI_C(0x0B) 59 60 61 /** 62 * \brief Options for BCJ filters 63 * 64 * The BCJ filters never change the size of the data. Specifying options 65 * for them is optional: if pointer to options is NULL, default value is 66 * used. You probably never need to specify options to BCJ filters, so just 67 * set the options pointer to NULL and be happy. 68 * 69 * If options with non-default values have been specified when encoding, 70 * the same options must also be specified when decoding. 71 * 72 * \note At the moment, none of the BCJ filters support 73 * LZMA_SYNC_FLUSH. If LZMA_SYNC_FLUSH is specified, 74 * LZMA_OPTIONS_ERROR will be returned. If there is need, 75 * partial support for LZMA_SYNC_FLUSH can be added in future. 76 * Partial means that flushing would be possible only at 77 * offsets that are multiple of 2, 4, or 16 depending on 78 * the filter, except x86 which cannot be made to support 79 * LZMA_SYNC_FLUSH predictably. 80 */ 81 typedef struct { 82 /** 83 * \brief Start offset for conversions 84 * 85 * This setting is useful only when the same filter is used 86 * _separately_ for multiple sections of the same executable file, 87 * and the sections contain cross-section branch/call/jump 88 * instructions. In that case it is beneficial to set the start 89 * offset of the non-first sections so that the relative addresses 90 * of the cross-section branch/call/jump instructions will use the 91 * same absolute addresses as in the first section. 92 * 93 * When the pointer to options is NULL, the default value (zero) 94 * is used. 95 */ 96 uint32_t start_offset; 97 98 } lzma_options_bcj; 99 100 101 /** 102 * \brief Raw ARM64 BCJ encoder 103 * 104 * This is for special use cases only. 105 * 106 * \param start_offset The lowest 32 bits of the offset in the 107 * executable being filtered. For the ARM64 108 * filter, this must be a multiple of four. 109 * For the very best results, this should also 110 * be in sync with 4096-byte page boundaries 111 * in the executable due to how ARM64's ADRP 112 * instruction works. 113 * \param buf Buffer to be filtered in place 114 * \param size Size of the buffer 115 * 116 * \return Number of bytes that were processed in `buf`. This is at most 117 * `size`. With the ARM64 filter, the return value is always 118 * a multiple of 4, and at most 3 bytes are left unfiltered. 119 * 120 * \since 5.7.1alpha 121 */ 122 extern LZMA_API(size_t) lzma_bcj_arm64_encode( 123 uint32_t start_offset, uint8_t *buf, size_t size) lzma_nothrow; 124 125 /** 126 * \brief Raw ARM64 BCJ decoder 127 * 128 * See lzma_bcj_arm64_encode(). 129 * 130 * \since 5.7.1alpha 131 */ 132 extern LZMA_API(size_t) lzma_bcj_arm64_decode( 133 uint32_t start_offset, uint8_t *buf, size_t size) lzma_nothrow; 134 135 136 /** 137 * \brief Raw RISC-V BCJ encoder 138 * 139 * This is for special use cases only. 140 * 141 * \param start_offset The lowest 32 bits of the offset in the 142 * executable being filtered. For the RISC-V 143 * filter, this must be a multiple of 2. 144 * \param buf Buffer to be filtered in place 145 * \param size Size of the buffer 146 * 147 * \return Number of bytes that were processed in `buf`. This is at most 148 * `size`. With the RISC-V filter, the return value is always 149 * a multiple of 2, and at most 7 bytes are left unfiltered. 150 * 151 * \since 5.7.1alpha 152 */ 153 extern LZMA_API(size_t) lzma_bcj_riscv_encode( 154 uint32_t start_offset, uint8_t *buf, size_t size) lzma_nothrow; 155 156 /** 157 * \brief Raw RISC-V BCJ decoder 158 * 159 * See lzma_bcj_riscv_encode(). 160 * 161 * \since 5.7.1alpha 162 */ 163 extern LZMA_API(size_t) lzma_bcj_riscv_decode( 164 uint32_t start_offset, uint8_t *buf, size_t size) lzma_nothrow; 165 166 167 /** 168 * \brief Raw x86 BCJ encoder 169 * 170 * This is for special use cases only. 171 * 172 * \param start_offset The lowest 32 bits of the offset in the 173 * executable being filtered. For the x86 174 * filter, all values are valid. 175 * \param buf Buffer to be filtered in place 176 * \param size Size of the buffer 177 * 178 * \return Number of bytes that were processed in `buf`. This is at most 179 * `size`. For the x86 filter, the return value is always 180 * a multiple of 1, and at most 4 bytes are left unfiltered. 181 * 182 * \since 5.7.1alpha 183 */ 184 extern LZMA_API(size_t) lzma_bcj_x86_encode( 185 uint32_t start_offset, uint8_t *buf, size_t size) lzma_nothrow; 186 187 /** 188 * \brief Raw x86 BCJ decoder 189 * 190 * See lzma_bcj_x86_encode(). 191 * 192 * \since 5.7.1alpha 193 */ 194 extern LZMA_API(size_t) lzma_bcj_x86_decode( 195 uint32_t start_offset, uint8_t *buf, size_t size) lzma_nothrow; 196