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

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

[m.chetan.kumar]

From: M Chetan Kumar <m.chetan.kumar@linux.intel.com>

Document the t7xx devlink commands usage for firmware flashing &
coredump collection.

Signed-off-by: M Chetan Kumar <m.chetan.kumar@linux.intel.com>
Signed-off-by: Devegowda Chandrashekar <chandrashekar.devegowda@intel.com>
--
v5:
 * No Change.
v4:
 * Spell out fw as firmware.
 * Drop "Refer to t7xx.rst file for details" in commit message.
 * Move explanation below commands under flash update.
 * Move firmware image type list under flash commands.
 * Keyword formatting.
 * Trim the unneeded trailing colon.
 * Describe region commands.
v3:
 * No change.
v2:
 * Documentation correction.
 * Add param details.
---
 Documentation/networking/devlink/index.rst |   1 +
 Documentation/networking/devlink/t7xx.rst  | 224 +++++++++++++++++++++
 2 files changed, 225 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..dc795c8cc851
--- /dev/null
+++ b/Documentation/networking/devlink/t7xx.rst
@@ -0,0 +1,224 @@
+.. 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
+   :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.
+
+``t7xx`` driver uses fastboot protocol for firmware flashing. In the firmware
+flashing 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 fw_activate
+
+Upon completion of firmware flashing or coredump collection the wwan device is
+reset to normal mode using devlink reload command, by passing ``fw_activate``
+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"
+
+::
+
+  $ 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.
+
+
+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
+
+
+Regions
+=======
+
+The ``t7xx`` driver supports core dump collection in exception state and second
+stage bootloader log collection in fastboot mode. The log snapshot is taken by
+the driver using fastboot commands.
+
+Region commands
+---------------
+
+::
+
+  $ devlink region show
+
+This command list the regions implemented by driver. These regions are accessed
+for device internal data. Below table describes the regions.
+
+.. list-table:: Regions
+    :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
+
+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.
+
+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.
-- 
2.34.1

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

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2923 bytes --]

On Sat, Jan 21, 2023 at 07:03:58PM +0530, m.chetan.kumar@linux.intel.com 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/Y7uOcBRN0Awn5xAb@debian.me/

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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

[Kumar, M Chetan]

On 1/22/2023 7:43 AM, Bagas Sanjaya wrote:
> On Sat, Jan 21, 2023 at 07:03:58PM +0530, m.chetan.kumar@linux.intel.com 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/Y7uOcBRN0Awn5xAb@debian.me/

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

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

[Jakub Kicinski]

On Sat, 21 Jan 2023 19:03:58 +0530 m.chetan.kumar@linux.intel.com wrote:
> +In fastboot mode the userspace application uses these commands for obtaining the
> +current snapshot of second stage bootloader.

I don't know what fastboot is, and reading this doc I see it used in
three forms:
 - fastboot protocol
 - fastboot mode
 - fastboot command & response

In the end - I have no idea what the devlink param you're adding does.

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

[Kumar, M Chetan]

On 1/25/2023 10:21 AM, Jakub Kicinski wrote:
> On Sat, 21 Jan 2023 19:03:58 +0530 m.chetan.kumar@linux.intel.com wrote:
>> +In fastboot mode the userspace application uses these commands for obtaining the
>> +current snapshot of second stage bootloader.
> 
> I don't know what fastboot is, and reading this doc I see it used in
> three forms:
>   - fastboot protocol
>   - fastboot mode
>   - fastboot command & response

The fastboot is sort of a tool. It implements the protocol for 
programming the device flash or getting device information. The device 
implements the fastboot commands and host issue those commands for 
programming the firmware to device flash or to obtain device 
information. Inorder to execute those commands, first the device needs 
to be put into fastboot mode.

More details on fastboot can be found in links [1].

> In the end - I have no idea what the devlink param you're adding does.

"fastboot" devlink param is used to put the device into fastboot mode
to program firmware to device flash or to obtain device information.


[1]
https://en.wikipedia.org/wiki/Fastboot
https://android.googlesource.com/platform/system/core/+/refs/heads/master/fastboot/README.md

-- 
Chetan

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

[Ilpo Järvinen]

On Wed, 25 Jan 2023, Kumar, M Chetan wrote:

> On 1/25/2023 10:21 AM, Jakub Kicinski wrote:
> > On Sat, 21 Jan 2023 19:03:58 +0530 m.chetan.kumar@linux.intel.com wrote:
> > > +In fastboot mode the userspace application uses these commands for
> > > obtaining the
> > > +current snapshot of second stage bootloader.
> > 
> > I don't know what fastboot is, and reading this doc I see it used in
> > three forms:
> >   - fastboot protocol
> >   - fastboot mode
> >   - fastboot command & response
> 
> The fastboot is sort of a tool. It implements the protocol for programming the
> device flash or getting device information. The device implements the fastboot
> commands and host issue those commands for programming the firmware to device
> flash or to obtain device information. Inorder to execute those commands,
> first the device needs to be put into fastboot mode.
> 
> More details on fastboot can be found in links [1].
> 
> > In the end - I have no idea what the devlink param you're adding does.
> 
> "fastboot" devlink param is used to put the device into fastboot mode
> to program firmware to device flash or to obtain device information.
> 
> 
> [1]
> https://en.wikipedia.org/wiki/Fastboot
> https://android.googlesource.com/platform/system/core/+/refs/heads/master/fastboot/README.md

