xref: /openbmc/qemu/include/hw/loader.h (revision 2b74dd91)
1 #ifndef LOADER_H
2 #define LOADER_H
3 #include "hw/nvram/fw_cfg.h"
4 
5 /* loader.c */
6 /**
7  * get_image_size: retrieve size of an image file
8  * @filename: Path to the image file
9  *
10  * Returns the size of the image file on success, -1 otherwise.
11  * On error, errno is also set as appropriate.
12  */
13 int64_t get_image_size(const char *filename);
14 /**
15  * load_image_size: load an image file into specified buffer
16  * @filename: Path to the image file
17  * @addr: Buffer to load image into
18  * @size: Size of buffer in bytes
19  *
20  * Load an image file from disk into the specified buffer.
21  * If the image is larger than the specified buffer, only
22  * @size bytes are read (this is not considered an error).
23  *
24  * Prefer to use the GLib function g_file_get_contents() rather
25  * than a "get_image_size()/g_malloc()/load_image_size()" sequence.
26  *
27  * Returns the number of bytes read, or -1 on error. On error,
28  * errno is also set as appropriate.
29  */
30 ssize_t load_image_size(const char *filename, void *addr, size_t size);
31 
32 /**load_image_targphys_as:
33  * @filename: Path to the image file
34  * @addr: Address to load the image to
35  * @max_sz: The maximum size of the image to load
36  * @as: The AddressSpace to load the ELF to. The value of address_space_memory
37  *      is used if nothing is supplied here.
38  *
39  * Load a fixed image into memory.
40  *
41  * Returns the size of the loaded image on success, -1 otherwise.
42  */
43 ssize_t load_image_targphys_as(const char *filename,
44                                hwaddr addr, uint64_t max_sz, AddressSpace *as);
45 
46 /**load_targphys_hex_as:
47  * @filename: Path to the .hex file
48  * @entry: Store the entry point given by the .hex file
49  * @as: The AddressSpace to load the .hex file to. The value of
50  *      address_space_memory is used if nothing is supplied here.
51  *
52  * Load a fixed .hex file into memory.
53  *
54  * Returns the size of the loaded .hex file on success, -1 otherwise.
55  */
56 ssize_t load_targphys_hex_as(const char *filename, hwaddr *entry,
57                              AddressSpace *as);
58 
59 /** load_image_targphys:
60  * Same as load_image_targphys_as(), but doesn't allow the caller to specify
61  * an AddressSpace.
62  */
63 ssize_t load_image_targphys(const char *filename, hwaddr,
64                             uint64_t max_sz);
65 
66 /**
67  * load_image_mr: load an image into a memory region
68  * @filename: Path to the image file
69  * @mr: Memory Region to load into
70  *
71  * Load the specified file into the memory region.
72  * The file loaded is registered as a ROM, so its contents will be
73  * reinstated whenever the system is reset.
74  * If the file is larger than the memory region's size the call will fail.
75  * Returns -1 on failure, or the size of the file.
76  */
77 ssize_t load_image_mr(const char *filename, MemoryRegion *mr);
78 
79 /* This is the limit on the maximum uncompressed image size that
80  * load_image_gzipped_buffer() will read. It prevents
81  * g_malloc() in those functions from allocating a huge amount of memory.
82  */
83 #define LOAD_IMAGE_MAX_GUNZIP_BYTES (256 << 20)
84 
85 ssize_t load_image_gzipped_buffer(const char *filename, uint64_t max_sz,
86                                   uint8_t **buffer);
87 /**
88  * unpack_efi_zboot_image:
89  * @buffer: pointer to a variable holding the address of a buffer containing the
90  *          image
91  * @size: pointer to a variable holding the size of the buffer
92  *
93  * Check whether the buffer contains a EFI zboot image, and if it does, extract
94  * the compressed payload and decompress it into a new buffer. If successful,
95  * the old buffer is freed, and the *buffer and size variables pointed to by the
96  * function arguments are updated to refer to the newly populated buffer.
97  *
98  * Returns 0 if the image could not be identified as a EFI zboot image.
99  * Returns -1 if the buffer contents were identified as a EFI zboot image, but
100  * unpacking failed for any reason.
101  * Returns the size of the decompressed payload if decompression was performed
102  * successfully.
103  */
104 ssize_t unpack_efi_zboot_image(uint8_t **buffer, int *size);
105 
106 #define ELF_LOAD_FAILED       -1
107 #define ELF_LOAD_NOT_ELF      -2
108 #define ELF_LOAD_WRONG_ARCH   -3
109 #define ELF_LOAD_WRONG_ENDIAN -4
110 #define ELF_LOAD_TOO_BIG      -5
111 const char *load_elf_strerror(ssize_t error);
112 
113 /** load_elf_ram_sym:
114  * @filename: Path of ELF file
115  * @elf_note_fn: optional function to parse ELF Note type
116  *               passed via @translate_opaque
117  * @translate_fn: optional function to translate load addresses
118  * @translate_opaque: opaque data passed to @translate_fn
119  * @pentry: Populated with program entry point. Ignored if NULL.
120  * @lowaddr: Populated with lowest loaded address. Ignored if NULL.
121  * @highaddr: Populated with highest loaded address. Ignored if NULL.
122  * @pflags: Populated with ELF processor-specific flags. Ignore if NULL.
123  * @bigendian: Expected ELF endianness. 0 for LE otherwise BE
124  * @elf_machine: Expected ELF machine type
125  * @clear_lsb: Set to mask off LSB of addresses (Some architectures use
126  *             this for non-address data)
127  * @data_swab: Set to order of byte swapping for data. 0 for no swap, 1
128  *             for swapping bytes within halfwords, 2 for bytes within
129  *             words and 3 for within doublewords.
130  * @as: The AddressSpace to load the ELF to. The value of address_space_memory
131  *      is used if nothing is supplied here.
132  * @load_rom : Load ELF binary as ROM
133  * @sym_cb: Callback function for symbol table entries
134  *
135  * Load an ELF file's contents to the emulated system's address space.
136  * Clients may optionally specify a callback to perform address
137  * translations. @pentry, @lowaddr and @highaddr are optional pointers
138  * which will be populated with various load information. @bigendian and
139  * @elf_machine give the expected endianness and machine for the ELF the
140  * load will fail if the target ELF does not match. Some architectures
141  * have some architecture-specific behaviours that come into effect when
142  * their particular values for @elf_machine are set.
143  * If @elf_machine is EM_NONE then the machine type will be read from the
144  * ELF header and no checks will be carried out against the machine type.
145  */
146 typedef void (*symbol_fn_t)(const char *st_name, int st_info,
147                             uint64_t st_value, uint64_t st_size);
148 
149 ssize_t load_elf_ram_sym(const char *filename,
150                          uint64_t (*elf_note_fn)(void *, void *, bool),
151                          uint64_t (*translate_fn)(void *, uint64_t),
152                          void *translate_opaque, uint64_t *pentry,
153                          uint64_t *lowaddr, uint64_t *highaddr,
154                          uint32_t *pflags, int big_endian, int elf_machine,
155                          int clear_lsb, int data_swab,
156                          AddressSpace *as, bool load_rom, symbol_fn_t sym_cb);
157 
158 /** load_elf_ram:
159  * Same as load_elf_ram_sym(), but doesn't allow the caller to specify a
160  * symbol callback function
161  */
162 ssize_t load_elf_ram(const char *filename,
163                      uint64_t (*elf_note_fn)(void *, void *, bool),
164                      uint64_t (*translate_fn)(void *, uint64_t),
165                      void *translate_opaque, uint64_t *pentry,
166                      uint64_t *lowaddr, uint64_t *highaddr, uint32_t *pflags,
167                      int big_endian, int elf_machine, int clear_lsb,
168                      int data_swab, AddressSpace *as, bool load_rom);
169 
170 /** load_elf_as:
171  * Same as load_elf_ram(), but always loads the elf as ROM
172  */
173 ssize_t load_elf_as(const char *filename,
174                     uint64_t (*elf_note_fn)(void *, void *, bool),
175                     uint64_t (*translate_fn)(void *, uint64_t),
176                     void *translate_opaque, uint64_t *pentry, uint64_t *lowaddr,
177                     uint64_t *highaddr, uint32_t *pflags, int big_endian,
178                     int elf_machine, int clear_lsb, int data_swab,
179                     AddressSpace *as);
180 
181 /** load_elf:
182  * Same as load_elf_as(), but doesn't allow the caller to specify an
183  * AddressSpace.
184  */
185 ssize_t load_elf(const char *filename,
186                  uint64_t (*elf_note_fn)(void *, void *, bool),
187                  uint64_t (*translate_fn)(void *, uint64_t),
188                  void *translate_opaque, uint64_t *pentry, uint64_t *lowaddr,
189                  uint64_t *highaddr, uint32_t *pflags, int big_endian,
190                  int elf_machine, int clear_lsb, int data_swab);
191 
192 /** load_elf_hdr:
193  * @filename: Path of ELF file
194  * @hdr: Buffer to populate with header data. Header data will not be
195  * filled if set to NULL.
196  * @is64: Set to true if the ELF is 64bit. Ignored if set to NULL
197  * @errp: Populated with an error in failure cases
198  *
199  * Inspect an ELF file's header. Read its full header contents into a
200  * buffer and/or determine if the ELF is 64bit.
201  */
202 void load_elf_hdr(const char *filename, void *hdr, bool *is64, Error **errp);
203 
204 ssize_t load_aout(const char *filename, hwaddr addr, int max_sz,
205                   int bswap_needed, hwaddr target_page_size);
206 
207 #define LOAD_UIMAGE_LOADADDR_INVALID (-1)
208 
209 /** load_uimage_as:
210  * @filename: Path of uimage file
211  * @ep: Populated with program entry point. Ignored if NULL.
212  * @loadaddr: load address if none specified in the image or when loading a
213  *            ramdisk. Populated with the load address. Ignored if NULL or
214  *            LOAD_UIMAGE_LOADADDR_INVALID (images which do not specify a load
215  *            address will not be loadable).
216  * @is_linux: Is set to true if the image loaded is Linux. Ignored if NULL.
217  * @translate_fn: optional function to translate load addresses
218  * @translate_opaque: opaque data passed to @translate_fn
219  * @as: The AddressSpace to load the ELF to. The value of address_space_memory
220  *      is used if nothing is supplied here.
221  *
222  * Loads a u-boot image into memory.
223  *
224  * Returns the size of the loaded image on success, -1 otherwise.
225  */
226 ssize_t load_uimage_as(const char *filename, hwaddr *ep,
227                        hwaddr *loadaddr, int *is_linux,
228                        uint64_t (*translate_fn)(void *, uint64_t),
229                        void *translate_opaque, AddressSpace *as);
230 
231 /** load_uimage:
232  * Same as load_uimage_as(), but doesn't allow the caller to specify an
233  * AddressSpace.
234  */
235 ssize_t load_uimage(const char *filename, hwaddr *ep,
236                     hwaddr *loadaddr, int *is_linux,
237                     uint64_t (*translate_fn)(void *, uint64_t),
238                     void *translate_opaque);
239 
240 /**
241  * load_ramdisk_as:
242  * @filename: Path to the ramdisk image
243  * @addr: Memory address to load the ramdisk to
244  * @max_sz: Maximum allowed ramdisk size (for non-u-boot ramdisks)
245  * @as: The AddressSpace to load the ELF to. The value of address_space_memory
246  *      is used if nothing is supplied here.
247  *
248  * Load a ramdisk image with U-Boot header to the specified memory
249  * address.
250  *
251  * Returns the size of the loaded image on success, -1 otherwise.
252  */
253 ssize_t load_ramdisk_as(const char *filename, hwaddr addr, uint64_t max_sz,
254                         AddressSpace *as);
255 
256 /**
257  * load_ramdisk:
258  * Same as load_ramdisk_as(), but doesn't allow the caller to specify
259  * an AddressSpace.
260  */
261 ssize_t load_ramdisk(const char *filename, hwaddr addr, uint64_t max_sz);
262 
263 ssize_t gunzip(void *dst, size_t dstlen, uint8_t *src, size_t srclen);
264 
265 ssize_t read_targphys(const char *name,
266                       int fd, hwaddr dst_addr, size_t nbytes);
267 void pstrcpy_targphys(const char *name,
268                       hwaddr dest, int buf_size,
269                       const char *source);
270 
271 ssize_t rom_add_file(const char *file, const char *fw_dir,
272                      hwaddr addr, int32_t bootindex,
273                      bool has_option_rom, MemoryRegion *mr, AddressSpace *as);
274 MemoryRegion *rom_add_blob(const char *name, const void *blob, size_t len,
275                            size_t max_len, hwaddr addr,
276                            const char *fw_file_name,
277                            FWCfgCallback fw_callback,
278                            void *callback_opaque, AddressSpace *as,
279                            bool read_only);
280 int rom_add_elf_program(const char *name, GMappedFile *mapped_file, void *data,
281                         size_t datasize, size_t romsize, hwaddr addr,
282                         AddressSpace *as);
283 int rom_check_and_register_reset(void);
284 void rom_set_fw(FWCfgState *f);
285 void rom_set_order_override(int order);
286 void rom_reset_order_override(void);
287 
288 /**
289  * rom_transaction_begin:
290  *
291  * Call this before of a series of rom_add_*() calls.  Call
292  * rom_transaction_end() afterwards to commit or abort.  These functions are
293  * useful for undoing a series of rom_add_*() calls if image file loading fails
294  * partway through.
295  */
296 void rom_transaction_begin(void);
297 
298 /**
299  * rom_transaction_end:
300  * @commit: true to commit added roms, false to drop added roms
301  *
302  * Call this after a series of rom_add_*() calls.  See rom_transaction_begin().
303  */
304 void rom_transaction_end(bool commit);
305 
306 int rom_copy(uint8_t *dest, hwaddr addr, size_t size);
307 void *rom_ptr(hwaddr addr, size_t size);
308 /**
309  * rom_ptr_for_as: Return a pointer to ROM blob data for the address
310  * @as: AddressSpace to look for the ROM blob in
311  * @addr: Address within @as
312  * @size: size of data required in bytes
313  *
314  * Returns: pointer into the data which backs the matching ROM blob,
315  * or NULL if no blob covers the address range.
316  *
317  * This function looks for a ROM blob which covers the specified range
318  * of bytes of length @size starting at @addr within the address space
319  * @as. This is useful for code which runs as part of board
320  * initialization or CPU reset which wants to read data that is part
321  * of a user-supplied guest image or other guest memory contents, but
322  * which runs before the ROM loader's reset function has copied the
323  * blobs into guest memory.
324  *
325  * rom_ptr_for_as() will look not just for blobs loaded directly to
326  * the specified address, but also for blobs which were loaded to an
327  * alias of the region at a different location in the AddressSpace.
328  * In other words, if a machine model has RAM at address 0x0000_0000
329  * which is aliased to also appear at 0x1000_0000, rom_ptr_for_as()
330  * will return the correct data whether the guest image was linked and
331  * loaded at 0x0000_0000 or 0x1000_0000.  Contrast rom_ptr(), which
332  * will only return data if the image load address is an exact match
333  * with the queried address.
334  *
335  * New code should prefer to use rom_ptr_for_as() instead of
336  * rom_ptr().
337  */
338 void *rom_ptr_for_as(AddressSpace *as, hwaddr addr, size_t size);
339 
340 #define rom_add_file_fixed(_f, _a, _i)          \
341     rom_add_file(_f, NULL, _a, _i, false, NULL, NULL)
342 #define rom_add_blob_fixed(_f, _b, _l, _a)      \
343     rom_add_blob(_f, _b, _l, _l, _a, NULL, NULL, NULL, NULL, true)
344 #define rom_add_file_mr(_f, _mr, _i)            \
345     rom_add_file(_f, NULL, 0, _i, false, _mr, NULL)
346 #define rom_add_file_as(_f, _as, _i)            \
347     rom_add_file(_f, NULL, 0, _i, false, NULL, _as)
348 #define rom_add_file_fixed_as(_f, _a, _i, _as)          \
349     rom_add_file(_f, NULL, _a, _i, false, NULL, _as)
350 #define rom_add_blob_fixed_as(_f, _b, _l, _a, _as)      \
351     rom_add_blob(_f, _b, _l, _l, _a, NULL, NULL, NULL, _as, true)
352 
353 ssize_t rom_add_vga(const char *file);
354 ssize_t rom_add_option(const char *file, int32_t bootindex);
355 
356 /* This is the usual maximum in uboot, so if a uImage overflows this, it would
357  * overflow on real hardware too. */
358 #define UBOOT_MAX_GUNZIP_BYTES (64 << 20)
359 
360 typedef struct RomGap {
361     hwaddr base;
362     size_t size;
363 } RomGap;
364 
365 /**
366  * rom_find_largest_gap_between: return largest gap between ROMs in given range
367  *
368  * Given a range of addresses, this function finds the largest
369  * contiguous subrange which has no ROMs loaded to it. That is,
370  * it finds the biggest gap which is free for use for other things.
371  */
372 RomGap rom_find_largest_gap_between(hwaddr base, size_t size);
373 
374 #endif
375