scripts/dtc/util.h

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