]>
Commit | Line | Data |
---|---|---|
83d290c5 | 1 | /* SPDX-License-Identifier: GPL-2.0+ */ |
7a9219c1 | 2 | /* |
d9165153 SG |
3 | * Operating System Interface |
4 | * | |
5 | * This provides access to useful OS routines for the sandbox architecture. | |
6 | * They are kept in a separate file so we can include system headers. | |
7 | * | |
7a9219c1 | 8 | * Copyright (c) 2011 The Chromium OS Authors. |
7a9219c1 SG |
9 | */ |
10 | ||
4f345d56 MF |
11 | #ifndef __OS_H__ |
12 | #define __OS_H__ | |
13 | ||
2a54d159 SG |
14 | #include <linux/types.h> |
15 | ||
94eefdee | 16 | struct rtc_time; |
70db4212 SG |
17 | struct sandbox_state; |
18 | ||
7750ee45 HS |
19 | /** |
20 | * os_printf() - print directly to OS console | |
21 | * | |
22 | * @format: format string | |
23 | */ | |
24 | int os_printf(const char *format, ...); | |
25 | ||
7a9219c1 SG |
26 | /** |
27 | * Access to the OS read() system call | |
28 | * | |
063790cb HS |
29 | * @fd: File descriptor as returned by os_open() |
30 | * @buf: Buffer to place data | |
31 | * @count: Number of bytes to read | |
32 | * Return: number of bytes read, or -1 on error | |
7a9219c1 SG |
33 | */ |
34 | ssize_t os_read(int fd, void *buf, size_t count); | |
35 | ||
36 | /** | |
37 | * Access to the OS write() system call | |
38 | * | |
063790cb HS |
39 | * @fd: File descriptor as returned by os_open() |
40 | * @buf: Buffer containing data to write | |
41 | * @count: Number of bytes to write | |
42 | * Return: number of bytes written, or -1 on error | |
7a9219c1 SG |
43 | */ |
44 | ssize_t os_write(int fd, const void *buf, size_t count); | |
45 | ||
e2dcefcb MF |
46 | /** |
47 | * Access to the OS lseek() system call | |
48 | * | |
063790cb HS |
49 | * @fd: File descriptor as returned by os_open() |
50 | * @offset: File offset (based on whence) | |
51 | * @whence: Position offset is relative to (see below) | |
52 | * Return: new file offset | |
e2dcefcb MF |
53 | */ |
54 | off_t os_lseek(int fd, off_t offset, int whence); | |
55 | ||
56 | /* Defines for "whence" in os_lseek() */ | |
57 | #define OS_SEEK_SET 0 | |
58 | #define OS_SEEK_CUR 1 | |
59 | #define OS_SEEK_END 2 | |
60 | ||
b4467fae SG |
61 | /** |
62 | * os_filesize() - Calculate the size of a file | |
63 | * | |
64 | * @fd: File descriptor as returned by os_open() | |
65 | * Return: file size or negative error code | |
66 | */ | |
1a07d395 | 67 | off_t os_filesize(int fd); |
b4467fae | 68 | |
7a9219c1 SG |
69 | /** |
70 | * Access to the OS open() system call | |
71 | * | |
063790cb HS |
72 | * @pathname: Pathname of file to open |
73 | * @flags: Flags, like OS_O_RDONLY, OS_O_RDWR | |
74 | * Return: file descriptor, or -1 on error | |
7a9219c1 SG |
75 | */ |
76 | int os_open(const char *pathname, int flags); | |
77 | ||
d9165153 SG |
78 | #define OS_O_RDONLY 0 |
79 | #define OS_O_WRONLY 1 | |
80 | #define OS_O_RDWR 2 | |
81 | #define OS_O_MASK 3 /* Mask for read/write flags */ | |
82 | #define OS_O_CREAT 0100 | |
50b288ac | 83 | #define OS_O_TRUNC 01000 |
d9165153 | 84 | |
7a9219c1 | 85 | /** |
063790cb | 86 | * os_close() - access to the OS close() system call |
7a9219c1 | 87 | * |
063790cb HS |
88 | * @fd: File descriptor to close |
89 | * Return: 0 on success, -1 on error | |
7a9219c1 SG |
90 | */ |
91 | int os_close(int fd); | |
92 | ||
cfd13e8d | 93 | /** |
063790cb | 94 | * os_unlink() - access to the OS unlink() system call |
cfd13e8d | 95 | * |
063790cb HS |
96 | * @pathname: Path of file to delete |
97 | * Return: 0 for success, other for error | |
cfd13e8d SW |
98 | */ |
99 | int os_unlink(const char *pathname); | |
100 | ||
e2d22f78 SG |
101 | /** os_persistent_fname() - Find the path to a test file |
102 | * | |
103 | * @buf: Buffer to hold path | |
104 | * @maxsize: Maximum size of buffer | |
105 | * @fname: Leaf filename to find | |
106 | * Returns: 0 on success, -ENOENT if file is not found, -ENOSPC if the buffer is | |
107 | * too small | |
108 | */ | |
109 | int os_persistent_file(char *buf, int maxsize, const char *fname); | |
110 | ||
7a9219c1 | 111 | /** |
063790cb | 112 | * os_exit() - access to the OS exit() system call |
7a9219c1 SG |
113 | * |
114 | * This exits with the supplied return code, which should be 0 to indicate | |
115 | * success. | |
116 | * | |
063790cb | 117 | * @exit_code: exit code for U-Boot |
7a9219c1 | 118 | */ |
9d72e67b | 119 | void os_exit(int exit_code) __attribute__((noreturn)); |
ab06a758 | 120 | |
10107efe RV |
121 | /** |
122 | * os_alarm() - access to the OS alarm() system call | |
6ca4d5b9 SG |
123 | * |
124 | * @seconds: number of seconds before the signal is sent | |
125 | * Returns: number of seconds remaining until any previously scheduled alarm was | |
126 | * due to be delivered; 0 if there was no previously scheduled alarm | |
10107efe RV |
127 | */ |
128 | unsigned int os_alarm(unsigned int seconds); | |
129 | ||
130 | /** | |
131 | * os_set_alarm_handler() - set handler for SIGALRM | |
132 | * | |
133 | * @handler: The handler function. Pass NULL for SIG_DFL. | |
134 | */ | |
135 | void os_set_alarm_handler(void (*handler)(int)); | |
136 | ||
137 | /** | |
138 | * os_raise_sigalrm() - do raise(SIGALRM) | |
139 | */ | |
140 | void os_raise_sigalrm(void); | |
141 | ||
ab06a758 | 142 | /** |
063790cb | 143 | * os_tty_raw() - put tty into raw mode to mimic serial console better |
ffb87905 | 144 | * |
063790cb HS |
145 | * @fd: File descriptor of stdin (normally 0) |
146 | * @allow_sigs: Allow Ctrl-C, Ctrl-Z to generate signals rather than | |
147 | * be handled by U-Boot | |
ab06a758 | 148 | */ |
ffb87905 | 149 | void os_tty_raw(int fd, bool allow_sigs); |
21899b10 | 150 | |
8939df09 | 151 | /** |
063790cb | 152 | * os_fs_restore() - restore the tty to its original mode |
8939df09 SG |
153 | * |
154 | * Call this to restore the original terminal mode, after it has been changed | |
155 | * by os_tty_raw(). This is an internal function. | |
156 | */ | |
157 | void os_fd_restore(void); | |
158 | ||
21899b10 | 159 | /** |
063790cb | 160 | * os_malloc() - aquires some memory from the underlying os. |
21899b10 | 161 | * |
063790cb | 162 | * @length: Number of bytes to be allocated |
14e46dfb | 163 | * Return: Pointer to length bytes or NULL if @length is 0 or on error |
21899b10 MW |
164 | */ |
165 | void *os_malloc(size_t length); | |
d99a6874 | 166 | |
77595c6d | 167 | /** |
063790cb | 168 | * os_free() - free memory previous allocated with os_malloc() |
77595c6d SG |
169 | * |
170 | * This returns the memory to the OS. | |
171 | * | |
b308d9fd SG |
172 | * @ptr: Pointer to memory block to free. If this is NULL then this |
173 | * function does nothing | |
77595c6d | 174 | */ |
347d06de | 175 | void os_free(void *ptr); |
77595c6d | 176 | |
14e46dfb SG |
177 | /** |
178 | * os_realloc() - reallocate memory | |
179 | * | |
180 | * This follows the semantics of realloc(), so can perform an os_malloc() or | |
181 | * os_free() depending on @ptr and @length. | |
182 | * | |
4c30d18e HS |
183 | * @ptr: pointer to previously allocated memory of NULL |
184 | * @length: number of bytes to allocate | |
185 | * Return: pointer to reallocated memory or NULL if @length is 0 | |
14e46dfb SG |
186 | */ |
187 | void *os_realloc(void *ptr, size_t length); | |
188 | ||
d99a6874 | 189 | /** |
063790cb | 190 | * os_usleep() - access to the usleep function of the os |
d99a6874 | 191 | * |
063790cb | 192 | * @usec: time to sleep in micro seconds |
d99a6874 MW |
193 | */ |
194 | void os_usleep(unsigned long usec); | |
195 | ||
196 | /** | |
197 | * Gets a monotonic increasing number of nano seconds from the OS | |
198 | * | |
063790cb | 199 | * Return: a monotonic increasing time scaled in nano seconds |
d99a6874 | 200 | */ |
2a54d159 | 201 | uint64_t os_get_nsec(void); |
4f345d56 | 202 | |
70db4212 SG |
203 | /** |
204 | * Parse arguments and update sandbox state. | |
205 | * | |
063790cb HS |
206 | * @state: sandbox state to update |
207 | * @argc: argument count | |
208 | * @argv: argument vector | |
209 | * Return: | |
210 | * * 0 if ok, and program should continue | |
211 | * * 1 if ok, but program should stop | |
212 | * * -1 on error: program should terminate | |
70db4212 SG |
213 | */ |
214 | int os_parse_args(struct sandbox_state *state, int argc, char *argv[]); | |
215 | ||
62584db1 | 216 | /* |
063790cb HS |
217 | * enum os_dirent_t - type of directory entry |
218 | * | |
62584db1 SG |
219 | * Types of directory entry that we support. See also os_dirent_typename in |
220 | * the C file. | |
221 | */ | |
222 | enum os_dirent_t { | |
063790cb HS |
223 | /** |
224 | * @OS_FILET_REG: regular file | |
225 | */ | |
226 | OS_FILET_REG, | |
227 | /** | |
228 | * @OS_FILET_LNK: symbolic link | |
229 | */ | |
230 | OS_FILET_LNK, | |
231 | /** | |
232 | * @OS_FILET_DIR: directory | |
233 | */ | |
234 | OS_FILET_DIR, | |
235 | /** | |
236 | * @OS_FILET_UNKNOWN: something else | |
237 | */ | |
238 | OS_FILET_UNKNOWN, | |
239 | /** | |
240 | * @OS_FILET_COUNT: number of directory entry types | |
241 | */ | |
62584db1 SG |
242 | OS_FILET_COUNT, |
243 | }; | |
244 | ||
063790cb HS |
245 | /** |
246 | * struct os_dirent_node - directory node | |
247 | * | |
248 | * A directory entry node, containing information about a single dirent | |
249 | * | |
250 | */ | |
62584db1 | 251 | struct os_dirent_node { |
063790cb HS |
252 | /** |
253 | * @next: pointer to next node, or NULL | |
254 | */ | |
255 | struct os_dirent_node *next; | |
256 | /** | |
257 | * @size: size of file in bytes | |
258 | */ | |
259 | ulong size; | |
260 | /** | |
261 | * @type: type of entry | |
262 | */ | |
263 | enum os_dirent_t type; | |
264 | /** | |
265 | * @name: name of entry | |
266 | */ | |
267 | char name[0]; | |
62584db1 SG |
268 | }; |
269 | ||
270 | /** | |
063790cb | 271 | * os_dirent_ls() - get a directory listing |
62584db1 SG |
272 | * |
273 | * This allocates and returns a linked list containing the directory listing. | |
274 | * | |
063790cb HS |
275 | * @dirname: directory to examine |
276 | * @headp: on return pointer to head of linked list, or NULL if none | |
277 | * Return: 0 if ok, -ve on error | |
62584db1 SG |
278 | */ |
279 | int os_dirent_ls(const char *dirname, struct os_dirent_node **headp); | |
280 | ||
86167089 | 281 | /** |
063790cb | 282 | * os_dirent_free() - free directory list |
86167089 SB |
283 | * |
284 | * This frees a linked list containing a directory listing. | |
285 | * | |
063790cb | 286 | * @node: pointer to head of linked list |
86167089 SB |
287 | */ |
288 | void os_dirent_free(struct os_dirent_node *node); | |
289 | ||
62584db1 | 290 | /** |
063790cb | 291 | * os_dirent_get_typename() - get the name of a directory entry type |
62584db1 | 292 | * |
063790cb HS |
293 | * @type: type to check |
294 | * Return: | |
295 | * string containing the name of that type, | |
296 | * or "???" if none/invalid | |
62584db1 SG |
297 | */ |
298 | const char *os_dirent_get_typename(enum os_dirent_t type); | |
299 | ||
300 | /** | |
063790cb | 301 | * os_get_filesize() - get the size of a file |
62584db1 | 302 | * |
063790cb HS |
303 | * @fname: filename to check |
304 | * @size: size of file is returned if no error | |
305 | * Return: 0 on success or -1 if an error ocurred | |
62584db1 | 306 | */ |
880dbc5f | 307 | int os_get_filesize(const char *fname, long long *size); |
62584db1 | 308 | |
0b189b6c | 309 | /** |
063790cb | 310 | * os_putc() - write a character to the controlling OS terminal |
0b189b6c SG |
311 | * |
312 | * This bypasses the U-Boot console support and writes directly to the OS | |
313 | * stdout file descriptor. | |
314 | * | |
063790cb | 315 | * @ch: haracter to write |
0b189b6c SG |
316 | */ |
317 | void os_putc(int ch); | |
318 | ||
319 | /** | |
063790cb | 320 | * os_puts() - write a string to the controlling OS terminal |
0b189b6c SG |
321 | * |
322 | * This bypasses the U-Boot console support and writes directly to the OS | |
323 | * stdout file descriptor. | |
324 | * | |
063790cb | 325 | * @str: string to write (note that \n is not appended) |
0b189b6c SG |
326 | */ |
327 | void os_puts(const char *str); | |
328 | ||
7df5b353 T |
329 | /** |
330 | * os_flush() - flush controlling OS terminal | |
331 | * | |
332 | * This bypasses the U-Boot console support and flushes directly the OS | |
333 | * stdout file descriptor. | |
334 | */ | |
335 | void os_flush(void); | |
336 | ||
5c2859cd | 337 | /** |
063790cb | 338 | * os_write_ram_buf() - write the sandbox RAM buffer to a existing file |
5c2859cd | 339 | * |
063790cb HS |
340 | * @fname: filename to write memory to (simple binary format) |
341 | * Return: 0 if OK, -ve on error | |
5c2859cd SG |
342 | */ |
343 | int os_write_ram_buf(const char *fname); | |
344 | ||
345 | /** | |
063790cb | 346 | * os_read_ram_buf() - read the sandbox RAM buffer from an existing file |
5c2859cd | 347 | * |
063790cb HS |
348 | * @fname: filename containing memory (simple binary format) |
349 | * Return: 0 if OK, -ve on error | |
5c2859cd SG |
350 | */ |
351 | int os_read_ram_buf(const char *fname); | |
352 | ||
47f5fcfb | 353 | /** |
063790cb | 354 | * os_jump_to_image() - jump to a new executable image |
47f5fcfb SG |
355 | * |
356 | * This uses exec() to run a new executable image, after putting it in a | |
357 | * temporary file. The same arguments and environment are passed to this | |
358 | * new image, with the addition of: | |
359 | * | |
360 | * -j <filename> Specifies the filename the image was written to. The | |
361 | * calling image may want to delete this at some point. | |
362 | * -m <filename> Specifies the file containing the sandbox memory | |
363 | * (ram_buf) from this image, so that the new image can | |
364 | * have access to this. It also means that the original | |
365 | * memory filename passed to U-Boot will be left intact. | |
366 | * | |
063790cb HS |
367 | * @dest: buffer containing executable image |
368 | * @size: size of buffer | |
369 | * Return: 0 if OK, -ve on error | |
47f5fcfb SG |
370 | */ |
371 | int os_jump_to_image(const void *dest, int size); | |
372 | ||
d4e33f5a | 373 | /** |
063790cb | 374 | * os_find_u_boot() - determine the path to U-Boot proper |
d4e33f5a SG |
375 | * |
376 | * This function is intended to be called from within sandbox SPL. It uses | |
377 | * a few heuristics to find U-Boot proper. Normally it is either in the same | |
378 | * directory, or the directory above (since u-boot-spl is normally in an | |
379 | * spl/ subdirectory when built). | |
380 | * | |
063790cb HS |
381 | * @fname: place to put full path to U-Boot |
382 | * @maxlen: maximum size of @fname | |
01ad9f75 | 383 | * @use_img: select the 'u-boot.img' file instead of the 'u-boot' ELF file |
f178bebf SG |
384 | * @cur_prefix: prefix of current executable, e.g. "spl" or "tpl" |
385 | * @next_prefix: prefix of executable to find, e.g. "spl" or "" | |
063790cb | 386 | * Return: 0 if OK, -NOSPC if the filename is too large, -ENOENT if not found |
d4e33f5a | 387 | */ |
f178bebf SG |
388 | int os_find_u_boot(char *fname, int maxlen, bool use_img, |
389 | const char *cur_prefix, const char *next_prefix); | |
d4e33f5a SG |
390 | |
391 | /** | |
392 | * os_spl_to_uboot() - Run U-Boot proper | |
393 | * | |
394 | * When called from SPL, this runs U-Boot proper. The filename is obtained by | |
395 | * calling os_find_u_boot(). | |
396 | * | |
063790cb HS |
397 | * @fname: full pathname to U-Boot executable |
398 | * Return: 0 if OK, -ve on error | |
d4e33f5a SG |
399 | */ |
400 | int os_spl_to_uboot(const char *fname); | |
401 | ||
94eefdee | 402 | /** |
063790cb | 403 | * os_localtime() - read the current system time |
94eefdee SG |
404 | * |
405 | * This reads the current Local Time and places it into the provided | |
406 | * structure. | |
407 | * | |
063790cb | 408 | * @rt: place to put system time |
94eefdee SG |
409 | */ |
410 | void os_localtime(struct rtc_time *rt); | |
411 | ||
fe938fb0 | 412 | /** |
063790cb | 413 | * os_abort() - raise SIGABRT to exit sandbox (e.g. to debugger) |
fe938fb0 | 414 | */ |
c30a7093 | 415 | void os_abort(void) __attribute__((noreturn)); |
9f8037ea SG |
416 | |
417 | /** | |
418 | * os_mprotect_allow() - Remove write-protection on a region of memory | |
419 | * | |
420 | * The start and length will be page-aligned before use. | |
421 | * | |
422 | * @start: Region start | |
423 | * @len: Region length in bytes | |
063790cb | 424 | * Return: 0 if OK, -1 on error from mprotect() |
9f8037ea SG |
425 | */ |
426 | int os_mprotect_allow(void *start, size_t len); | |
427 | ||
056a5cea | 428 | /** |
063790cb | 429 | * os_write_file() - write a file to the host filesystem |
056a5cea SG |
430 | * |
431 | * This can be useful when debugging for writing data out of sandbox for | |
432 | * inspection by external tools. | |
433 | * | |
434 | * @name: File path to write to | |
435 | * @buf: Data to write | |
436 | * @size: Size of data to write | |
063790cb | 437 | * Return: 0 if OK, -ve on error |
056a5cea SG |
438 | */ |
439 | int os_write_file(const char *name, const void *buf, int size); | |
440 | ||
566bf3a8 SG |
441 | /** |
442 | * os_read_file() - Read a file from the host filesystem | |
443 | * | |
444 | * This can be useful when reading test data into sandbox for use by test | |
445 | * routines. The data is allocated using os_malloc() and should be freed by | |
446 | * the caller. | |
447 | * | |
448 | * @name: File path to read from | |
449 | * @bufp: Returns buffer containing data read | |
450 | * @sizep: Returns size of data | |
063790cb | 451 | * Return: 0 if OK, -ve on error |
566bf3a8 SG |
452 | */ |
453 | int os_read_file(const char *name, void **bufp, int *sizep); | |
454 | ||
b9274095 SG |
455 | /** |
456 | * os_map_file() - Map a file from the host filesystem into memory | |
457 | * | |
458 | * This can be useful when to provide a backing store for an emulated device | |
459 | * | |
460 | * @pathname: File pathname to map | |
461 | * @os_flags: Flags, like OS_O_RDONLY, OS_O_RDWR | |
462 | * @bufp: Returns buffer containing the file | |
463 | * @sizep: Returns size of data | |
464 | * Return: 0 if OK, -ve on error | |
465 | */ | |
466 | int os_map_file(const char *pathname, int os_flags, void **bufp, int *sizep); | |
467 | ||
a0ff280a SG |
468 | /** |
469 | * os_unmap() - Unmap a file previously mapped | |
470 | * | |
471 | * @buf: Mapped address | |
472 | * @size: Size in bytes | |
473 | * Return: 0 if OK, -ve on error | |
474 | */ | |
475 | int os_unmap(void *buf, int size); | |
476 | ||
001d1885 SG |
477 | /* |
478 | * os_find_text_base() - Find the text section in this running process | |
479 | * | |
480 | * This tries to find the address of the text section in this running process. | |
481 | * It can be useful to map the address of functions to the address listed in | |
482 | * the u-boot.map file. | |
483 | * | |
063790cb | 484 | * Return: address if found, else NULL |
001d1885 SG |
485 | */ |
486 | void *os_find_text_base(void); | |
487 | ||
329dccc0 HS |
488 | /** |
489 | * os_relaunch() - restart the sandbox | |
490 | * | |
491 | * This functions is used to implement the cold reboot of the sand box. | |
063790cb | 492 | * @argv\[0] specifies the binary that is started while the calling process |
329dccc0 HS |
493 | * stops immediately. If the new binary cannot be started, the process is |
494 | * terminated and 1 is set as shell return code. | |
495 | * | |
496 | * The PID of the process stays the same. All file descriptors that have not | |
497 | * been opened with O_CLOEXEC stay open including stdin, stdout, stderr. | |
498 | * | |
499 | * @argv: NULL terminated list of command line parameters | |
500 | */ | |
501 | void os_relaunch(char *argv[]); | |
502 | ||
b46f30a3 HS |
503 | /** |
504 | * os_setup_signal_handlers() - setup signal handlers | |
505 | * | |
506 | * Install signal handlers for SIGBUS and SIGSEGV. | |
507 | * | |
508 | * Return: 0 for success | |
509 | */ | |
510 | int os_setup_signal_handlers(void); | |
511 | ||
512 | /** | |
513 | * os_signal_action() - handle a signal | |
514 | * | |
515 | * @sig: signal | |
516 | * @pc: program counter | |
517 | */ | |
518 | void os_signal_action(int sig, unsigned long pc); | |
519 | ||
43db0750 HS |
520 | /** |
521 | * os_get_time_offset() - get time offset | |
522 | * | |
523 | * Get the time offset from environment variable UBOOT_SB_TIME_OFFSET. | |
524 | * | |
525 | * Return: offset in seconds | |
526 | */ | |
527 | long os_get_time_offset(void); | |
528 | ||
529 | /** | |
530 | * os_set_time_offset() - set time offset | |
531 | * | |
532 | * Save the time offset in environment variable UBOOT_SB_TIME_OFFSET. | |
533 | * | |
534 | * @offset: offset in seconds | |
535 | */ | |
536 | void os_set_time_offset(long offset); | |
537 | ||
4f345d56 | 538 | #endif |