libbladeRF: Flash image format

| libbladeRF 2.4.0-git Nuand bladeRF library

Modules | Data Structures | Enumerations | Macros | Functions
Flash image format

## Description

This section contains a file format and associated routines for storing and loading flash contents with metadata.

These functions are thread-safe.

## Modules
| Flash image format constants

## Data Structures
struct | bladerf_image

## Enumerations
enum | bladerf_image_type { BLADERF_IMAGE_TYPE_INVALID = -1 , BLADERF_IMAGE_TYPE_RAW , BLADERF_IMAGE_TYPE_FIRMWARE , BLADERF_IMAGE_TYPE_FPGA_40KLE , BLADERF_IMAGE_TYPE_FPGA_115KLE , BLADERF_IMAGE_TYPE_FPGA_A4 , BLADERF_IMAGE_TYPE_FPGA_A9 , BLADERF_IMAGE_TYPE_CALIBRATION , BLADERF_IMAGE_TYPE_RX_DC_CAL , BLADERF_IMAGE_TYPE_TX_DC_CAL , BLADERF_IMAGE_TYPE_RX_IQ_CAL , BLADERF_IMAGE_TYPE_TX_IQ_CAL }

## Macros
#define | BLADERF_IMAGE_MAGIC_LEN 7
#define | BLADERF_IMAGE_CHECKSUM_LEN 32
#define | BLADERF_IMAGE_RESERVED_LEN 128

## Functions
API_EXPORT struct bladerf_image *CALL_CONV | bladerf_alloc_image (struct bladerf *dev, bladerf_image_type type, uint32_t address, uint32_t length)
API_EXPORT struct bladerf_image *CALL_CONV | bladerf_alloc_cal_image (struct bladerf *dev, bladerf_fpga_size fpga_size, uint16_t vctcxo_trim)
API_EXPORT void CALL_CONV | bladerf_free_image (struct bladerf_image *image)
API_EXPORT int CALL_CONV | bladerf_image_write (struct bladerf *dev, struct bladerf_image *image, const char *file)
API_EXPORT int CALL_CONV | bladerf_image_read (struct bladerf_image *image, const char *file)

## Enumeration Type Documentation

## ◆ bladerf_image_type

enum bladerf_image_type

Type of data stored in a flash image

Enumerator
BLADERF_IMAGE_TYPE_INVALID | Used to denote invalid value
BLADERF_IMAGE_TYPE_RAW | Misc. raw data
BLADERF_IMAGE_TYPE_FIRMWARE | Firmware data
BLADERF_IMAGE_TYPE_FPGA_40KLE | FPGA bitstream for 40 KLE device
BLADERF_IMAGE_TYPE_FPGA_115KLE | FPGA bitstream for 115 KLE device
BLADERF_IMAGE_TYPE_FPGA_A4 | FPGA bitstream for A4 device
BLADERF_IMAGE_TYPE_FPGA_A9 | FPGA bitstream for A9 device
BLADERF_IMAGE_TYPE_CALIBRATION | Board calibration
BLADERF_IMAGE_TYPE_RX_DC_CAL | RX DC offset calibration table
BLADERF_IMAGE_TYPE_TX_DC_CAL | TX DC offset calibration table
BLADERF_IMAGE_TYPE_RX_IQ_CAL | RX IQ balance calibration table
BLADERF_IMAGE_TYPE_TX_IQ_CAL | TX IQ balance calibration table

Definition at line 3159 of file libbladeRF.h.

## Macro Definition Documentation

## ◆ BLADERF_IMAGE_CHECKSUM_LEN

#define BLADERF_IMAGE_CHECKSUM_LEN 32

Size of bladeRF flash image checksum

Definition at line 3178 of file libbladeRF.h.

## ◆ BLADERF_IMAGE_MAGIC_LEN

#define BLADERF_IMAGE_MAGIC_LEN 7

Size of the magic signature at the beginning of bladeRF image files

Definition at line 3175 of file libbladeRF.h.

## ◆ BLADERF_IMAGE_RESERVED_LEN

#define BLADERF_IMAGE_RESERVED_LEN 128

Size of reserved region of flash image

Definition at line 3181 of file libbladeRF.h.

## Function Documentation

## ◆ bladerf_alloc_cal_image()

API_EXPORT struct bladerf_image* CALL_CONV bladerf_alloc_cal_image | ( | struct bladerf * | dev,
|  | bladerf_fpga_size | fpga_size,
|  | uint16_t | vctcxo_trim
| ) |  |

Create a flash image initialized to contain a calibration data region.

This is intended to be used in conjunction with bladerf_image_write(), or a write of the image's `data` field to flash.

Parameters

  [in] | dev | Device handle
  [in] | fpga_size | Target FPGA size
  [in] | vctcxo_trim | VCTCXO oscillator trim value.

Returns
  Pointer to allocated and initialized structure on success, `NULL` on memory allocation failure

## ◆ bladerf_alloc_image()

API_EXPORT struct bladerf_image* CALL_CONV bladerf_alloc_image | ( | struct bladerf * | dev,
|  | bladerf_image_type | type,
|  | uint32_t | address,
|  | uint32_t | length
| ) |  |

Allocate and initialize an image structure.

This following bladerf_image fields are populated: `magic`, `version`, `timestamp`, `type`, `address`, and `length`

The following bladerf_image fields are zeroed out: `checksum`, `serial`, and `reserved`

If the `length` parameter is not 0, the bladerf_image `data` field will be dynamically allocated. Otherwise, `data` will be set to NULL.

Note
  A non-zero `length` should be use only with bladerf_image_write(); bladerf_image_read() allocates and sets `data` based upon size of the image contents, and does not attempt to free() the `data` field before setting it.

The `address` and `length` fields should be set 0 when reading an image from a file.

Returns
  Pointer to allocated and initialized structure on success, `NULL` on memory allocation failure or invalid address/length.

## ◆ bladerf_free_image()

API_EXPORT void CALL_CONV bladerf_free_image | ( | struct bladerf_image * | image | ) |

Free a bladerf_image previously obtained via bladerf_alloc_image.

If the bladerf_image's `data` field is non-`NULL`, it will be freed.

Parameters

  [in,out] | image | Flash image

## ◆ bladerf_image_read()

API_EXPORT int CALL_CONV bladerf_image_read | ( | struct bladerf_image * | image,
|  | const char * | file
| ) |  |

Read flash image from a file.

Precondition
  The `image` parameter has been obtained via a call to bladerf_alloc_image(), with a `length` of 0.

Postcondition
  The `image` fields will be populated upon success, overwriting any previous values.

Note
  The contents of the `image` parameter should not be used if this function fails.

Parameters

  [out] | image | Flash image structure to populate.
  [in] | file | File to read image from.

Returns
  0 upon success, BLADERF_ERR_CHECKSUM upon detecting a checksum mismatch, BLADERF_ERR_INVAL if any image fields are invalid, BLADERF_ERR_IO on a file I/O error, or a value from Error codes list on any other failure

## ◆ bladerf_image_write()

API_EXPORT int CALL_CONV bladerf_image_write | ( | struct bladerf * | dev,
|  | struct bladerf_image * | image,
|  | const char * | file
| ) |  |

Write a flash image to a file.

This function will fill in the checksum field before writing the contents to the specified file. The user-supplied contents of this field are ignored.

Precondition
  `image` has been initialized using bladerf_alloc_image()

Postcondition
  `image->checksum` will be populated if this function succeeds

Parameters

  [in] | dev | Device handle
  [in] | image | Flash image
  [in] | file | File to write the flash image to

Returns
  0 upon success, or a value from Error codes list on failure