linux-kernel - Re: [PATCH] docs: ipmb: place it at driver-api and convert to ReST

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Date:   Sun, 30 Jun 2019 19:34:23 -0500
From:   Corey Minyard <cminyard@...sta.com>
To:     Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Randy Dunlap <rdunlap@...radead.org>,
        "Rafael J. Wysocki" <rafael.j.wysocki@...el.com>,
        Logan Gunthorpe <logang@...tatee.com>,
        Asmaa Mnebhi <Asmaa@...lanox.com>, vadimp@...lanox.com
Subject: Re: [PATCH] docs: ipmb: place it at driver-api and convert to ReST

On Sat, Jun 29, 2019 at 07:36:46AM -0300, Mauro Carvalho Chehab wrote:
> No new doc should be added at the main Documentation/ directory.
> 
> Instead, new docs should be added as ReST files, within the
> Kernel documentation body.

Got it, thanks.

-corey

> 
> Fixes: 51bd6f291583 ("Add support for IPMB driver")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
> ---
>  Documentation/driver-api/index.rst            |  1 +
>  .../{IPMB.txt => driver-api/ipmb.rst}         | 62 ++++++++++---------
>  2 files changed, 33 insertions(+), 30 deletions(-)
>  rename Documentation/{IPMB.txt => driver-api/ipmb.rst} (71%)
> 
> diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
> index e33849b948c7..e49c34bf16c0 100644
> --- a/Documentation/driver-api/index.rst
> +++ b/Documentation/driver-api/index.rst
> @@ -75,6 +75,7 @@ available subsections can be seen below.
>     dell_rbu
>     edid
>     eisa
> +   ipmb
>     isa
>     isapnp
>     generic-counter
> diff --git a/Documentation/IPMB.txt b/Documentation/driver-api/ipmb.rst
> similarity index 71%
> rename from Documentation/IPMB.txt
> rename to Documentation/driver-api/ipmb.rst
> index cd20c9764705..3ec3baed84c4 100644
> --- a/Documentation/IPMB.txt
> +++ b/Documentation/driver-api/ipmb.rst
> @@ -32,11 +32,11 @@ This driver works with the I2C driver and a userspace
>  program such as OpenIPMI:
>  
>  1) It is an I2C slave backend driver. So, it defines a callback
> -function to set the Satellite MC as an I2C slave.
> -This callback function handles the received IPMI requests.
> +   function to set the Satellite MC as an I2C slave.
> +   This callback function handles the received IPMI requests.
>  
>  2) It defines the read and write functions to enable a user
> -space program (such as OpenIPMI) to communicate with the kernel.
> +   space program (such as OpenIPMI) to communicate with the kernel.
>  
>  
>  Load the IPMB driver
> @@ -48,34 +48,35 @@ CONFIG_IPMB_DEVICE_INTERFACE=y
>  
>  1) If you want the driver to be loaded at boot time:
>  
> -a) Add this entry to your ACPI table, under the appropriate SMBus:
> +a) Add this entry to your ACPI table, under the appropriate SMBus::
>  
> -Device (SMB0) // Example SMBus host controller
> -{
> -  Name (_HID, "<Vendor-Specific HID>") // Vendor-Specific HID
> -  Name (_UID, 0) // Unique ID of particular host controller
> -  :
> -  :
> -    Device (IPMB)
> -    {
> -      Name (_HID, "IPMB0001") // IPMB device interface
> -      Name (_UID, 0) // Unique device identifier
> -    }
> -}
> +     Device (SMB0) // Example SMBus host controller
> +     {
> +     Name (_HID, "<Vendor-Specific HID>") // Vendor-Specific HID
> +     Name (_UID, 0) // Unique ID of particular host controller
> +     :
> +     :
> +       Device (IPMB)
> +       {
> +         Name (_HID, "IPMB0001") // IPMB device interface
> +         Name (_UID, 0) // Unique device identifier
> +       }
> +     }
>  
> -b) Example for device tree:
> +b) Example for device tree::
>  
> -&i2c2 {
> -         status = "okay";
> +     &i2c2 {
> +            status = "okay";
>  
> -         ipmb@10 {
> -                 compatible = "ipmb-dev";
> -                 reg = <0x10>;
> -         };
> -};
> +            ipmb@10 {
> +                    compatible = "ipmb-dev";
> +                    reg = <0x10>;
> +            };
> +     };
>  
> -2) Manually from Linux:
> -modprobe ipmb-dev-int
> +2) Manually from Linux::
> +
> +     modprobe ipmb-dev-int
>  
>  
>  Instantiate the device
> @@ -86,15 +87,16 @@ described in 'Documentation/i2c/instantiating-devices.rst'.
>  If you have multiple BMCs, each connected to your Satellite MC via
>  a different I2C bus, you can instantiate a device for each of
>  those BMCs.
> +
>  The name of the instantiated device contains the I2C bus number
> -associated with it as follows:
> +associated with it as follows::
>  
> -BMC1 ------ IPMB/I2C bus 1 ---------|   /dev/ipmb-1
> +  BMC1 ------ IPMB/I2C bus 1 ---------|   /dev/ipmb-1
>  				Satellite MC
> -BMC1 ------ IPMB/I2C bus 2 ---------|   /dev/ipmb-2
> +  BMC1 ------ IPMB/I2C bus 2 ---------|   /dev/ipmb-2
>  
>  For instance, you can instantiate the ipmb-dev-int device from
> -user space at the 7 bit address 0x10 on bus 2:
> +user space at the 7 bit address 0x10 on bus 2::
>  
>    # echo ipmb-dev 0x1010 > /sys/bus/i2c/devices/i2c-2/new_device
>  
> -- 
> 2.21.0
>