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:func:`close(int fd)`.
42
43A code snippet for an application communicating with Intel AMTHI client:
44
45.. code-block:: C
46
47	struct mei_connect_client_data data;
48	fd = open(MEI_DEVICE);
49
50	data.d.in_client_uuid = AMTHI_GUID;
51
52	ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
53
54	printf("Ver=%d, MaxLen=%ld\n",
55	       data.d.in_client_uuid.protocol_version,
56	       data.d.in_client_uuid.max_msg_length);
57
58	[...]
59
60	write(fd, amthi_req_data, amthi_req_data_len);
61
62	[...]
63
64	read(fd, &amthi_res_data, amthi_res_data_len);
65
66	[...]
67	close(fd);
68
69
70User space API
71
72IOCTLs:
73=======
74
75The Intel MEI Driver supports the following IOCTL commands:
76
77IOCTL_MEI_CONNECT_CLIENT
78-------------------------
79Connect to firmware Feature/Client.
80
81.. code-block:: none
82
83	Usage:
84
85        struct mei_connect_client_data client_data;
86
87        ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &client_data);
88
89	Inputs:
90
91        struct mei_connect_client_data - contain the following
92	Input field:
93
94		in_client_uuid -	GUID of the FW Feature that needs
95					to connect to.
96         Outputs:
97		out_client_properties - Client Properties: MTU and Protocol Version.
98
99         Error returns:
100
101                ENOTTY  No such client (i.e. wrong GUID) or connection is not allowed.
102		EINVAL	Wrong IOCTL Number
103		ENODEV	Device or Connection is not initialized or ready.
104		ENOMEM	Unable to allocate memory to client internal data.
105		EFAULT	Fatal Error (e.g. Unable to access user input data)
106		EBUSY	Connection Already Open
107
108:Note:
109        max_msg_length (MTU) in client properties describes the maximum
110        data that can be sent or received. (e.g. if MTU=2K, can send
111        requests up to bytes 2k and received responses up to 2k bytes).
112
113
114IOCTL_MEI_NOTIFY_SET
115---------------------
116Enable or disable event notifications.
117
118
119.. code-block:: none
120
121	Usage:
122
123		uint32_t enable;
124
125		ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
126
127
128		uint32_t enable = 1;
129		or
130		uint32_t enable[disable] = 0;
131
132	Error returns:
133
134
135		EINVAL	Wrong IOCTL Number
136		ENODEV	Device  is not initialized or the client not connected
137		ENOMEM	Unable to allocate memory to client internal data.
138		EFAULT	Fatal Error (e.g. Unable to access user input data)
139		EOPNOTSUPP if the device doesn't support the feature
140
141:Note:
142	The client must be connected in order to enable notification events
143
144
145IOCTL_MEI_NOTIFY_GET
146--------------------
147Retrieve event
148
149.. code-block:: none
150
151	Usage:
152		uint32_t event;
153		ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
154
155	Outputs:
156		1 - if an event is pending
157		0 - if there is no even pending
158
159	Error returns:
160		EINVAL	Wrong IOCTL Number
161		ENODEV	Device is not initialized or the client not connected
162		ENOMEM	Unable to allocate memory to client internal data.
163		EFAULT	Fatal Error (e.g. Unable to access user input data)
164		EOPNOTSUPP if the device doesn't support the feature
165
166:Note:
167	The client must be connected and event notification has to be enabled
168	in order to receive an event
169
170
171
172Supported Chipsets
173==================
17482X38/X48 Express and newer
175
176linux-mei@linux.intel.com
177