fu-quirks: fwupd Reference Manual

## fu-quirks fu-quirks |

## Functions

void | (*FuQuirksIter) ()
FuQuirks * | fu_quirks_new ()
gboolean | fu_quirks_load ()
const gchar * | fu_quirks_lookup_by_id ()
gboolean | fu_quirks_lookup_by_id_iter ()
void | fu_quirks_add_possible_key ()

## Types and Values

#define | FU_TYPE_QUIRKS
enum | FuQuirksLoadFlags
#define | FU_QUIRKS_PLUGIN
#define | FU_QUIRKS_FLAGS
#define | FU_QUIRKS_SUMMARY
#define | FU_QUIRKS_ICON
#define | FU_QUIRKS_NAME
#define | FU_QUIRKS_BRANCH
#define | FU_QUIRKS_GUID
#define | FU_QUIRKS_COUNTERPART_GUID
#define | FU_QUIRKS_PARENT_GUID
#define | FU_QUIRKS_PROXY_GUID
#define | FU_QUIRKS_CHILDREN
#define | FU_QUIRKS_VERSION
#define | FU_QUIRKS_VENDOR
#define | FU_QUIRKS_VENDOR_ID
#define | FU_QUIRKS_FIRMWARE_SIZE_MIN
#define | FU_QUIRKS_FIRMWARE_SIZE_MAX
#define | FU_QUIRKS_FIRMWARE_SIZE
#define | FU_QUIRKS_INSTALL_DURATION
#define | FU_QUIRKS_VERSION_FORMAT
#define | FU_QUIRKS_GTYPE
#define | FU_QUIRKS_FIRMWARE_GTYPE
#define | FU_QUIRKS_PROTOCOL
#define | FU_QUIRKS_UPDATE_MESSAGE
#define | FU_QUIRKS_UPDATE_IMAGE
#define | FU_QUIRKS_PRIORITY
#define | FU_QUIRKS_BATTERY_THRESHOLD
#define | FU_QUIRKS_REMOVE_DELAY
#define | FU_QUIRKS_INHIBIT
| FuQuirks

## Description

## Functions

### FuQuirksIter ()

    void
    (*FuQuirksIter) (FuQuirks *self,
                     const gchar *key,
                     const gchar *value,
                     gpointer user_data);

The quirks iteration callback.

#### Parameters

self | a FuQuirks |
key | a key |
value | a value |
user_data | user data |

### fu_quirks_new ()

    FuQuirks *
    fu_quirks_new (void);

Creates a new quirks object.

[skip]

#### Returns

a new FuQuirks

Since: 1.0.1

### fu_quirks_load ()

    gboolean
    fu_quirks_load (FuQuirks *self,
                    FuQuirksLoadFlags load_flags,
                    GError **error);

Loads the various files that define the hardware quirks used in plugins.

[skip]

#### Parameters

