Re: [PATCH] Documentation: misc-devices: mei: Convert mei txt files to reST

[Shreeya Patel]

On Sun, 2019-06-30 at 06:23 +0000, Winkler, Tomas wrote:
> > -----Original Message-----
> > From: Shreeya Patel [mailto:shreeya.patel23498@xxxxxxxxx]
> > Sent: Sunday, June 30, 2019 00:32
> > To: skhan@xxxxxxxxxxxxxxxxxxx; corbet@xxxxxxx; Winkler, Tomas
> > <tomas.winkler@xxxxxxxxx>; linux-doc@xxxxxxxxxxxxxxx; linux-
> > kernel@xxxxxxxxxxxxxxx; 
> > linux-kernel-mentees@xxxxxxxxxxxxxxxxxxxxxxxxx
> > Subject: [PATCH] Documentation: misc-devices: mei: Convert mei txt
> > files to
> > reST
> > 
> > Convert the MEI misc device's documentation files from .txt to
> > reStructuredText format. Make a minor change of correcting the
> > wrong macro
> > name MEI_CONNECT_CLIENT_IOCTL to IOCTL_MEI_CONNECT_CLIENT.
> > Add an index file in mei as there are two sections for it in the
> > documentation.
> > 
> > Signed-off-by: Shreeya Patel <shreeya.patel23498@xxxxxxxxx>
> > ---
> 
> Sorry you are late, we've already done that, it should be merged via
> Greg's char-misc tree.
> Thanks
> Tomas
> 
Oh okay.
Thanks
> 
> 
> > I am not sure if I have placed the Documentation in the right place
> > so I would
> > like to get some suggestions from the MAINTAINERS on this part.
> > 
> >  Documentation/misc-devices/index.rst          |   1 +
> >  Documentation/misc-devices/mei/index.rst      |  15 +
> >  .../misc-devices/mei/mei-client-bus.rst       | 151 +++++++++
> >  .../misc-devices/mei/mei-client-bus.txt       | 141 ---------
> >  Documentation/misc-devices/mei/mei.rst        | 289
> > ++++++++++++++++++
> >  Documentation/misc-devices/mei/mei.txt        | 266 --------------
> > --
> >  6 files changed, 456 insertions(+), 407 deletions(-)  create mode
> > 100644
> > Documentation/misc-devices/mei/index.rst
> >  create mode 100644 Documentation/misc-devices/mei/mei-client-
> > bus.rst
> >  delete mode 100644 Documentation/misc-devices/mei/mei-client-
> > bus.txt
> >  create mode 100644 Documentation/misc-devices/mei/mei.rst
> >  delete mode 100644 Documentation/misc-devices/mei/mei.txt
> > 
> > diff --git a/Documentation/misc-devices/index.rst
> > b/Documentation/misc-
> > devices/index.rst
> > index dfd1f45a3127..e788a12b2b19 100644
> > --- a/Documentation/misc-devices/index.rst
> > +++ b/Documentation/misc-devices/index.rst
> > @@ -15,3 +15,4 @@ fit into other categories.
> >     :maxdepth: 2
> > 
> >     ibmvmc
> > +   mei/index
> > diff --git a/Documentation/misc-devices/mei/index.rst
> > b/Documentation/misc-
> > devices/mei/index.rst
> > new file mode 100644
> > index 000000000000..3018098ad075
> > --- /dev/null
> > +++ b/Documentation/misc-devices/mei/index.rst
> > @@ -0,0 +1,15 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +===============================================================
> > ==
> > +Intel(R) Management Engine Interface Kernel Driver (Intel(R) MEI)
> > +===============================================================
> > ==
> > +
> > +.. class:: toc-title
> > +
> > +           Table of contents
> > +
> > +.. toctree::
> > +   :maxdepth: 2
> > +
> > +   mei
> > +   mei-client-bus
> > diff --git a/Documentation/misc-devices/mei/mei-client-bus.rst
> > b/Documentation/misc-devices/mei/mei-client-bus.rst
> > new file mode 100644
> > index 000000000000..82d455afae78
> > --- /dev/null
> > +++ b/Documentation/misc-devices/mei/mei-client-bus.rst
> > @@ -0,0 +1,151 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +==============================================
> > +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 stack and expose them through existing kernel
> > subsystems.
> > +
> > +In order to plug seamlessly into the kernel device driver model we
> > add
> > +kernel virtual bus abstraction on top of the MEI driver. This
> > allows
> > +implementing linux kernel drivers for the various MEI features as
> > a stand
> > alone entities found in their respective subsystem.
> > +Existing device drivers can even potentially be re-used by adding
> > an
> > +MEI CL bus layer to 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 :c:type:`mei_cl_driver` structure:
> > +
> > +::
> > +
> > +        struct mei_cl_driver {
> > +	        struct device_driver driver;
> > +	        const char *name;
> > +
> > +	        const struct mei_cl_device_id *id_table;
> > +
> > +	        int (*probe)(struct mei_cl_device *dev, const struct
> > mei_cl_id
> > *id);
> > +	        int (*remove)(struct mei_cl_device *dev);
> > +        };
> > +
> > +        struct mei_cl_id {
> > +	        char name[MEI_NAME_SIZE];
> > +	        kernel_ulong_t driver_info;
> > +        };
> > +
> > +
> > +The :c:type:`mei_cl_id` structure allows the driver to bind itself
> > against a
> > device name.
> > +
> > +To actually register a driver on the ME Client bus one must call
> > the
> > +:c:func:`mei_cl_add_driver()` API. This is typically called at
> > module init time.
> > +
> > +Once registered on the ME Client bus, a driver will typically try
> > to do
> > +some I/O on this bus and this should be done through the
> > +:c:func:`mei_cl_send()` and :c:func:`mei_cl_recv()` routines. The
> > latter is
> > synchronous (blocks and sleeps until data shows up).
> > +In order for drivers to be notified of pending events waiting for
> > them (e.g.
> > +an Rx event) they can register an event handler through the
> > +:c:func:`mei_cl_register_event_cb()` routine. Currently only the
> > +:c:macro:`MEI_EVENT_RX` event will trigger an event handler call
> > and
> > +the driver implementation is supposed to call :c:func:`mei_recv()`
> > from
> > +the event handler in order to fetch the pending 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:
> > +
> > +::
> > +
> > +        #define CONTACT_DRIVER_NAME "contact"
> > +
> > +        static struct mei_cl_device_id contact_mei_cl_tbl[] = {
> > +	        { CONTACT_DRIVER_NAME, },
> > +	        /* required last entry */
> > +	        { }
> > +        };
> > +        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,
> > +	        .probe = contact_probe,
> > +	        .remove = contact_remove,
> > +        };
> > +
> > +        static int contact_init(void)
> > +        {
> > +	        int r;
> > +
> > +	        r = mei_cl_driver_register(&contact_driver);
> > +	        if (r) {
> > +		        pr_err(CONTACT_DRIVER_NAME ": driver
> > registration
> > failed\n");
> > +		        return r;
> > +	        }
> > +
> > +	        return 0;
> > +        }
> > +
> > +        static void __exit contact_exit(void)
> > +        {
> > +	        mei_cl_driver_unregister(&contact_driver);
> > +        }
> > +
> > +        module_init(contact_init);
> > +        module_exit(contact_exit);
> > +
> > +And the driver's simplified probe routine would look like that:
> > +
> > +::
> > +
> > +        int contact_probe(struct mei_cl_device *dev, struct
> > mei_cl_device_id
> > *id)
> > +        {
> > +	        struct contact_driver *contact;
> > +
> > +	        [...]
> > +	        mei_cl_enable_device(dev);
> > +
> > +	        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 threaded IRQ handler.
> > +The handler implementation will typically call some I/O routine
> > +depending on the pending events:
> > +
> > +::
> > +
> > +        #define MAX_NFC_PAYLOAD 128
> > +
> > +        static void contact_event_cb(struct mei_cl_device *dev,
> > u32 events,
> > +                                     void *context)
> > +        {
> > +	        struct contact_driver *contact = context;
> > +
> > +	        if (events & BIT(MEI_EVENT_RX)) {
> > +		        u8 payload[MAX_NFC_PAYLOAD];
> > +		        int payload_size;
> > +
> > +		        payload_size = mei_recv(dev, payload,
> > MAX_NFC_PAYLOAD);
> > +		        if (payload_size <= 0)
> > +			        return;
> > +
> > +		        /* Hook to the NFC subsystem */
> > +		        nfc_hci_recv_frame(contact->hdev, payload,
> > payload_size);
> > +	        }
> > +        }
> > diff --git a/Documentation/misc-devices/mei/mei-client-bus.txt
> > b/Documentation/misc-devices/mei/mei-client-bus.txt
> > deleted file mode 100644
> > index 743be4ec8989..000000000000
> > --- a/Documentation/misc-devices/mei/mei-client-bus.txt
> > +++ /dev/null
> > @@ -1,141 +0,0 @@
> > -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 -stack and expose them through existing kernel subsystems.
> > -
> > -In order to plug seamlessly into the kernel device driver model we
> > add kernel
> > virtual -bus abstraction on top of the MEI driver. This allows
> > implementing linux
> > kernel drivers -for the various MEI features as a stand alone
> > entities found in
> > their respective subsystem.
> > -Existing device drivers can even potentially be re-used by adding
> > an MEI CL
> > bus layer to -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:
> > -
> > -struct mei_cl_driver {
> > -	struct device_driver driver;
> > -	const char *name;
> > -
> > -	const struct mei_cl_device_id *id_table;
> > -
> > -	int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id
> > *id);
> > -	int (*remove)(struct mei_cl_device *dev);
> > -};
> > -
> > -struct mei_cl_id {
> > -	char name[MEI_NAME_SIZE];
> > -	kernel_ulong_t driver_info;
> > -};
> > -
> > -The mei_cl_id structure allows the driver to bind itself against a
> > device name.
> > -
> > -To actually register a driver on the ME Client bus one must call
> > the
> > mei_cl_add_driver() -API. This is typically called at module init
> > time.
> > -
> > -Once registered on the ME Client bus, a driver will typically try
> > to do some I/O
> > on -this bus and this should be done through the mei_cl_send() and
> > mei_cl_recv() -routines. The latter is synchronous (blocks and
> > sleeps until data
> > shows up).
> > -In order for drivers to be notified of pending events waiting for
> > them (e.g.
> > -an Rx event) they can register an event handler through the
> > -mei_cl_register_event_cb() routine. Currently only the
> > MEI_EVENT_RX event -
> > will trigger an event handler call and the driver implementation is
> > supposed -to
> > call mei_recv() from the event handler in order to fetch the
> > pending -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:
> > -
> > -#define CONTACT_DRIVER_NAME "contact"
> > -
> > -static struct mei_cl_device_id contact_mei_cl_tbl[] = {
> > -	{ CONTACT_DRIVER_NAME, },
> > -
> > -	/* required last entry */
> > -	{ }
> > -};
> > -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,
> > -
> > -	.probe = contact_probe,
> > -	.remove = contact_remove,
> > -};
> > -
> > -static int contact_init(void)
> > -{
> > -	int r;
> > -
> > -	r = mei_cl_driver_register(&contact_driver);
> > -	if (r) {
> > -		pr_err(CONTACT_DRIVER_NAME ": driver registration
> > failed\n");
> > -		return r;
> > -	}
> > -
> > -	return 0;
> > -}
> > -
> > -static void __exit contact_exit(void)
> > -{
> > -	mei_cl_driver_unregister(&contact_driver);
> > -}
> > -
> > -module_init(contact_init);
> > -module_exit(contact_exit);
> > -
> > -And the driver's simplified probe routine would look like that:
> > -
> > -int contact_probe(struct mei_cl_device *dev, struct
> > mei_cl_device_id *id) -{
> > -	struct contact_driver *contact;
> > -
> > -	[...]
> > -	mei_cl_enable_device(dev);
> > -
> > -	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 -
> > threaded IRQ handler.
> > -The handler implementation will typically call some I/O routine
> > depending on -
> > the pending events:
> > -
> > -#define MAX_NFC_PAYLOAD 128
> > -
> > -static void contact_event_cb(struct mei_cl_device *dev, u32
> > events,
> > -			     void *context)
> > -{
> > -	struct contact_driver *contact = context;
> > -
> > -	if (events & BIT(MEI_EVENT_RX)) {
> > -		u8 payload[MAX_NFC_PAYLOAD];
> > -		int payload_size;
> > -
> > -		payload_size = mei_recv(dev, payload, MAX_NFC_PAYLOAD);
> > -		if (payload_size <= 0)
> > -			return;
> > -
> > -		/* Hook to the NFC subsystem */
> > -		nfc_hci_recv_frame(contact->hdev, payload,
> > payload_size);
> > -	}
> > -}
> > diff --git a/Documentation/misc-devices/mei/mei.rst
> > b/Documentation/misc-
> > devices/mei/mei.rst
> > new file mode 100644
> > index 000000000000..e91ac2570b4d
> > --- /dev/null
> > +++ b/Documentation/misc-devices/mei/mei.rst
> > @@ -0,0 +1,289 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +====================================
> > +Intel(R) Management Engine Interface
> > +====================================
> > +
> > +Introduction
> > +============
> > +
> > +The Intel Management Engine (Intel ME) is an isolated and
> > protected
> > +computing resource (Co-processor) residing inside certain Intel
> > +chipsets. The Intel ME provides support for computer/IT management
> > +features. The feature set depends on the Intel chipset SKU.
> > +
> > +The Intel Management Engine Interface (Intel MEI, previously known
> > as
> > +HECI) is the interface between the Host and Intel ME. This
> > interface is
> > +exposed to the host as a PCI device. The Intel MEI Driver is in
> > charge
> > +of the communication channel between a host application and the
> > Intel ME
> > feature.
> > +
> > +Each Intel ME feature (Intel ME Client) is addressed by a
> > GUID/UUID and
> > +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 the Intel ME.
> > +
> > +Intel AMT provides the ability to manage a host remotely out-of-
> > band
> > +(OOB) even when the operating system running on the host processor
> > has
> > +crashed or is in a sleep state.
> > +
> > +Some examples of Intel AMT usage are:
> > +        * Monitoring hardware state and platform components
> > +        * Remote power off/on (useful for green computing or
> > overnight IT
> > +          maintenance)
> > +        * OS updates
> > +        * Storage of useful platform information such as software
> > assets
> > +        * Built-in hardware KVM
> > +        * Selective network isolation of Ethernet and IP protocol
> > flows based
> > +          on policies set by a remote management console
> > +        * IDE device redirection from remote management console
> > +
> > +Intel AMT (OOB) communication is based on SOAP (deprecated
> > starting
> > +with Release 6.0) over HTTP/S or WS-Management protocol over
> > 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 :file:`/dev/mei`.
> > +
> > +An application maintains communication with an Intel ME feature
> > while
> > +:file:`/dev/mei` is open. The binding to a specific feature is
> > +performed by calling :c:macro:`IOCTL_MEI_CONNECT_CLIENT`, which
> > passes
> > the desired UUID.
> > +The number of instances of an Intel ME feature that can be opened
> > at
> > +the same time depends on the Intel ME feature, but most of the
> > features
> > +allow only a single instance.
> > +
> > +The Intel AMT Host Interface (Intel AMTHI) feature supports
> > multiple
> > +simultaneous user connected applications. The Intel MEI driver
> > handles
> > +this internally by maintaining request queues for the
> > applications.
> > +
> > +The driver is transparent to data that are passed between firmware
> > +feature and host application.
> > +
> > +Because some of the Intel ME features can change the system
> > +configuration, the driver by default allows only a privileged user
> > to
> > +access it.
> > +
> > +A code snippet for an application communicating with Intel AMTHI
> > client:
> > +
> > +::
> > +
> > +        struct mei_connect_client_data data;
> > +        fd = open(MEI_DEVICE);
> > +
> > +        data.d.in_client_uuid = AMTHI_UUID;
> > +
> > +        ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
> > +
> > +        printf("Ver=%d, MaxLen=%ld\n",
> > +               data.d.in_client_uuid.protocol_version,
> > +               data.d.in_client_uuid.max_msg_length);
> > +
> > +        [...]
> > +
> > +        write(fd, amthi_req_data, amthi_req_data_len);
> > +
> > +        [...]
> > +
> > +        read(fd, &amthi_res_data, amthi_res_data_len);
> > +
> > +        [...]
> > +
> > +        close(fd);
> > +
> > +
> > +IOCTL
> > +=====
> > +
> > +The Intel MEI Driver supports the following IOCTL commands:
> > +
> > +
> > +:c:macro:`IOCTL_MEI_CONNECT_CLIENT`
> > +-------------------------------------
> > +Connect to firmware Feature (client)
> > +
> > +**Usage:**
> > +
> > +::
> > +
> > +        struct mei_connect_client_data clientData;
> > +        ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData);
> > +
> > +**Inputs:**
> > +        :c:type:`mei_connect_client_data` - structure contain the
> > following
> > +        input field.
> > +
> > +        :c:data:`in_client_uuid` - UUID of the FW Feature that
> > needs to connect
> > to.
> > +
> > +**Outputs:**
> > +        :c:data:`out_client_properties` - Client Properties: MTU
> > and Protocol
> > Version.
> > +
> > +**Error returns:**
> > +        | :c:macro:`EINVAL` -  Wrong IOCTL Number.
> > +        | :c:macro:`ENODEV` -  Device or Connection is not
> > initialized or ready.
> > (e.g. Wrong UUID).
> > +        | :c:macro:`ENOMEM` - Unable to allocate memory to client
> > internal
> > data.
> > +        | :c:macro:`EFAULT` -  Fatal Error (e.g. Unable to access
> > user input data).
> > +        | :c:macro:`EBUSY` -  Connection Already Open.
> > +
> > +**Notes:**
> > +        :c:data:`max_msg_length` (MTU) in client properties
> > describes the
> > maximum
> > +        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).
> > +
> > +
> > +:c:macro:`IOCTL_MEI_NOTIFY_SET`
> > +-------------------------------
> > +Enable or disable event notifications
> > +
> > +**Usage:**
> > +
> > +::
> > +
> > +        uint32_t enable;
> > +        ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
> > +
> > +**Inputs:**
> > +        | :c:data:`uint32_t enable = 1;`
> > +        | or
> > +        | :c:data:`uint32_t enable[disable] = 0;`
> > +
> > +**Error returns:**
> > +        | :c:macro:`EINVAL` - Wrong IOCTL Number.
> > +        | :c:macro:`ENODEV` - Device  is not initialized or the
> > client not
> > connected.
> > +        | :c:macro:`ENOMEM` - Unable to allocate memory to client
> > internal
> > data.
> > +        | :c:macro:`EFAULT` - Fatal Error (e.g. Unable to access
> > user input data).
> > +        | :c:macro:`EOPNOTSUPP` - if the device doesn't support
> > the feature.
> > +
> > +**Notes:**
> > +        The client must be connected in order to enable
> > notification events.
> > +
> > +
> > +:c:macro:`IOCTL_MEI_NOTIFY_GET`
> > +-------------------------------
> > +Retrieve event
> > +
> > +**Usage:**
> > +
> > +::
> > +
> > +        uint32_t event;
> > +        ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
> > +
> > +**Outputs:**
> > +        | 1 - if an event is pending.
> > +        | 0 - if there is no even pending.
> > +
> > +**Error returns:**
> > +        | :c:macro:`EINVAL` - Wrong IOCTL Number.
> > +        | :c:macro:`ENODEV` - Device is not initialized or the
> > client not
> > connected.
> > +        | :c:macro:`ENOMEM` - Unable to allocate memory to client
> > internal
> > data.
> > +        | :c:macro:`EFAULT` - Fatal Error (e.g. Unable to access
> > user input data).
> > +        | :c:macro:`EOPNOTSUPP` - if the device doesn't support
> > the feature.
> > +
> > +**Notes:**
> > +        The client must be connected and event notification has to
> > be enabled
> > +        in order to receive an event.
> > +
> > +
> > +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_Re
> > ference_Guide>`_
> > +        Under "About Intel AMT" => "Local Access"
> > +
> > +        For downloading Intel LMS:
> > +
> > + `<
> > http://software.intel.com/en-us/articles/download-the-latest-intel-a
> > + mt-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_Ref
> > erence_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_Re
> > ference_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,	impleme
> > nting a local
> > agent
> > +        that accesses the Intel MEI driver, can be found here:
> > +
> > + `<
> > http://software.intel.com/en-us/articles/download-the-latest-intel-a
> > + mt-open-source-drivers/>`
> > +
> > +
> > +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 IT knows when
> > a
> > +platform crashes even when there is a hard failure on the host.
> > +
> > +The Intel AMT Watchdog is composed of two parts:
> > +        1) Firmware feature - receives the heartbeats
> > +           and sends an event when the heartbeats stop.
> > +        2) Intel MEI iAMT watchdog driver - connects to the
> > watchdog feature,
> > +           configures the watchdog and sends the heartbeats.
> > +
> > +The Intel iAMT watchdog MEI driver uses the kernel watchdog API to
> > +configure the Intel AMT Watchdog and to send heartbeats to it. The
> > +default timeout of the watchdog is 120 seconds.
> > +
> > +If the Intel AMT is not enabled in the firmware then the watchdog
> > +client won't enumerate on the me client bus and watchdog devices
> > won't be
> > exposed.
> > +
> > +
> > +Supported Chipsets
> > +==================
> > +
> > +| 7 Series Chipset Family
> > +| 6 Series Chipset Family
> > +| 5 Series Chipset Family
> > +| 4 Series Chipset Family
> > +| Mobile 4 Series Chipset Family
> > +| ICH9
> > +| 82946GZ/GL
> > +| 82G35 Express
> > +| 82Q963/Q965
> > +| 82P965/G965
> > +| Mobile PM965/GM965
> > +| Mobile GME965/GLE960
> > +| 82Q35 Express
> > +| 82G33/G31/P35/P31 Express
> > +| 82Q33 Express
> > +| 82X38/X48 Express
> > +
> > +---
> > +linux-mei@xxxxxxxxxxxxxxx
> > diff --git a/Documentation/misc-devices/mei/mei.txt
> > b/Documentation/misc-
> > devices/mei/mei.txt
> > deleted file mode 100644
> > index 2b80a0cd621f..000000000000
> > --- a/Documentation/misc-devices/mei/mei.txt
> > +++ /dev/null
> > @@ -1,266 +0,0 @@
> > -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 -provides support for computer/IT management features. The
> > feature
> > set -depends on the Intel chipset SKU.
> > -
> > -The Intel Management Engine Interface (Intel MEI, previously known
> > as HECI)
> > -is the interface between the Host and Intel ME. This interface is
> > exposed -to
> > the host as a PCI device. The Intel MEI Driver is in charge of the
> > -
> > communication channel between a host application and the Intel ME
> > feature.
> > -
> > -Each Intel ME feature (Intel ME Client) is addressed by a
> > GUID/UUID and -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 -the Intel ME.
> > -
> > -Intel AMT provides the ability to manage a host remotely out-of-
> > band (OOB) -
> > even when the operating system running on the host processor has
> > crashed or -
> > is in a sleep state.
> > -
> > -Some examples of Intel AMT usage are:
> > -   - Monitoring hardware state and platform components
> > -   - Remote power off/on (useful for green computing or overnight
> > IT
> > -     maintenance)
> > -   - OS updates
> > -   - Storage of useful platform information such as software
> > assets
> > -   - Built-in hardware KVM
> > -   - Selective network isolation of Ethernet and IP protocol flows
> > based
> > -     on policies set by a remote management console
> > -   - IDE device redirection from remote management console
> > -
> > -Intel AMT (OOB) communication is based on SOAP (deprecated
> > -starting with
> > Release 6.0) over HTTP/S or WS-Management protocol over -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_Refe
> > rence_Guide
> > -
> > -
> > -Intel MEI Driver
> > -================
> > -
> > -The driver exposes a misc device called /dev/mei.
> > -
> > -An application maintains communication with an Intel ME feature
> > while -
> > /dev/mei is open. The binding to a specific feature is performed by
> > calling -
> > MEI_CONNECT_CLIENT_IOCTL, which passes the desired UUID.
> > -The number of instances of an Intel ME feature that can be opened
> > -at the
> > same time depends on the Intel ME feature, but most of the
> > -features allow
> > only a single instance.
> > -
> > -The Intel AMT Host Interface (Intel AMTHI) feature supports
> > multiple -
> > simultaneous user connected applications. The Intel MEI driver
> > -handles this
> > internally by maintaining request queues for the applications.
> > -
> > -The driver is transparent to data that are passed between firmware
> > feature -
> > and host application.
> > -
> > -Because some of the Intel ME features can change the system
> > -configuration,
> > the driver by default allows only a privileged -user to access it.
> > -
> > -A code snippet for an application communicating with Intel AMTHI
> > client:
> > -
> > -	struct mei_connect_client_data data;
> > -	fd = open(MEI_DEVICE);
> > -
> > -	data.d.in_client_uuid = AMTHI_UUID;
> > -
> > -	ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
> > -
> > -	printf("Ver=%d, MaxLen=%ld\n",
> > -			data.d.in_client_uuid.protocol_version,
> > -			data.d.in_client_uuid.max_msg_length);
> > -
> > -	[...]
> > -
> > -	write(fd, amthi_req_data, amthi_req_data_len);
> > -
> > -	[...]
> > -
> > -	read(fd, &amthi_res_data, amthi_res_data_len);
> > -
> > -	[...]
> > -	close(fd);
> > -
> > -
> > -IOCTL
> > -=====
> > -
> > -The Intel MEI Driver supports the following IOCTL commands:
> > -	IOCTL_MEI_CONNECT_CLIENT	Connect to firmware Feature
> > (client).
> > -
> > -	usage:
> > -		struct mei_connect_client_data clientData;
> > -		ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData);
> > -
> > -	inputs:
> > -		mei_connect_client_data struct contain the following
> > -		input field:
> > -
> > -		in_client_uuid -	UUID of the FW Feature that needs
> > -					to connect to.
> > -	outputs:
> > -		out_client_properties - Client Properties: MTU and
> > Protocol
> > Version.
> > -
> > -	error returns:
> > -		EINVAL	Wrong IOCTL Number
> > -		ENODEV	Device or Connection is not initialized or
> > ready.
> > -			(e.g. Wrong UUID)
> > -		ENOMEM	Unable to allocate memory to client
> > internal
> > data.
> > -		EFAULT	Fatal Error (e.g. Unable to access user
> > input data)
> > -		EBUSY	Connection Already Open
> > -
> > -	Notes:
> > -        max_msg_length (MTU) in client properties describes the
> > maximum
> > -        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).
> > -
> > -	IOCTL_MEI_NOTIFY_SET: enable or disable event notifications
> > -
> > -	Usage:
> > -		uint32_t enable;
> > -		ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
> > -
> > -	Inputs:
> > -		uint32_t enable = 1;
> > -		or
> > -		uint32_t enable[disable] = 0;
> > -
> > -	Error returns:
> > -		EINVAL	Wrong IOCTL Number
> > -		ENODEV	Device  is not initialized or the client
> > not
> > connected
> > -		ENOMEM	Unable to allocate memory to client
> > internal
> > data.
> > -		EFAULT	Fatal Error (e.g. Unable to access user
> > input data)
> > -		EOPNOTSUPP if the device doesn't support the feature
> > -
> > -	Notes:
> > -	The client must be connected in order to enable notification
> > events
> > -
> > -
> > -	IOCTL_MEI_NOTIFY_GET : retrieve event
> > -
> > -	Usage:
> > -		uint32_t event;
> > -		ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
> > -
> > -	Outputs:
> > -		1 - if an event is pending
> > -		0 - if there is no even pending
> > -
> > -	Error returns:
> > -		EINVAL	Wrong IOCTL Number
> > -		ENODEV	Device is not initialized or the client not
> > connected
> > -		ENOMEM	Unable to allocate memory to client
> > internal
> > data.
> > -		EFAULT	Fatal Error (e.g. Unable to access user
> > input data)
> > -		EOPNOTSUPP if the device doesn't support the feature
> > -
> > -	Notes:
> > -	The client must be connected and event notification has to be
> > enabled
> > -	in order to receive an event
> > -
> > -
> > -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_Refe
> > rence_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_Refe
> > rence_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_Refe
> > rence_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,	implementin
> > g 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
> > -============================
> > -
> > -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 -IT knows when
> > a platform
> > crashes even when there is a hard failure on the host.
> > -
> > -The Intel AMT Watchdog is composed of two parts:
> > -	1) Firmware feature - receives the heartbeats
> > -	   and sends an event when the heartbeats stop.
> > -	2) Intel MEI iAMT watchdog driver - connects to the watchdog
> > feature,
> > -	   configures the watchdog and sends the heartbeats.
> > -
> > -The Intel iAMT watchdog MEI driver uses the kernel watchdog API to
> > configure
> > -the Intel AMT Watchdog and to send heartbeats to it. The default
> > timeout of
> > the -watchdog is 120 seconds.
> > -
> > -If the Intel AMT is not enabled in the firmware then the watchdog
> > client won't
> > enumerate -on the me client bus and watchdog devices won't be
> > exposed.
> > -
> > -
> > -Supported Chipsets
> > -==================
> > -
> > -7 Series Chipset Family
> > -6 Series Chipset Family
> > -5 Series Chipset Family
> > -4 Series Chipset Family
> > -Mobile 4 Series Chipset Family
> > -ICH9
> > -82946GZ/GL
> > -82G35 Express
> > -82Q963/Q965
> > -82P965/G965
> > -Mobile PM965/GM965
> > -Mobile GME965/GLE960
> > -82Q35 Express
> > -82G33/G31/P35/P31 Express
> > -82Q33 Express
> > -82X38/X48 Express
> > -
> > ----
> > -linux-mei@xxxxxxxxxxxxxxx
> > --
> > 2.17.1
> 
>