| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
Introduction |
| 4 |
============ |
| 5 |
|
| 6 |
The Intel Management Engine (Intel ME) is an isolated and protected computing |
| 7 |
resource (Co-processor) residing inside certain Intel chipsets. The Intel ME |
| 8 |
provides support for computer/IT management and security features. |
| 9 |
The actual feature set depends on the Intel chipset SKU. |
| 10 |
|
| 11 |
The Intel Management Engine Interface (Intel MEI, previously known as HECI) |
| 12 |
is the interface between the Host and Intel ME. This interface is exposed |
| 13 |
to the host as a PCI device, actually multiple PCI devices might be exposed. |
| 14 |
The Intel MEI Driver is in charge of the communication channel between |
| 15 |
a host application and the Intel ME features. |
| 16 |
|
| 17 |
Each Intel ME feature, or Intel ME Client is addressed by a unique GUID and |
| 18 |
each client has its own protocol. The protocol is message-based with a |
| 19 |
header and payload up to maximal number of bytes advertised by the client, |
| 20 |
upon connection. |
| 21 |
|
| 22 |
Intel MEI Driver |
| 23 |
================ |
| 24 |
|
| 25 |
The driver exposes a character device with device nodes /dev/meiX. |
| 26 |
|
| 27 |
An application maintains communication with an Intel ME feature while |
| 28 |
/dev/meiX is open. The binding to a specific feature is performed by calling |
| 29 |
:c:macro:`MEI_CONNECT_CLIENT_IOCTL`, which passes the desired GUID. |
| 30 |
The number of instances of an Intel ME feature that can be opened |
| 31 |
at the same time depends on the Intel ME feature, but most of the |
| 32 |
features allow only a single instance. |
| 33 |
|
| 34 |
The driver is transparent to data that are passed between firmware feature |
| 35 |
and host application. |
| 36 |
|
| 37 |
Because some of the Intel ME features can change the system |
| 38 |
configuration, the driver by default allows only a privileged |
| 39 |
user to access it. |
| 40 |
|
| 41 |
The session is terminated calling :c:expr:`close(fd)`. |
| 42 |
|
| 43 |
A code snippet for an application communicating with Intel AMTHI client: |
| 44 |
|
| 45 |
In order to support virtualization or sandboxing a trusted supervisor |
| 46 |
can use :c:macro:`MEI_CONNECT_CLIENT_IOCTL_VTAG` to create |
| 47 |
virtual channels with an Intel ME feature. Not all features support |
| 48 |
virtual channels such client with answer EOPNOTSUPP. |
| 49 |
|
| 50 |
.. code-block:: C |
| 51 |
|
| 52 |
struct mei_connect_client_data data; |
| 53 |
fd = open(MEI_DEVICE); |
| 54 |
|
| 55 |
data.d.in_client_uuid = AMTHI_GUID; |
| 56 |
|
| 57 |
ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data); |
| 58 |
|
| 59 |
printf("Ver=%d, MaxLen=%ld\n", |
| 60 |
data.d.in_client_uuid.protocol_version, |
| 61 |
data.d.in_client_uuid.max_msg_length); |
| 62 |
|
| 63 |
[...] |
| 64 |
|
| 65 |
write(fd, amthi_req_data, amthi_req_data_len); |
| 66 |
|
| 67 |
[...] |
| 68 |
|
| 69 |
read(fd, &amthi_res_data, amthi_res_data_len); |
| 70 |
|
| 71 |
[...] |
| 72 |
close(fd); |
| 73 |
|
| 74 |
|
| 75 |
User space API |
| 76 |
|
| 77 |
IOCTLs: |
| 78 |
======= |
| 79 |
|
| 80 |
The Intel MEI Driver supports the following IOCTL commands: |
| 81 |
|
| 82 |
IOCTL_MEI_CONNECT_CLIENT |
| 83 |
------------------------- |
| 84 |
Connect to firmware Feature/Client. |
| 85 |
|
| 86 |
.. code-block:: none |
| 87 |
|
| 88 |
Usage: |
| 89 |
|
| 90 |
struct mei_connect_client_data client_data; |
| 91 |
|
| 92 |
ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &client_data); |
| 93 |
|
| 94 |
Inputs: |
| 95 |
|
| 96 |
struct mei_connect_client_data - contain the following |
| 97 |
Input field: |
| 98 |
|
| 99 |
in_client_uuid - GUID of the FW Feature that needs |
| 100 |
to connect to. |
| 101 |
Outputs: |
| 102 |
out_client_properties - Client Properties: MTU and Protocol Version. |
| 103 |
|
| 104 |
Error returns: |
| 105 |
|
| 106 |
ENOTTY No such client (i.e. wrong GUID) or connection is not allowed. |
| 107 |
EINVAL Wrong IOCTL Number |
| 108 |
ENODEV Device or Connection is not initialized or ready. |
| 109 |
ENOMEM Unable to allocate memory to client internal data. |
| 110 |
EFAULT Fatal Error (e.g. Unable to access user input data) |
| 111 |
EBUSY Connection Already Open |
| 112 |
|
| 113 |
:Note: |
| 114 |
max_msg_length (MTU) in client properties describes the maximum |
| 115 |
data that can be sent or received. (e.g. if MTU=2K, can send |
| 116 |
requests up to bytes 2k and received responses up to 2k bytes). |
| 117 |
|
| 118 |
IOCTL_MEI_CONNECT_CLIENT_VTAG: |
| 119 |
------------------------------ |
| 120 |
|
| 121 |
.. code-block:: none |
| 122 |
|
| 123 |
Usage: |
| 124 |
|
| 125 |
struct mei_connect_client_data_vtag client_data_vtag; |
| 126 |
|
| 127 |
ioctl(fd, IOCTL_MEI_CONNECT_CLIENT_VTAG, &client_data_vtag); |
| 128 |
|
| 129 |
Inputs: |
| 130 |
|
| 131 |
struct mei_connect_client_data_vtag - contain the following |
| 132 |
Input field: |
| 133 |
|
| 134 |
in_client_uuid - GUID of the FW Feature that needs |
| 135 |
to connect to. |
| 136 |
vtag - virtual tag [1, 255] |
| 137 |
|
| 138 |
Outputs: |
| 139 |
out_client_properties - Client Properties: MTU and Protocol Version. |
| 140 |
|
| 141 |
Error returns: |
| 142 |
|
| 143 |
ENOTTY No such client (i.e. wrong GUID) or connection is not allowed. |
| 144 |
EINVAL Wrong IOCTL Number or tag == 0 |
| 145 |
ENODEV Device or Connection is not initialized or ready. |
| 146 |
ENOMEM Unable to allocate memory to client internal data. |
| 147 |
EFAULT Fatal Error (e.g. Unable to access user input data) |
| 148 |
EBUSY Connection Already Open |
| 149 |
EOPNOTSUPP Vtag is not supported |
| 150 |
|
| 151 |
IOCTL_MEI_NOTIFY_SET |
| 152 |
--------------------- |
| 153 |
Enable or disable event notifications. |
| 154 |
|
| 155 |
|
| 156 |
.. code-block:: none |
| 157 |
|
| 158 |
Usage: |
| 159 |
|
| 160 |
uint32_t enable; |
| 161 |
|
| 162 |
ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable); |
| 163 |
|
| 164 |
|
| 165 |
uint32_t enable = 1; |
| 166 |
or |
| 167 |
uint32_t enable[disable] = 0; |
| 168 |
|
| 169 |
Error returns: |
| 170 |
|
| 171 |
|
| 172 |
EINVAL Wrong IOCTL Number |
| 173 |
ENODEV Device is not initialized or the client not connected |
| 174 |
ENOMEM Unable to allocate memory to client internal data. |
| 175 |
EFAULT Fatal Error (e.g. Unable to access user input data) |
| 176 |
EOPNOTSUPP if the device doesn't support the feature |
| 177 |
|
| 178 |
:Note: |
| 179 |
The client must be connected in order to enable notification events |
| 180 |
|
| 181 |
|
| 182 |
IOCTL_MEI_NOTIFY_GET |
| 183 |
-------------------- |
| 184 |
Retrieve event |
| 185 |
|
| 186 |
.. code-block:: none |
| 187 |
|
| 188 |
Usage: |
| 189 |
uint32_t event; |
| 190 |
ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event); |
| 191 |
|
| 192 |
Outputs: |
| 193 |
1 - if an event is pending |
| 194 |
0 - if there is no even pending |
| 195 |
|
| 196 |
Error returns: |
| 197 |
EINVAL Wrong IOCTL Number |
| 198 |
ENODEV Device is not initialized or the client not connected |
| 199 |
ENOMEM Unable to allocate memory to client internal data. |
| 200 |
EFAULT Fatal Error (e.g. Unable to access user input data) |
| 201 |
EOPNOTSUPP if the device doesn't support the feature |
| 202 |
|
| 203 |
:Note: |
| 204 |
The client must be connected and event notification has to be enabled |
| 205 |
in order to receive an event |
| 206 |
|
| 207 |
|
| 208 |
|
| 209 |
Supported Chipsets |
| 210 |
================== |
| 211 |
82X38/X48 Express and newer |
| 212 |
|
| 213 |
[email protected] |