FuFirmware

FuFirmware

Functions

const gchar * fu_firmware_flag_to_string ()
FuFirmwareFlags fu_firmware_flag_from_string ()
FuFirmware * fu_firmware_new ()
FuFirmware * fu_firmware_new_from_bytes ()
FuFirmware * fu_firmware_new_from_gtypes ()
gchar * fu_firmware_to_string ()
void fu_firmware_export ()
gchar * fu_firmware_export_to_xml ()
const gchar * fu_firmware_get_version ()
void fu_firmware_set_version ()
guint64 fu_firmware_get_version_raw ()
void fu_firmware_set_version_raw ()
void fu_firmware_add_flag ()
gboolean fu_firmware_has_flag ()
const gchar * fu_firmware_get_filename ()
void fu_firmware_set_filename ()
const gchar * fu_firmware_get_id ()
void fu_firmware_set_id ()
guint64 fu_firmware_get_addr ()
void fu_firmware_set_addr ()
guint64 fu_firmware_get_offset ()
void fu_firmware_set_offset ()
gsize fu_firmware_get_size ()
void fu_firmware_set_size ()
guint64 fu_firmware_get_idx ()
void fu_firmware_set_idx ()
GBytes * fu_firmware_get_bytes ()
GBytes * fu_firmware_get_bytes_with_patches ()
void fu_firmware_set_bytes ()
guint8 fu_firmware_get_alignment ()
void fu_firmware_set_alignment ()
void fu_firmware_add_chunk ()
GPtrArray * fu_firmware_get_chunks ()
gboolean fu_firmware_tokenize ()
gboolean fu_firmware_build ()
gboolean fu_firmware_build_from_xml ()
gboolean fu_firmware_parse ()
gboolean fu_firmware_parse_file ()
gboolean fu_firmware_parse_full ()
GBytes * fu_firmware_write ()
GBytes * fu_firmware_write_chunk ()
gboolean fu_firmware_write_file ()
gchar * fu_firmware_get_checksum ()
void fu_firmware_add_image ()
gboolean fu_firmware_remove_image ()
gboolean fu_firmware_remove_image_by_idx ()
gboolean fu_firmware_remove_image_by_id ()
GPtrArray * fu_firmware_get_images ()
FuFirmware * fu_firmware_get_image_by_id ()
GBytes * fu_firmware_get_image_by_id_bytes ()
FuFirmware * fu_firmware_get_image_by_idx ()
GBytes * fu_firmware_get_image_by_idx_bytes ()
FuFirmware * fu_firmware_get_image_by_checksum ()
void fu_firmware_add_patch ()

Types and Values

#define FU_TYPE_FIRMWARE
#define FU_FIRMWARE_EXPORT_FLAG_NONE
#define FU_FIRMWARE_EXPORT_FLAG_INCLUDE_DEBUG
#define FU_FIRMWARE_EXPORT_FLAG_ASCII_DATA
typedef FuFirmwareExportFlags
struct FuFirmwareClass
#define FU_FIRMWARE_FLAG_NONE
#define FU_FIRMWARE_FLAG_DEDUPE_ID
#define FU_FIRMWARE_FLAG_DEDUPE_IDX
#define FU_FIRMWARE_FLAG_HAS_CHECKSUM
#define FU_FIRMWARE_FLAG_HAS_VID_PID
#define FU_FIRMWARE_FLAG_DONE_PARSE
typedef FuFirmwareFlags
#define FU_FIRMWARE_ID_PAYLOAD
#define FU_FIRMWARE_ID_SIGNATURE
#define FU_FIRMWARE_ID_HEADER
#define FU_FIRMWARE_ALIGNMENT_1
#define FU_FIRMWARE_ALIGNMENT_2
#define FU_FIRMWARE_ALIGNMENT_4
#define FU_FIRMWARE_ALIGNMENT_8
#define FU_FIRMWARE_ALIGNMENT_16
#define FU_FIRMWARE_ALIGNMENT_32
#define FU_FIRMWARE_ALIGNMENT_64
#define FU_FIRMWARE_ALIGNMENT_128
#define FU_FIRMWARE_ALIGNMENT_256
#define FU_FIRMWARE_ALIGNMENT_512
#define FU_FIRMWARE_ALIGNMENT_1K
#define FU_FIRMWARE_ALIGNMENT_2K
#define FU_FIRMWARE_ALIGNMENT_4K
#define FU_FIRMWARE_ALIGNMENT_8K
#define FU_FIRMWARE_ALIGNMENT_16K
#define FU_FIRMWARE_ALIGNMENT_32K
#define FU_FIRMWARE_ALIGNMENT_64K
#define FU_FIRMWARE_ALIGNMENT_128K
#define FU_FIRMWARE_ALIGNMENT_256K
#define FU_FIRMWARE_ALIGNMENT_512K
#define FU_FIRMWARE_ALIGNMENT_1M
#define FU_FIRMWARE_ALIGNMENT_2M
#define FU_FIRMWARE_ALIGNMENT_4M
#define FU_FIRMWARE_ALIGNMENT_8M
#define FU_FIRMWARE_ALIGNMENT_16M
#define FU_FIRMWARE_ALIGNMENT_32M
#define FU_FIRMWARE_ALIGNMENT_64M
#define FU_FIRMWARE_ALIGNMENT_128M
#define FU_FIRMWARE_ALIGNMENT_256M
#define FU_FIRMWARE_ALIGNMENT_512M
#define FU_FIRMWARE_ALIGNMENT_1G
#define FU_FIRMWARE_ALIGNMENT_2G
#define FU_FIRMWARE_ALIGNMENT_4G
  FuFirmware

