util/cbfstool/flashmap/fmap.h

   1 /* SPDX-License-Identifier: BSD-3-Clause or GPL-2.0-only */
   2
   3 #ifndef FLASHMAP_LIB_FMAP_H__
   4 #define FLASHMAP_LIB_FMAP_H__
   5
   6 #include <inttypes.h>
   7 #include <valstr.h>
   8
   9 #define FMAP_SIGNATURE          "__FMAP__"
  10 #define FMAP_VER_MAJOR          1       /* this header's FMAP minor version */
  11 #define FMAP_VER_MINOR          1       /* this header's FMAP minor version */
  12 #define FMAP_STRLEN             32      /* maximum length for strings, */
  13                                         /* including null-terminator */
  14 extern const struct valstr flag_lut[16];
  15 enum fmap_flags {
  16         FMAP_AREA_STATIC        = 1 << 0,
  17         FMAP_AREA_COMPRESSED    = 1 << 1,
  18         FMAP_AREA_RO            = 1 << 2,
  19         FMAP_AREA_PRESERVE      = 1 << 3,
  20 };
  21
  22 /* Mapping of volatile and static regions in firmware binary */
  23 struct fmap_area {
  24         uint32_t offset;                /* offset relative to base */
  25         uint32_t size;                  /* size in bytes */
  26         uint8_t  name[FMAP_STRLEN];     /* descriptive name */
  27         uint16_t flags;                 /* flags for this area */
  28 }  __packed;
  29
  30 struct fmap {
  31         uint8_t  signature[8];          /* "__FMAP__" (0x5F5F464D41505F5F) */
  32         uint8_t  ver_major;             /* major version */
  33         uint8_t  ver_minor;             /* minor version */
  34         uint64_t base;                  /* address of the firmware binary */
  35         uint32_t size;                  /* size of firmware binary in bytes */
  36         uint8_t  name[FMAP_STRLEN];     /* name of this firmware binary */
  37         uint16_t nareas;                /* number of areas described by
  38                                            fmap_areas[] below */
  39         struct fmap_area areas[];
  40 } __packed;
  41
  42 /*
  43  * fmap_find - find FMAP signature in a binary image
  44  *
  45  * @image:      binary image
  46  * @len:        length of binary image
  47  *
  48  * This function does no error checking. The caller is responsible for
  49  * verifying that the contents are sane.
  50  *
  51  * returns offset of FMAP signature to indicate success
  52  * returns <0 to indicate failure
  53  */
  54 extern long int fmap_find(const uint8_t *image, unsigned int len);
  55
  56 /*
  57  * fmap_print - Print contents of flash map data structure
  58  *
  59  * @map:        raw map data
  60  *
  61  * returns 0 to indicate success
  62  * returns <0 to indicate failure
  63  */
  64 extern int fmap_print(const struct fmap *map);
  65
  66 /*
  67  * fmap_flags_to_string - convert raw flags field into user-friendly string
  68  *
  69  * @flags:      raw flags
  70  *
  71  * This function returns a user-friendly comma-separated list of fmap area
  72  * flags. If there are no flags (flags == 0), the string will contain only
  73  * a terminating character ('\0')
  74  *
  75  * This function allocates memory which the caller must free.
  76  *
  77  * returns pointer to an allocated string if successful
  78  * returns NULL to indicate failure
  79  */
  80 char *fmap_flags_to_string(uint16_t flags);
  81
  82 /*
  83  * fmap_create - allocate and initialize a new fmap structure
  84  *
  85  * @base:       base address of firmware within address space
  86  * @size:       size of the firmware (bytes)
  87  * @name:       name of firmware
  88  *
  89  * This function will allocate a flashmap header. Members of the structure
  90  * which are not passed in are automatically initialized.
  91  *
  92  * returns pointer to newly allocated flashmap header if successful
  93  * returns NULL to indicate failure
  94  */
  95 extern struct fmap *fmap_create(uint64_t base,
  96                                 uint32_t size, uint8_t *name);
  97
  98 /* free memory used by an fmap structure */
  99 extern void fmap_destroy(struct fmap *fmap);
 100
 101 /*
 102  * fmap_size - returns size of fmap data structure (including areas)
 103  *
 104  * @fmap:       fmap
 105  *
 106  * returns size of fmap structure if successful
 107  * returns <0 to indicate failure
 108  */
 109 extern int fmap_size(const struct fmap *fmap);
 110
 111 /*
 112  * fmap_append_area - realloc an existing flashmap and append an area
 113  *
 114  * @fmap:       double pointer to existing flashmap
 115  * @offset:     offset of area
 116  * @size:       size of area
 117  * @name:       name of area
 118  * @flags:      area flags
 119  *
 120  * returns total size of reallocated flashmap structure if successful
 121  * returns <0 to indicate failure
 122  */
 123 extern int fmap_append_area(struct fmap **fmap,
 124                             uint32_t offset, uint32_t size,
 125                             const uint8_t *name, uint16_t flags);
 126
 127 /*
 128  * fmap_find_area - find an fmap_area entry (by name) and return pointer to it
 129  *
 130  * @fmap:       fmap structure to parse
 131  * @name:       name of area to find
 132  *
 133  * returns a pointer to the entry in the fmap structure if successful
 134  * returns NULL to indicate failure or if no matching area entry is found
 135  */
 136 extern const struct fmap_area *fmap_find_area(const struct fmap *fmap,
 137                                                         const char *name);
 138
 139 /* unit testing stuff */
 140 extern int fmap_test(void);
 141
 142 #endif  /* FLASHMAP_LIB_FMAP_H__*/