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__*/