Re: [PATCH net-next RFC v2 13/13] devlink: Add Documentation/networking/devlink/devlink-reload.rst

[Moshe Shemesh]

On 8/18/2020 2:07 PM, Jiri Pirko wrote:
> Tue, Aug 18, 2020 at 11:14:16AM CEST, moshe@xxxxxxxxxx wrote:
> > On 8/17/2020 7:39 PM, Jiri Pirko wrote:
> > > Mon, Aug 17, 2020 at 11:37:52AM CEST, moshe@xxxxxxxxxxxx wrote:
> > > > Add devlink reload rst documentation file.
> > > > Update index file to include it.
> > > >
> > > > Signed-off-by: Moshe Shemesh <moshe@xxxxxxxxxxxx>
> > > > ---
> > > > - 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     | 54 +++++++++++++++++++
> > > > Documentation/networking/devlink/index.rst    |  1 +
> > > > 2 files changed, 55 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..9846ea727f3b
> > > > --- /dev/null
> > > > +++ b/Documentation/networking/devlink/devlink-reload.rst
> > > > @@ -0,0 +1,54 @@
> > > > +.. SPDX-License-Identifier: GPL-2.0
> > > > +
> > > > +==============
> > > > +Devlink Reload
> > > > +==============
> > > > +
> > > > +``devlink-reload`` provides mechanism to either reload 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 done.
> > > > +
> > > > +.. list-table:: Possible reload actions
> > > > +   :widths: 5 90
> > > > +
> > > > +   * - Name
> > > > +     - Description
> > > > +   * - ``driver-reinit``
> > > > +     - 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. Can be used for firmware reload or firmware
> > > > +       upgrade if new firmware is stored and driver supports such
> > > > +       firmware upgrade.
> > > Does this do the same as "driver-reinit" + fw activation? If yes, it
> > > should be written here. If no, it should be written here as well.
> > No, The only thing required here is the action of firmware activation. If a
> > driver needs to do reload to make that happen and do reinit that's ok, but
> > not required.
> What does the "FW activation" mean? I believe that this needs explicit
> documentation here.
I will add it explicitly.

FW activation means FW upgrade if new image is pending activation. If no 
FW image pending, it reloads the current FW.

> > > > +   * - ``fw_live_patch``
> > > > +     - Firmware live patch, applies firmware changes without reset.
> > > > +
> > > > +Change namespace
> > > > +================
> > > > +
> > > > +All devlink instances are created in init_net and stay there for a
> > > > +lifetime. Allow user to be able to move devlink instances into
> > > > +namespaces during devlink reload operation. That ensures proper
> > > > +re-instantiation of driver objects, including netdevices.
> > > > +
> > > > +example usage
> > > > +-------------
> > > > +
> > > > +.. code:: shell
> > > > +
> > > > +    $ devlink dev reload help
> > > > +    $ devlink dev reload DEV [ netns { PID | NAME | ID } ] [ action { fw_live_patch | driver_reinit | fw_activate } ]
> > > > +
> > > > +    # Run reload command for devlink driver entities re-initialization:
> > > > +    $ devlink dev reload pci/0000:82:00.0 action driver_reinit
> > > > +
> > > > +    # Run reload command to activate firmware:
> > > > +    $ devlink dev reload pci/0000:82:00.0 action 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.17.1