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 */
81typedef 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 */
122extern 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 */
132extern 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 */
153extern 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 */
163extern 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 */
184extern 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 */
194extern LZMA_API(size_t) lzma_bcj_x86_decode(
195 uint32_t start_offset, uint8_t *buf, size_t size) lzma_nothrow;
196