util.h 7.7 KB

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