1.. SPDX-License-Identifier: GPL-2.0
2
3Introduction
4============
5
6The Intel Management Engine (Intel ME) is an isolated and protected computing
7resource (Co-processor) residing inside certain Intel chipsets. The Intel ME
8provides support for computer/IT management and security features.
9The actual feature set depends on the Intel chipset SKU.
10
11The Intel Management Engine Interface (Intel MEI, previously known as HECI)
12is the interface between the Host and Intel ME. This interface is exposed
13to the host as a PCI device, actually multiple PCI devices might be exposed.
14The Intel MEI Driver is in charge of the communication channel between
15a host application and the Intel ME features.
16
17Each Intel ME feature, or Intel ME Client is addressed by a unique GUID and
18each client has its own protocol. The protocol is message-based with a
19header and payload up to maximal number of bytes advertised by the client,
20upon connection.
21
22Intel MEI Driver
23================
24
25The driver exposes a character device with device nodes /dev/meiX.
26
27An 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.
30The number of instances of an Intel ME feature that can be opened
31at the same time depends on the Intel ME feature, but most of the
32features allow only a single instance.
33
34The driver is transparent to data that are passed between firmware feature
35and host application.
36
37Because some of the Intel ME features can change the system
38configuration, the driver by default allows only a privileged
39user to access it.
40
41The session is terminated calling :c:expr:`close(fd)`.
42
43A code snippet for an application communicating with Intel AMTHI client:
44
45In order to support virtualization or sandboxing a trusted supervisor
46can use :c:macro:`MEI_CONNECT_CLIENT_IOCTL_VTAG` to create
47virtual channels with an Intel ME feature. Not all features support
48virtual 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
75User space API
76
77IOCTLs:
78=======
79
80The Intel MEI Driver supports the following IOCTL commands:
81
82IOCTL_MEI_CONNECT_CLIENT
83-------------------------
84Connect 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
118IOCTL_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
151IOCTL_MEI_NOTIFY_SET
152---------------------
153Enable 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
182IOCTL_MEI_NOTIFY_GET
183--------------------
184Retrieve 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
209Supported Chipsets
210==================
21182X38/X48 Express and newer
212
213linux-mei@linux.intel.com
214