Description

Functions

fu_firmware_flag_to_string ()

const gchar *
fu_firmware_flag_to_string (FuFirmwareFlags flag);

Converts a FuFirmwareFlags to a string.

Parameters

Returns

identifier string

Since: 1.5.0


fu_firmware_flag_from_string ()

FuFirmwareFlags
fu_firmware_flag_from_string (const gchar *flag);

Converts a string to a FuFirmwareFlags.

Parameters

flag

a string, e.g. dedupe-id

 

Returns

enumerated value

Since: 1.5.0


fu_firmware_new ()

FuFirmware *
fu_firmware_new (void);

Creates an empty firmware object.

Returns

a FuFirmware

Since: 1.3.1


fu_firmware_new_from_bytes ()

FuFirmware *
fu_firmware_new_from_bytes (GBytes *fw);

Creates a firmware object with the provided image set as default.

Parameters

fw

firmware blob image

 

Returns

a FuFirmware

Since: 1.3.1


fu_firmware_new_from_gtypes ()

FuFirmware *
fu_firmware_new_from_gtypes (GBytes *fw,
                             FwupdInstallFlags flags,
                             GError **error,
                             ...);

Tries to parse the firmware with each GType in order.

Parameters

fw

firmware blob

 

flags

install flags, e.g. FWUPD_INSTALL_FLAG_IGNORE_CHECKSUM

 

error

optional return location for an error.

[nullable]

...

an array of GTypes, ending with G_TYPE_INVALID

 

Returns

a FuFirmware, or NULL.

[transfer full][nullable]

Since: 1.5.6


fu_firmware_to_string ()

gchar *
fu_firmware_to_string (FuFirmware *self);

This allows us to easily print the object.

Parameters

self

a FuFirmware

 

Returns

a string value, or NULL for invalid.

Since: 1.3.1


fu_firmware_export ()

void
fu_firmware_export (FuFirmware *self,
                    FuFirmwareExportFlags flags,
                    XbBuilderNode *bn);

This allows us to build an XML object for the nested firmware.

Parameters

self

a FuFirmware

 

flags

firmware export flags, e.g. FU_FIRMWARE_EXPORT_FLAG_INCLUDE_DEBUG

 

bn

a Xmlb builder node

 

Since: 1.6.0


fu_firmware_export_to_xml ()

gchar *
fu_firmware_export_to_xml (FuFirmware *self,
                           FuFirmwareExportFlags flags,
                           GError **error);

This allows us to build an XML object for the nested firmware.

Parameters

self

a FuFirmware

 

flags

firmware export flags, e.g. FU_FIRMWARE_EXPORT_FLAG_INCLUDE_DEBUG

 

error

optional return location for an error.

[nullable]

Returns

a string value, or NULL for invalid.

Since: 1.6.0


fu_firmware_get_version ()

const gchar *
fu_firmware_get_version (FuFirmware *self);

Gets an optional version that represents the firmware.

Parameters

self

a FuFirmware

 

Returns

a string, or NULL

Since: 1.3.3


fu_firmware_set_version ()

void
fu_firmware_set_version (FuFirmware *self,
                         const gchar *version);

Sets an optional version that represents the firmware.

Parameters

self

a FuFirmware

 

version

optional string version.

[nullable]

Since: 1.3.3


fu_firmware_get_version_raw ()

guint64
fu_firmware_get_version_raw (FuFirmware *self);

