diff mbox series

[net-next,16/16] devlink: Add Documentation/networking/devlink/devlink-reload.rst

Message ID 1601560759-11030-17-git-send-email-moshe@mellanox.com
State Superseded
Headers show
Series Add devlink reload action and limit options | expand

Commit Message

Moshe Shemesh Oct. 1, 2020, 1:59 p.m. UTC
Add devlink reload rst documentation file.
Update index file to include it.

Signed-off-by: Moshe Shemesh <moshe@mellanox.com>
---
RFCv5 -> v1:
- Rename reload_action_limit_level to reload_limit
RFCv4 -> RFCv5:
- Rephrase namespace chnage section
- Rephrase note on actions performed
RFCv3 -> RFCv4:
- Remove reload action fw_activate_no_reset
- Add reload actions limit levels and document the no_reset limit level
  constrains
RFCv2 -> RFCv3:
- Devlink reload returns the actions done
- Replace fw_live_patch action by fw_activate_no_reset
- Explain fw_activate meaning
RFCv1 -> RFCv2:
- Instead of reload levels driver,fw_reset,fw_live_patch have reload
  actions driver_reinit,fw_activate,fw_live_patch
---
 .../networking/devlink/devlink-reload.rst     | 81 +++++++++++++++++++
 Documentation/networking/devlink/index.rst    |  1 +
 2 files changed, 82 insertions(+)
 create mode 100644 Documentation/networking/devlink/devlink-reload.rst

Comments

Jiri Pirko Oct. 3, 2020, 9:14 a.m. UTC | #1
Thu, Oct 01, 2020 at 03:59:19PM CEST, moshe@mellanox.com wrote:
>Add devlink reload rst documentation file.
>Update index file to include it.
>
>Signed-off-by: Moshe Shemesh <moshe@mellanox.com>
>---
>RFCv5 -> v1:
>- Rename reload_action_limit_level to reload_limit
>RFCv4 -> RFCv5:
>- Rephrase namespace chnage section
>- Rephrase note on actions performed
>RFCv3 -> RFCv4:
>- Remove reload action fw_activate_no_reset
>- Add reload actions limit levels and document the no_reset limit level
>  constrains
>RFCv2 -> RFCv3:
>- Devlink reload returns the actions done
>- Replace fw_live_patch action by fw_activate_no_reset
>- Explain fw_activate meaning
>RFCv1 -> RFCv2:
>- Instead of reload levels driver,fw_reset,fw_live_patch have reload
>  actions driver_reinit,fw_activate,fw_live_patch
>---
> .../networking/devlink/devlink-reload.rst     | 81 +++++++++++++++++++
> Documentation/networking/devlink/index.rst    |  1 +
> 2 files changed, 82 insertions(+)
> create mode 100644 Documentation/networking/devlink/devlink-reload.rst
>
>diff --git a/Documentation/networking/devlink/devlink-reload.rst b/Documentation/networking/devlink/devlink-reload.rst
>new file mode 100644
>index 000000000000..5abc5c2c75fd
>--- /dev/null
>+++ b/Documentation/networking/devlink/devlink-reload.rst
>@@ -0,0 +1,81 @@
>+.. SPDX-License-Identifier: GPL-2.0
>+
>+==============
>+Devlink Reload

No reason for capital "R".


>+==============
>+
>+``devlink-reload`` provides mechanism to either reinit driver entities,
>+applying ``devlink-params`` and ``devlink-resources`` new values or firmware
>+activation depends on reload action selected.

Could you perhaps split the sentense? It is hard to read.


>+
>+Reload actions
>+==============
>+
>+User may select a reload action.
>+By default ``driver_reinit`` action is selected.
>+
>+.. list-table:: Possible reload actions
>+   :widths: 5 90
>+
>+   * - Name
>+     - Description
>+   * - ``driver-reinit``
>+     - Devlink driver entities re-initialization, including applying
>+       new values to devlink entities which are used during driver
>+       load such as ``devlink-params`` in configuration mode
>+       ``driverinit`` or ``devlink-resources``
>+   * - ``fw_activate``
>+     - Firmware activate. Activates new firmware if such image is stored and
>+       pending activation. If no limitation specified this action may involve
>+       firmware reset. If no new image pending this action will reload current
>+       firmware image.
>+
>+Note that even though user asks for a specific action, the driver
>+implementation might require to perform another action alongside with
>+it. For example, some driver do not support driver reinitialization
>+being performed without fw activation. Therefore, the devlink reload
>+command returns the list of actions which were actrually performed.
>+
>+Reload limits
>+=============
>+
>+By default reload actions are not limited and driver implementation may
>+include reset or downtime as needed to perform the actions.
>+
>+However, some drivers support action limits, which limit the action
>+implementation to specific constrains.
>+
>+.. list-table:: Possible reload limits
>+   :widths: 5 90
>+
>+   * - Name
>+     - Description
>+   * - ``no_reset``
>+     - No reset allowed, no down time allowed, no link flap and no
>+       configuration is lost.
>+
>+Change namespace
>+================
>+
>+The netns option allow user to be able to move devlink instances into

