[PATCH 0/4] Documentation/misc-devices/mei: Fix formatting

[PATCH 0/4] Documentation/misc-devices/mei: Fix formatting

[Julian Brost]

This patch series fixes multiple formatting issues in the documentation for the
Intel MEI, including improperly formatted headlines and issues with spacing and
indentation.

Julian Brost (4):
  Documentation/misc-devices/mei: Fix formatting of headings.
  Documentation/misc-devices/mei: Fix spacing around parentheses.
  Documentation/misc-devices/mei: Fix indentation of enumeration.
  Documentation/misc-devices/mei: Fix indentation of embedded code.

 Documentation/misc-devices/mei/mei-client-bus.txt |  17 +--
 Documentation/misc-devices/mei/mei.txt            | 126 ++++++++++++----------
 2 files changed, 77 insertions(+), 66 deletions(-)

-- 
2.2.1

[PATCH 1/4] Documentation/misc-devices/mei: Fix formatting of headings.

[Julian Brost]

Make the heading underlines fit the length of the heading, remove colons
at the end of headings and consistently place an empty line after each
heading and two empty lines before each that is preceded by a paragraph.

Signed-off-by: Julian Brost <linux-kernel@0x4a42.net>
Signed-off-by: Fabian Hofmann <fabian.hofmann@fau.de>
---
 Documentation/misc-devices/mei/mei-client-bus.txt |  7 ++++--
 Documentation/misc-devices/mei/mei.txt            | 27 ++++++++++++++---------
 2 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/Documentation/misc-devices/mei/mei-client-bus.txt b/Documentation/misc-devices/mei/mei-client-bus.txt
index f83910a..6ca486b 100644
--- a/Documentation/misc-devices/mei/mei-client-bus.txt
+++ b/Documentation/misc-devices/mei/mei-client-bus.txt
@@ -1,9 +1,10 @@
 Intel(R) Management Engine (ME) Client bus API
-===============================================
+==============================================
 
 
 Rationale
 =========
+
 MEI misc character device is useful for dedicated applications to send and receive
 data to the many FW appliance found in Intel's ME from the user space.
 However for some of the ME functionalities it make sense to leverage existing software
@@ -17,7 +18,8 @@ the existing code.
 
 
 MEI CL bus API
-===========
+==============
+
 A driver implementation for an MEI Client is very similar to existing bus
 based device drivers. The driver registers itself as an MEI CL bus driver through
 the mei_cl_driver structure:
@@ -55,6 +57,7 @@ received buffers.
 
 Example
 =======
+
 As a theoretical example let's pretend the ME comes with a "contact" NFC IP.
 The driver init and exit routines for this device would look like:
 
diff --git a/Documentation/misc-devices/mei/mei.txt b/Documentation/misc-devices/mei/mei.txt
index 15bba1a..9a96af1 100644
--- a/Documentation/misc-devices/mei/mei.txt
+++ b/Documentation/misc-devices/mei/mei.txt
@@ -1,8 +1,8 @@
 Intel(R) Management Engine Interface (Intel(R) MEI)
-=======================
+===================================================
 
 Introduction
-=======================
+============
 
 The Intel Management Engine (Intel ME) is an isolated and protected computing
 resource (Co-processor) residing inside certain Intel chipsets. The Intel ME
@@ -44,8 +44,9 @@ HTTP/S that are received from a remote management console application.
 For more information about Intel AMT:
 http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
 
+
 Intel MEI Driver
-=======================
+================
 
 The driver exposes a misc device called /dev/mei.
 
@@ -91,8 +92,10 @@ A code snippet for an application communicating with Intel AMTHI client:
 	[...]
 	close(fd);
 
-IOCTL:
-======
+
+IOCTL
+=====
+
 The Intel MEI Driver supports the following IOCTL command:
 	IOCTL_MEI_CONNECT_CLIENT	Connect to firmware Feature (client).
 
@@ -122,8 +125,9 @@ The Intel MEI Driver supports the following IOCTL command:
         data that can be sent or received. (e.g. if MTU=2K, can send
         requests up to bytes 2k and received responses up to 2k bytes).
 
