util.h 7.7 KB

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