Skip to contentSkip to conversation

Documentation/misc-devices/mei: Fix formatting

PATCH In review Julian Brost 5 participants 11 messages Jan 11, 2015 – Jan 29, 2015 Documentation

lore
Share & tools
lore
#0 lore raw

cover Documentation/misc-devices/mei: Fix formatting

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(-)
Signature · 1 line
2.2.1
#1 lore raw

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

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.

---
 Documentation/misc-devices/mei/mei-client-bus.txt |  7 ++++--
 Documentation/misc-devices/mei/mei.txt            | 27 ++++++++++++++---------
 2 files changed, 22 insertions(+), 12 deletions(-)
Documentation/misc-devices/mei/mei-client-bus.txt +5 -2
index f83910a..6ca486b 100644
@@ -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:
 
Documentation/misc-devices/mei/mei.txt +17 -10
index 15bba1a..9a96af1 100644
@@ -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
Signature · 1 line
2.2.1
maintainer
#2 lore raw

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

Quoted 6 lines · On Mon, 12 Jan 2015 00:58:06 +0100 Julian Brost <[email protected]> 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.

[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

#3 lore raw

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

Quoted 7 lines · Jonathan Corbet
Quoted 4 lines · On Mon, 12 Jan 2015 00:58:06 +0100 Julian Brost <[email protected]> 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.

Quoted 7 lines
Quoted 2 lines

[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
[email protected] [email protected] 3CD3D074014E217A745FC4A34E2CCA53C746347D
[email protected] https://www4.cs.fau.de/~arw

maintainer
#4 lore raw

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

Quoted 6 lines · On Thu, 29 Jan 2015 02:39:18 +0100 Alexander Wuerstlein <[email protected]> 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

#5 lore raw

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

In reply to Julian Brost

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

---
 Documentation/misc-devices/mei/mei.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
Documentation/misc-devices/mei/mei.txt +5 -5
index 9a96af1..63f9ccc 100644
@@ -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
Signature · 1 line
2.2.1
#6 lore raw

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

In reply to Julian Brost

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

---
 Documentation/misc-devices/mei/mei.txt | 91 +++++++++++++++++-----------------
 1 file changed, 46 insertions(+), 45 deletions(-)
Documentation/misc-devices/mei/mei.txt +46 -45
index 63f9ccc..8d47501 100644
@@ -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
Signature · 1 line
2.2.1
#7 lore raw

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

In reply to 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.

---
 Documentation/misc-devices/mei/mei-client-bus.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
Documentation/misc-devices/mei/mei-client-bus.txt +5 -5
index 6ca486b..743be4e 100644
@@ -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
Signature · 1 line
2.2.1
Reviewed-by on v1 4/4
#8 lore raw

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

Julian,

On Mon, Jan 12, 2015 at 12:58:09AM +0100, Julian Brost wrote:
[...]

Documentation/misc-devices/mei/mei-client-bus.txt static struct mei_cl_device_id contact_mei_cl_tbl[] = { · line 80

Quoted 12 lines

static struct mei_cl_driver contact_driver = {

Documentation/misc-devices/mei/mei-client-bus.txt +4 -4
-       .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.

[...]

Signature · 1 line
- Jeremiah Mahler
Reviewed-by on the v1 series
#9 lore raw
In reply to Julian Brost

Julian,

Quoted 10 lines · 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.

Quoted 11 lines
 Documentation/misc-devices/mei/mei-client-bus.txt |  17 +--
 Documentation/misc-devices/mei/mei.txt            | 126 ++++++++++++----------
 2 files changed, 77 insertions(+), 66 deletions(-)
Signature · 6 lines
2.2.1

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to [email protected]
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 :-)

Signature · 1 line
- Jeremiah Mahler
#10 lore raw
Quoted 17 lines

Julian,

Quoted 14 lines · 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(-)
Quoted 8 lines
Quoted 1 line

--

Series looks good.

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

Thanks for the cleanup

ACK

Tomas