-Intel ME Applications:
-==============
+
+Intel ME Applications
+=====================
 
 1) Intel Local Management Service (Intel LMS)
 
@@ -172,8 +176,9 @@ Intel ME Applications:
 	http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
 
 
-Intel AMT OS Health Watchdog:
-=============================
+Intel AMT OS Health Watchdog
+============================
+
 The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
 Whenever the OS hangs or crashes, Intel AMT will send an event
 to any subscriber to this event. This mechanism means that
@@ -192,8 +197,10 @@ watchdog is 120 seconds.
 If the Intel AMT Watchdog feature does not exist (i.e. the connection failed),
 the Intel MEI driver will disable the sending of heartbeats.
 
-Supported Chipsets:
+
+Supported Chipsets
 ==================
+
 7 Series Chipset Family
 6 Series Chipset Family
 5 Series Chipset Family
-- 
2.2.1

Re: [PATCH 1/4] Documentation/misc-devices/mei: Fix formatting of headings.

[Jonathan Corbet]

On Mon, 12 Jan 2015 00:58:06 +0100
Julian Brost <linux-kernel@0x4a42.net> wrote:

> Make the heading underlines fit the length of the heading, remove colons
> at the end of headings and consistently place an empty line after each
> heading and two empty lines before each that is preceded by a paragraph.
> 
> Signed-off-by: Julian Brost <linux-kernel@0x4a42.net>
> Signed-off-by: Fabian Hofmann <fabian.hofmann@fau.de>

[Finally catching up with stuff after a long travel]

These changes look fine, but what's with the two signoffs?  Who is the
actual author of these patches, and why is the second signoff there?

Thanks,

jon

Re: [i4passt] [PATCH 1/4] Documentation/misc-devices/mei: Fix formatting of headings.

[Alexander Wuerstlein]

On 2015-01-28T20:17, Jonathan Corbet <corbet@lwn.net> wrote:
> On Mon, 12 Jan 2015 00:58:06 +0100
> Julian Brost <linux-kernel@0x4a42.net> wrote:
> 
> > Make the heading underlines fit the length of the heading, remove colons
> > at the end of headings and consistently place an empty line after each
> > heading and two empty lines before each that is preceded by a paragraph.
> > 
> > Signed-off-by: Julian Brost <linux-kernel@0x4a42.net>
> > Signed-off-by: Fabian Hofmann <fabian.hofmann@fau.de>
> 
> [Finally catching up with stuff after a long travel]
> 
> These changes look fine, but what's with the two signoffs?  Who is the
> actual author of these patches, and why is the second signoff there?

I'm not an author of this patch, but I can explain that: Julian and
Fabian are students of mine and as part of classwork they are supposed
to submit a patch to the linux kernel. Since we require our students to
work in groups of two and to collaborate on producing and submitting the
patch, we also strongly urge them to submit with two signed-off-by-lines
to properly attribute the patch to both students.

I hope this doesn't cause any confusion or misbehaving tools or
anything.

If you are interested in further information on the course you can visit
https://www4.cs.fau.de/Lehre/WS14/P_PASST/ (unfortunately only in
german) or ask me by email. There is also a (not up-to-date for this
semester) list of previously accepted patches that were produced in
earlier iterations of this course:
https://www4.cs.fau.de/Lehre/WS14/P_PASST/kernel-commits-all.shtml


Greetings,

Alexander Wuerstlein.

----
Alexander Wuerstlein         Informatik 4            Univ. of Erlangen
Martensstrasse 1            91058 Erlangen           +49-9131-85-27824
arw@arw.name  arw@cs.fau.de   3CD3D074014E217A745FC4A34E2CCA53C746347D
snalwuer@cip.cs.fau.de                     https://www4.cs.fau.de/~arw

Re: [i4passt] [PATCH 1/4] Documentation/misc-devices/mei: Fix formatting of headings.

[Jonathan Corbet]

