Commit | Line | Data |
---|---|---|
7e527e11 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
6624fc23 OW |
2 | |
3 | Introduction | |
cfba6784 | 4 | ============ |
6624fc23 | 5 | |
5f9092f3 | 6 | The Intel Management Engine (Intel ME) is an isolated and protected computing |
463ac7f7 | 7 | resource (Co-processor) residing inside certain Intel chipsets. The Intel ME |
d0a17809 TW |
8 | provides support for computer/IT management and security features. |
9 | The actual feature set depends on the Intel chipset SKU. | |
6624fc23 | 10 | |
463ac7f7 OW |
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 | |
d0a17809 TW |
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. | |
6624fc23 | 16 | |
d0a17809 | 17 | Each Intel ME feature, or Intel ME Client is addressed by a unique GUID and |
463ac7f7 | 18 | each client has its own protocol. The protocol is message-based with a |
d0a17809 TW |
19 | header and payload up to maximal number of bytes advertised by the client, |
20 | upon connection. | |
6624fc23 | 21 | |
463ac7f7 | 22 | Intel MEI Driver |
cfba6784 | 23 | ================ |
6624fc23 | 24 | |
d0a17809 | 25 | The driver exposes a character device with device nodes /dev/meiX. |
6624fc23 | 26 | |
463ac7f7 | 27 | An application maintains communication with an Intel ME feature while |
d0a17809 TW |
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. | |
463ac7f7 OW |
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 | |
6624fc23 OW |
32 | features allow only a single instance. |
33 | ||
f6a4e494 | 34 | The driver is transparent to data that are passed between firmware feature |
463ac7f7 | 35 | and host application. |
6624fc23 | 36 | |
463ac7f7 OW |
37 | Because some of the Intel ME features can change the system |
38 | configuration, the driver by default allows only a privileged | |
6624fc23 OW |
39 | user to access it. |
40 | ||
ccf12273 | 41 | The session is terminated calling :c:expr:`close(fd)`. |
d0a17809 | 42 | |
f6a4e494 TW |
43 | A code snippet for an application communicating with Intel AMTHI client: |
44 | ||
2257b74e TW |
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 | ||
7e527e11 TW |
50 | .. code-block:: C |
51 | ||
6624fc23 OW |
52 | struct mei_connect_client_data data; |
53 | fd = open(MEI_DEVICE); | |
54 | ||
d0a17809 | 55 | data.d.in_client_uuid = AMTHI_GUID; |
6624fc23 OW |
56 | |
57 | ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data); | |
58 | ||
463ac7f7 | 59 | printf("Ver=%d, MaxLen=%ld\n", |
d0a17809 TW |
60 | data.d.in_client_uuid.protocol_version, |
61 | data.d.in_client_uuid.max_msg_length); | |
6624fc23 OW |
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 | ||
cfba6784 | 74 | |
d0a17809 TW |
75 | User space API |
76 | ||
77 | IOCTLs: | |
78 | ======= | |
cfba6784 | 79 | |
3c7c8468 | 80 | The Intel MEI Driver supports the following IOCTL commands: |
463ac7f7 | 81 | |
d0a17809 TW |
82 | IOCTL_MEI_CONNECT_CLIENT |
83 | ------------------------- | |
84 | Connect to firmware Feature/Client. | |
85 | ||
86 | .. code-block:: none | |
87 | ||
88 | Usage: | |
463ac7f7 | 89 | |
d0a17809 | 90 | struct mei_connect_client_data client_data; |
463ac7f7 | 91 | |
d0a17809 TW |
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 | |
463ac7f7 | 100 | to connect to. |
d0a17809 | 101 | Outputs: |
463ac7f7 OW |
102 | out_client_properties - Client Properties: MTU and Protocol Version. |
103 | ||
d0a17809 TW |
104 | Error returns: |
105 | ||
106 | ENOTTY No such client (i.e. wrong GUID) or connection is not allowed. | |
463ac7f7 | 107 | EINVAL Wrong IOCTL Number |
d0a17809 | 108 | ENODEV Device or Connection is not initialized or ready. |
463ac7f7 OW |
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 | ||
d0a17809 | 113 | :Note: |
463ac7f7 OW |
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 | |
f884ab15 | 116 | requests up to bytes 2k and received responses up to 2k bytes). |
463ac7f7 | 117 | |
2257b74e TW |
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 | |
d0a17809 TW |
150 | |
151 | IOCTL_MEI_NOTIFY_SET | |
152 | --------------------- | |
153 | Enable or disable event notifications. | |
154 | ||
155 | ||
156 | .. code-block:: none | |
3c7c8468 TW |
157 | |
158 | Usage: | |
d0a17809 | 159 | |
3c7c8468 | 160 | uint32_t enable; |
d0a17809 | 161 | |
3c7c8468 TW |
162 | ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable); |
163 | ||
d0a17809 | 164 | |
3c7c8468 TW |
165 | uint32_t enable = 1; |
166 | or | |
167 | uint32_t enable[disable] = 0; | |
168 | ||
169 | Error returns: | |
d0a17809 TW |
170 | |
171 | ||
3c7c8468 TW |
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 | ||
d0a17809 | 178 | :Note: |
3c7c8468 TW |
179 | The client must be connected in order to enable notification events |
180 | ||
181 | ||
d0a17809 TW |
182 | IOCTL_MEI_NOTIFY_GET |
183 | -------------------- | |
184 | Retrieve event | |
185 | ||
186 | .. code-block:: none | |
3c7c8468 TW |
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 | ||
d0a17809 | 203 | :Note: |
3c7c8468 TW |
204 | The client must be connected and event notification has to be enabled |
205 | in order to receive an event | |
206 | ||
cfba6784 | 207 | |
6624fc23 | 208 | |
cfba6784 | 209 | Supported Chipsets |
6624fc23 | 210 | ================== |
7e527e11 | 211 | 82X38/X48 Express and newer |
cfba6784 | 212 | |
6624fc23 | 213 | linux-mei@linux.intel.com |