Documentation/misc-devices/mei: Fix formatting
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
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
@@ -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
@@ -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
Jonathan Corbet
maintainerRe: [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.
Signed-off-by Julian Brost <[email protected]>Signed-off-by Fabian Hofmann <[email protected]>
[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.
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
Signed-off-by Julian Brost <[email protected]>Signed-off-by Fabian Hofmann <[email protected]>[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
Jonathan Corbet
maintainerRe: [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
PATCH 2/4 Documentation/misc-devices/mei: Fix spacing around parentheses.
In reply to Julian BrostAdd 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
@@ -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
PATCH 3/4 Documentation/misc-devices/mei: Fix indentation of enumeration.
In reply to Julian BrostProperly 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
@@ -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
PATCH 4/4 Documentation/misc-devices/mei: Fix indentation of embedded code.
In reply to Julian BrostSome 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
@@ -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
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_drivercontact_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
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
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 :-)
Reviewed-by Jeremiah Mahler <[email protected]>
Thanks for the cleanup
ACK
Tomas