fu-quirks: fwupd Reference Manual

## fu-quirks fu-quirks — device quirks |

## Functions

FuQuirks * | fu_quirks_new ()
gboolean | fu_quirks_load ()
const gchar * | fu_quirks_lookup_by_id ()
void | fu_quirks_add_value ()
gboolean | fu_quirks_get_kvs_for_guid ()

## Types and Values

#define | FU_TYPE_QUIRKS
#define | FU_QUIRKS_PLUGIN
#define | FU_QUIRKS_UEFI_VERSION_FORMAT
#define | FU_QUIRKS_DAEMON_VERSION_FORMAT
#define | FU_QUIRKS_FLAGS
#define | FU_QUIRKS_SUMMARY
#define | FU_QUIRKS_ICON
#define | FU_QUIRKS_NAME
#define | FU_QUIRKS_GUID
#define | FU_QUIRKS_COUNTERPART_GUID
#define | FU_QUIRKS_PARENT_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_INSTALL_DURATION
#define | FU_QUIRKS_VERSION_FORMAT
| FuQuirks

## Description

Quirks can be used to modify device behaviour. 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: FuDevice, FuPlugin

## Functions

### fu_quirks_new ()

    FuQuirks *
    fu_quirks_new (void);

Creates a new quirks object.

[skip]

#### Returns

a new FuQuirks

### fu_quirks_load ()

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

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

[skip]

#### Parameters

self | A FuQuirks |
error | A GError, or `NULL` |

#### Returns

`TRUE` for success

Since: 1.0.1

### fu_quirks_lookup_by_id ()

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

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

#### Parameters

self | A FuPlugin |
group | A string group, e.g. "DeviceInstanceId=USB\VID_1235&PID_AB11" |
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_add_value ()

    void
    fu_quirks_add_value (FuQuirks *self,
                         const gchar *group,
                         const gchar *key,
                         const gchar *value);

Adds a value to the quirk database. Normally this is achieved by loading a quirk file using `fu_quirks_load()`.

[skip]

#### Parameters

self | A FuQuirks |
group | group, e.g. `DeviceInstanceId=USB\VID_0BDA&amp;PID_1100` |
key | group, e.g. `Name` |
value | group, e.g. `Unknown Device` |

Since: 1.1.2

### fu_quirks_get_kvs_for_guid ()

    gboolean
    fu_quirks_get_kvs_for_guid (FuQuirks *self,
                                const gchar *guid,
                                GHashTableIter *iter);

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

#### Parameters

self | A FuPlugin |
guid | a GUID |
iter | A GHashTableIter, typically allocated on the stack by the caller |

#### Returns

`TRUE` if the GUID was found, and `iter` was set

Since: 1.1.2

## Types and Values

### FU_TYPE_QUIRKS

    #define FU_TYPE_QUIRKS (fu_quirks_get_type ())

### FU_QUIRKS_PLUGIN

    #define FU_QUIRKS_PLUGIN			"Plugin"

Sets the plugin to use for a specific hardware device.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the plugin name, e.g. `csr` |

Since: 1.1.0

### FU_QUIRKS_UEFI_VERSION_FORMAT

    #define FU_QUIRKS_UEFI_VERSION_FORMAT		"UefiVersionFormat"

Assigns the version format to use for a specific manufacturer. A specific version format is sometimes chosen to match the appearance of other systems or specifications.

Default value: `use-triplet`

#### Parameters

key | a `FU_HWIDS_KEY_MANUFACTURER`, e.g. `Alienware` |
value | the version format, e.g. `none` |

Since: 1.0.1

### FU_QUIRKS_DAEMON_VERSION_FORMAT

    #define FU_QUIRKS_DAEMON_VERSION_FORMAT		"ComponentIDs"

Assigns the version format to use for a specific AppStream component. A specific version format is sometimes chosen to match the appearance of other systems or specifications.

Default value: `use-triplet`

#### Parameters

key | the optionally wildcarded AppStream ID e.g. `com.dell.uefi*.firmware` |
value | the version format, e.g. `none` |

Since: 1.0.1

### FU_QUIRKS_FLAGS

    #define FU_QUIRKS_FLAGS				"Flags"

Assigns optional quirks to use for a 8Bitdo device. The list of supported quirks is thus:

- `none`: No device quirks

- `is-bootloader`: Device is in bootloader mode

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the quirk, e.g. `is-bootloader` |

Since: 1.0.3

### FU_QUIRKS_SUMMARY

    #define FU_QUIRKS_SUMMARY			"Summary"

