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