request_firmware API

You would typically load firmware and then load it into your device somehow.The typical firmware work flow is reflected below:

if(request_firmware(&fw_entry, $FIRMWARE, device) == 0)       copy_fw_to_device(fw_entry->data, fw_entry->size);release_firmware(fw_entry);

Synchronous firmware requests

Synchronous firmware requests will wait until the firmware is found or untilan error is returned.

request_firmware

intrequest_firmware(conststructfirmware**firmware_p,constchar*name,structdevice*device)

send firmware request and wait for it

Parameters

conststructfirmware**firmware_p

pointer to firmware image

constchar*name

name of firmware file

structdevice*device

device for which firmware is being loaded

Description

firmware_p will be used to return a firmware image by the nameofname for devicedevice.

Should be called from user context where sleeping is allowed.

name will be used as $FIRMWARE in the uevent environment andshould be distinctive enough not to be confused with any otherfirmware image for this or any other device.It must not contain any “..” path components - “foo/bar..bin” isallowed, but “foo/../bar.bin” is not.

Caller must hold the reference count ofdevice.

The function can be called safely inside device’s suspend andresume callback.

firmware_request_nowarn

intfirmware_request_nowarn(conststructfirmware**firmware,constchar*name,structdevice*device)

request for an optional fw module

Parameters

conststructfirmware**firmware

pointer to firmware image

constchar*name

name of firmware file

structdevice*device

device for which firmware is being loaded

Description

This function is similar in behaviour torequest_firmware(), except itdoesn’t produce warning messages when the file is not found. The sysfsfallback mechanism is enabled if direct filesystem lookup fails. However,failures to find the firmware file with it are still suppressed. It istherefore up to the driver to check for the return value of this call and todecide when to inform the users of errors.

firmware_request_platform

intfirmware_request_platform(conststructfirmware**firmware,constchar*name,structdevice*device)

request firmware with platform-fw fallback

Parameters

conststructfirmware**firmware

pointer to firmware image

constchar*name

name of firmware file

structdevice*device

device for which firmware is being loaded

Description

This function is similar in behaviour to request_firmware, except that ifdirect filesystem lookup fails, it will fallback to looking for a copy of therequested firmware embedded in the platform’s main (e.g. UEFI) firmware.

request_firmware_direct

intrequest_firmware_direct(conststructfirmware**firmware_p,constchar*name,structdevice*device)

load firmware directly without usermode helper

Parameters

conststructfirmware**firmware_p

pointer to firmware image

constchar*name

name of firmware file

structdevice*device

device for which firmware is being loaded

Description

This function works pretty much likerequest_firmware(), but this doesn’tfall back to usermode helper even if the firmware couldn’t be loadeddirectly from fs. Hence it’s useful for loading optional firmwares, whicharen’t always present, without extra long timeouts of udev.

request_firmware_into_buf

intrequest_firmware_into_buf(conststructfirmware**firmware_p,constchar*name,structdevice*device,void*buf,size_tsize)

load firmware into a previously allocated buffer

Parameters

conststructfirmware**firmware_p

pointer to firmware image

constchar*name

name of firmware file

structdevice*device

device for which firmware is being loaded and DMA region allocated

void*buf

address of buffer to load firmware into

size_tsize

size of buffer

Description

This function works pretty much likerequest_firmware(), but it doesn’tallocate a buffer to hold the firmware data. Instead, the firmwareis loaded directly into the buffer pointed to bybuf and thefirmware_pdata member is pointed atbuf.

This function doesn’t cache firmware either.

Asynchronous firmware requests

Asynchronous firmware requests allow driver code to not have to waituntil the firmware or an error is returned. Function callbacks areprovided so that when the firmware or an error is found the driver isinformed through the callback.request_firmware_nowait() cannot be calledin atomic contexts.

request_firmware_nowait

intrequest_firmware_nowait(structmodule*module,booluevent,constchar*name,structdevice*device,gfp_tgfp,void*context,void(*cont)(conststructfirmware*fw,void*context))

asynchronous version of request_firmware

Parameters

structmodule*module

module requesting the firmware

booluevent

sends uevent to copy the firmware image if this flagis non-zero else the firmware copy must be done manually.

constchar*name

name of firmware file

structdevice*device

device for which firmware is being loaded

gfp_tgfp

allocation flags

void*context

will be passed over tocont, andfw may beNULL if firmware request fails.

void(*cont)(conststructfirmware*fw,void*context)

function will be called asynchronously when the firmwarerequest is over.

Description

Caller must hold the reference count ofdevice.

Asynchronous variant of request_firmware() for user contexts:

  • sleep for as small periods as possible since it mayincrease kernel boot time of built-in device driversrequesting firmware in their ->probe() methods, ifgfp is GFP_KERNEL.

  • can’t sleep at all ifgfp is GFP_ATOMIC.

Special optimizations on reboot

Some devices have an optimization in place to enable the firmware to beretained during system reboot. When such optimizations are used the driverauthor must ensure the firmware is still available on resume from suspend,this can be done withfirmware_request_cache() instead of requesting for thefirmware to be loaded.

firmware_request_cache()

intfirmware_request_cache(structdevice*device,constchar*name)

cache firmware for suspend so resume can use it

Parameters

structdevice*device

device for which firmware should be cached for

constchar*name

name of firmware file

Description

There are some devices with an optimization that enables the device to notrequire loading firmware on system reboot. This optimization may stillrequire the firmware present on resume from suspend. This routine can beused to ensure the firmware is present on resume from suspend in thesesituations. This helper is not compatible with drivers which userequest_firmware_into_buf() orrequest_firmware_nowait() with no uevent set.

request firmware API expected driver use

Once an API call returns you process the firmware and then release thefirmware. For example if you usedrequest_firmware() and it returns,the driver has the firmware image accessible in fw_entry->{data,size}.If something went wrongrequest_firmware() returns non-zero and fw_entryis set to NULL. Once your driver is done with processing the firmware itcan call release_firmware(fw_entry) to release the firmware imageand any related resource.