Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752875AbdFQPq3 (ORCPT ); Sat, 17 Jun 2017 11:46:29 -0400 Received: from mail-pf0-f194.google.com ([209.85.192.194]:36607 "EHLO mail-pf0-f194.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752145AbdFQPq0 (ORCPT ); Sat, 17 Jun 2017 11:46:26 -0400 Reply-To: minyard@acm.org Subject: Re: [PATCH v2 01/29] IPMI.txt: standardize document format To: Mauro Carvalho Chehab , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , openipmi-developer@lists.sourceforge.net References: <2932e5ece623ed990b6c3b80174df270278dc314.1497713210.git.mchehab@s-opensource.com> From: Corey Minyard Message-ID: <7f180ab4-b3fe-8cfb-f95e-b401a9d7e26e@acm.org> Date: Sat, 17 Jun 2017 10:46:15 -0500 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.1.1 MIME-Version: 1.0 In-Reply-To: <2932e5ece623ed990b6c3b80174df270278dc314.1497713210.git.mchehab@s-opensource.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Content-Language: en-GB Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 10015 Lines: 267 On 06/17/2017 10:26 AM, Mauro Carvalho Chehab wrote: > Each text file under Documentation follows a different > format. Some doesn't even have titles! > > Change its representation to follow the adopted standard, > using ReST markups for it to be parseable by Sphinx: > > - fix document type; > - add missing markups for subitems; > - mark literal blocks; > - add whitespaces and blank lines where needed; > - use bulleted list markups where neded. > > Signed-off-by: Mauro Carvalho Chehab > --- > Documentation/IPMI.txt | 76 +++++++++++++++++++++++++++++--------------------- > 1 file changed, 44 insertions(+), 32 deletions(-) This is ok by me. Nice to have a standard format for this. Reviewed-by: Corey Minyard > diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt > index 6962cab997ef..aa77a25a0940 100644 > --- a/Documentation/IPMI.txt > +++ b/Documentation/IPMI.txt > @@ -1,9 +1,8 @@ > +===================== > +The Linux IPMI Driver > +===================== > > - The Linux IPMI Driver > - --------------------- > - Corey Minyard > - > - > +:Author: Corey Minyard / > > The Intelligent Platform Management Interface, or IPMI, is a > standard for controlling intelligent devices that monitor a system. > @@ -141,7 +140,7 @@ Addressing > ---------- > > The IPMI addressing works much like IP addresses, you have an overlay > -to handle the different address types. The overlay is: > +to handle the different address types. The overlay is:: > > struct ipmi_addr > { > @@ -153,7 +152,7 @@ to handle the different address types. The overlay is: > The addr_type determines what the address really is. The driver > currently understands two different types of addresses. > > -"System Interface" addresses are defined as: > +"System Interface" addresses are defined as:: > > struct ipmi_system_interface_addr > { > @@ -166,7 +165,7 @@ straight to the BMC on the current card. The channel must be > IPMI_BMC_CHANNEL. > > Messages that are destined to go out on the IPMB bus use the > -IPMI_IPMB_ADDR_TYPE address type. The format is > +IPMI_IPMB_ADDR_TYPE address type. The format is:: > > struct ipmi_ipmb_addr > { > @@ -184,16 +183,16 @@ spec. > Messages > -------- > > -Messages are defined as: > +Messages are defined as:: > > -struct ipmi_msg > -{ > + struct ipmi_msg > + { > unsigned char netfn; > unsigned char lun; > unsigned char cmd; > unsigned char *data; > int data_len; > -}; > + }; > > The driver takes care of adding/stripping the header information. The > data portion is just the data to be send (do NOT put addressing info > @@ -208,7 +207,7 @@ block of data, even when receiving messages. Otherwise the driver > will have no place to put the message. > > Messages coming up from the message handler in kernelland will come in > -as: > +as:: > > struct ipmi_recv_msg > { > @@ -246,6 +245,7 @@ and the user should not have to care what type of SMI is below them. > > > Watching For Interfaces > +^^^^^^^^^^^^^^^^^^^^^^^ > > When your code comes up, the IPMI driver may or may not have detected > if IPMI devices exist. So you might have to defer your setup until > @@ -256,6 +256,7 @@ and tell you when they come and go. > > > Creating the User > +^^^^^^^^^^^^^^^^^ > > To use the message handler, you must first create a user using > ipmi_create_user. The interface number specifies which SMI you want > @@ -272,6 +273,7 @@ closing the device automatically destroys the user. > > > Messaging > +^^^^^^^^^ > > To send a message from kernel-land, the ipmi_request_settime() call does > pretty much all message handling. Most of the parameter are > @@ -321,6 +323,7 @@ though, since it is tricky to manage your own buffers. > > > Events and Incoming Commands > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > The driver takes care of polling for IPMI events and receiving > commands (commands are messages that are not responses, they are > @@ -367,7 +370,7 @@ in the system. It discovers interfaces through a host of different > methods, depending on the system. > > You can specify up to four interfaces on the module load line and > -control some module parameters: > +control some module parameters:: > > modprobe ipmi_si.o type=,.... > ports=,... addrs=,... > @@ -437,7 +440,7 @@ default is one. Setting to 0 is useful with the hotmod, but is > obviously only useful for modules. > > When compiled into the kernel, the parameters can be specified on the > -kernel command line as: > +kernel command line as:: > > ipmi_si.type=,... > ipmi_si.ports=,... ipmi_si.addrs=,... > @@ -474,16 +477,22 @@ The driver supports a hot add and remove of interfaces. This way, > interfaces can be added or removed after the kernel is up and running. > This is done using /sys/modules/ipmi_si/parameters/hotmod, which is a > write-only parameter. You write a string to this interface. The string > -has the format: > +has the format:: > + > [:op2[:op3...]] > -The "op"s are: > + > +The "op"s are:: > + > add|remove,kcs|bt|smic,mem|i/o,
[,[,[,...]]] > -You can specify more than one interface on the line. The "opt"s are: > + > +You can specify more than one interface on the line. The "opt"s are:: > + > rsp= > rsi= > rsh= > irq= > ipmb= > + > and these have the same meanings as discussed above. Note that you > can also use this on the kernel command line for a more compact format > for specifying an interface. Note that when removing an interface, > @@ -496,7 +505,7 @@ The SMBus Driver (SSIF) > The SMBus driver allows up to 4 SMBus devices to be configured in the > system. By default, the driver will only register with something it > finds in DMI or ACPI tables. You can change this > -at module load time (for a module) with: > +at module load time (for a module) with:: > > modprobe ipmi_ssif.o > addr=[,[,...]] > @@ -535,7 +544,7 @@ the smb_addr parameter unless you have DMI or ACPI data to tell the > driver what to use. > > When compiled into the kernel, the addresses can be specified on the > -kernel command line as: > +kernel command line as:: > > ipmb_ssif.addr=[,[...]] > ipmi_ssif.adapter=[,[...]] > @@ -565,9 +574,9 @@ Some users need more detailed information about a device, like where > the address came from or the raw base device for the IPMI interface. > You can use the IPMI smi_watcher to catch the IPMI interfaces as they > come or go, and to grab the information, you can use the function > -ipmi_get_smi_info(), which returns the following structure: > +ipmi_get_smi_info(), which returns the following structure:: > > -struct ipmi_smi_info { > + struct ipmi_smi_info { > enum ipmi_addr_src addr_src; > struct device *dev; > union { > @@ -575,7 +584,7 @@ struct ipmi_smi_info { > void *acpi_handle; > } acpi_info; > } addr_info; > -}; > + }; > > Currently special info for only for SI_ACPI address sources is > returned. Others may be added as necessary. > @@ -590,7 +599,7 @@ Watchdog > > A watchdog timer is provided that implements the Linux-standard > watchdog timer interface. It has three module parameters that can be > -used to control it: > +used to control it:: > > modprobe ipmi_watchdog timeout= pretimeout= action= > preaction= preop= start_now=x > @@ -635,7 +644,7 @@ watchdog device is closed. The default value of nowayout is true > if the CONFIG_WATCHDOG_NOWAYOUT option is enabled, or false if not. > > When compiled into the kernel, the kernel command line is available > -for configuring the watchdog: > +for configuring the watchdog:: > > ipmi_watchdog.timeout= ipmi_watchdog.pretimeout= > ipmi_watchdog.action= > @@ -675,6 +684,7 @@ also get a bunch of OEM events holding the panic string. > > > The field settings of the events are: > + > * Generator ID: 0x21 (kernel) > * EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format) > * Sensor Type: 0x20 (OS critical stop sensor) > @@ -683,18 +693,20 @@ The field settings of the events are: > * Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3) > * Event data 2: second byte of panic string > * Event data 3: third byte of panic string > + > See the IPMI spec for the details of the event layout. This event is > always sent to the local management controller. It will handle routing > the message to the right place > > Other OEM events have the following format: > -Record ID (bytes 0-1): Set by the SEL. > -Record type (byte 2): 0xf0 (OEM non-timestamped) > -byte 3: The slave address of the card saving the panic > -byte 4: A sequence number (starting at zero) > -The rest of the bytes (11 bytes) are the panic string. If the panic string > -is longer than 11 bytes, multiple messages will be sent with increasing > -sequence numbers. > + > +* Record ID (bytes 0-1): Set by the SEL. > +* Record type (byte 2): 0xf0 (OEM non-timestamped) > +* byte 3: The slave address of the card saving the panic > +* byte 4: A sequence number (starting at zero) > + The rest of the bytes (11 bytes) are the panic string. If the panic string > + is longer than 11 bytes, multiple messages will be sent with increasing > + sequence numbers. > > Because you cannot send OEM events using the standard interface, this > function will attempt to find an SEL and add the events there. It