Firmware Upload API

Firmware Upload API 개요

이 문서는 `GPL-2.0` SPDX license identifier를 사용하며 제목은 `Firmware Upload API`입니다.

Firmware loader에 등록한 device driver는 사용자가 해당 device의 firmware update를 시작할 수 있도록 persistent sysfs node를 노출합니다.

받은 data의 유효성을 검사할 책임은 device driver와 device 자체에 있습니다.

Firmware upload는 firmware fallback 문서에서 설명한 것과 같은 `loading` 및 `data` sysfs file을 사용합니다. 여기에 firmware image를 device로 전송하는 상태를 제공하는 추가 sysfs file도 노출합니다.

Firmware upload 등록과 전송 시작

Device driver는 `firmware_upload_register()`를 호출해 firmware upload에 등록합니다. Parameter에는 `/sys/class/firmware` 아래에서 device를 식별할 이름이 포함됩니다.

사용자는 target device의 `loading` sysfs file에 1을 echo해 upload를 시작하고, 이어서 `data` sysfs file에 firmware image를 씁니다. Firmware data 기록이 끝나면 `loading`에 0을 echo해 완료를 알립니다.

`loading`에 0을 쓰면 kernel worker thread context에서 firmware를 lower-level device driver로 전송하는 작업도 시작됩니다.

Upload driver 구현 예제

Firmware upload API를 사용하려면 operation 집합을 구현하는 driver를 작성합니다. Probe function은 `firmware_upload_register()`를 호출하고 remove function은 `firmware_upload_unregister()`를 호출합니다.

예제는 `prepare`, `write`, `poll_complete`, `cancel`, `cleanup` callback으로 `m10bmc_ops`를 구성합니다. Probe에서는 private data와 firmware name을 준비해 upload object를 등록하고, remove에서는 등록 해제 뒤 이름 memory를 해제합니다.

static const struct fw_upload_ops m10bmc_ops = {
        .prepare = m10bmc_sec_prepare,
        .write = m10bmc_sec_write,
        .poll_complete = m10bmc_sec_poll_complete,
        .cancel = m10bmc_sec_cancel,
        .cleanup = m10bmc_sec_cleanup,
};

static int m10bmc_sec_probe(struct platform_device *pdev)
{
        const char *fw_name, *truncate;
        struct m10bmc_sec *sec;
        struct fw_upload *fwl;
        unsigned int len;

        sec = devm_kzalloc(&pdev->dev, sizeof(*sec), GFP_KERNEL);
        if (!sec)
                return -ENOMEM;

        sec->dev = &pdev->dev;
        sec->m10bmc = dev_get_drvdata(pdev->dev.parent);
        dev_set_drvdata(&pdev->dev, sec);

        fw_name = dev_name(sec->dev);
        truncate = strstr(fw_name, ".auto");
        len = (truncate) ? truncate - fw_name : strlen(fw_name);
        sec->fw_name = kmemdup_nul(fw_name, len, GFP_KERNEL);

        fwl = firmware_upload_register(THIS_MODULE, sec->dev, sec->fw_name,
                                       &m10bmc_ops, sec);
        if (IS_ERR(fwl)) {
                dev_err(sec->dev, "Firmware Upload driver failed to start\n");
                kfree(sec->fw_name);
                return PTR_ERR(fwl);
        }

        sec->fwl = fwl;
        return 0;
}

static int m10bmc_sec_remove(struct platform_device *pdev)
{
        struct m10bmc_sec *sec = dev_get_drvdata(&pdev->dev);

        firmware_upload_unregister(sec->fwl);
        kfree(sec->fw_name);
        return 0;
}

Register·unregister API와 ops

`firmware_upload_register`와 `firmware_upload_unregister`의 kernel-doc은 `drivers/base/firmware_loader/sysfs_upload.c`에서 가져옵니다.

.. kernel-doc:: drivers/base/firmware_loader/sysfs_upload.c
   :identifiers: firmware_upload_register

.. kernel-doc:: drivers/base/firmware_loader/sysfs_upload.c
   :identifiers: firmware_upload_unregister

Firmware upload operation 집합인 `fw_upload_ops`의 kernel-doc은 `include/linux/firmware.h`에서 가져옵니다.

.. kernel-doc:: include/linux/firmware.h
   :identifiers: fw_upload_ops

Progress code와 error code

Firmware loader는 `fw_upload_prog` progress code를 내부적으로 사용합니다. 대응하는 string은 아래에서 설명하는 `status` sysfs node로 보고되며 ABI 문서에도 정의되어 있습니다.

.. kernel-doc:: drivers/base/firmware_loader/sysfs_upload.h
   :identifiers: fw_upload_prog

Driver operation이 실패하면 `fw_upload_err` error code를 반환할 수 있습니다.

.. kernel-doc:: include/linux/firmware.h
   :identifiers: fw_upload_err

Firmware upload sysfs attribute

`loading`과 `data` 이외에도 target device로의 data transfer 상태와 최종 성공·실패를 확인하는 sysfs file을 제공합니다. Device와 firmware image 크기에 따라 update는 수 millisecond에서 수 minute까지 걸릴 수 있습니다.

• `status`: firmware update 진행 상태를 표시합니다.
• `error`: 실패한 firmware update의 error 정보를 제공합니다.
• `remaining_size`: update 중 data transfer 부분의 남은 크기를 추적합니다.
• `cancel`: 이 file에 1을 echo하면 update를 취소합니다.