[PATCH v3 net-next 5/5] net: wwan: t7xx: Devlink documentation

[Kumar, M Chetan]

On 1/7/2023 12:07 AM, Jesse Brandeburg wrote:
> On 1/6/2023 8:28 AM, m.chetan.kumar at linux.intel.com wrote:
>> From: M Chetan Kumar <m.chetan.kumar at linux.intel.com>
>>
>> Document the t7xx devlink commands usage for fw flashing &
> 
> it would make the documentation easier and faster to read if you just 
> spelled out fw as firmware.

Sure. Will correct all such instances.

> 
>> coredump collection.
>>
>> Refer to t7xx.rst file for details.
>>
>> Signed-off-by: M Chetan Kumar <m.chetan.kumar at linux.intel.com>
>> Signed-off-by: Devegowda Chandrashekar 
>> <chandrashekar.devegowda at intel.com>
>> -- 
>> v3:
>>   * No Change.
>> v2:
>>   * Documentation correction.
>>   * Add param details.
>> ---
>>   Documentation/networking/devlink/index.rst |   1 +
>>   Documentation/networking/devlink/t7xx.rst  | 161 +++++++++++++++++++++
>>   2 files changed, 162 insertions(+)
>>   create mode 100644 Documentation/networking/devlink/t7xx.rst
>>
>> diff --git a/Documentation/networking/devlink/index.rst 
>> b/Documentation/networking/devlink/index.rst
>> index fee4d3968309..0c4f5961e78f 100644
>> --- a/Documentation/networking/devlink/index.rst
>> +++ b/Documentation/networking/devlink/index.rst
>> @@ -66,3 +66,4 @@ parameters, info versions, and other features it 
>> supports.
>>      prestera
>>      iosm
>>      octeontx2
>> +   t7xx
>> diff --git a/Documentation/networking/devlink/t7xx.rst 
>> b/Documentation/networking/devlink/t7xx.rst
>> new file mode 100644
>> index 000000000000..de220878ad76
>> --- /dev/null
>> +++ b/Documentation/networking/devlink/t7xx.rst
>> @@ -0,0 +1,161 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +====================
>> +t7xx devlink support
>> +====================
>> +
>> +This document describes the devlink features implemented by the ``t7xx``
>> +device driver.
>> +
>> +Parameters
>> +==========
>> +The ``t7xx_driver`` driver implements the following driver-specific 
>> parameters.
>> +
>> +.. list-table:: Driver-specific parameters implemented
>> +   :widths: 5 5 5 85
>> +
>> +   * - Name
>> +     - Type
>> +     - Mode
>> +     - Description
>> +   * - ``fastboot``
>> +     - boolean
>> +     - driverinit
>> +     - Set this param to enter fastboot mode.
>> +
>> +Flash Update
>> +============
>> +
>> +The ``t7xx`` driver implements the flash update using the 
>> ``devlink-flash``
>> +interface.
>> +
>> +The driver uses DEVLINK_SUPPORT_FLASH_UPDATE_COMPONENT to identify 
>> the type of
>> +firmware image that need to be programmed upon the request by user 
>> space application.
>> +
>> +The supported list of firmware image types is described below.
>> +
>> +.. list-table:: Firmware Image types
>> +    :widths: 15 85
>> +
>> +    * - Name
>> +      - Description
>> +    * - ``preloader``
>> +      - The first-stage bootloader image
>> +    * - ``loader_ext1``
>> +      - Preloader extension image
>> +    * - ``tee1``
>> +      - ARM trusted firmware and TEE (Trusted Execution Environment) 
>> image
>> +    * - ``lk``
>> +      - The second-stage bootloader image
>> +    * - ``spmfw``
>> +      - MediaTek in-house ASIC for power management image
>> +    * - ``sspm_1``
>> +      - MediaTek in-house ASIC for power management under secure 
>> world image
>> +    * - ``mcupm_1``
>> +      - MediaTek in-house ASIC for cpu power management image
>> +    * - ``dpm_1``
>> +      - MediaTek in-house ASIC for dram power management image
>> +    * - ``boot``
>> +      - The kernel and dtb image
>> +    * - ``rootfs``
>> +      - Root filesystem image
>> +    * - ``md1img``
>> +      - Modem image
>> +    * - ``md1dsp``
>> +      - Modem DSP image
>> +    * - ``mcf1``
>> +      - Modem OTA image (Modem Configuration Framework) for operators
>> +    * - ``mcf2``
>> +      - Modem OTA image (Modem Configuration Framework) for OEM vendors
>> +    * - ``mcf3``
>> +      - Modem OTA image (other usage) for OEM configurations
>> +
>> +``t7xx`` driver uses fastboot protocol for fw flashing. In the fw 
>> flashing
> 
> it would make the documentation easier and faster to read if you just 
> spelled out fw as firmware.
> 
>> +procedure, fastboot command & response are exchanged between driver 
>> and wwan
>> +device.
>> +
>> +The wwan device is put into fastboot mode via devlink reload command, by
>> +passing "driver_reinit" action.
>> +
>> +$ devlink dev reload pci/0000:$bdf action driver_reinit
>> +
>> +Upon completion of fw flashing or coredump collection the wwan device is
>> +reset to normal mode using devlink reload command, by passing 
>> "fw_activate"
>> +action.
>> +
>> +$ devlink dev reload pci/0000:$bdf action fw_activate
>> +
>> +Flash Commands:
>> +===============
>> +
>> +$ devlink dev flash pci/0000:$bdf file 
>> preloader_k6880v1_mdot2_datacard.bin component "preloader"
>> +
>> +$ devlink dev flash pci/0000:$bdf file loader_ext-verified.img 
>> component "loader_ext1"
>> +
>> +$ devlink dev flash pci/0000:$bdf file tee-verified.img component "tee1"
>> +
>> +$ devlink dev flash pci/0000:$bdf file lk-verified.img component "lk"
>> +
>> +$ devlink dev flash pci/0000:$bdf file spmfw-verified.img component 
>> "spmfw"
>> +
>> +$ devlink dev flash pci/0000:$bdf file sspm-verified.img component 
>> "sspm_1"
>> +
>> +$ devlink dev flash pci/0000:$bdf file mcupm-verified.img component 
>> "mcupm_1"
>> +
>> +$ devlink dev flash pci/0000:$bdf file dpm-verified.img component 
>> "dpm_1"
>> +
>> +$ devlink dev flash pci/0000:$bdf file boot-verified.img component 
>> "boot"
>> +
>> +$ devlink dev flash pci/0000:$bdf file root.squashfs component "rootfs"
>> +
>> +$ devlink dev flash pci/0000:$bdf file modem-verified.img component 
>> "md1img"
>> +
>> +$ devlink dev flash pci/0000:$bdf file dsp-verified.bin component 
>> "md1dsp"
>> +
>> +$ devlink dev flash pci/0000:$bdf file OP_OTA.img component "mcf1"
>> +
>> +$ devlink dev flash pci/0000:$bdf file OEM_OTA.img component "mcf2"
>> +
>> +$ devlink dev flash pci/0000:$bdf file DEV_OTA.img component "mcf3"
>> +
>> +Note: Component selects the partition type to be programmed.
>> +
>> +Regions
>> +=======
>> +
>> +The ``t7xx`` driver supports core dump collection when device encounters
>> +an exception. When wwan device encounters an exception, a snapshot of 
>> device
>> +internal data will be taken by the driver using fastboot commands.
>> +
>> +Following regions are accessed for device internal data.
>> +
>> +.. list-table:: Regions implemented
>> +    :widths: 15 85
>> +
>> +    * - Name
>> +      - Description
>> +    * - ``mr_dump``
>> +      - The detailed modem component logs are captured in this region
>> +    * - ``lk_dump``
>> +      - This region dumps the current snapshot of lk
>> +
>> +
>> +Region commands
>> +===============
>> +
>> +$ devlink region show
>> +
>> +
>> +$ devlink region new mr_dump
>> +
>> +$ devlink region read mr_dump snapshot 0 address 0 length $len
>> +
>> +$ devlink region del mr_dump snapshot 0
>> +
>> +$ devlink region new lk_dump
>> +
>> +$ devlink region read lk_dump snapshot 0 address 0 length $len
>> +
>> +$ devlink region del lk_dump snapshot 0
>> +
>> +Note: $len is actual len to be dumped.
> 

-- 
Chetan