self | a FuQuirks |
load_flags | load flags |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` for success

Since: 1.0.1

### fu_quirks_lookup_by_id ()

    const gchar *
    fu_quirks_lookup_by_id (FuQuirks *self,
                            const gchar *guid,
                            const gchar *key);

Looks up an entry in the hardware database using a string value.

#### Parameters

self | a FuQuirks |
guid | GUID to lookup |
key | an ID to match the entry, e.g. `Name` |

#### Returns

values from the database, or `NULL` if not found.

[transfer none]

Since: 1.0.1

### fu_quirks_lookup_by_id_iter ()

    gboolean
    fu_quirks_lookup_by_id_iter (FuQuirks *self,
                                 const gchar *guid,
                                 FuQuirksIter iter_cb,
                                 gpointer user_data);

Looks up all entries in the hardware database using a GUID value.

#### Parameters

self | a FuQuirks |
guid | GUID to lookup |
iter_cb | a function to call for each result. | [scope async]
user_data | user data passed to `iter_cb` |

#### Returns

`TRUE` if the ID was found, and `iter` was called

Since: 1.3.3

### fu_quirks_add_possible_key ()

    void
    fu_quirks_add_possible_key (FuQuirks *self,
                                const gchar *possible_key);

Adds a possible quirk key. If added by a plugin it should be namespaced using the plugin name, where possible.

#### Parameters

self | a FuQuirks |
possible_key | a key name, e.g. `Flags` |

Since: 1.5.8

## Types and Values

### FU_TYPE_QUIRKS

    #define FU_TYPE_QUIRKS (fu_quirks_get_type())

### enum FuQuirksLoadFlags

The flags to use when loading quirks.

#### Members

FU_QUIRKS_LOAD_FLAG_NONE | No flags set |
FU_QUIRKS_LOAD_FLAG_READONLY_FS | Ignore readonly filesystem errors |
FU_QUIRKS_LOAD_FLAG_NO_CACHE | Do not save to a persistent cache |
FU_QUIRKS_LOAD_FLAG_NO_VERIFY | Do not check the key files for errors |

### FU_QUIRKS_PLUGIN

    #define FU_QUIRKS_PLUGIN "Plugin"

The quirk key for the plugin name.

Since: 1.3.7

### FU_QUIRKS_FLAGS

    #define FU_QUIRKS_FLAGS "Flags"

The quirk key for the public flags.

Since: 1.3.7

### FU_QUIRKS_SUMMARY

    #define FU_QUIRKS_SUMMARY "Summary"

The quirk key for the summary.

Since: 1.3.7

### FU_QUIRKS_ICON

    #define FU_QUIRKS_ICON "Icon"

The quirk key for the icon.

Since: 1.3.7

### FU_QUIRKS_NAME

    #define FU_QUIRKS_NAME "Name"

The quirk key for the name.

Since: 1.3.7

### FU_QUIRKS_BRANCH

    #define FU_QUIRKS_BRANCH "Branch"

The quirk key for the firmware branch.

Since: 1.5.0

### FU_QUIRKS_GUID

    #define FU_QUIRKS_GUID "Guid"

The quirk key for the GUID.

Since: 1.3.7

### FU_QUIRKS_COUNTERPART_GUID

    #define FU_QUIRKS_COUNTERPART_GUID "CounterpartGuid"

The quirk key for the counterpart GUID.

Since: 1.3.7

### FU_QUIRKS_PARENT_GUID

    #define FU_QUIRKS_PARENT_GUID "ParentGuid"

The quirk key for the parent GUID.

Since: 1.3.7

### FU_QUIRKS_PROXY_GUID

    #define FU_QUIRKS_PROXY_GUID "ProxyGuid"

The quirk key for the proxy GUID.

Since: 1.4.1

### FU_QUIRKS_CHILDREN

    #define FU_QUIRKS_CHILDREN "Children"

The quirk key for the children. This should contain the custom GType.

Since: 1.3.7

### FU_QUIRKS_VERSION

    #define FU_QUIRKS_VERSION "Version"

The quirk key for the version.

Since: 1.3.7

### FU_QUIRKS_VENDOR

    #define FU_QUIRKS_VENDOR "Vendor"

The quirk key for the vendor name.

Since: 1.3.7

### FU_QUIRKS_VENDOR_ID

    #define FU_QUIRKS_VENDOR_ID "VendorId"

The quirk key for the vendor ID.

Since: 1.3.7

### FU_QUIRKS_FIRMWARE_SIZE_MIN

    #define FU_QUIRKS_FIRMWARE_SIZE_MIN "FirmwareSizeMin"

The quirk key for the minimum firmware size in bytes.

Since: 1.3.7

### FU_QUIRKS_FIRMWARE_SIZE_MAX

    #define FU_QUIRKS_FIRMWARE_SIZE_MAX "FirmwareSizeMax"

The quirk key for the maximum firmware size in bytes.

Since: 1.3.7

### FU_QUIRKS_FIRMWARE_SIZE

    #define FU_QUIRKS_FIRMWARE_SIZE "FirmwareSize"

The quirk key for the exact required firmware size in bytes.

Since: 1.3.7

### FU_QUIRKS_INSTALL_DURATION

    #define FU_QUIRKS_INSTALL_DURATION "InstallDuration"

The quirk key for the install duration in seconds.

Since: 1.3.7

### FU_QUIRKS_VERSION_FORMAT

    #define FU_QUIRKS_VERSION_FORMAT "VersionFormat"

The quirk key for the version format, e.g. `quad`.

Since: 1.3.7

### FU_QUIRKS_GTYPE

    #define FU_QUIRKS_GTYPE "GType"

The quirk key for the custom GType.

Since: 1.3.7

### FU_QUIRKS_FIRMWARE_GTYPE

    #define FU_QUIRKS_FIRMWARE_GTYPE "FirmwareGType"

The quirk key for the custom firmware GType.

Since: 1.7.2

### FU_QUIRKS_PROTOCOL

    #define FU_QUIRKS_PROTOCOL "Protocol"

The quirk key for the protocol, e.g. `org.usb.dfu`.

Since: 1.3.7

### FU_QUIRKS_UPDATE_MESSAGE

    #define FU_QUIRKS_UPDATE_MESSAGE "UpdateMessage"

The quirk key for the update message shown after the transaction has completed.

Since: 1.4.0

### FU_QUIRKS_UPDATE_IMAGE

    #define FU_QUIRKS_UPDATE_IMAGE "UpdateImage"

The quirk key for the update image shown before the update is performed.

Since: 1.5.0

### FU_QUIRKS_PRIORITY

    #define FU_QUIRKS_PRIORITY "Priority"

The quirk key for the device priority.

Since: 1.4.1

### FU_QUIRKS_BATTERY_THRESHOLD

    #define FU_QUIRKS_BATTERY_THRESHOLD "BatteryThreshold"

The quirk key for the battery threshold in percent.

Since: 1.6.0

### FU_QUIRKS_REMOVE_DELAY

    #define FU_QUIRKS_REMOVE_DELAY "RemoveDelay"

The quirk key for the device removal delay in seconds.

Since: 1.5.0

### FU_QUIRKS_INHIBIT

    #define FU_QUIRKS_INHIBIT "Inhibit"

The quirk key to inhibit the UPDATABLE flag and to set an update error.

Since: 1.6.2

### FuQuirks

    typedef struct _FuQuirks FuQuirks;

Quirks can be used to modify device behavior. When fwupd is installed in long-term support distros it's very hard to backport new versions as new hardware is released.

There are several reasons why we can't just include the mapping and quirk information in the AppStream metadata:

- The extra data is hugely specific to the installed fwupd plugin versions

- The device-id is per-device, and the mapping is usually per-plugin

- Often the information is needed before the FuDevice is created

- There are security implications in allowing plugins to handle new devices

The idea with quirks is that the end user can drop an additional (or replace an existing) file in a .d director with a simple format and the hardware will magically start working. This assumes no new quirks are required, as this would obviously need code changes, but allows us to get most existing devices working in an easy way without the user compiling anything.

See also: [class`FuDevice` ], [class`FuPlugin` ]