1 .. SPDX-License-Identifier: GPL-2.0
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.
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.
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,
25 The driver exposes a character device with device nodes /dev/meiX.
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.
34 The driver is transparent to data that are passed between firmware feature
37 Because some of the Intel ME features can change the system
38 configuration, the driver by default allows only a privileged
41 The session is terminated calling :c:expr:`close(fd)`.
43 A code snippet for an application communicating with Intel AMTHI client:
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.
52 struct mei_connect_client_data data;
53 fd = open(MEI_DEVICE);
55 data.d.in_client_uuid = AMTHI_GUID;
57 ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
59 printf("Ver=%d, MaxLen=%ld\n",
60 data.d.in_client_uuid.protocol_version,
61 data.d.in_client_uuid.max_msg_length);
65 write(fd, amthi_req_data, amthi_req_data_len);
69 read(fd, &amthi_res_data, amthi_res_data_len);
80 The Intel MEI Driver supports the following IOCTL commands:
82 IOCTL_MEI_CONNECT_CLIENT
83 -------------------------
84 Connect to firmware Feature/Client.
90 struct mei_connect_client_data client_data;
92 ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &client_data);
96 struct mei_connect_client_data - contain the following
99 in_client_uuid - GUID of the FW Feature that needs
102 out_client_properties - Client Properties: MTU and Protocol Version.
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
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).
118 IOCTL_MEI_CONNECT_CLIENT_VTAG:
119 ------------------------------
125 struct mei_connect_client_data_vtag client_data_vtag;
127 ioctl(fd, IOCTL_MEI_CONNECT_CLIENT_VTAG, &client_data_vtag);
131 struct mei_connect_client_data_vtag - contain the following
134 in_client_uuid - GUID of the FW Feature that needs
136 vtag - virtual tag [1, 255]
139 out_client_properties - Client Properties: MTU and Protocol Version.
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
152 ---------------------
153 Enable or disable event notifications.
162 ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
167 uint32_t enable[disable] = 0;
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
179 The client must be connected in order to enable notification events
190 ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
193 1 - if an event is pending
194 0 - if there is no even pending
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
204 The client must be connected and event notification has to be enabled
205 in order to receive an event
211 82X38/X48 Express and newer
213 linux-mei@linux.intel.com