Gets an raw version that represents the firmware. This is most frequently used when building firmware with <version_raw>0x123456</version_raw> in a firmware.builder.xml file to avoid string splitting and sanity checks.

Parameters

self

a FuFirmware

 

Returns

an integer, or G_MAXUINT64 for invalid

Since: 1.5.7


fu_firmware_set_version_raw ()

void
fu_firmware_set_version_raw (FuFirmware *self,
                             guint64 version_raw);

Sets an raw version that represents the firmware.

This is optional, and is typically only used for debugging.

Parameters

self

a FuFirmware

 

version_raw

a raw version, or G_MAXUINT64 for invalid

 

Since: 1.5.7


fu_firmware_add_flag ()

void
fu_firmware_add_flag (FuFirmware *firmware,
                      FuFirmwareFlags flag);

Adds a specific firmware flag to the firmware.

Parameters

firmware

a FuFirmware

 

flag

the firmware flag

 

Since: 1.5.0


fu_firmware_has_flag ()

gboolean
fu_firmware_has_flag (FuFirmware *firmware,
                      FuFirmwareFlags flag);

Finds if the firmware has a specific firmware flag.

Parameters

firmware

a FuFirmware

 

flag

the firmware flag

 

Returns

TRUE if the flag is set

Since: 1.5.0


fu_firmware_get_filename ()

const gchar *
fu_firmware_get_filename (FuFirmware *self);

Gets an optional filename that represents the image source or destination.

Parameters

self

a FuFirmware

 

Returns

a string, or NULL

Since: 1.6.0


fu_firmware_set_filename ()

void
fu_firmware_set_filename (FuFirmware *self,
                          const gchar *filename);

Sets an optional filename that represents the image source or destination.

Parameters

self

a FuFirmware

 

filename

a string filename.

[nullable]

Since: 1.6.0


fu_firmware_get_id ()

const gchar *
fu_firmware_get_id (FuFirmware *self);

Gets the image ID, typically set at construction.

Parameters

self

a FuPlugin

 

Returns

image ID, e.g. config

Since: 1.6.0


fu_firmware_set_id ()

void
fu_firmware_set_id (FuFirmware *self,
                    const gchar *id);

Parameters

self

a FuPlugin

 

id

image ID, e.g. config.

[nullable]

Since: 1.6.0


fu_firmware_get_addr ()

guint64
fu_firmware_get_addr (FuFirmware *self);

Gets the base address of the image.

Parameters

self

a FuPlugin

 

Returns

integer

Since: 1.6.0


fu_firmware_set_addr ()

void
fu_firmware_set_addr (FuFirmware *self,
                      guint64 addr);

Sets the base address of the image.

Parameters

self

a FuPlugin

 

addr

integer

 

Since: 1.6.0


fu_firmware_get_offset ()

guint64
fu_firmware_get_offset (FuFirmware *self);

Gets the base offset of the image.

Parameters

self

a FuPlugin

 

Returns

integer

Since: 1.6.0


fu_firmware_set_offset ()

void
fu_firmware_set_offset (FuFirmware *self,
                        guint64 offset);

Sets the base offset of the image.

Parameters

self

a FuPlugin

 

offset

integer

 

Since: 1.6.0


fu_firmware_get_size ()

gsize
fu_firmware_get_size (FuFirmware *self);

Gets the total size of the image, which is typically the same size as the data from fu_firmware_write().

If the size has not been explicitly set, and fu_firmware_set_bytes() has been used then the size of this is used instead.

Parameters

self

a FuPlugin

 

Returns

integer

Since: 1.6.0


fu_firmware_set_size ()

void
fu_firmware_set_size (FuFirmware *self,
                      gsize size);

Sets the total size of the image, which should be the same size as the data from fu_firmware_write().

Parameters

self

a FuPlugin

 

size

integer

 

Since: 1.6.0


fu_firmware_get_idx ()

guint64
fu_firmware_get_idx (FuFirmware *self);

Gets the index of the image which is used for ordering.

Parameters

self

a FuPlugin

 

Returns

integer

Since: 1.6.0


fu_firmware_set_idx ()

void
fu_firmware_set_idx (FuFirmware *self,
                     guint64 idx);

Sets the index of the image which is used for ordering.

Parameters

self

a FuPlugin

 

idx

integer

 

Since: 1.6.0


fu_firmware_get_bytes ()

GBytes *
fu_firmware_get_bytes (FuFirmware *self,
                       GError **error);

Gets the firmware payload, which does not have any header or footer included.

