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