1 .. SPDX-License-Identifier: GPL-2.0
2
3 Introduction
4 ============
5
6 The Intel Management Engine (Intel ME) is an i
7 resource (Co-processor) residing inside certai
8 provides support for computer/IT management an
9 The actual feature set depends on the Intel ch
10
11 The Intel Management Engine Interface (Intel M
12 is the interface between the Host and Intel ME
13 to the host as a PCI device, actually multiple
14 The Intel MEI Driver is in charge of the commu
15 a host application and the Intel ME features.
16
17 Each Intel ME feature, or Intel ME Client is a
18 each client has its own protocol. The protocol
19 header and payload up to maximal number of byt
20 upon connection.
21
22 Intel MEI Driver
23 ================
24
25 The driver exposes a character device with dev
26
27 An application maintains communication with an
28 /dev/meiX is open. The binding to a specific f
29 :c:macro:`MEI_CONNECT_CLIENT_IOCTL`, which pas
30 The number of instances of an Intel ME feature
31 at the same time depends on the Intel ME featu
32 features allow only a single instance.
33
34 The driver is transparent to data that are pas
35 and host application.
36
37 Because some of the Intel ME features can chan
38 configuration, the driver by default allows on
39 user to access it.
40
41 The session is terminated calling :c:expr:`clo
42
43 A code snippet for an application communicatin
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
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, &d
58
59 printf("Ver=%d, MaxLen=%ld\n",
60 data.d.in_client_uuid.protocol_
61 data.d.in_client_uuid.max_msg_l
62
63 [...]
64
65 write(fd, amthi_req_data, amthi_req_da
66
67 [...]
68
69 read(fd, &amthi_res_data, amthi_res_da
70
71 [...]
72 close(fd);
73
74
75 User space API
76
77 IOCTLs:
78 =======
79
80 The Intel MEI Driver supports the following IO
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_
91
92 ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &c
93
94 Inputs:
95
96 struct mei_connect_client_data - conta
97 Input field:
98
99 in_client_uuid - GUID o
100 to con
101 Outputs:
102 out_client_properties - Client
103
104 Error returns:
105
106 ENOTTY No such client (i.e. w
107 EINVAL Wrong IOCTL Number
108 ENODEV Device or Connection i
109 ENOMEM Unable to allocate mem
110 EFAULT Fatal Error (e.g. Unab
111 EBUSY Connection Already Ope
112
113 :Note:
114 max_msg_length (MTU) in client propert
115 data that can be sent or received. (e.
116 requests up to bytes 2k and received r
117
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
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
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 initial
174 ENOMEM Unable to allocate mem
175 EFAULT Fatal Error (e.g. Unab
176 EOPNOTSUPP if the device doesn
177
178 :Note:
179 The client must be connected in order
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
191
192 Outputs:
193 1 - if an event is pending
194 0 - if there is no even pendin
195
196 Error returns:
197 EINVAL Wrong IOCTL Number
198 ENODEV Device is not initiali
199 ENOMEM Unable to allocate mem
200 EFAULT Fatal Error (e.g. Unab
201 EOPNOTSUPP if the device doesn
202
203 :Note:
204 The client must be connected and event
205 in order to receive an event
206
207
208
209 Supported Chipsets
210 ==================
211 82X38/X48 Express and newer
212
213 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.