On Thu, 29 Jan 2015 02:39:18 +0100
Alexander Wuerstlein <arw@cs.fau.de> wrote:

> I'm not an author of this patch, but I can explain that: Julian and
> Fabian are students of mine and as part of classwork they are supposed
> to submit a patch to the linux kernel. Since we require our students to
> work in groups of two and to collaborate on producing and submitting the
> patch, we also strongly urge them to submit with two signed-off-by-lines
> to properly attribute the patch to both students.

OK, good enough; patches have been applied.

Thanks,

jon

[PATCH 2/4] Documentation/misc-devices/mei: Fix spacing around parentheses.

[Julian Brost]

Add a space before opening and after closing parentheses where
appropriate.

Signed-off-by: Julian Brost <linux-kernel@0x4a42.net>
Signed-off-by: Fabian Hofmann <fabian.hofmann@fau.de>
---
 Documentation/misc-devices/mei/mei.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/misc-devices/mei/mei.txt b/Documentation/misc-devices/mei/mei.txt
index 9a96af1..63f9ccc 100644
--- a/Documentation/misc-devices/mei/mei.txt
+++ b/Documentation/misc-devices/mei/mei.txt
@@ -19,7 +19,7 @@ each client has its own protocol. The protocol is message-based with a
 header and payload up to 512 bytes.
 
 Prominent usage of the Intel ME Interface is to communicate with Intel(R)
-Active Management Technology (Intel AMT)implemented in firmware running on
+Active Management Technology (Intel AMT) implemented in firmware running on
 the Intel ME.
 
 Intel AMT provides the ability to manage a host remotely out-of-band (OOB)
@@ -150,15 +150,15 @@ Intel ME Applications
 
 	The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
 	firmware feature using a defined UUID and then communicates with the feature
-	using a protocol called Intel AMT Port Forwarding Protocol(Intel APF protocol).
+	using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
 	The protocol is used to maintain multiple sessions with Intel AMT from a
 	single application.
 
-	See the protocol specification in the Intel AMT Software Development Kit(SDK)
+	See the protocol specification in the Intel AMT Software Development Kit (SDK)
 	http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
-	Under "SDK Resources" => "Intel(R) vPro(TM) Gateway(MPS)"
+	Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
 	=> "Information for Intel(R) vPro(TM) Gateway Developers"
-	=> "Description of the Intel AMT Port Forwarding (APF)Protocol"
+	=> "Description of the Intel AMT Port Forwarding (APF) Protocol"
 
   2) Intel AMT Remote configuration using a Local Agent
 	A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
-- 
2.2.1

[PATCH 3/4] Documentation/misc-devices/mei: Fix indentation of enumeration.

[Julian Brost]

Properly indent a list in mei.txt in the same way as another list in
that file.

Signed-off-by: Julian Brost <linux-kernel@0x4a42.net>
Signed-off-by: Fabian Hofmann <fabian.hofmann@fau.de>
---
 Documentation/misc-devices/mei/mei.txt | 91 +++++++++++++++++-----------------
 1 file changed, 46 insertions(+), 45 deletions(-)

diff --git a/Documentation/misc-devices/mei/mei.txt b/Documentation/misc-devices/mei/mei.txt
index 63f9ccc..8d47501 100644
--- a/Documentation/misc-devices/mei/mei.txt
+++ b/Documentation/misc-devices/mei/mei.txt
@@ -129,51 +129,52 @@ The Intel MEI Driver supports the following IOCTL command:
 Intel ME Applications
 =====================
 
