mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
213 lines
5.9 KiB
213 lines
5.9 KiB
.. SPDX-License-Identifier: GPL-2.0 |
|
|
|
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 and security features. |
|
The actual 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, actually multiple PCI devices might be exposed. |
|
The Intel MEI Driver is in charge of the communication channel between |
|
a host application and the Intel ME features. |
|
|
|
Each Intel ME feature, or Intel ME Client is addressed by a unique GUID and |
|
each client has its own protocol. The protocol is message-based with a |
|
header and payload up to maximal number of bytes advertised by the client, |
|
upon connection. |
|
|
|
Intel MEI Driver |
|
================ |
|
|
|
The driver exposes a character device with device nodes /dev/meiX. |
|
|
|
An application maintains communication with an Intel ME feature while |
|
/dev/meiX is open. The binding to a specific feature is performed by calling |
|
:c:macro:`MEI_CONNECT_CLIENT_IOCTL`, which passes the desired GUID. |
|
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 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. |
|
|
|
The session is terminated calling :c:expr:`close(fd)`. |
|
|
|
A code snippet for an application communicating with Intel AMTHI client: |
|
|
|
In order to support virtualization or sandboxing a trusted supervisor |
|
can use :c:macro:`MEI_CONNECT_CLIENT_IOCTL_VTAG` to create |
|
virtual channels with an Intel ME feature. Not all features support |
|
virtual channels such client with answer EOPNOTSUPP. |
|
|
|
.. code-block:: C |
|
|
|
struct mei_connect_client_data data; |
|
fd = open(MEI_DEVICE); |
|
|
|
data.d.in_client_uuid = AMTHI_GUID; |
|
|
|
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); |
|
|
|
|
|
User space API |
|
|
|
IOCTLs: |
|
======= |
|
|
|
The Intel MEI Driver supports the following IOCTL commands: |
|
|
|
IOCTL_MEI_CONNECT_CLIENT |
|
------------------------- |
|
Connect to firmware Feature/Client. |
|
|
|
.. code-block:: none |
|
|
|
Usage: |
|
|
|
struct mei_connect_client_data client_data; |
|
|
|
ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &client_data); |
|
|
|
Inputs: |
|
|
|
struct mei_connect_client_data - contain the following |
|
Input field: |
|
|
|
in_client_uuid - GUID of the FW Feature that needs |
|
to connect to. |
|
Outputs: |
|
out_client_properties - Client Properties: MTU and Protocol Version. |
|
|
|
Error returns: |
|
|
|
ENOTTY No such client (i.e. wrong GUID) or connection is not allowed. |
|
EINVAL Wrong IOCTL Number |
|
ENODEV Device or Connection is not initialized or ready. |
|
ENOMEM Unable to allocate memory to client internal data. |
|
EFAULT Fatal Error (e.g. Unable to access user input data) |
|
EBUSY Connection Already Open |
|
|
|
:Note: |
|
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_CONNECT_CLIENT_VTAG: |
|
------------------------------ |
|
|
|
.. code-block:: none |
|
|
|
Usage: |
|
|
|
struct mei_connect_client_data_vtag client_data_vtag; |
|
|
|
ioctl(fd, IOCTL_MEI_CONNECT_CLIENT_VTAG, &client_data_vtag); |
|
|
|
Inputs: |
|
|
|
struct mei_connect_client_data_vtag - contain the following |
|
Input field: |
|
|
|
in_client_uuid - GUID of the FW Feature that needs |
|
to connect to. |
|
vtag - virtual tag [1, 255] |
|
|
|
Outputs: |
|
out_client_properties - Client Properties: MTU and Protocol Version. |
|
|
|
Error returns: |
|
|
|
ENOTTY No such client (i.e. wrong GUID) or connection is not allowed. |
|
EINVAL Wrong IOCTL Number or tag == 0 |
|
ENODEV Device or Connection is not initialized or ready. |
|
ENOMEM Unable to allocate memory to client internal data. |
|
EFAULT Fatal Error (e.g. Unable to access user input data) |
|
EBUSY Connection Already Open |
|
EOPNOTSUPP Vtag is not supported |
|
|
|
IOCTL_MEI_NOTIFY_SET |
|
--------------------- |
|
Enable or disable event notifications. |
|
|
|
|
|
.. code-block:: none |
|
|
|
Usage: |
|
|
|
uint32_t enable; |
|
|
|
ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable); |
|
|
|
|
|
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 |
|
|
|
:Note: |
|
The client must be connected in order to enable notification events |
|
|
|
|
|
IOCTL_MEI_NOTIFY_GET |
|
-------------------- |
|
Retrieve event |
|
|
|
.. code-block:: none |
|
|
|
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 |
|
|
|
:Note: |
|
The client must be connected and event notification has to be enabled |
|
in order to receive an event |
|
|
|
|
|
|
|
Supported Chipsets |
|
================== |
|
82X38/X48 Express and newer |
|
|
|
[email protected]
|
|
|