"allows"


>+namespaces during devlink reload operation.
>+By default all devlink instances are created in init_net and stay there.
>+
>+example usage
>+-------------
>+
>+.. code:: shell
>+
>+    $ devlink dev reload help
>+    $ devlink dev reload DEV [ netns { PID | NAME | ID } ] [ action { driver_reinit | fw_activate } ] [ limit no_reset ]
>+
>+    # Run reload command for devlink driver entities re-initialization:
>+    $ devlink dev reload pci/0000:82:00.0 action driver_reinit
>+    reload_actions_performed:
>+      driver_reinit
>+
>+    # Run reload command to activate firmware:
>+    # Note that mlx5 driver reloads the driver while activating firmware
>+    $ devlink dev reload pci/0000:82:00.0 action fw_activate
>+    reload_actions_performed:
>+      driver_reinit fw_activate
>diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
>index 7684ae5c4a4a..d82874760ae2 100644
>--- a/Documentation/networking/devlink/index.rst
>+++ b/Documentation/networking/devlink/index.rst
>@@ -20,6 +20,7 @@ general.
>    devlink-params
>    devlink-region
>    devlink-resource
>+   devlink-reload
>    devlink-trap
> 
> Driver-specific documentation
>-- 
>2.18.2
>
Moshe Shemesh Oct. 4, 2020, 7:15 a.m. UTC | #2
On 10/3/2020 12:14 PM, Jiri Pirko wrote:
> Thu, Oct 01, 2020 at 03:59:19PM CEST, moshe@mellanox.com wrote:
>> Add devlink reload rst documentation file.
>> Update index file to include it.
>>
>> Signed-off-by: Moshe Shemesh <moshe@mellanox.com>
>> ---
>> RFCv5 -> v1:
>> - Rename reload_action_limit_level to reload_limit
>> RFCv4 -> RFCv5:
>> - Rephrase namespace chnage section
>> - Rephrase note on actions performed
>> RFCv3 -> RFCv4:
>> - Remove reload action fw_activate_no_reset
>> - Add reload actions limit levels and document the no_reset limit level
>>   constrains
>> RFCv2 -> RFCv3:
>> - Devlink reload returns the actions done
>> - Replace fw_live_patch action by fw_activate_no_reset
>> - Explain fw_activate meaning
>> RFCv1 -> RFCv2:
>> - Instead of reload levels driver,fw_reset,fw_live_patch have reload
>>   actions driver_reinit,fw_activate,fw_live_patch
>> ---
>> .../networking/devlink/devlink-reload.rst     | 81 +++++++++++++++++++
>> Documentation/networking/devlink/index.rst    |  1 +
>> 2 files changed, 82 insertions(+)
>> create mode 100644 Documentation/networking/devlink/devlink-reload.rst
>>
>> diff --git a/Documentation/networking/devlink/devlink-reload.rst b/Documentation/networking/devlink/devlink-reload.rst
>> new file mode 100644
>> index 000000000000..5abc5c2c75fd
>> --- /dev/null
>> +++ b/Documentation/networking/devlink/devlink-reload.rst
>> @@ -0,0 +1,81 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +==============
>> +Devlink Reload
> No reason for capital "R".


It looks as the convention here for rst headers, as in 
devlink-region.rst, devlink-trap.rst, devlink-resource.rst