-1) Intel Local Management Service (Intel LMS)
-
-	Applications running locally on the platform communicate with Intel AMT Release
-	2.0 and later releases in the same way that network applications do via SOAP
-	over HTTP (deprecated starting with Release 6.0) or with WS-Management over
-	SOAP over HTTP. This means that some Intel AMT features can be accessed from a
-	local application using the same network interface as a remote application
-	communicating with Intel AMT over the network.
-
-	When a local application sends a message addressed to the local Intel AMT host
-	name, the Intel LMS, which listens for traffic directed to the host name,
-	intercepts the message and routes it to the Intel MEI.
-	For more information:
-	http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
-	Under "About Intel AMT" => "Local Access"
-
-	For downloading Intel LMS:
-	http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
-
-	The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
-	firmware feature using a defined UUID and then communicates with the feature
-	using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
-	The protocol is used to maintain multiple sessions with Intel AMT from a
-	single application.
-
-	See the protocol specification in the Intel AMT Software Development Kit (SDK)
-	http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
-	Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
-	=> "Information for Intel(R) vPro(TM) Gateway Developers"
-	=> "Description of the Intel AMT Port Forwarding (APF) Protocol"
-
-  2) Intel AMT Remote configuration using a Local Agent
-	A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
-	without requiring installing additional data to enable setup. The remote
-	configuration process may involve an ISV-developed remote configuration
-	agent that runs on the host.
-	For more information:
-	http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
-	Under "Setup and Configuration of Intel AMT" =>
-	"SDK Tools Supporting Setup and Configuration" =>
-	"Using the Local Agent Sample"
-
-	An open source Intel AMT configuration utility,	implementing a local agent
-	that accesses the Intel MEI driver, can be found here:
-	http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
+	1) Intel Local Management Service (Intel LMS)
+
+	   Applications running locally on the platform communicate with Intel AMT Release
+	   2.0 and later releases in the same way that network applications do via SOAP
+	   over HTTP (deprecated starting with Release 6.0) or with WS-Management over
+	   SOAP over HTTP. This means that some Intel AMT features can be accessed from a
+	   local application using the same network interface as a remote application
+	   communicating with Intel AMT over the network.
+
+	   When a local application sends a message addressed to the local Intel AMT host
+	   name, the Intel LMS, which listens for traffic directed to the host name,
+	   intercepts the message and routes it to the Intel MEI.
+	   For more information:
+	   http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
+	   Under "About Intel AMT" => "Local Access"
+
+	   For downloading Intel LMS:
+	   http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
+
+	   The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
+	   firmware feature using a defined UUID and then communicates with the feature
+	   using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
+	   The protocol is used to maintain multiple sessions with Intel AMT from a
+	   single application.
+
+	   See the protocol specification in the Intel AMT Software Development Kit (SDK)
+	   http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
+	   Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
+	   => "Information for Intel(R) vPro(TM) Gateway Developers"
+	   => "Description of the Intel AMT Port Forwarding (APF) Protocol"
+
+	2) Intel AMT Remote configuration using a Local Agent
+
+	   A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
+	   without requiring installing additional data to enable setup. The remote
+	   configuration process may involve an ISV-developed remote configuration
+	   agent that runs on the host.
+	   For more information:
+	   http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
+	   Under "Setup and Configuration of Intel AMT" =>
+	   "SDK Tools Supporting Setup and Configuration" =>
+	   "Using the Local Agent Sample"
+
+	   An open source Intel AMT configuration utility,	implementing a local agent
+	   that accesses the Intel MEI driver, can be found here:
+	   http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
 
 
 Intel AMT OS Health Watchdog
-- 
2.2.1

[PATCH 4/4] Documentation/misc-devices/mei: Fix indentation of embedded code.

[Julian Brost]

Some of the source code embedded in mei-client-bus.txt was indented
using spaces. This properly indents it with tabs and also removes a
single space that was placed in front of a closing curly brace.

Signed-off-by: Julian Brost <linux-kernel@0x4a42.net>
Signed-off-by: Fabian Hofmann <fabian.hofmann@fau.de>
---
 Documentation/misc-devices/mei/mei-client-bus.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/misc-devices/mei/mei-client-bus.txt b/Documentation/misc-devices/mei/mei-client-bus.txt
