libbladeRF 2.6.0-git
Nuand bladeRF library
Loading...
Searching...
No Matches
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.

Topics

 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 ,
  BLADERF_IMAGE_TYPE_FPGA_A5 , BLADERF_IMAGE_TYPE_GAIN_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_print_metadata (const struct bladerf_image *image)
 Prints the metadata of a bladeRF image structure.
API_EXPORT const char * bladerf_image_type_to_string (bladerf_image_type type)
 Converts a bladeRF image type to its corresponding string representation.
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

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

BLADERF_IMAGE_TYPE_FPGA_A5 

FPGA bitstream for A5 device

BLADERF_IMAGE_TYPE_GAIN_CAL 

Gain calibration

Definition at line 3312 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 3333 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 3330 of file libbladeRF.h.

◆ BLADERF_IMAGE_RESERVED_LEN

#define BLADERF_IMAGE_RESERVED_LEN   128

Size of reserved region of flash image

Definition at line 3336 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]devDevice handle
[in]fpga_sizeTarget FPGA size
[in]vctcxo_trimVCTCXO 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.

Parameters
[in]devDevice handle
[in]typeImage type to be created, represented by bladerf_image_type
[in]addressAddress in flash memory where the image is stored. Use 0xffffffff if not applicable.
[in]lengthLength of the image data in bytes
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]imageFlash image

◆ bladerf_image_print_metadata()

API_EXPORT int CALL_CONV bladerf_image_print_metadata ( const struct bladerf_image * image)

Prints the metadata of a bladeRF image structure.

This function displays the metadata of a provided bladerf_image structure. It includes information such as the magic number, version, timestamp, serial number, address, and length of the image. The function will return an error code if the provided image pointer is NULL.

Precondition
The image should have been allocated using bladerf_alloc_image().
Note
This function only prints the metadata of the image and does not perform any operations on the image data itself.
Parameters
[in]imagePointer to the bladerf_image structure whose metadata is to be printed. It should not be NULL.
Returns
0 on success, BLADERF_ERR_MEM if the image pointer is NULL.

◆ 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]imageFlash image structure to populate.
[in]fileFile 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_type_to_string()

API_EXPORT const char * bladerf_image_type_to_string ( bladerf_image_type type)

Converts a bladeRF image type to its corresponding string representation.

This function maps a bladerf_image_type enumeration value to a human-readable string. It is useful for logging, debugging, or displaying the image type to an end user.

Parameters
[in]typeThe bladerf_image_type enumeration value to be converted.
Returns
A pointer to a string representing the image type. Returns "Unknown Type" for any unrecognized or out-of-range values.

◆ 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]devDevice handle
[in]imageFlash image
[in]fileFile to write the flash image to
Returns
0 upon success, or a value from Error codes list on failure