fu-quirks

fu-quirks — device quirks

Functions

Types and Values

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 *prefix,
                        const gchar *id);

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

Parameters

self

A FuPlugin

 

prefix

A string prefix that matches the quirks file basename, e.g. "dfu-quirks"

 

id

An ID to match the entry, e.g. "012345"

 

Returns

values from the database, or NULL if not found.

[transfer none]

Since: 1.0.1


fu_quirks_lookup_by_glob ()

const gchar *
fu_quirks_lookup_by_glob (FuQuirks *self,
                          const gchar *prefix,
                          const gchar *glob);

Looks up an entry in the hardware database using a key glob. NOTE: This is *much* slower than using fu_quirks_lookup_by_id() as each key in the quirk database is compared.

Parameters

self

A FuPlugin

 

prefix

A string prefix that matches the quirks file basename, e.g. "dfu-quirks"

 

glob

An glob to match the entry, e.g. "foo*bar?baz"

 

Returns

values from the database, or NULL if not found.

[transfer none]

Since: 1.0.1


fu_quirks_lookup_by_usb_device ()

const gchar *
fu_quirks_lookup_by_usb_device (FuQuirks *self,
                                const gchar *prefix,
                                GUsbDevice *dev);

Looks up an entry in the hardware database using various keys generated from dev .

Parameters

self

A FuPlugin

 

prefix

A string prefix that matches the quirks file basename, e.g. "dfu-quirks"

 

dev

A GUsbDevice

 

Returns

values from the database, or NULL if not found.

[transfer none]

Since: 1.0.1

Types and Values

FU_TYPE_QUIRKS

#define FU_TYPE_QUIRKS (fu_quirks_get_type ())

FU_QUIRKS_DFU

#define FU_QUIRKS_DFU				"fwupd-dfu"

Assigns optional quirks to use for a DFU device which does not follow the DFU 1.0 or 1.1 specification. The list of supported quirks is thus:

  • none: No device quirks

  • action-required: User has to do something manually, e.g. press a button

  • attach-extra-reset: Device needs resetting twice for attach

  • attach-upload-download: An upload or download is required for attach

  • force-dfu-mode: Force DFU mode

  • ignore-invalid-version: Ignore invalid version numbers

  • ignore-polltimeout: Ignore the device download timeout

  • ignore-runtime: Device has broken DFU runtime support

  • ignore-upload: Uploading from the device is broken

  • no-dfu-runtime: No DFU runtime interface is provided

  • no-get-status-upload: Do not do GetStatus when uploading

  • no-pid-change: Accept the same VID:PID when changing modes

  • use-atmel-avr: Device uses the ATMEL bootloader

  • use-protocol-zero: Fix up the protocol number

Default value: none

Parameters

key

the USB device ID, e.g. USB\VID_0763&PID_2806

 

value

a string, separated using |, e.g. ignore-polltimeout|no-pid-change

 

Since: 1.0.1


FU_QUIRKS_UEFI_VERSION_FORMAT

#define FU_QUIRKS_UEFI_VERSION_FORMAT		"fwupd-uefi-version-format"

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		"fwupd-daemon-version-format"

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_DFU_JABRA_DETACH

#define FU_QUIRKS_DFU_JABRA_DETACH		"fwupd-dfu-jabra-detach"

Assigns the two magic bytes sent to the Jabra hardware when the device is in runtime mode to make it switch into DFU mode.

Parameters

key

the USB device ID, e.g. USB\VID_0763&PID_2806

 

value

the two uint8_t unlock values, encoded in base 16, e.g. 0201

 

Since: 1.0.1


FU_QUIRKS_DFU_ALTERNATE_VIDPID

#define FU_QUIRKS_DFU_ALTERNATE_VIDPID		"fwupd-dfu-alternate-vidpid"

Assigns the USB vendor ID and product ID when the device is in the alternate mode. For instance this can be used to set the application VID/PID when in DFU mode or the bootloader VID/PID when in application mode.

Parameters

key

the USB device ID, e.g. USB\VID_0763&PID_2806

 

value

the uint16_t VID and uint16_t PID values, encoded in base 16, e.g. 0B0E0411

 

Since: 1.0.1


FU_QUIRKS_DFU_AVR_CHIP_ID

#define FU_QUIRKS_DFU_AVR_CHIP_ID		"fwupd-dfu-avr-chip-id"

Assigns a sector description for the chip ID. This is required so fwupd can program the user firmware avoiding the bootloader and for checking the total element size.

The chip ID can be found from a datasheet or using dfu-tool list when the hardware is connected and in bootloader mode.

Parameters

key

the AVR chip ID, e.g. 0x58200204

 

value

the UM0424 sector description, e.g. @Flash/0x2000/1*248Kg

 

Since: 1.0.1


FuQuirks

typedef struct _FuQuirks FuQuirks;