FuFirmware

FuFirmware — a firmware file

Functions

Types and Values

Description

An object that represents a firmware file. See also: FuDfuFirmware, FuIhexFirmware, FuSrecFirmware

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

A GBytes 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

a GBytes

 

flags

a FwupdInstallFlags, e.g. FWUPD_INSTALL_FLAG_IGNORE_CHECKSUM

 

error

a GError or NULL.

[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_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

A string version, or NULL

 

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 FuFirmwareFlags

 

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 FuFirmwareFlags

 

Returns

TRUE if the flag is set

Since: 1.5.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

A GBytes

 

flags

some FwupdInstallFlags, e.g. FWUPD_INSTALL_FLAG_FORCE

 

error

A GError, or NULL

 

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>
  <image gtype="FuBcm57xxStage1Image">
    <version>7.8.9</version>
    <id>stage1</id>
    <idx>0x01</idx>
    <filename>stage1.bin</filename>
  </image>
  <image gtype="FuBcm57xxStage2Image">
    <id>stage2</id>
    <data/> <!-- empty! -->
  </image>
  <image gtype="FuBcm57xxDictImage">
    <id>ape</id>
    <addr>0x7</addr>
    <data>aGVsbG8gd29ybGQ=</data> <!-- base64 -->
  </image>
</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 <image>/<data> sections and is encoded as base64 text if not empty.

Additionally, extra nodes can be included under <image> and <firmware> which can be parsed by the subclassed objects. You should verify the subclassed object FuFirmwareImage->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 XbNode

 

error

A GError, or NULL

 

Returns

TRUE for success

Since: 1.5.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

A GBytes

 

flags

some FwupdInstallFlags, e.g. FWUPD_INSTALL_FLAG_FORCE

 

error

A GError, or NULL

 

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 GFile

 

flags

some FwupdInstallFlags, e.g. FWUPD_INSTALL_FLAG_FORCE

 

error

A GError, or NULL

 

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

A GBytes

 

addr_start

Start address, useful for ignoring a bootloader

 

addr_end

End address, useful for ignoring config bytes

 

flags

some FwupdInstallFlags, e.g. FWUPD_INSTALL_FLAG_FORCE

 

error

A GError, or NULL

 

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

A GError, or NULL

 

Returns

a GBytes.

[transfer full]

Since: 1.3.1


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 GFile

 

error

A GError, or NULL

 

Returns

TRUE for success

Since: 1.3.3


fu_firmware_add_image ()

void
fu_firmware_add_image (FuFirmware *self,
                       FuFirmwareImage *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 FuFirmwareImage

 

Since: 1.3.1


fu_firmware_remove_image ()

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

Remove an image from the firmware.

Parameters

self

a FuPlugin

 

img

A FuFirmwareImage

 

error

A GError, or NULL

 

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

A GError, or NULL

 

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

A GError, or NULL

 

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 FuFirmwareImage]

Since: 1.3.1


fu_firmware_get_image_by_id ()

FuFirmwareImage *
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

A GError, or NULL

 

Returns

a FuFirmwareImage, 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

A GError, or NULL

 

Returns

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

[transfer full]

Since: 1.3.1


fu_firmware_get_image_by_idx ()

FuFirmwareImage *
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

A GError, or NULL

 

Returns

a FuFirmwareImage, 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

A GError, or NULL

 

Returns

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

[transfer full]

Since: 1.3.1


fu_firmware_get_image_by_checksum ()

FuFirmwareImage *
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

A GError, or NULL

 

Returns

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

[transfer full]

Since: 1.5.5


fu_firmware_get_image_default ()

FuFirmwareImage *
fu_firmware_get_image_default (FuFirmware *self,
                               GError **error);

Gets the default firmware image.

NOTE: If the firmware has multiple images included then fu_firmware_get_image_by_id() or fu_firmware_get_image_by_idx() must be used rather than this function.

Parameters

self

a FuPlugin

 

error

A GError, or NULL

 

Returns

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

[transfer full]

Since: 1.3.1


fu_firmware_get_image_default_bytes ()

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

Gets the default firmware image.

Parameters

self

a FuPlugin

 

error

A GError, or NULL

 

Returns

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

[transfer full]

Since: 1.3.1

Types and Values

FU_TYPE_FIRMWARE

#define FU_TYPE_FIRMWARE (fu_firmware_get_type ())

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			 (*to_string)		(FuFirmware *self,
							 guint		 indent,
							 GString *str);
	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;
};

FU_FIRMWARE_FLAG_NONE

#define FU_FIRMWARE_FLAG_NONE			(0u)		/* Since: 1.5.0 */

FU_FIRMWARE_FLAG_DEDUPE_ID

#define FU_FIRMWARE_FLAG_DEDUPE_ID		(1u << 0) /* Since: 1.5.0 */

FU_FIRMWARE_FLAG_DEDUPE_IDX

#define FU_FIRMWARE_FLAG_DEDUPE_IDX		(1u << 1) /* Since: 1.5.0 */

FU_FIRMWARE_FLAG_HAS_CHECKSUM

#define FU_FIRMWARE_FLAG_HAS_CHECKSUM		(1u << 2) /* Since: 1.5.6 */

FU_FIRMWARE_FLAG_HAS_VID_PID

#define FU_FIRMWARE_FLAG_HAS_VID_PID		(1u << 3) /* Since: 1.5.6 */

FuFirmwareFlags

typedef guint64 FuFirmwareFlags;

The firmware flags.


FuFirmware

typedef struct _FuFirmware FuFirmware;