If there is more than one potential payload or image section then fu_firmware_add_image() should be used instead.

Parameters

self

a FuPlugin

 

error

optional return location for an error.

[nullable]

Returns

a GBytes, or NULL if the payload has never been set.

[transfer full]

Since: 1.6.0


fu_firmware_get_bytes_with_patches ()

GBytes *
fu_firmware_get_bytes_with_patches (FuFirmware *self,
                                    GError **error);

Gets the firmware payload, with any defined patches applied.

Parameters

self

a FuPlugin

 

error

optional return location for an error.

[nullable]

Returns

a GBytes, or NULL if the payload has never been set.

[transfer full]

Since: 1.7.4


fu_firmware_set_bytes ()

void
fu_firmware_set_bytes (FuFirmware *self,
                       GBytes *bytes);

Sets the contents of the image if not created with fu_firmware_new_from_bytes().

Parameters

self

a FuPlugin

 

bytes

data blob

 

Since: 1.6.0


fu_firmware_get_alignment ()

guint8
fu_firmware_get_alignment (FuFirmware *self);

Gets the alignment of the firmware.

This allows a firmware to pad to a power of 2 boundary, where alignment is the bit position to align to.

Parameters

self

a FuFirmware

 

Returns

integer

Since: 1.6.0


fu_firmware_set_alignment ()

void
fu_firmware_set_alignment (FuFirmware *self,
                           guint8 alignment);

Sets the alignment of the firmware.

This allows a firmware to pad to a power of 2 boundary, where alignment is the bit position to align to.

Parameters

self

a FuFirmware

 

alignment

integer, or 0 to disable

 

Since: 1.6.0


fu_firmware_add_chunk ()

void
fu_firmware_add_chunk (FuFirmware *self,
                       FuChunk *chk);

Adds a chunk to the image.

Parameters

self

a FuFirmware

 

chk

a FuChunk

 

Since: 1.6.0


fu_firmware_get_chunks ()

GPtrArray *
fu_firmware_get_chunks (FuFirmware *self,
                        GError **error);

Gets the optional image chunks.

Parameters

self

a FuFirmware

 

error

optional return location for an error.

[nullable]

Returns

chunk data, or NULL.

[transfer container][element-type FuChunk][nullable]

Since: 1.6.0


fu_firmware_tokenize ()

gboolean
fu_firmware_tokenize (FuFirmware *self,
                      GBytes *fw,
                      FwupdInstallFlags flags,
                      GError **error);

Tokenizes a firmware, typically breaking the firmware into records.

Records can be enumerated using subclass-specific functionality, for example using fu_srec_firmware_get_records().

Parameters

self

a FuFirmware

 

fw

firmware blob

 

flags

install flags, e.g. FWUPD_INSTALL_FLAG_FORCE

 

error

optional return location for an error.

[nullable]

Returns

TRUE for success

Since: 1.3.2


fu_firmware_build ()

gboolean
fu_firmware_build (FuFirmware *self,
                   XbNode *n,
                   GError **error);

Builds a firmware from an XML manifest. The manifest would typically have the following form:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?xml version="1.0" encoding="UTF-8"?>
<firmware gtype="FuBcm57xxFirmware">
  <version>1.2.3</version>
  <firmware gtype="FuBcm57xxStage1Image">
    <version>7.8.9</version>
    <id>stage1</id>
    <idx>0x01</idx>
    <filename>stage1.bin</filename>
  </firmware>
  <firmware gtype="FuBcm57xxStage2Image">
    <id>stage2</id>
    <data/> <!-- empty! -->
  </firmware>
  <firmware gtype="FuBcm57xxDictImage">
    <id>ape</id>
    <addr>0x7</addr>
    <data>aGVsbG8gd29ybGQ=</data> <!-- base64 -->
  </firmware>
</firmware>

This would be used in a build-system to merge images from generated files: fwupdtool firmware-build fw.builder.xml test.fw

Static binary content can be specified in the <firmware>/<data> section and is encoded as base64 text if not empty.

Additionally, extra nodes can be included under nested <firmware> objects which can be parsed by the subclassed objects. You should verify the subclassed object FuFirmware->build vfunc for the specific additional options supported.

Plugins should manually g_type_ensure() subclassed image objects if not constructed as part of the plugin fu_plugin_init() or fu_plugin_setup() functions.

Parameters

self

a FuFirmware

 

n

a Xmlb node

 

error

optional return location for an error.

[nullable]

Returns

TRUE for success

Since: 1.5.0


fu_firmware_build_from_xml ()

