Top | ![]() |
![]() |
![]() |
![]() |
const gchar *
fu_firmware_flag_to_string (FuFirmwareFlags flag
);
Converts a FuFirmwareFlags to a string.
Since: 1.5.0
FuFirmwareFlags
fu_firmware_flag_from_string (const gchar *flag
);
Converts a string to a FuFirmwareFlags.
Since: 1.5.0
FuFirmware *
fu_firmware_new (void
);
Creates an empty firmware object.
Since: 1.3.1
FuFirmware *
fu_firmware_new_from_bytes (GBytes *fw
);
Creates a firmware object with the provided image set as default.
Since: 1.3.1
FuFirmware * fu_firmware_new_from_gtypes (GBytes *fw
,FwupdInstallFlags flags
,GError **error
,...
);
Tries to parse the firmware with each GType in order.
fw |
firmware blob |
|
flags |
install flags, e.g. |
|
error |
optional return location for an error. |
[nullable] |
... |
an array of GTypes, ending with |
Since: 1.5.6
gchar *
fu_firmware_to_string (FuFirmware *self
);
This allows us to easily print the object.
Since: 1.3.1
void fu_firmware_export (FuFirmware *self
,FuFirmwareExportFlags flags
,XbBuilderNode *bn
);
This allows us to build an XML object for the nested firmware.
self |
||
flags |
firmware export flags, e.g. |
|
bn |
a Xmlb builder node |
Since: 1.6.0
gchar * fu_firmware_export_to_xml (FuFirmware *self
,FuFirmwareExportFlags flags
,GError **error
);
This allows us to build an XML object for the nested firmware.
self |
||
flags |
firmware export flags, e.g. |
|
error |
optional return location for an error. |
[nullable] |
Since: 1.6.0
const gchar *
fu_firmware_get_version (FuFirmware *self
);
Gets an optional version that represents the firmware.
Since: 1.3.3
void fu_firmware_set_version (FuFirmware *self
,const gchar *version
);
Sets an optional version that represents the firmware.
Since: 1.3.3
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.
Since: 1.5.7
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.
Since: 1.5.7
void fu_firmware_add_flag (FuFirmware *firmware
,FuFirmwareFlags flag
);
Adds a specific firmware flag to the firmware.
Since: 1.5.0
gboolean fu_firmware_has_flag (FuFirmware *firmware
,FuFirmwareFlags flag
);
Finds if the firmware has a specific firmware flag.
Since: 1.5.0
const gchar *
fu_firmware_get_filename (FuFirmware *self
);
Gets an optional filename that represents the image source or destination.
Since: 1.6.0
void fu_firmware_set_filename (FuFirmware *self
,const gchar *filename
);
Sets an optional filename that represents the image source or destination.
Since: 1.6.0
const gchar *
fu_firmware_get_id (FuFirmware *self
);
Gets the image ID, typically set at construction.
Since: 1.6.0
guint64
fu_firmware_get_addr (FuFirmware *self
);
Gets the base address of the image.
Since: 1.6.0
void fu_firmware_set_addr (FuFirmware *self
,guint64 addr
);
Sets the base address of the image.
Since: 1.6.0
guint64
fu_firmware_get_offset (FuFirmware *self
);
Gets the base offset of the image.
Since: 1.6.0
void fu_firmware_set_offset (FuFirmware *self
,guint64 offset
);
Sets the base offset of the image.
Since: 1.6.0
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.
Since: 1.6.0
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()
.
Since: 1.6.0
guint64
fu_firmware_get_idx (FuFirmware *self
);
Gets the index of the image which is used for ordering.
Since: 1.6.0
void fu_firmware_set_idx (FuFirmware *self
,guint64 idx
);
Sets the index of the image which is used for ordering.
Since: 1.6.0
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.
Since: 1.6.0
GBytes * fu_firmware_get_bytes_with_patches (FuFirmware *self
,GError **error
);
Gets the firmware payload, with any defined patches applied.
Since: 1.7.4
void fu_firmware_set_bytes (FuFirmware *self
,GBytes *bytes
);
Sets the contents of the image if not created with fu_firmware_new_from_bytes()
.
Since: 1.6.0
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.
Since: 1.6.0
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.
Since: 1.6.0
void fu_firmware_add_chunk (FuFirmware *self
,FuChunk *chk
);
Adds a chunk to the image.
Since: 1.6.0
GPtrArray * fu_firmware_get_chunks (FuFirmware *self
,GError **error
);
Gets the optional image chunks.
Since: 1.6.0
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()
.
self |
||
fw |
firmware blob |
|
flags |
install flags, e.g. |
|
error |
optional return location for an error. |
[nullable] |
Since: 1.3.2
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.
Since: 1.5.0
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.
Since: 1.6.0
gboolean fu_firmware_parse (FuFirmware *self
,GBytes *fw
,FwupdInstallFlags flags
,GError **error
);
Parses a firmware, typically breaking the firmware into images.
self |
||
fw |
firmware blob |
|
flags |
install flags, e.g. |
|
error |
optional return location for an error. |
[nullable] |
Since: 1.3.1
gboolean fu_firmware_parse_file (FuFirmware *self
,GFile *file
,FwupdInstallFlags flags
,GError **error
);
Parses a firmware file, typically breaking the firmware into images.
self |
||
file |
a file |
|
flags |
install flags, e.g. |
|
error |
optional return location for an error. |
[nullable] |
Since: 1.3.3
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.
self |
||
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. |
|
error |
optional return location for an error. |
[nullable] |
Since: 1.3.1
GBytes * fu_firmware_write (FuFirmware *self
,GError **error
);
Writes a firmware, typically packing the images into a binary blob.
Since: 1.3.1
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.
self |
||
address |
an address smaller than |
|
chunk_sz_max |
the size of the new chunk |
|
error |
optional return location for an error. |
[nullable] |
Since: 1.6.0
gboolean fu_firmware_write_file (FuFirmware *self
,GFile *file
,GError **error
);
Writes a firmware, typically packing the images into a binary blob.
Since: 1.3.3
gchar * fu_firmware_get_checksum (FuFirmware *self
,GChecksumType csum_kind
,GError **error
);
Returns a checksum of the payload data.
self |
a FuPlugin |
|
csum_kind |
a checksum type, e.g. |
|
error |
optional return location for an error. |
[nullable] |
Since: 1.6.0
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.
Since: 1.3.1
gboolean fu_firmware_remove_image (FuFirmware *self
,FuFirmware *img
,GError **error
);
Remove an image from the firmware.
self |
a FuPlugin |
|
img |
a child firmware image |
|
error |
optional return location for an error. |
[nullable] |
Since: 1.5.0
gboolean fu_firmware_remove_image_by_idx (FuFirmware *self
,guint64 idx
,GError **error
);
Removes the first image from the firmware matching the index.
Since: 1.5.0
gboolean fu_firmware_remove_image_by_id (FuFirmware *self
,const gchar *id
,GError **error
);
Removes the first image from the firmware matching the ID.
self |
a FuPlugin |
|
id |
image ID, e.g. |
[nullable] |
error |
optional return location for an error. |
[nullable] |
Since: 1.5.0
GPtrArray *
fu_firmware_get_images (FuFirmware *self
);
Returns all the images in the firmware.
Since: 1.3.1
FuFirmware * fu_firmware_get_image_by_id (FuFirmware *self
,const gchar *id
,GError **error
);
Gets the firmware image using the image ID.
self |
a FuPlugin |
|
id |
image ID, e.g. |
[nullable] |
error |
optional return location for an error. |
[nullable] |
Since: 1.3.1
GBytes * fu_firmware_get_image_by_id_bytes (FuFirmware *self
,const gchar *id
,GError **error
);
Gets the firmware image bytes using the image ID.
self |
a FuPlugin |
|
id |
image ID, e.g. |
[nullable] |
error |
optional return location for an error. |
[nullable] |
Since: 1.3.1
FuFirmware * fu_firmware_get_image_by_idx (FuFirmware *self
,guint64 idx
,GError **error
);
Gets the firmware image using the image index.
Since: 1.3.1
GBytes * fu_firmware_get_image_by_idx_bytes (FuFirmware *self
,guint64 idx
,GError **error
);
Gets the firmware image bytes using the image index.
Since: 1.3.1
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.
self |
a FuPlugin |
|
checksum |
checksum string of any format |
|
error |
optional return location for an error. |
[nullable] |
Since: 1.5.5
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.
self |
||
offset |
an address smaller than |
|
blob |
bytes to replace. |
[not nullable] |
Since: 1.7.4
#define FU_FIRMWARE_EXPORT_FLAG_INCLUDE_DEBUG (1u << 0)
Include debug information when exporting.
Since: 1.6.0
#define FU_FIRMWARE_EXPORT_FLAG_ASCII_DATA (1u << 1)
Write the data as UTF-8 strings.
Since: 1.6.0
struct FuFirmwareClass { GObjectClass parent_class; gboolean (*parse)(FuFirmware *self, GBytes *fw, guint64 addr_start, guint64 addr_end, FwupdInstallFlags flags, GError **error); 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); gboolean (*build)(FuFirmware *self, XbNode *n, GError **error); gchar *(*get_checksum)(FuFirmware *self, GChecksumType csum_kind, GError **error)G_GNUC_WARN_UNUSED_RESULT; };
#define FU_FIRMWARE_FLAG_DEDUPE_ID (1u << 0)
Dedupe imges by ID.
Since: 1.5.0
#define FU_FIRMWARE_FLAG_DEDUPE_IDX (1u << 1)
Dedupe imges by IDX.
Since: 1.5.0
#define FU_FIRMWARE_FLAG_HAS_CHECKSUM (1u << 2)
Has a CRC or checksum to test internal consistency.
Since: 1.5.6
#define FU_FIRMWARE_FLAG_HAS_VID_PID (1u << 3)
Has a vendor or product ID in the firmware.
Since: 1.5.6
#define FU_FIRMWARE_FLAG_DONE_PARSE (1u << 4)
The firmware object has been used by fu_firmware_parse_full()
.
Since: 1.7.3
#define FU_FIRMWARE_ID_PAYLOAD "payload"
The usual firmware ID string for the payload.
Since: 1.6.0
#define FU_FIRMWARE_ID_SIGNATURE "signature"
The usual firmware ID string for the signature.
Since: 1.6.0
#define FU_FIRMWARE_ID_HEADER "header"
The usual firmware ID string for the header.
Since: 1.6.0