1 | /* SPDX-License-Identifier: GPL-2.0-or-later */ |
2 | #ifndef UTIL_H |
3 | #define UTIL_H |
4 | |
5 | #include <stdlib.h> |
6 | #include <stdarg.h> |
7 | #include <stdbool.h> |
8 | #include <getopt.h> |
9 | |
10 | /* |
11 | * Copyright 2011 The Chromium Authors, All Rights Reserved. |
12 | * Copyright 2008 Jon Loeliger, Freescale Semiconductor, Inc. |
13 | */ |
14 | |
15 | #ifdef __GNUC__ |
16 | #if __GNUC__ >= 5 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4) |
17 | #define PRINTF(i, j) __attribute__((format (gnu_printf, i, j))) |
18 | #else |
19 | #define PRINTF(i, j) __attribute__((format (printf, i, j))) |
20 | #endif |
21 | #define NORETURN __attribute__((noreturn)) |
22 | #else |
23 | #define PRINTF(i, j) |
24 | #define NORETURN |
25 | #endif |
26 | |
27 | #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) |
28 | |
29 | #define stringify(s) stringify_(s) |
30 | #define stringify_(s) #s |
31 | |
32 | static inline void NORETURN PRINTF(1, 2) die(const char *str, ...) |
33 | { |
34 | va_list ap; |
35 | |
36 | va_start(ap, str); |
37 | fprintf(stderr, format: "FATAL ERROR: " ); |
38 | vfprintf(stderr, format: str, arg: ap); |
39 | va_end(ap); |
40 | exit(status: 1); |
41 | } |
42 | |
43 | static inline void *xmalloc(size_t len) |
44 | { |
45 | void *new = malloc(size: len); |
46 | |
47 | if (!new) |
48 | die(str: "malloc() failed\n" ); |
49 | |
50 | return new; |
51 | } |
52 | |
53 | static inline void *xrealloc(void *p, size_t len) |
54 | { |
55 | void *new = realloc(ptr: p, size: len); |
56 | |
57 | if (!new) |
58 | die(str: "realloc() failed (len=%zd)\n" , len); |
59 | |
60 | return new; |
61 | } |
62 | |
63 | extern char *xstrdup(const char *s); |
64 | extern char *xstrndup(const char *s, size_t len); |
65 | |
66 | extern int PRINTF(2, 3) xasprintf(char **strp, const char *fmt, ...); |
67 | extern int PRINTF(2, 3) xasprintf_append(char **strp, const char *fmt, ...); |
68 | extern int xavsprintf_append(char **strp, const char *fmt, va_list ap); |
69 | extern char *join_path(const char *path, const char *name); |
70 | |
71 | /** |
72 | * Check a property of a given length to see if it is all printable and |
73 | * has a valid terminator. The property can contain either a single string, |
74 | * or multiple strings each of non-zero length. |
75 | * |
76 | * @param data The string to check |
77 | * @param len The string length including terminator |
78 | * @return 1 if a valid printable string, 0 if not |
79 | */ |
80 | bool util_is_printable_string(const void *data, int len); |
81 | |
82 | /* |
83 | * Parse an escaped character starting at index i in string s. The resulting |
84 | * character will be returned and the index i will be updated to point at the |
85 | * character directly after the end of the encoding, this may be the '\0' |
86 | * terminator of the string. |
87 | */ |
88 | char get_escape_char(const char *s, int *i); |
89 | |
90 | /** |
91 | * Read a device tree file into a buffer. This will report any errors on |
92 | * stderr. |
93 | * |
94 | * @param filename The filename to read, or - for stdin |
95 | * @param len If non-NULL, the amount of data we managed to read |
96 | * @return Pointer to allocated buffer containing fdt, or NULL on error |
97 | */ |
98 | char *utilfdt_read(const char *filename, size_t *len); |
99 | |
100 | /** |
101 | * Read a device tree file into a buffer. Does not report errors, but only |
102 | * returns them. The value returned can be passed to strerror() to obtain |
103 | * an error message for the user. |
104 | * |
105 | * @param filename The filename to read, or - for stdin |
106 | * @param buffp Returns pointer to buffer containing fdt |
107 | * @param len If non-NULL, the amount of data we managed to read |
108 | * @return 0 if ok, else an errno value representing the error |
109 | */ |
110 | int utilfdt_read_err(const char *filename, char **buffp, size_t *len); |
111 | |
112 | /** |
113 | * Write a device tree buffer to a file. This will report any errors on |
114 | * stderr. |
115 | * |
116 | * @param filename The filename to write, or - for stdout |
117 | * @param blob Pointer to buffer containing fdt |
118 | * @return 0 if ok, -1 on error |
119 | */ |
120 | int utilfdt_write(const char *filename, const void *blob); |
121 | |
122 | /** |
123 | * Write a device tree buffer to a file. Does not report errors, but only |
124 | * returns them. The value returned can be passed to strerror() to obtain |
125 | * an error message for the user. |
126 | * |
127 | * @param filename The filename to write, or - for stdout |
128 | * @param blob Pointer to buffer containing fdt |
129 | * @return 0 if ok, else an errno value representing the error |
130 | */ |
131 | int utilfdt_write_err(const char *filename, const void *blob); |
132 | |
133 | /** |
134 | * Decode a data type string. The purpose of this string |
135 | * |
136 | * The string consists of an optional character followed by the type: |
137 | * Modifier characters: |
138 | * hh or b 1 byte |
139 | * h 2 byte |
140 | * l 4 byte, default |
141 | * |
142 | * Type character: |
143 | * s string |
144 | * i signed integer |
145 | * u unsigned integer |
146 | * x hex |
147 | * r raw |
148 | * |
149 | * TODO: Implement ll modifier (8 bytes) |
150 | * TODO: Implement o type (octal) |
151 | * |
152 | * @param fmt Format string to process |
153 | * @param type Returns type found(s/d/u/x), or 0 if none |
154 | * @param size Returns size found(1,2,4,8) or 4 if none |
155 | * @return 0 if ok, -1 on error (no type given, or other invalid format) |
156 | */ |
157 | int utilfdt_decode_type(const char *fmt, int *type, int *size); |
158 | |
159 | /* |
160 | * This is a usage message fragment for the -t option. It is the format |
161 | * supported by utilfdt_decode_type. |
162 | */ |
163 | |
164 | #define USAGE_TYPE_MSG \ |
165 | "<type>\ts=string, i=int, u=unsigned, x=hex, r=raw\n" \ |
166 | "\tOptional modifier prefix:\n" \ |
167 | "\t\thh or b=byte, h=2 byte, l=4 byte (default)"; |
168 | |
169 | /** |
170 | * Print property data in a readable format to stdout |
171 | * |
172 | * Properties that look like strings will be printed as strings. Otherwise |
173 | * the data will be displayed either as cells (if len is a multiple of 4 |
174 | * bytes) or bytes. |
175 | * |
176 | * If len is 0 then this function does nothing. |
177 | * |
178 | * @param data Pointers to property data |
179 | * @param len Length of property data |
180 | */ |
181 | void utilfdt_print_data(const char *data, int len); |
182 | |
183 | /** |
184 | * Show source version and exit |
185 | */ |
186 | void NORETURN util_version(void); |
187 | |
188 | /** |
189 | * Show usage and exit |
190 | * |
191 | * This helps standardize the output of various utils. You most likely want |
192 | * to use the usage() helper below rather than call this. |
193 | * |
194 | * @param errmsg If non-NULL, an error message to display |
195 | * @param synopsis The initial example usage text (and possible examples) |
196 | * @param short_opts The string of short options |
197 | * @param long_opts The structure of long options |
198 | * @param opts_help An array of help strings (should align with long_opts) |
199 | */ |
200 | void NORETURN util_usage(const char *errmsg, const char *synopsis, |
201 | const char *short_opts, |
202 | struct option const long_opts[], |
203 | const char * const opts_help[]); |
204 | |
205 | /** |
206 | * Show usage and exit |
207 | * |
208 | * If you name all your usage variables with usage_xxx, then you can call this |
209 | * help macro rather than expanding all arguments yourself. |
210 | * |
211 | * @param errmsg If non-NULL, an error message to display |
212 | */ |
213 | #define usage(errmsg) \ |
214 | util_usage(errmsg, usage_synopsis, usage_short_opts, \ |
215 | usage_long_opts, usage_opts_help) |
216 | |
217 | /** |
218 | * Call getopt_long() with standard options |
219 | * |
220 | * Since all util code runs getopt in the same way, provide a helper. |
221 | */ |
222 | #define util_getopt_long() getopt_long(argc, argv, usage_short_opts, \ |
223 | usage_long_opts, NULL) |
224 | |
225 | /* Helper for aligning long_opts array */ |
226 | #define a_argument required_argument |
227 | |
228 | /* Helper for usage_short_opts string constant */ |
229 | #define USAGE_COMMON_SHORT_OPTS "hV" |
230 | |
231 | /* Helper for usage_long_opts option array */ |
232 | #define USAGE_COMMON_LONG_OPTS \ |
233 | {"help", no_argument, NULL, 'h'}, \ |
234 | {"version", no_argument, NULL, 'V'}, \ |
235 | {NULL, no_argument, NULL, 0x0} |
236 | |
237 | /* Helper for usage_opts_help array */ |
238 | #define USAGE_COMMON_OPTS_HELP \ |
239 | "Print this help and exit", \ |
240 | "Print version and exit", \ |
241 | NULL |
242 | |
243 | /* Helper for getopt case statements */ |
244 | #define case_USAGE_COMMON_FLAGS \ |
245 | case 'h': usage(NULL); \ |
246 | case 'V': util_version(); \ |
247 | case '?': usage("unknown option"); |
248 | |
249 | #endif /* UTIL_H */ |
250 | |