gboolean
fu_firmware_build_from_xml (FuFirmware *self,
                            const gchar *xml,
                            GError **error);

Builds a firmware from an XML manifest. The manifest would typically have the following form:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?xml version="1.0" encoding="UTF-8"?>
<firmware gtype="FuBcm57xxFirmware">
  <version>1.2.3</version>
  <firmware gtype="FuBcm57xxStage1Image">
    <version>7.8.9</version>
    <id>stage1</id>
    <idx>0x01</idx>
    <filename>stage1.bin</filename>
  </firmware>
  <firmware gtype="FuBcm57xxStage2Image">
    <id>stage2</id>
    <data/> <!-- empty! -->
  </firmware>
  <firmware gtype="FuBcm57xxDictImage">
    <id>ape</id>
    <addr>0x7</addr>
    <data>aGVsbG8gd29ybGQ=</data> <!-- base64 -->
  </firmware>
</firmware>

This would be used in a build-system to merge images from generated files: fwupdtool firmware-build fw.builder.xml test.fw

Static binary content can be specified in the <firmware>/<data> section and is encoded as base64 text if not empty.

Additionally, extra nodes can be included under nested <firmware> objects which can be parsed by the subclassed objects. You should verify the subclassed object FuFirmware->build vfunc for the specific additional options supported.

Plugins should manually g_type_ensure() subclassed image objects if not constructed as part of the plugin fu_plugin_init() or fu_plugin_setup() functions.

Parameters

self

a FuFirmware

 

xml

XML text

 

error

optional return location for an error.

[nullable]

Returns

TRUE for success

Since: 1.6.0


fu_firmware_parse ()

gboolean
fu_firmware_parse (FuFirmware *self,
                   GBytes *fw,
                   FwupdInstallFlags flags,
                   GError **error);

Parses a firmware, typically breaking the firmware into images.

Parameters

self

a FuFirmware

 

fw

firmware blob

 

flags

install flags, e.g. FWUPD_INSTALL_FLAG_FORCE

 

error

optional return location for an error.

[nullable]

Returns

TRUE for success

Since: 1.3.1


fu_firmware_parse_file ()

gboolean
fu_firmware_parse_file (FuFirmware *self,
                        GFile *file,
                        FwupdInstallFlags flags,
                        GError **error);

Parses a firmware file, typically breaking the firmware into images.

Parameters

self

a FuFirmware

 

file

a file

 

flags

install flags, e.g. FWUPD_INSTALL_FLAG_FORCE

 

error

optional return location for an error.

[nullable]

Returns

TRUE for success

Since: 1.3.3


fu_firmware_parse_full ()

gboolean
fu_firmware_parse_full (FuFirmware *self,
                        GBytes *fw,
                        guint64 addr_start,
                        guint64 addr_end,
                        FwupdInstallFlags flags,
                        GError **error);

Parses a firmware, typically breaking the firmware into images.

Parameters

self

a FuFirmware

 

fw

firmware blob

 

addr_start

start address, useful for ignoring a bootloader

 

addr_end

end address, useful for ignoring config bytes

 

flags

install flags, e.g. FWUPD_INSTALL_FLAG_FORCE

 

error

optional return location for an error.

[nullable]

Returns

TRUE for success

Since: 1.3.1


fu_firmware_write ()

GBytes *
fu_firmware_write (FuFirmware *self,
                   GError **error);

Writes a firmware, typically packing the images into a binary blob.

Parameters

self

a FuFirmware

 

error

optional return location for an error.

[nullable]

Returns

a data blob.

[transfer full]

Since: 1.3.1


fu_firmware_write_chunk ()

GBytes *
fu_firmware_write_chunk (FuFirmware *self,
                         guint64 address,
                         guint64 chunk_sz_max,
                         GError **error);

Gets a block of data from the image. If the contents of the image is smaller than the requested chunk size then the GBytes will be smaller than chunk_sz_max . Use fu_common_bytes_pad() if padding is required.

If the address is larger than the size of the image then an error is returned.

Parameters

self

a FuFirmware

 

address

an address smaller than fu_firmware_get_addr()

 

chunk_sz_max

the size of the new chunk

 

error

optional return location for an error.

[nullable]

Returns

a GBytes, or NULL.

[transfer full]

Since: 1.6.0


fu_firmware_write_file ()

gboolean
fu_firmware_write_file (FuFirmware *self,
                        GFile *file,
                        GError **error);

Writes a firmware, typically packing the images into a binary blob.

Parameters

self

a FuFirmware

 

file

a file

 

error