Make sure to improve the documentation too so that the next reader won't 
have the same problem in understanding. I hope this was obvious but just 
in case it wasn't, your true audience is the ones reading the doc later
and if a reviewer cannot understand your doc, the chances are the person 
reading the doc understands even less. And they won't have your reply to
the reviewer available so enough information should go into the 
documentation itself.


-- 
 i.

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

[Jakub Kicinski]

On Wed, 25 Jan 2023 16:03:37 +0530 Kumar, M Chetan wrote:
> > I don't know what fastboot is, and reading this doc I see it used in
> > three forms:
> >   - fastboot protocol
> >   - fastboot mode
> >   - fastboot command & response  
> 
> The fastboot is sort of a tool. It implements the protocol for 
> programming the device flash or getting device information. The device 
> implements the fastboot commands and host issue those commands for 
> programming the firmware to device flash or to obtain device 
> information. Inorder to execute those commands, first the device needs 
> to be put into fastboot mode.
> 
> More details on fastboot can be found in links [1].
> 
> > In the end - I have no idea what the devlink param you're adding does.  
> 
> "fastboot" devlink param is used to put the device into fastboot mode
> to program firmware to device flash or to obtain device information.
> 
> 
> [1]
> https://en.wikipedia.org/wiki/Fastboot
> https://android.googlesource.com/platform/system/core/+/refs/heads/master/fastboot/README.md

As Ilpo mentions, please add this info into the doc, including 
the links.

The most confusing part is that "fastboot" sounds like it's going 
to boot fast, while IIUC the behavior is the opposite - it's not going
to boot at all and just expose an interface to load the FW, is that
right?

Please also clarify what the normal operation for the device is.
In what scenarios does the fastboot mode get used?

And just to double confirm - that the FW loaded in fastboot mode is
persistently stored on the device, and will be used after power cycle.
Rather than it being an upload into RAM.

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

[Kumar, M Chetan]

On 1/25/2023 11:38 PM, Jakub Kicinski wrote:
> On Wed, 25 Jan 2023 16:03:37 +0530 Kumar, M Chetan wrote:
>>> I don't know what fastboot is, and reading this doc I see it used in
>>> three forms:
>>>    - fastboot protocol
>>>    - fastboot mode
>>>    - fastboot command & response
>>
>> The fastboot is sort of a tool. It implements the protocol for
>> programming the device flash or getting device information. The device
>> implements the fastboot commands and host issue those commands for
>> programming the firmware to device flash or to obtain device
>> information. Inorder to execute those commands, first the device needs
>> to be put into fastboot mode.
>>
>> More details on fastboot can be found in links [1].
>>
>>> In the end - I have no idea what the devlink param you're adding does.
>>
>> "fastboot" devlink param is used to put the device into fastboot mode
>> to program firmware to device flash or to obtain device information.
>>
>>
>> [1]
>> https://en.wikipedia.org/wiki/Fastboot
>> https://android.googlesource.com/platform/system/core/+/refs/heads/master/fastboot/README.md
> 
> As Ilpo mentions, please add this info into the doc, including
> the links.

Sure. In the next patch, I will detail out the fastboot and include 
those links for reference.

> 
> The most confusing part is that "fastboot" sounds like it's going
> to boot fast, while IIUC the behavior is the opposite - it's not going
> to boot at all and just expose an interface to load the FW, is that
> right?

On device side, the fastboot protocol is implemented in bootloader. When 
the host request the device to enter fastboot mode, the device is reset. 
Post reset, the host will be able to communicate with device bootloader 
using fastboot protocol.

Fastboot protocol implements a set of commands for various operations. 
The "flash" is one such command used for programming firmware.

> 
> Please also clarify what the normal operation for the device is.

It means fully functional mode.
In this mode wwan functionalities like AT, MBIM, modem trace collection 
& data path are operational.

> In what scenarios does the fastboot mode get used?

It is used in 2 scenarios.
1> Firmware update, when user/app wants to update firmware.
2> Core dump collection, when device encounters an exception.

> 
> And just to double confirm - that the FW loaded in fastboot mode is
> persistently stored on the device, and will be used after power cycle.
> Rather than it being an upload into RAM.

That's correct.
The firmware is permanently stored on the device & it will be used after 
power cycle.

-- 
Chetan