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

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