optional return location for an error.

[nullable]

Returns

TRUE for success

Since: 1.3.3


fu_firmware_get_checksum ()

gchar *
fu_firmware_get_checksum (FuFirmware *self,
                          GChecksumType csum_kind,
                          GError **error);

Returns a checksum of the payload data.

Parameters

self

a FuPlugin

 

csum_kind

a checksum type, e.g. G_CHECKSUM_SHA256

 

error

optional return location for an error.

[nullable]

Returns

a checksum string, or NULL if the checksum is not available.

[transfer full]

Since: 1.6.0


fu_firmware_add_image ()

void
fu_firmware_add_image (FuFirmware *self,
                       FuFirmware *img);

Adds an image to the firmware.

If FU_FIRMWARE_FLAG_DEDUPE_ID is set, an image with the same ID is already present it is replaced.

Parameters

self

a FuPlugin

 

img

a child firmware image

 

Since: 1.3.1


fu_firmware_remove_image ()

gboolean
fu_firmware_remove_image (FuFirmware *self,
                          FuFirmware *img,
                          GError **error);

Remove an image from the firmware.

Parameters

self

a FuPlugin

 

img

a child firmware image

 

error

optional return location for an error.

[nullable]

Returns

TRUE if the image was removed

Since: 1.5.0


fu_firmware_remove_image_by_idx ()

gboolean
fu_firmware_remove_image_by_idx (FuFirmware *self,
                                 guint64 idx,
                                 GError **error);

Removes the first image from the firmware matching the index.

Parameters

self

a FuPlugin

 

idx

index

 

error

optional return location for an error.

[nullable]

Returns

TRUE if an image was removed

Since: 1.5.0


fu_firmware_remove_image_by_id ()

gboolean
fu_firmware_remove_image_by_id (FuFirmware *self,
                                const gchar *id,
                                GError **error);

Removes the first image from the firmware matching the ID.

Parameters

self

a FuPlugin

 

id

image ID, e.g. config.

[nullable]

error

optional return location for an error.

[nullable]

Returns

TRUE if an image was removed

Since: 1.5.0


fu_firmware_get_images ()

GPtrArray *
fu_firmware_get_images (FuFirmware *self);

Returns all the images in the firmware.

Parameters

self

a FuFirmware

 

Returns

images.

[transfer container][element-type FuFirmware]

Since: 1.3.1


fu_firmware_get_image_by_id ()

FuFirmware *
fu_firmware_get_image_by_id (FuFirmware *self,
                             const gchar *id,
                             GError **error);

Gets the firmware image using the image ID.

Parameters

self

a FuPlugin

 

id

image ID, e.g. config.

[nullable]

error

optional return location for an error.

[nullable]

Returns

a FuFirmware, or NULL if the image is not found.

[transfer full]

Since: 1.3.1


fu_firmware_get_image_by_id_bytes ()

GBytes *
fu_firmware_get_image_by_id_bytes (FuFirmware *self,
                                   const gchar *id,
                                   GError **error);

Gets the firmware image bytes using the image ID.

Parameters

self

a FuPlugin

 

id

image ID, e.g. config.

[nullable]

error

optional return location for an error.

[nullable]

Returns

a GBytes of a FuFirmware, or NULL if the image is not found.

[transfer full]

Since: 1.3.1


fu_firmware_get_image_by_idx ()

FuFirmware *
fu_firmware_get_image_by_idx (FuFirmware *self,
                              guint64 idx,
                              GError **error);

Gets the firmware image using the image index.

Parameters

self

a FuPlugin

 

idx

image index

 

error

optional return location for an error.

[nullable]

Returns

a FuFirmware, or NULL if the image is not found.

[transfer full]

Since: 1.3.1


fu_firmware_get_image_by_idx_bytes ()

GBytes *
fu_firmware_get_image_by_idx_bytes (FuFirmware *self,
                                    guint64 idx,
                                    GError **error);

Gets the firmware image bytes using the image index.

Parameters

self

a FuPlugin

 

idx

image index

 

error

optional return location for an error.

[nullable]

Returns

a GBytes of a FuFirmware, or NULL if the image is not found.

[transfer full]

Since: 1.3.1


fu_firmware_get_image_by_checksum ()

FuFirmware *
fu_firmware_get_image_by_checksum (FuFirmware *self,
                                   const gchar *checksum,
                                   GError **error);

Gets the firmware image using the image checksum. The checksum type is guessed based on the length of the input string.

Parameters

self

a FuPlugin

 

checksum

checksum string of any format

 

