1Intel(R) Management Engine Interface (Intel(R) MEI)
2===================================================
3
4Introduction
5============
6
7The Intel Management Engine (Intel ME) is an isolated and protected computing
8resource (Co-processor) residing inside certain Intel chipsets. The Intel ME
9provides support for computer/IT management features. The feature set
10depends on the Intel chipset SKU.
11
12The Intel Management Engine Interface (Intel MEI, previously known as HECI)
13is the interface between the Host and Intel ME. This interface is exposed
14to the host as a PCI device. The Intel MEI Driver is in charge of the
15communication channel between a host application and the Intel ME feature.
16
17Each Intel ME feature (Intel ME Client) is addressed by a GUID/UUID and
18each client has its own protocol. The protocol is message-based with a
19header and payload up to 512 bytes.
20
21Prominent usage of the Intel ME Interface is to communicate with Intel(R)
22Active Management Technology (Intel AMT) implemented in firmware running on
23the Intel ME.
24
25Intel AMT provides the ability to manage a host remotely out-of-band (OOB)
26even when the operating system running on the host processor has crashed or
27is in a sleep state.
28
29Some examples of Intel AMT usage are:
30   - Monitoring hardware state and platform components
31   - Remote power off/on (useful for green computing or overnight IT
32     maintenance)
33   - OS updates
34   - Storage of useful platform information such as software assets
35   - Built-in hardware KVM
36   - Selective network isolation of Ethernet and IP protocol flows based
37     on policies set by a remote management console
38   - IDE device redirection from remote management console
39
40Intel AMT (OOB) communication is based on SOAP (deprecated
41starting with Release 6.0) over HTTP/S or WS-Management protocol over
42HTTP/S that are received from a remote management console application.
43
44For more information about Intel AMT:
45http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
46
47
48Intel MEI Driver
49================
50
51The driver exposes a misc device called /dev/mei.
52
53An application maintains communication with an Intel ME feature while
54/dev/mei is open. The binding to a specific feature is performed by calling
55MEI_CONNECT_CLIENT_IOCTL, which passes the desired UUID.
56The number of instances of an Intel ME feature that can be opened
57at the same time depends on the Intel ME feature, but most of the
58features allow only a single instance.
59
60The Intel AMT Host Interface (Intel AMTHI) feature supports multiple
61simultaneous user connected applications. The Intel MEI driver
62handles this internally by maintaining request queues for the applications.
63
64The driver is transparent to data that are passed between firmware feature
65and host application.
66
67Because some of the Intel ME features can change the system
68configuration, the driver by default allows only a privileged
69user to access it.
70
71A code snippet for an application communicating with Intel AMTHI client:
72
73	struct mei_connect_client_data data;
74	fd = open(MEI_DEVICE);
75
76	data.d.in_client_uuid = AMTHI_UUID;
77
78	ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
79
80	printf("Ver=%d, MaxLen=%ld\n",
81			data.d.in_client_uuid.protocol_version,
82			data.d.in_client_uuid.max_msg_length);
83
84	[...]
85
86	write(fd, amthi_req_data, amthi_req_data_len);
87
88	[...]
89
90	read(fd, &amthi_res_data, amthi_res_data_len);
91
92	[...]
93	close(fd);
94
95
96IOCTL
97=====
98
99The Intel MEI Driver supports the following IOCTL commands:
100	IOCTL_MEI_CONNECT_CLIENT	Connect to firmware Feature (client).
101
102	usage:
103		struct mei_connect_client_data clientData;
104		ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData);
105
106	inputs:
107		mei_connect_client_data struct contain the following
108		input field:
109
110		in_client_uuid -	UUID of the FW Feature that needs
111					to connect to.
112	outputs:
113		out_client_properties - Client Properties: MTU and Protocol Version.
114
115	error returns:
116		EINVAL	Wrong IOCTL Number
117		ENODEV	Device or Connection is not initialized or ready.
118			(e.g. Wrong UUID)
119		ENOMEM	Unable to allocate memory to client internal data.
120		EFAULT	Fatal Error (e.g. Unable to access user input data)
121		EBUSY	Connection Already Open
122
123	Notes:
124        max_msg_length (MTU) in client properties describes the maximum
125        data that can be sent or received. (e.g. if MTU=2K, can send
126        requests up to bytes 2k and received responses up to 2k bytes).
127
128	IOCTL_MEI_NOTIFY_SET: enable or disable event notifications
129
130	Usage:
131		uint32_t enable;
132		ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
133
134	Inputs:
135		uint32_t enable = 1;
136		or
137		uint32_t enable[disable] = 0;
138
139	Error returns:
140		EINVAL	Wrong IOCTL Number
141		ENODEV	Device  is not initialized or the client not connected
142		ENOMEM	Unable to allocate memory to client internal data.
143		EFAULT	Fatal Error (e.g. Unable to access user input data)
144		EOPNOTSUPP if the device doesn't support the feature
145
146	Notes:
147	The client must be connected in order to enable notification events
148
149
150	IOCTL_MEI_NOTIFY_GET : retrieve event
151
152	Usage:
153		uint32_t event;
154		ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
155
156	Outputs:
157		1 - if an event is pending
158		0 - if there is no even pending
159
160	Error returns:
161		EINVAL	Wrong IOCTL Number
162		ENODEV	Device is not initialized or the client not connected
163		ENOMEM	Unable to allocate memory to client internal data.
164		EFAULT	Fatal Error (e.g. Unable to access user input data)
165		EOPNOTSUPP if the device doesn't support the feature
166
167	Notes:
168	The client must be connected and event notification has to be enabled
169	in order to receive an event
170
171
172Intel ME Applications
173=====================
174
175	1) Intel Local Management Service (Intel LMS)
176
177	   Applications running locally on the platform communicate with Intel AMT Release
178	   2.0 and later releases in the same way that network applications do via SOAP
179	   over HTTP (deprecated starting with Release 6.0) or with WS-Management over
180	   SOAP over HTTP. This means that some Intel AMT features can be accessed from a
181	   local application using the same network interface as a remote application
182	   communicating with Intel AMT over the network.
183
184	   When a local application sends a message addressed to the local Intel AMT host
185	   name, the Intel LMS, which listens for traffic directed to the host name,
186	   intercepts the message and routes it to the Intel MEI.
187	   For more information:
188	   http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
189	   Under "About Intel AMT" => "Local Access"
190
191	   For downloading Intel LMS:
192	   http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
193
194	   The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
195	   firmware feature using a defined UUID and then communicates with the feature
196	   using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
197	   The protocol is used to maintain multiple sessions with Intel AMT from a
198	   single application.
199
200	   See the protocol specification in the Intel AMT Software Development Kit (SDK)
201	   http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
202	   Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
203	   => "Information for Intel(R) vPro(TM) Gateway Developers"
204	   => "Description of the Intel AMT Port Forwarding (APF) Protocol"
205
206	2) Intel AMT Remote configuration using a Local Agent
207
208	   A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
209	   without requiring installing additional data to enable setup. The remote
210	   configuration process may involve an ISV-developed remote configuration
211	   agent that runs on the host.
212	   For more information:
213	   http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
214	   Under "Setup and Configuration of Intel AMT" =>
215	   "SDK Tools Supporting Setup and Configuration" =>
216	   "Using the Local Agent Sample"
217
218	   An open source Intel AMT configuration utility,	implementing a local agent
219	   that accesses the Intel MEI driver, can be found here:
220	   http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
221
222
223Intel AMT OS Health Watchdog
224============================
225
226The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
227Whenever the OS hangs or crashes, Intel AMT will send an event
228to any subscriber to this event. This mechanism means that
229IT knows when a platform crashes even when there is a hard failure on the host.
230
231The Intel AMT Watchdog is composed of two parts:
232	1) Firmware feature - receives the heartbeats
233	   and sends an event when the heartbeats stop.
234	2) Intel MEI driver - connects to the watchdog feature, configures the
235	   watchdog and sends the heartbeats.
236
237The Intel MEI driver uses the kernel watchdog API to configure the Intel AMT
238Watchdog and to send heartbeats to it. The default timeout of the
239watchdog is 120 seconds.
240
241If the Intel AMT Watchdog feature does not exist (i.e. the connection failed),
242the Intel MEI driver will disable the sending of heartbeats.
243
244
245Supported Chipsets
246==================
247
2487 Series Chipset Family
2496 Series Chipset Family
2505 Series Chipset Family
2514 Series Chipset Family
252Mobile 4 Series Chipset Family
253ICH9
25482946GZ/GL
25582G35 Express
25682Q963/Q965
25782P965/G965
258Mobile PM965/GM965
259Mobile GME965/GLE960
26082Q35 Express
26182G33/G31/P35/P31 Express
26282Q33 Express
26382X38/X48 Express
264
265---
266linux-mei@linux.intel.com
267