Subject: Re: [PATCH v5 net-next 5/5] net: wwan: t7xx: Devlink documentation

From: "Kumar, M Chetan" <[email-masked]>
Date: Tue, 24 Jan 2023 20:00:59 +0530

On 1/22/2023 7:43 AM, Bagas Sanjaya wrote:
> On Sat, Jan 21, 2023 at 07:03:58PM +0530, [email-masked] wrote:
>> +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"
> 
> It seems like you didn't describe what ``devlink dev flash`` commands above
> are doing, as I had requested from v3 review [1].
> 
>> +Coredump Collection
>> +~~~~~~~~~~~~~~~~~~~
>> +
>> +::
>> +
>> +  $ devlink region new mr_dump
>> +
>> +::
>> +
>> +  $ devlink region read mr_dump snapshot 0 address 0 length $len
>> +
>> +::
>> +
>> +  $ devlink region del mr_dump snapshot 0
>> +
>> +Note: $len is actual len to be dumped.
>> +
>> +The userspace application uses these commands for obtaining the modem component
>> +logs when device encounters an exception.
> 
> Individual command explanation please?
> 
>> +
>> +Second Stage Bootloader dump
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +::
>> +
>> +  $ 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.
>> +
>> +In fastboot mode the userspace application uses these commands for obtaining the
>> +current snapshot of second stage bootloader.
> 
> Individual command explanation please?
> 
> Hint: see any manpages to get sense of how to write the explanations.
> 
> Thanks.
> 
> [1]: https://lore.kernel.org/linux-doc/[email-masked]/

I have added the explanation for each of those commands and also have 
changed the format a bit.

Could you please take a look and suggest on below changes.

--- a/Documentation/networking/devlink/t7xx.rst
+++ b/Documentation/networking/devlink/t7xx.rst
@@ -54,65 +54,52 @@ action.
  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"
+.. code:: shell

-::
+    # Update device Preloader image
+    $ devlink dev flash pci/0000:$bdf file 
preloader_k6880v1_mdot2_datacard.bin component "preloader"

-  $ devlink dev flash pci/0000:$bdf file dpm-verified.img component "dpm_1"
+    # Update device Preloader extension image
+    $ devlink dev flash pci/0000:$bdf file loader_ext-verified.img 
component "loader_ext1"

-::
+    # Update device TEE (Trusted Execution Environment) image
+    $ devlink dev flash pci/0000:$bdf file tee-verified.img component 
"tee1"

-  $ devlink dev flash pci/0000:$bdf file boot-verified.img component "boot"
+    # Update device Second stage bootloader image
+    $ devlink dev flash pci/0000:$bdf file lk-verified.img component "lk"

-::
+    # Update device PM (Power Management) image
+    $ devlink dev flash pci/0000:$bdf file spmfw-verified.img component 
"spmfw"

-  $ devlink dev flash pci/0000:$bdf file root.squashfs component "rootfs"
-
-::
+    # Update device Secure PM image
+    $ devlink dev flash pci/0000:$bdf file sspm-verified.img component 
"sspm_1"

-  $ devlink dev flash pci/0000:$bdf file modem-verified.img component 
"md1img"
+    # Update device CPU PM image
+    $ devlink dev flash pci/0000:$bdf file mcupm-verified.img component 
"mcupm_1"

-::
+    # Update device DRAM PM image
+    $ devlink dev flash pci/0000:$bdf file dpm-verified.img component 
"dpm_1"

-  $ devlink dev flash pci/0000:$bdf file dsp-verified.bin component 
"md1dsp"
+    # Update Kernel image
+    $ devlink dev flash pci/0000:$bdf file boot-verified.img component 
"boot"

-::
+    # Update Root filesystem image
+    $ devlink dev flash pci/0000:$bdf file root.squashfs component "rootfs"

-  $ devlink dev flash pci/0000:$bdf file OP_OTA.img component "mcf1"
+    # Update Modem image
+    $ devlink dev flash pci/0000:$bdf file modem-verified.img component 
"md1img"

-::
+    # Update DSP image
+    $ devlink dev flash pci/0000:$bdf file dsp-verified.bin component 
"md1dsp"

-  $ devlink dev flash pci/0000:$bdf file OEM_OTA.img component "mcf2"
+    # Update Modem OTA image (operator specific)
+    $ devlink dev flash pci/0000:$bdf file OP_OTA.img component "mcf1"

-::
+    # Update Modem OTA image (vendor specific)
+    $ devlink dev flash pci/0000:$bdf file OEM_OTA.img component "mcf2"

-  $ devlink dev flash pci/0000:$bdf file DEV_OTA.img component "mcf3"
+    # Update Modem OTA image (vendor configurtions)
+    $ devlink dev flash pci/0000:$bdf file DEV_OTA.img component "mcf3"

  Note: Component selects the partition type to be programmed.

@@ -166,12 +153,13 @@ the driver using fastboot commands.
  Region commands
  ---------------

-::
+.. code:: shell

-  $ devlink region show
+    # Show all the regions supported by driver.
+    $ devlink region show

-This command list the regions implemented by driver. These regions are 
accessed
-for device internal data. Below table describes the regions.
+Regions are used for accessing device internal data for debugging 
purpose. Below table
+describes the regions.

  .. list-table:: Regions
      :widths: 15 85
@@ -186,17 +174,16 @@ for device internal data. Below table describes 
the regions.
  Coredump Collection
  ~~~~~~~~~~~~~~~~~~~

-::
-
-  $ devlink region new mr_dump
+.. code:: shell

-::
+    # Create a modem region snapshot using:
+    $ devlink region new mr_dump

-  $ devlink region read mr_dump snapshot 0 address 0 length $len
-
-::
+    # Read a specific part of modem region snapshot using:
+    $ devlink region read mr_dump snapshot 0 address 0 length $len

-  $ devlink region del mr_dump snapshot 0
+    # Delete a modem region snapshot using:
+    $ devlink region del mr_dump snapshot 0

  Note: $len is actual len to be dumped.

@@ -206,17 +193,16 @@ logs when device encounters an exception.
  Second Stage Bootloader dump
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-::
-
-  $ devlink region new lk_dump
+.. code:: shell

-::
+    # Create a second stage bootloader snapshot using:
+    $ devlink region new lk_dump

-  $ devlink region read lk_dump snapshot 0 address 0 length $len
-
-::
+    # Read a specific part of second stage booloader snapshot using:
+    $ devlink region read lk_dump snapshot 0 address 0 length $len

-  $ devlink region del lk_dump snapshot 0
+    # Delete a second stage bootloader snapshot using:
+    $ devlink region del lk_dump snapshot 0

  Note: $len is actual len to be dumped.

-- 
Chetan