error

optional return location for an error.

[nullable]

Returns

a FuFirmware, or NULL if the image is not found.

[transfer full]

Since: 1.5.5


fu_firmware_add_patch ()

void
fu_firmware_add_patch (FuFirmware *self,
                       gsize offset,
                       GBytes *blob);

Adds a byte patch at a specific offset. If a patch already exists at the specified address then it is replaced.

If the address is larger than the size of the image then an error is returned.

Parameters

self

a FuFirmware

 

offset

an address smaller than fu_firmware_get_size()

 

blob

bytes to replace.

[not nullable]

Since: 1.7.4

Types and Values

FU_TYPE_FIRMWARE

#define FU_TYPE_FIRMWARE (fu_firmware_get_type())

FU_FIRMWARE_EXPORT_FLAG_NONE

#define FU_FIRMWARE_EXPORT_FLAG_NONE (0u)

No flags set.

Since: 1.6.0


FU_FIRMWARE_EXPORT_FLAG_INCLUDE_DEBUG

#define FU_FIRMWARE_EXPORT_FLAG_INCLUDE_DEBUG (1u << 0)

Include debug information when exporting.

Since: 1.6.0


FU_FIRMWARE_EXPORT_FLAG_ASCII_DATA

#define FU_FIRMWARE_EXPORT_FLAG_ASCII_DATA (1u << 1)

Write the data as UTF-8 strings.

Since: 1.6.0


FuFirmwareExportFlags

typedef guint64 FuFirmwareExportFlags;

The firmware export flags.


struct FuFirmwareClass

struct FuFirmwareClass {
	GObjectClass parent_class;
	gboolean (*parse)(FuFirmware *self,
			  GBytes *fw,
			  guint64 addr_start,
			  guint64 addr_end,
			  FwupdInstallFlags flags,
			  GError **error) G_GNUC_WARN_UNUSED_RESULT;
	GBytes *(*write)(FuFirmware *self, GError **error)G_GNUC_WARN_UNUSED_RESULT;
	void (*export)(FuFirmware *self, FuFirmwareExportFlags flags, XbBuilderNode *bn);
	gboolean (*tokenize)(FuFirmware *self, GBytes *fw, FwupdInstallFlags flags, GError **error)
	    G_GNUC_WARN_UNUSED_RESULT;
	gboolean (*build)(FuFirmware *self, XbNode *n, GError **error) G_GNUC_WARN_UNUSED_RESULT;
	gchar *(*get_checksum)(FuFirmware *self,
			       GChecksumType csum_kind,
			       GError **error)G_GNUC_WARN_UNUSED_RESULT;
};

FU_FIRMWARE_FLAG_NONE

#define FU_FIRMWARE_FLAG_NONE (0u)

No flags set.

Since: 1.5.0


FU_FIRMWARE_FLAG_DEDUPE_ID

#define FU_FIRMWARE_FLAG_DEDUPE_ID (1u << 0)

Dedupe imges by ID.

Since: 1.5.0


FU_FIRMWARE_FLAG_DEDUPE_IDX

#define FU_FIRMWARE_FLAG_DEDUPE_IDX (1u << 1)

Dedupe imges by IDX.

Since: 1.5.0


FU_FIRMWARE_FLAG_HAS_CHECKSUM

#define FU_FIRMWARE_FLAG_HAS_CHECKSUM (1u << 2)

Has a CRC or checksum to test internal consistency.

Since: 1.5.6


FU_FIRMWARE_FLAG_HAS_VID_PID

#define FU_FIRMWARE_FLAG_HAS_VID_PID (1u << 3)

Has a vendor or product ID in the firmware.

Since: 1.5.6


FU_FIRMWARE_FLAG_DONE_PARSE

#define FU_FIRMWARE_FLAG_DONE_PARSE (1u << 4)

The firmware object has been used by fu_firmware_parse_full().

Since: 1.7.3


FuFirmwareFlags

typedef guint64 FuFirmwareFlags;

The firmware flags.


FU_FIRMWARE_ID_PAYLOAD

#define FU_FIRMWARE_ID_PAYLOAD "payload"

The usual firmware ID string for the payload.

Since: 1.6.0


FU_FIRMWARE_ID_SIGNATURE

#define FU_FIRMWARE_ID_SIGNATURE "signature"

The usual firmware ID string for the signature.

Since: 1.6.0


FU_FIRMWARE_ID_HEADER

#define FU_FIRMWARE_ID_HEADER "header"

The usual firmware ID string for the header.

Since: 1.6.0


