1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3 * Copyright (C) 2022 Sean Anderson <sean.anderson@seco.com>
4 */
5
6 #ifndef _SEMIHOSTING_H
7 #define _SEMIHOSTING_H
8
9 /*
10 * These are the encoded instructions used to indicate a semihosting trap. They
11 * are named like SMH_ISA_INSN, where ISA is the instruction set (e.g.
12 * AArch64), and INSN is the mneumonic for the instruction.
13 */
14 #define SMH_A64_HLT 0xD45E0000
15 #define SMH_A32_SVC 0xEF123456
16 #define SMH_A32_HLT 0xE10F0070
17 #define SMH_T32_SVC 0xDFAB
18 #define SMH_T32_HLT 0xBABC
19
20 /**
21 * smh_trap() - ARCH-specific semihosting call.
22 *
23 * Semihosting library/driver can use this function to do the
24 * actual semihosting calls.
25 *
26 * Return: Error code defined by semihosting spec.
27 */
28
29 long smh_trap(unsigned int sysnum, void *addr);
30
31 #if CONFIG_IS_ENABLED(SEMIHOSTING_FALLBACK)
32 /**
33 * semihosting_enabled() - Determine whether semihosting is supported
34 *
35 * Semihosting-based drivers should call this function before making other
36 * semihosting calls.
37 *
38 * Return: %true if a debugger is attached which supports semihosting, %false
39 * otherwise
40 */
41 bool semihosting_enabled(void);
42
43 /**
44 * disable_semihosting() - Cause semihosting_enabled() to return false
45 *
46 * If U-Boot ever receives an unhandled exception caused by a semihosting trap,
47 * the trap handler should call this function.
48 */
49 void disable_semihosting(void);
50 #else
semihosting_enabled(void)51 static inline bool semihosting_enabled(void)
52 {
53 return CONFIG_IS_ENABLED(SEMIHOSTING);
54 }
55
disable_semihosting(void)56 static inline void disable_semihosting(void)
57 {
58 }
59 #endif
60
61 /**
62 * enum smh_open_mode - Numeric file modes for use with smh_open()
63 * MODE_READ: 'r'
64 * MODE_BINARY: 'b'
65 * MODE_PLUS: '+'
66 * MODE_WRITE: 'w'
67 * MODE_APPEND: 'a'
68 *
69 * These modes represent the mode string used by fopen(3) in a form which can
70 * be passed to smh_open(). These do NOT correspond directly to %O_RDONLY,
71 * %O_CREAT, etc; see fopen(3) for details. In particular, @MODE_PLUS
72 * effectively results in adding %O_RDWR, and @MODE_WRITE will add %O_TRUNC.
73 * For compatibility, @MODE_BINARY should be added when opening non-text files
74 * (such as images).
75 */
76 enum smh_open_mode {
77 MODE_READ = 0x0,
78 MODE_BINARY = 0x1,
79 MODE_PLUS = 0x2,
80 MODE_WRITE = 0x4,
81 MODE_APPEND = 0x8,
82 };
83
84 /**
85 * smh_open() - Open a file on the host
86 * @fname: The name of the file to open
87 * @mode: The mode to use when opening the file
88 *
89 * Return: Either a file descriptor or a negative error on failure
90 */
91 long smh_open(const char *fname, enum smh_open_mode mode);
92
93 /**
94 * smh_read() - Read data from a file
95 * @fd: A file descriptor returned from smh_open()
96 * @memp: Pointer to a buffer of memory of at least @len bytes
97 * @len: The number of bytes to read
98 *
99 * Return:
100 * * The number of bytes read on success, with 0 indicating %EOF
101 * * A negative error on failure
102 */
103 long smh_read(long fd, void *memp, size_t len);
104
105 /**
106 * smh_write() - Write data to a file
107 * @fd: A file descriptor returned from smh_open()
108 * @memp: Pointer to a buffer of memory of at least @len bytes
109 * @len: The number of bytes to read
110 * @written: Pointer which will be updated with the actual bytes written
111 *
112 * Return: 0 on success or negative error on failure
113 */
114 long smh_write(long fd, const void *memp, size_t len, ulong *written);
115
116 /**
117 * smh_close() - Close an open file
118 * @fd: A file descriptor returned from smh_open()
119 *
120 * Return: 0 on success or negative error on failure
121 */
122 long smh_close(long fd);
123
124 /**
125 * smh_flen() - Get the length of a file
126 * @fd: A file descriptor returned from smh_open()
127 *
128 * Return: The length of the file, in bytes, or a negative error on failure
129 */
130 long smh_flen(long fd);
131
132 /**
133 * smh_seek() - Seek to a position in a file
134 * @fd: A file descriptor returned from smh_open()
135 * @pos: The offset (in bytes) to seek to
136 *
137 * Return: 0 on success or negative error on failure
138 */
139 long smh_seek(long fd, long pos);
140
141 /**
142 * smh_getc() - Read a character from stdin
143 *
144 * Return: The character read, or a negative error on failure
145 */
146 int smh_getc(void);
147
148 /**
149 * smh_putc() - Print a character on stdout
150 * @ch: The character to print
151 */
152 void smh_putc(char ch);
153
154 /**
155 * smh_write0() - Print a nul-terminated string on stdout
156 * @s: The string to print
157 */
158 void smh_puts(const char *s);
159
160 #endif /* _SEMIHOSTING_H */
161