> -----Original Message----- > From: Shreeya Patel [mailto:shreeya.patel23498@xxxxxxxxx] > Sent: Sunday, June 30, 2019 00:32 > To: skhan@xxxxxxxxxxxxxxxxxxx; corbet@xxxxxxx; Winkler, Tomas > <tomas.winkler@xxxxxxxxx>; linux-doc@xxxxxxxxxxxxxxx; linux- > kernel@xxxxxxxxxxxxxxx; linux-kernel-mentees@xxxxxxxxxxxxxxxxxxxxxxxxx > Subject: [PATCH] Documentation: misc-devices: mei: Convert mei txt files to > reST > > Convert the MEI misc device's documentation files from .txt to > reStructuredText format. Make a minor change of correcting the wrong macro > name MEI_CONNECT_CLIENT_IOCTL to IOCTL_MEI_CONNECT_CLIENT. > Add an index file in mei as there are two sections for it in the documentation. > > Signed-off-by: Shreeya Patel <shreeya.patel23498@xxxxxxxxx> > --- Sorry you are late, we've already done that, it should be merged via Greg's char-misc tree. Thanks Tomas > 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 > + > +--- > +linux-mei@xxxxxxxxxxxxxxx > diff --git a/Documentation/misc-devices/mei/mei.txt b/Documentation/misc- > devices/mei/mei.txt > deleted file mode 100644 > index 2b80a0cd621f..000000000000 > --- a/Documentation/misc-devices/mei/mei.txt > +++ /dev/null > @@ -1,266 +0,0 @@ > -Intel(R) Management Engine Interface (Intel(R) MEI) - > =================================================== > - > -Introduction > -============ > - > -The Intel Management Engine (Intel ME) is an isolated and protected > computing -resource (Co-processor) residing inside certain Intel chipsets. The > Intel ME -provides support for computer/IT management features. The feature > set -depends on the Intel chipset SKU. > - > -The Intel Management Engine Interface (Intel MEI, previously known as HECI) > -is the interface between the Host and Intel ME. This interface is exposed -to > the host as a PCI device. The Intel MEI Driver is in charge of the - > communication channel between a host application and the Intel ME feature. > - > -Each Intel ME feature (Intel ME Client) is addressed by a GUID/UUID and -each > client has its own protocol. The protocol is message-based with a -header and > payload up to 512 bytes. > - > -Prominent usage of the Intel ME Interface is to communicate with Intel(R) - > Active Management Technology (Intel AMT) implemented in firmware running > on -the Intel ME. > - > -Intel AMT provides the ability to manage a host remotely out-of-band (OOB) - > even when the operating system running on the host processor has crashed or - > is in a sleep state. > - > -Some examples of Intel AMT usage are: > - - Monitoring hardware state and platform components > - - Remote power off/on (useful for green computing or overnight IT > - maintenance) > - - OS updates > - - Storage of useful platform information such as software assets > - - Built-in hardware KVM > - - Selective network isolation of Ethernet and IP protocol flows based > - on policies set by a remote management console > - - IDE device redirection from remote management console > - > -Intel AMT (OOB) communication is based on SOAP (deprecated -starting with > Release 6.0) over HTTP/S or WS-Management protocol over -HTTP/S that are > received from a remote management console application. > - > -For more information about Intel AMT: > - > http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe > rence_Guide > - > - > -Intel MEI Driver > -================ > - > -The driver exposes a misc device called /dev/mei. > - > -An application maintains communication with an Intel ME feature while - > /dev/mei is open. The binding to a specific feature is performed by calling - > MEI_CONNECT_CLIENT_IOCTL, which passes the desired UUID. > -The number of instances of an Intel ME feature that can be opened -at the > same time depends on the Intel ME feature, but most of the -features allow > only a single instance. > - > -The Intel AMT Host Interface (Intel AMTHI) feature supports multiple - > simultaneous user connected applications. The Intel MEI driver -handles this > internally by maintaining request queues for the applications. > - > -The driver is transparent to data that are passed between firmware feature - > and host application. > - > -Because some of the Intel ME features can change the system -configuration, > the driver by default allows only a privileged -user to access it. > - > -A code snippet for an application communicating with Intel AMTHI client: > - > - struct mei_connect_client_data data; > - fd = open(MEI_DEVICE); > - > - data.d.in_client_uuid = AMTHI_UUID; > - > - ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data); > - > - printf("Ver=%d, MaxLen=%ld\n", > - data.d.in_client_uuid.protocol_version, > - data.d.in_client_uuid.max_msg_length); > - > - [...] > - > - write(fd, amthi_req_data, amthi_req_data_len); > - > - [...] > - > - read(fd, &amthi_res_data, amthi_res_data_len); > - > - [...] > - close(fd); > - > - > -IOCTL > -===== > - > -The Intel MEI Driver supports the following IOCTL commands: > - IOCTL_MEI_CONNECT_CLIENT Connect to firmware Feature (client). > - > - usage: > - struct mei_connect_client_data clientData; > - ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData); > - > - inputs: > - mei_connect_client_data struct contain the following > - input field: > - > - in_client_uuid - UUID of the FW Feature that needs > - to connect to. > - outputs: > - out_client_properties - Client Properties: MTU and Protocol > Version. > - > - error returns: > - EINVAL Wrong IOCTL Number > - ENODEV Device or Connection is not initialized or > ready. > - (e.g. Wrong UUID) > - ENOMEM Unable to allocate memory to client internal > data. > - EFAULT Fatal Error (e.g. Unable to access user input data) > - EBUSY Connection Already Open > - > - Notes: > - max_msg_length (MTU) in client properties describes the maximum > - data that can be sent or received. (e.g. if MTU=2K, can send > - requests up to bytes 2k and received responses up to 2k bytes). > - > - IOCTL_MEI_NOTIFY_SET: enable or disable event notifications > - > - Usage: > - uint32_t enable; > - ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable); > - > - Inputs: > - uint32_t enable = 1; > - or > - uint32_t enable[disable] = 0; > - > - Error returns: > - EINVAL Wrong IOCTL Number > - ENODEV Device is not initialized or the client not > connected > - ENOMEM Unable to allocate memory to client internal > data. > - EFAULT Fatal Error (e.g. Unable to access user input data) > - EOPNOTSUPP if the device doesn't support the feature > - > - Notes: > - The client must be connected in order to enable notification events > - > - > - IOCTL_MEI_NOTIFY_GET : retrieve event > - > - Usage: > - uint32_t event; > - ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event); > - > - Outputs: > - 1 - if an event is pending > - 0 - if there is no even pending > - > - Error returns: > - EINVAL Wrong IOCTL Number > - ENODEV Device is not initialized or the client not > connected > - ENOMEM Unable to allocate memory to client internal > data. > - EFAULT Fatal Error (e.g. Unable to access user input data) > - EOPNOTSUPP if the device doesn't support the feature > - > - Notes: > - The client must be connected and event notification has to be enabled > - in order to receive an event > - > - > -Intel ME Applications > -===================== > - > - 1) Intel Local Management Service (Intel LMS) > - > - Applications running locally on the platform communicate with Intel > AMT Release > - 2.0 and later releases in the same way that network applications do > via SOAP > - over HTTP (deprecated starting with Release 6.0) or with WS- > Management over > - SOAP over HTTP. This means that some Intel AMT features can be > accessed from a > - local application using the same network interface as a remote > application > - communicating with Intel AMT over the network. > - > - When a local application sends a message addressed to the local Intel > AMT host > - name, the Intel LMS, which listens for traffic directed to the host > name, > - intercepts the message and routes it to the Intel MEI. > - For more information: > - > http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe > rence_Guide > - Under "About Intel AMT" => "Local Access" > - > - For downloading Intel LMS: > - http://software.intel.com/en-us/articles/download-the-latest-intel- > amt-open-source-drivers/ > - > - The Intel LMS opens a connection using the Intel MEI driver to the > Intel LMS > - firmware feature using a defined UUID and then communicates with > the feature > - using a protocol called Intel AMT Port Forwarding Protocol (Intel APF > protocol). > - The protocol is used to maintain multiple sessions with Intel AMT > from a > - single application. > - > - See the protocol specification in the Intel AMT Software Development > Kit (SDK) > - > http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe > rence_Guide > - Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)" > - => "Information for Intel(R) vPro(TM) Gateway Developers" > - => "Description of the Intel AMT Port Forwarding (APF) Protocol" > - > - 2) Intel AMT Remote configuration using a Local Agent > - > - A Local Agent enables IT personnel to configure Intel AMT out-of-the- > box > - without requiring installing additional data to enable setup. The > remote > - configuration process may involve an ISV-developed remote > configuration > - agent that runs on the host. > - For more information: > - > http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe > rence_Guide > - Under "Setup and Configuration of Intel AMT" => > - "SDK Tools Supporting Setup and Configuration" => > - "Using the Local Agent Sample" > - > - An open source Intel AMT configuration utility, 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 > - > ---- > -linux-mei@xxxxxxxxxxxxxxx > -- > 2.17.1