FU_FIRMWARE_ALIGNMENT_1

#define FU_FIRMWARE_ALIGNMENT_1	   0x00

FU_FIRMWARE_ALIGNMENT_2

#define FU_FIRMWARE_ALIGNMENT_2	   0x01

FU_FIRMWARE_ALIGNMENT_4

#define FU_FIRMWARE_ALIGNMENT_4	   0x02

FU_FIRMWARE_ALIGNMENT_8

#define FU_FIRMWARE_ALIGNMENT_8	   0x03

FU_FIRMWARE_ALIGNMENT_16

#define FU_FIRMWARE_ALIGNMENT_16   0x04

FU_FIRMWARE_ALIGNMENT_32

#define FU_FIRMWARE_ALIGNMENT_32   0x05

FU_FIRMWARE_ALIGNMENT_64

#define FU_FIRMWARE_ALIGNMENT_64   0x06

FU_FIRMWARE_ALIGNMENT_128

#define FU_FIRMWARE_ALIGNMENT_128  0x07

FU_FIRMWARE_ALIGNMENT_256

#define FU_FIRMWARE_ALIGNMENT_256  0x08

FU_FIRMWARE_ALIGNMENT_512

#define FU_FIRMWARE_ALIGNMENT_512  0x09

FU_FIRMWARE_ALIGNMENT_1K

#define FU_FIRMWARE_ALIGNMENT_1K   0x0A

FU_FIRMWARE_ALIGNMENT_2K

#define FU_FIRMWARE_ALIGNMENT_2K   0x0B

FU_FIRMWARE_ALIGNMENT_4K

#define FU_FIRMWARE_ALIGNMENT_4K   0x0C

FU_FIRMWARE_ALIGNMENT_8K

#define FU_FIRMWARE_ALIGNMENT_8K   0x0D

FU_FIRMWARE_ALIGNMENT_16K

#define FU_FIRMWARE_ALIGNMENT_16K  0x0E

FU_FIRMWARE_ALIGNMENT_32K

#define FU_FIRMWARE_ALIGNMENT_32K  0x0F

FU_FIRMWARE_ALIGNMENT_64K

#define FU_FIRMWARE_ALIGNMENT_64K  0x10

FU_FIRMWARE_ALIGNMENT_128K

#define FU_FIRMWARE_ALIGNMENT_128K 0x11

FU_FIRMWARE_ALIGNMENT_256K

#define FU_FIRMWARE_ALIGNMENT_256K 0x12

FU_FIRMWARE_ALIGNMENT_512K

#define FU_FIRMWARE_ALIGNMENT_512K 0x13

FU_FIRMWARE_ALIGNMENT_1M

#define FU_FIRMWARE_ALIGNMENT_1M   0x14

FU_FIRMWARE_ALIGNMENT_2M

#define FU_FIRMWARE_ALIGNMENT_2M   0x15

FU_FIRMWARE_ALIGNMENT_4M

#define FU_FIRMWARE_ALIGNMENT_4M   0x16

FU_FIRMWARE_ALIGNMENT_8M

#define FU_FIRMWARE_ALIGNMENT_8M   0x17

FU_FIRMWARE_ALIGNMENT_16M

#define FU_FIRMWARE_ALIGNMENT_16M  0x18

FU_FIRMWARE_ALIGNMENT_32M

#define FU_FIRMWARE_ALIGNMENT_32M  0x19

FU_FIRMWARE_ALIGNMENT_64M

#define FU_FIRMWARE_ALIGNMENT_64M  0x1A

FU_FIRMWARE_ALIGNMENT_128M

#define FU_FIRMWARE_ALIGNMENT_128M 0x1B

FU_FIRMWARE_ALIGNMENT_256M

#define FU_FIRMWARE_ALIGNMENT_256M 0x1C

FU_FIRMWARE_ALIGNMENT_512M

#define FU_FIRMWARE_ALIGNMENT_512M 0x1D

FU_FIRMWARE_ALIGNMENT_1G

#define FU_FIRMWARE_ALIGNMENT_1G   0x1E

FU_FIRMWARE_ALIGNMENT_2G

#define FU_FIRMWARE_ALIGNMENT_2G   0x1F

FU_FIRMWARE_ALIGNMENT_4G

#define FU_FIRMWARE_ALIGNMENT_4G   0x20

FuFirmware

typedef struct _FuFirmware FuFirmware;

A firmware file which can have children which represent the images within.

See also: [classFuDfuFirmware ], [classFuIhexFirmware ], [classFuSrecFirmware ]