>
>> +==============
>> +
>> +``devlink-reload`` provides mechanism to either reinit driver entities,
>> +applying ``devlink-params`` and ``devlink-resources`` new values or firmware
>> +activation depends on reload action selected.
> Could you perhaps split the sentense? It is hard to read.
Yes.
>
>> +
>> +Reload actions
>> +==============
>> +
>> +User may select a reload action.
>> +By default ``driver_reinit`` action is selected.
>> +
>> +.. list-table:: Possible reload actions
>> +   :widths: 5 90
>> +
>> +   * - Name
>> +     - Description
>> +   * - ``driver-reinit``
>> +     - Devlink driver entities re-initialization, including applying
>> +       new values to devlink entities which are used during driver
>> +       load such as ``devlink-params`` in configuration mode
>> +       ``driverinit`` or ``devlink-resources``
>> +   * - ``fw_activate``
>> +     - Firmware activate. Activates new firmware if such image is stored and
>> +       pending activation. If no limitation specified this action may involve
>> +       firmware reset. If no new image pending this action will reload current
>> +       firmware image.
>> +
>> +Note that even though user asks for a specific action, the driver
>> +implementation might require to perform another action alongside with
>> +it. For example, some driver do not support driver reinitialization
>> +being performed without fw activation. Therefore, the devlink reload
>> +command returns the list of actions which were actrually performed.
>> +
>> +Reload limits
>> +=============
>> +
>> +By default reload actions are not limited and driver implementation may
>> +include reset or downtime as needed to perform the actions.
>> +
>> +However, some drivers support action limits, which limit the action
>> +implementation to specific constrains.
>> +
>> +.. list-table:: Possible reload limits
>> +   :widths: 5 90
>> +
>> +   * - Name
>> +     - Description
>> +   * - ``no_reset``
>> +     - No reset allowed, no down time allowed, no link flap and no
>> +       configuration is lost.
>> +
>> +Change namespace
>> +================
>> +
>> +The netns option allow user to be able to move devlink instances into
> "allows"
Ack.
>
>> +namespaces during devlink reload operation.
>> +By default all devlink instances are created in init_net and stay there.
>> +
>> +example usage
>> +-------------
>> +
>> +.. code:: shell
>> +
>> +    $ devlink dev reload help
>> +    $ devlink dev reload DEV [ netns { PID | NAME | ID } ] [ action { driver_reinit | fw_activate } ] [ limit no_reset ]
>> +
>> +    # Run reload command for devlink driver entities re-initialization:
>> +    $ devlink dev reload pci/0000:82:00.0 action driver_reinit
>> +    reload_actions_performed:
>> +      driver_reinit
>> +
>> +    # Run reload command to activate firmware:
>> +    # Note that mlx5 driver reloads the driver while activating firmware
>> +    $ devlink dev reload pci/0000:82:00.0 action fw_activate
>> +    reload_actions_performed:
>> +      driver_reinit fw_activate
>> diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
>> index 7684ae5c4a4a..d82874760ae2 100644
>> --- a/Documentation/networking/devlink/index.rst
>> +++ b/Documentation/networking/devlink/index.rst
>> @@ -20,6 +20,7 @@ general.
>>     devlink-params
>>     devlink-region
>>     devlink-resource
>> +   devlink-reload
>>     devlink-trap
>>
>> Driver-specific documentation
>> -- 
>> 2.18.2
>>
diff mbox series

Patch

diff --git a/Documentation/networking/devlink/devlink-reload.rst b/Documentation/networking/devlink/devlink-reload.rst
new file mode 100644
index 000000000000..5abc5c2c75fd
--- /dev/null
+++ b/Documentation/networking/devlink/devlink-reload.rst
@@ -0,0 +1,81 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+==============
+Devlink Reload
+==============
+
+``devlink-reload`` provides mechanism to either reinit driver entities,
+applying ``devlink-params`` and ``devlink-resources`` new values or firmware
+activation depends on reload action selected.
+
+Reload actions
+==============
+
+User may select a reload action.
+By default ``driver_reinit`` action is selected.
+
+.. list-table:: Possible reload actions
+   :widths: 5 90
+
+   * - Name
+     - Description
+   * - ``driver-reinit``
+     - Devlink driver entities re-initialization, including applying
+       new values to devlink entities which are used during driver
+       load such as ``devlink-params`` in configuration mode
+       ``driverinit`` or ``devlink-resources``
+   * - ``fw_activate``
+     - Firmware activate. Activates new firmware if such image is stored and
+       pending activation. If no limitation specified this action may involve
+       firmware reset. If no new image pending this action will reload current
+       firmware image.
+
+Note that even though user asks for a specific action, the driver
+implementation might require to perform another action alongside with
+it. For example, some driver do not support driver reinitialization
+being performed without fw activation. Therefore, the devlink reload
+command returns the list of actions which were actrually performed.
+
+Reload limits
+=============
+
+By default reload actions are not limited and driver implementation may
+include reset or downtime as needed to perform the actions.
+
+However, some drivers support action limits, which limit the action
+implementation to specific constrains.
+
+.. list-table:: Possible reload limits
+   :widths: 5 90
+
+   * - Name
+     - Description
+   * - ``no_reset``
+     - No reset allowed, no down time allowed, no link flap and no
+       configuration is lost.
+
+Change namespace
+================
+
+The netns option allow user to be able to move devlink instances into
+namespaces during devlink reload operation.
+By default all devlink instances are created in init_net and stay there.
+
+example usage
+-------------
+
+.. code:: shell
+
+    $ devlink dev reload help
+    $ devlink dev reload DEV [ netns { PID | NAME | ID } ] [ action { driver_reinit | fw_activate } ] [ limit no_reset ]
+
+    # Run reload command for devlink driver entities re-initialization:
+    $ devlink dev reload pci/0000:82:00.0 action driver_reinit
+    reload_actions_performed:
+      driver_reinit
+
+    # Run reload command to activate firmware:
+    # Note that mlx5 driver reloads the driver while activating firmware
+    $ devlink dev reload pci/0000:82:00.0 action fw_activate
+    reload_actions_performed:
+      driver_reinit fw_activate
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index 7684ae5c4a4a..d82874760ae2 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -20,6 +20,7 @@  general.
    devlink-params
    devlink-region
    devlink-resource
+   devlink-reload
    devlink-trap
 
 Driver-specific documentation