Sets a name for a specific hardware device.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the USB device summary, e.g. `An open source display colorimeter` |

Since: 1.0.2

### FU_QUIRKS_ICON

    #define FU_QUIRKS_ICON				"Icon"

Adds an icon name for a specific hardware device.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the USB device icon name, e.g. `media-removable` |

Since: 1.0.2

### FU_QUIRKS_NAME

    #define FU_QUIRKS_NAME				"Name"

Sets a name for a specific hardware device.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the USB device name, e.g. `ColorHug` |

Since: 1.0.2

### FU_QUIRKS_GUID

    #define FU_QUIRKS_GUID				"Guid"

Adds an extra GUID for a specific hardware device. If the value provided is not already a suitable GUID, it will be converted to one.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the GUID, e.g. `537f7800-8529-5656-b2fa-b0901fe91696` |

Since: 1.0.3

### FU_QUIRKS_COUNTERPART_GUID

    #define FU_QUIRKS_COUNTERPART_GUID		"CounterpartGuid"

Adds an counterpart GUID for a specific hardware device. If the value provided is not already a suitable GUID, it will be converted to one.

A counterpart GUID is typically the GUID of the same device in bootloader or runtime mode, if they have a different device PCI or USB ID. Adding this type of GUID does not cause a "cascade" by matching using the quirk database.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the GUID, e.g. `537f7800-8529-5656-b2fa-b0901fe91696` |

Since: 1.1.2

### FU_QUIRKS_PARENT_GUID

    #define FU_QUIRKS_PARENT_GUID			"ParentGuid"

Adds an extra GUID to mark as the parent device. If the value provided is not already a suitable GUID, it will be converted to one.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the GUID, e.g. `537f7800-8529-5656-b2fa-b0901fe91696` |

Since: 1.1.2

### FU_QUIRKS_CHILDREN

    #define FU_QUIRKS_CHILDREN			"Children"

Adds one or more virtual devices to a physical device, delimited by comma.

To set the object type of the child device use a pipe before the object type, for instance: `FuRts54xxDevice|USB\VID_0763&amp;PID_2806&amp;I2C_01` If the type of device is not specified the parent device type is used.

If the values provided are not already suitable GUIDs, they will be converted.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the GUID, e.g. `USB\VID_0763&amp;PID_2806&amp;I2C_01` |

Since: 1.1.2

### FU_QUIRKS_VERSION

    #define FU_QUIRKS_VERSION			"Version"

Sets a version for a specific hardware device.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806&amp;REV_0001` |
value | the version number, e.g. `1.2` |

Since: 1.0.3

### FU_QUIRKS_VENDOR

    #define FU_QUIRKS_VENDOR			"Vendor"

Sets a vendor name for a specific hardware device.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the vendor, e.g. `Hughski Limited` |

Since: 1.0.3

### FU_QUIRKS_VENDOR_ID

    #define FU_QUIRKS_VENDOR_ID			"VendorId"

Sets a vendor ID for a specific hardware device.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the vendor, e.g. `USB:0x123A` |

Since: 1.1.2

### FU_QUIRKS_FIRMWARE_SIZE_MIN

    #define FU_QUIRKS_FIRMWARE_SIZE_MIN		"FirmwareSizeMin"

Sets the minimum allowed firmware size.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the vendor, e.g. `0x10000` |

Since: 1.1.2

### FU_QUIRKS_FIRMWARE_SIZE_MAX

    #define FU_QUIRKS_FIRMWARE_SIZE_MAX		"FirmwareSizeMax"

Sets the maximum allowed firmware size.

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the vendor, e.g. `0x10000` |

Since: 1.1.2

### FU_QUIRKS_INSTALL_DURATION

    #define FU_QUIRKS_INSTALL_DURATION		"InstallDuration"

Sets the estimated time to flash the device

#### Parameters

key | the USB device ID, e.g. `DeviceInstanceId=USB\VID_0763&amp;PID_2806` |
value | the estimated time for flashing the device in seconds |

Since: 1.1.3

### FU_QUIRKS_VERSION_FORMAT

    #define FU_QUIRKS_VERSION_FORMAT		"VersionFormat"

Sets the version format the device should use for conversion.

#### Parameters

key | the device ID, e.g. `HwId=USB\VID_0763&amp;PID_2806` |
value | the quirk format, e.g. `quad` |

Since: 1.2.0

### FuQuirks

    typedef struct _FuQuirks FuQuirks;