Message-ID: <Y7uOcBRN0Awn5xAb@debian.me>
Date:   Mon, 9 Jan 2023 10:48:00 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     m.chetan.kumar@...ux.intel.com, netdev@...r.kernel.org
Cc:     kuba@...nel.org, davem@...emloft.net, johannes@...solutions.net,
        ryazanov.s.a@...il.com, loic.poulain@...aro.org,
        ilpo.jarvinen@...ux.intel.com, ricardo.martinez@...ux.intel.com,
        chiranjeevi.rapolu@...ux.intel.com, haijun.liu@...iatek.com,
        edumazet@...gle.com, pabeni@...hat.com, linuxwwan@...el.com,
        linuxwwan_5g@...el.com, chandrashekar.devegowda@...el.com,
        matthias.bgg@...il.com, linux-arm-kernel@...ts.infradead.org,
        linux-mediatek@...ts.infradead.org, linux-doc@...r.kernel.org,
        jiri@...dia.com, corbet@....net
Subject: Re: [PATCH v3 net-next 5/5] net: wwan: t7xx: Devlink documentation

On Fri, Jan 06, 2023 at 09:58:06PM +0530, m.chetan.kumar@...ux.intel.com wrote:
> Refer to t7xx.rst file for details.

Above line is unnecessary.

> +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

Personally I prefer to put command-line explanations below the actual
command:

---- >8 ----

diff --git a/Documentation/networking/devlink/t7xx.rst b/Documentation/networking/devlink/t7xx.rst
index de220878ad7649..24f9e0ee69bffb 100644
--- a/Documentation/networking/devlink/t7xx.rst
+++ b/Documentation/networking/devlink/t7xx.rst
@@ -74,17 +74,21 @@ The supported list of firmware image types is described below.
 procedure, fastboot command & response are exchanged between driver and wwan
 device.
 
+::
+
+  $ devlink dev reload pci/0000:$bdf action driver_reinit
+
 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
+::
+
+  $ devlink dev reload pci/0000:$bdf action fw_activate
 
 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:
 ===============
 

However, I find it's odd to jump from firmware image type list directly to
devlink usage. Perhaps the latter should be put into the following section
below?

I also find that there is minor inconsistency of keyword formatting, so I
have to inline-code the uninlined remainings:

---- >8 ----

diff --git a/Documentation/networking/devlink/t7xx.rst b/Documentation/networking/devlink/t7xx.rst
index 24f9e0ee69bffb..d8feefe116c978 100644
--- a/Documentation/networking/devlink/t7xx.rst
+++ b/Documentation/networking/devlink/t7xx.rst
@@ -29,7 +29,7 @@ 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
+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.
@@ -79,14 +79,14 @@ device.
   $ devlink dev reload pci/0000:$bdf action driver_reinit
 
 The wwan device is put into fastboot mode via devlink reload command, by
-passing "driver_reinit" action.
+passing ``driver_reinit`` action.
 
 ::
 
   $ devlink dev reload pci/0000:$bdf action fw_activate
 
 Upon completion of fw flashing or coredump collection the wwan device is
-reset to normal mode using devlink reload command, by passing "fw_activate"
+reset to normal mode using devlink reload command, by passing ``fw_activate``
 action.
 
 Flash Commands:
 
> +
> +Flash Commands:
> +===============

Trim the unneeded trailing colon on the section title.

> +
> +$ 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"
> +
> <snipped>...
> +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.

Please briefly describe these devlink commands.

Also, wrap them in literal code blocks:

---- >8 ----

diff --git a/Documentation/networking/devlink/t7xx.rst b/Documentation/networking/devlink/t7xx.rst
index d8feefe116c978..1ba3ba4680e721 100644
--- a/Documentation/networking/devlink/t7xx.rst
+++ b/Documentation/networking/devlink/t7xx.rst
@@ -92,35 +92,65 @@ 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 preloader_k6880v1_mdot2_datacard.bin component "preloader"
 
-$ 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 loader_ext-verified.img component "loader_ext1"
 
-$ 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 tee-verified.img component "tee1"
 
-$ 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 lk-verified.img component "lk"
 
-$ 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 spmfw-verified.img component "spmfw"
 
-$ 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 sspm-verified.img component "sspm_1"
 
-$ 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 mcupm-verified.img component "mcupm_1"
 
-$ devlink dev flash pci/0000:$bdf file DEV_OTA.img component "mcf3"
+::
+
+  $ 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.
 
@@ -147,19 +177,31 @@ Following regions are accessed for device internal data.
 Region commands
 ===============
 
-$ devlink region show
+::
+  $ devlink region show
 
+::
 
-$ devlink region new mr_dump
+  $ 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 read mr_dump snapshot 0 address 0 length $len
 
-$ devlink region new lk_dump
+::
 
-$ devlink region read lk_dump snapshot 0 address 0 length $len
+  $ devlink region del mr_dump snapshot 0
 
-$ devlink region del lk_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.

Thanks.

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

Download attachment "signature.asc" of type "application/pgp-signature" (229 bytes)

Powered by blists - more mailing lists