index 6ca486b..743be4e 100644
--- a/Documentation/misc-devices/mei/mei-client-bus.txt
+++ b/Documentation/misc-devices/mei/mei-client-bus.txt
@@ -72,11 +72,11 @@ static struct mei_cl_device_id contact_mei_cl_tbl[] = {
 MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
 
 static struct mei_cl_driver contact_driver = {
-       .id_table = contact_mei_tbl,
-       .name = CONTACT_DRIVER_NAME,
+	.id_table = contact_mei_tbl,
+	.name = CONTACT_DRIVER_NAME,
 
-       .probe = contact_probe,
-       .remove = contact_remove,
+	.probe = contact_probe,
+	.remove = contact_remove,
 };
 
 static int contact_init(void)
@@ -112,7 +112,7 @@ int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id)
 	mei_cl_register_event_cb(dev, contact_event_cb, contact);
 
 	return 0;
- }
+}
 
 In the probe routine the driver first enable the MEI device and then registers
 an ME bus event handler which is as close as it can get to registering a
-- 
2.2.1

Re: [PATCH 4/4] Documentation/misc-devices/mei: Fix indentation of embedded code.

[Jeremiah Mahler]

Julian,

On Mon, Jan 12, 2015 at 12:58:09AM +0100, Julian Brost wrote:
[...]
>  static struct mei_cl_driver contact_driver = {
> -       .id_table = contact_mei_tbl,
> -       .name = CONTACT_DRIVER_NAME,
> +	.id_table = contact_mei_tbl,
> +	.name = CONTACT_DRIVER_NAME,
>  
> -       .probe = contact_probe,
> -       .remove = contact_remove,
> +	.probe = contact_probe,
> +	.remove = contact_remove,
>  };
>  

Looking at this file the majority of the code is formatted at the left
with tabs.  So I think your change is in agreement with the current
design.

[...]

Reviewed-by: Jeremiah Mahler <jmmahler@gmail.com>

-- 
- Jeremiah Mahler

Re: [PATCH 0/4] Documentation/misc-devices/mei: Fix formatting

[Jeremiah Mahler]

Julian,

On Mon, Jan 12, 2015 at 12:58:05AM +0100, Julian Brost wrote:
> This patch series fixes multiple formatting issues in the documentation for the
> Intel MEI, including improperly formatted headlines and issues with spacing and
> indentation.
> 
> Julian Brost (4):
>   Documentation/misc-devices/mei: Fix formatting of headings.
>   Documentation/misc-devices/mei: Fix spacing around parentheses.
>   Documentation/misc-devices/mei: Fix indentation of enumeration.
>   Documentation/misc-devices/mei: Fix indentation of embedded code.
> 
>  Documentation/misc-devices/mei/mei-client-bus.txt |  17 +--
>  Documentation/misc-devices/mei/mei.txt            | 126 ++++++++++++----------
>  2 files changed, 77 insertions(+), 66 deletions(-)
> 
> -- 
> 2.2.1
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Series looks good.

I'm glad I am not the only one with OCD around here :-)

Reviewed-by: Jeremiah Mahler <jmmahler@gmail.com>

-- 
- Jeremiah Mahler

RE: [PATCH 0/4] Documentation/misc-devices/mei: Fix formatting

[Winkler, Tomas]

> Julian,
> 
> On Mon, Jan 12, 2015 at 12:58:05AM +0100, Julian Brost wrote:
> > This patch series fixes multiple formatting issues in the documentation for the
> > Intel MEI, including improperly formatted headlines and issues with spacing and
> > indentation.
> >
> > Julian Brost (4):
> >   Documentation/misc-devices/mei: Fix formatting of headings.
> >   Documentation/misc-devices/mei: Fix spacing around parentheses.
> >   Documentation/misc-devices/mei: Fix indentation of enumeration.
> >   Documentation/misc-devices/mei: Fix indentation of embedded code.
> >
> >  Documentation/misc-devices/mei/mei-client-bus.txt |  17 +--
> >  Documentation/misc-devices/mei/mei.txt            | 126 ++++++++++++----------
> >  2 files changed, 77 insertions(+), 66 deletions(-)
> >
> > --

> 
> Series looks good.
> 
> I'm glad I am not the only one with OCD around here :-)
> 
> Reviewed-by: Jeremiah Mahler <jmmahler@gmail.com>

Thanks for the cleanup

ACK

Tomas