text: // SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
  /* Copyright 2013-2018 IBM Corp. */
  
  #ifndef __LIBFFS_H
  #define __LIBFFS_H
  
  #include <libflash/libflash.h>
  #include <libflash/blocklevel.h>
  
  /* FFS handle, opaque */
  struct ffs_handle;
  struct ffs_hdr;
  struct ffs_entry;
  struct ffs_entry_user;
  
  /**
   * struct ffs_entry_user - User data entries
   *
   * Usable in memory representation of a struct __ffs_entry_user
   *
   *  @chip:		Chip Select (0,1)
   *  @compressType:	Compression Indication/alg (0=not compressed)
   *  @dataInteg:		Indicates Data Integrity mechanism
   *  @verCheck:		Indicates Version check type
   *  @miscFlags:		Misc Partition related Flags
   */
  struct ffs_entry_user {
  	uint8_t chip;
  	uint8_t compresstype;
  	uint16_t datainteg;
  	uint8_t vercheck;
  	uint8_t miscflags;
  };
  
  /* Error codes:
   *
   * < 0 = flash controller errors
   *   0 = success
   * > 0 = libffs / libflash errors
   */
  #define FFS_ERR_BAD_MAGIC	100
  #define FFS_ERR_BAD_VERSION	101
  #define FFS_ERR_BAD_CKSUM	102
  #define FFS_ERR_PART_NOT_FOUND	103
  #define FFS_ERR_BAD_ECC		104
  #define FFS_ERR_BAD_SIZE	105
  #define FFS_ERR_BAD_PART_NAME	106
  #define FFS_ERR_BAD_PART_BASE	107
  #define FFS_ERR_BAD_PART_SIZE	108
  #define FFS_ERR_BAD_PART_PID	109
  
  /* The maximum length of the partition name */
  #define FFS_PART_NAME_MAX   15
  /* Old version of the name DEPRECATED */
  #define PART_NAME_MAX   15
  
  /*
   * Flag bit definitions
   */
  #define FFS_FLAGS_PROTECTED	0x0001
  #define FFS_FLAGS_U_BOOT_ENV	0x0002
  
  /* Data integrity flags */
  #define FFS_ENRY_INTEG_ECC 0x8000
  
  /*
   * User verCheck definitions
   */
  #define FFS_VERCHECK_SHA512V 0x80
  #define FFS_VERCHECK_SHA512EC 0x40
  
  /*
   * User miscFlags
   */
  #define FFS_MISCFLAGS_PRESERVED 0x80
  #define FFS_MISCFLAGS_READONLY 0x40
  #define FFS_MISCFLAGS_BACKUP 0x20
  #define FFS_MISCFLAGS_REPROVISION 0x10
  #define FFS_MISCFLAGS_VOLATILE 0x08
  #define FFS_MISCFLAGS_CLEARECC 0x04
  #define FFS_MISCFLAGS_GOLDEN 0x01
  
  
  int ffs_string_to_entry_user(const char *flags, int nflags,
  		struct ffs_entry_user *user);
  char *ffs_entry_user_to_string(struct ffs_entry_user *user);
  
  bool has_ecc(struct ffs_entry *ent);
  
  bool has_flag(struct ffs_entry *ent, uint16_t flag);
  
  /* Init */
  
  int ffs_init(uint32_t offset, uint32_t max_size, struct blocklevel_device *bl,
  		struct ffs_handle **ffs, bool mark_ecc);
  
  /*
   * Initialise a new ffs_handle to the "OTHER SIDE".
   * Reuses the underlying blocklevel_device.
   */
  int ffs_next_side(struct ffs_handle *ffs, struct ffs_handle **new_ffs,
  		bool mark_ecc);
  
  /*
   * There are quite a few ways one might consider two ffs_handles to be the
   * same. For the purposes of this function we are trying to detect a fairly
   * specific scenario:
   * Consecutive calls to ffs_next_side() may succeed but have gone circular.
   * It is possible that the OTHER_SIDE partition in one TOC actually points
   * back to the TOC of the first ffs_handle.
   * This function compares for this case, therefore the requirements are
   * simple, the underlying blocklevel_devices must be the same along with
   * the toc_offset and the max_size.
   */
  bool ffs_equal(struct ffs_handle *one, struct ffs_handle *two);
  
  void ffs_close(struct ffs_handle *ffs);
  
  int ffs_lookup_part(struct ffs_handle *ffs, const char *name,
  		    uint32_t *part_idx);
  
  int ffs_part_info(struct ffs_handle *ffs, uint32_t part_idx,
  		  char **name, uint32_t *start,
  		  uint32_t *total_size, uint32_t *act_size, bool *ecc);
  
  struct ffs_entry *ffs_entry_get(struct ffs_handle *ffs, uint32_t index);
  
  int ffs_update_act_size(struct ffs_handle *ffs, uint32_t part_idx,
  			uint32_t act_size);
  
  int ffs_hdr_new(uint32_t block_size, uint32_t block_count,
  		struct ffs_entry **e, struct ffs_hdr **r);
  
  int ffs_hdr_add_side(struct ffs_hdr *hdr);
  
  int ffs_entry_new(const char *name, uint32_t base, uint32_t size, struct ffs_entry **r);
  
  struct ffs_entry *ffs_entry_put(struct ffs_entry *ent);
  
  int ffs_entry_user_set(struct ffs_entry *ent, struct ffs_entry_user *user);
  
  int ffs_entry_set_act_size(struct ffs_entry *ent, uint32_t actual_size);
  
  
  struct ffs_entry_user ffs_entry_user_get(struct ffs_entry *ent);
  
  int ffs_entry_add(struct ffs_hdr *hdr, struct ffs_entry *entry);
  
  int ffs_hdr_finalise(struct blocklevel_device *bl, struct ffs_hdr *hdr);
  
  void ffs_hdr_free(struct ffs_hdr *hdr);
  #endif /* __LIBFFS_H */
  