Re: [PATCH net-next v3 03/10] ethtool: Add an interface for flashing transceiver modules' firmware

[Bagas Sanjaya]

On Wed, Apr 17, 2024 at 11:53:40AM +0300, Danielle Ratson wrote:
> +MODULE_FW_FLASH_ACT
> +===================
> +
> +Flashes transceiver module firmware.
> +
> +Request contents:
> +
> +  =======================================  ======  ===========================
> +  ``ETHTOOL_A_MODULE_FW_FLASH_HEADER``     nested  request header
> +  ``ETHTOOL_A_MODULE_FW_FLASH_FILE_NAME``  string  firmware image file name
> +  ``ETHTOOL_A_MODULE_FW_FLASH_PASSWORD``   u32     transceiver module password
> +  =======================================  ======  ===========================
> +
> +The firmware update process is composed from three logical steps:
                          "... consists of ..."
> +
> +1. Downloading a firmware image to the transceiver module and validating it.
> +2. Running the firmware image.
> +3. Committing the firmware image so that it is run upon reset.
> +
> +When flash command is given, those three steps are taken in that order.
> +
> +The ``ETHTOOL_A_MODULE_FW_FLASH_FILE_NAME`` attribute encodes the firmware
> +image file name. The firmware image is downloaded to the transceiver module,
> +validated, run and committed.
> +
> +The optional ``ETHTOOL_A_MODULE_FW_FLASH_PASSWORD`` attribute encodes a password
> +that might be required as part of the transceiver module firmware update
> +process.
> +
> +The firmware update process can take several minutes to complete. Therefore,
> +during the update process notifications are emitted from the kernel to user
> +space updating it about the status and progress.
> +
> +Notification contents:
> +
> + +---------------------------------------------------+--------+----------------+
> + | ``ETHTOOL_A_MODULE_FW_FLASH_HEADER``              | nested | reply header   |
> + +---------------------------------------------------+--------+----------------+
> + | ``ETHTOOL_A_MODULE_FW_FLASH_STATUS``              | u32    | status         |
> + +---------------------------------------------------+--------+----------------+
> + | ``ETHTOOL_A_MODULE_FW_FLASH_STATUS_MSG``          | string | status message |
> + +---------------------------------------------------+--------+----------------+
> + | ``ETHTOOL_A_MODULE_FW_FLASH_DONE``                | u64    | progress       |
> + +---------------------------------------------------+--------+----------------+
> + | ``ETHTOOL_A_MODULE_FW_FLASH_TOTAL``               | u64    | total          |
> + +---------------------------------------------------+--------+----------------+
> +
> +The ``ETHTOOL_A_MODULE_FW_FLASH_STATUS`` attribute encodes the current status
> +of the firmware update process. Possible values are:
> +
> +.. kernel-doc:: include/uapi/linux/ethtool.h
> +    :identifiers: ethtool_module_fw_flash_status
> +
> +The ``ETHTOOL_A_MODULE_FW_FLASH_STATUS_MSG`` attribute encodes a status message
> +string.
> +
> +The ``ETHTOOL_A_MODULE_FW_FLASH_DONE`` and ``ETHTOOL_A_MODULE_FW_FLASH_TOTAL``
> +attributes encode the completed and total amount of work, respectively.
> +

The rest of doc LGTM.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

Attachment: signature.asc
Description: PGP signature