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 <[email protected]>
---
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_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
+============================
+
+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
+
+---
[email protected]
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_Reference_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_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
-============================
-
-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
-
----
[email protected]
--
2.17.1
> -----Original Message-----
> From: Shreeya Patel [mailto:[email protected]]
> Sent: Sunday, June 30, 2019 00:32
> To: [email protected]; [email protected]; Winkler, Tomas
> <[email protected]>; [email protected]; linux-
> [email protected]; [email protected]
> 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 <[email protected]>
> ---
Sorry you are late, we've already done that, it should be merged via Greg's char-misc tree.
Thanks
Tomas
> 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, 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-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
> +
> +---
> [email protected]
> 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, 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
> -============================
> -
> -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
> -
> ----
> [email protected]
> --
> 2.17.1
On Sun, 2019-06-30 at 06:23 +0000, Winkler, Tomas wrote:
> > -----Original Message-----
> > From: Shreeya Patel [mailto:[email protected]]
> > Sent: Sunday, June 30, 2019 00:32
> > To: [email protected]; [email protected]; Winkler, Tomas
> > <[email protected]>; [email protected]; linux-
> > [email protected];
> > [email protected]
> > 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 <[email protected]>
> > ---
>
> 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
> > +
> > +---
> > [email protected]
> > 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
> > -
> > ----
> > [email protected]
> > --
> > 2.17.1
>
>