blob: 2b80a0cd621f09554fb74f2dc100787f76a6176b [file] [log] [blame]
Oren Weil463ac7f2011-12-06 23:25:18 +02001Intel(R) Management Engine Interface (Intel(R) MEI)
Julian Brostcfba6782015-01-12 00:58:06 +01002===================================================
Oren Weil6624fc22011-05-15 13:43:39 +03003
4Introduction
Julian Brostcfba6782015-01-12 00:58:06 +01005============
Oren Weil6624fc22011-05-15 13:43:39 +03006
Justin P. Mattock5f9092f32012-03-12 07:18:09 -07007The Intel Management Engine (Intel ME) is an isolated and protected computing
Oren Weil463ac7f2011-12-06 23:25:18 +02008resource (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.
Oren Weil6624fc22011-05-15 13:43:39 +030011
Oren Weil463ac7f2011-12-06 23:25:18 +020012The 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.
Oren Weil6624fc22011-05-15 13:43:39 +030016
Oren Weil463ac7f2011-12-06 23:25:18 +020017Each 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.
Oren Weil6624fc22011-05-15 13:43:39 +030020
Oren Weil463ac7f2011-12-06 23:25:18 +020021Prominent usage of the Intel ME Interface is to communicate with Intel(R)
Julian Brostccd7b012015-01-12 00:58:07 +010022Active Management Technology (Intel AMT) implemented in firmware running on
Oren Weil463ac7f2011-12-06 23:25:18 +020023the Intel ME.
Oren Weil6624fc22011-05-15 13:43:39 +030024
25Intel AMT provides the ability to manage a host remotely out-of-band (OOB)
Oren Weil463ac7f2011-12-06 23:25:18 +020026even when the operating system running on the host processor has crashed or
27is in a sleep state.
Oren Weil6624fc22011-05-15 13:43:39 +030028
29Some examples of Intel AMT usage are:
30 - Monitoring hardware state and platform components
Oren Weil463ac7f2011-12-06 23:25:18 +020031 - Remote power off/on (useful for green computing or overnight IT
32 maintenance)
Oren Weil6624fc22011-05-15 13:43:39 +030033 - OS updates
34 - Storage of useful platform information such as software assets
Oren Weil463ac7f2011-12-06 23:25:18 +020035 - Built-in hardware KVM
36 - Selective network isolation of Ethernet and IP protocol flows based
37 on policies set by a remote management console
Oren Weil6624fc22011-05-15 13:43:39 +030038 - IDE device redirection from remote management console
39
40Intel AMT (OOB) communication is based on SOAP (deprecated
Oren Weil463ac7f2011-12-06 23:25:18 +020041starting with Release 6.0) over HTTP/S or WS-Management protocol over
42HTTP/S that are received from a remote management console application.
Oren Weil6624fc22011-05-15 13:43:39 +030043
44For more information about Intel AMT:
Oren Weil463ac7f2011-12-06 23:25:18 +020045http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
Oren Weil6624fc22011-05-15 13:43:39 +030046
Julian Brostcfba6782015-01-12 00:58:06 +010047
Oren Weil463ac7f2011-12-06 23:25:18 +020048Intel MEI Driver
Julian Brostcfba6782015-01-12 00:58:06 +010049================
Oren Weil6624fc22011-05-15 13:43:39 +030050
Oren Weil463ac7f2011-12-06 23:25:18 +020051The driver exposes a misc device called /dev/mei.
Oren Weil6624fc22011-05-15 13:43:39 +030052
Oren Weil463ac7f2011-12-06 23:25:18 +020053An application maintains communication with an Intel ME feature while
Tomas Winklerf6a4e492012-05-29 16:39:09 +030054/dev/mei is open. The binding to a specific feature is performed by calling
Oren Weil463ac7f2011-12-06 23:25:18 +020055MEI_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
Oren Weil6624fc22011-05-15 13:43:39 +030058features allow only a single instance.
59
Oren Weil463ac7f2011-12-06 23:25:18 +020060The Intel AMT Host Interface (Intel AMTHI) feature supports multiple
Tomas Winklerf6a4e492012-05-29 16:39:09 +030061simultaneous user connected applications. The Intel MEI driver
62handles this internally by maintaining request queues for the applications.
Oren Weil6624fc22011-05-15 13:43:39 +030063
Tomas Winklerf6a4e492012-05-29 16:39:09 +030064The driver is transparent to data that are passed between firmware feature
Oren Weil463ac7f2011-12-06 23:25:18 +020065and host application.
Oren Weil6624fc22011-05-15 13:43:39 +030066
Oren Weil463ac7f2011-12-06 23:25:18 +020067Because some of the Intel ME features can change the system
68configuration, the driver by default allows only a privileged
Oren Weil6624fc22011-05-15 13:43:39 +030069user to access it.
70
Tomas Winklerf6a4e492012-05-29 16:39:09 +030071A code snippet for an application communicating with Intel AMTHI client:
72
Oren Weil6624fc22011-05-15 13:43:39 +030073 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
Oren Weil463ac7f2011-12-06 23:25:18 +020080 printf("Ver=%d, MaxLen=%ld\n",
Oren Weil6624fc22011-05-15 13:43:39 +030081 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
Julian Brostcfba6782015-01-12 00:58:06 +010095
96IOCTL
97=====
98
Tomas Winkler3c7c8462015-07-26 09:54:20 +030099The Intel MEI Driver supports the following IOCTL commands:
Oren Weil463ac7f2011-12-06 23:25:18 +0200100 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
Anatol Pomozovf884ab12013-05-08 16:56:16 -0700126 requests up to bytes 2k and received responses up to 2k bytes).
Oren Weil463ac7f2011-12-06 23:25:18 +0200127
Tomas Winkler3c7c8462015-07-26 09:54:20 +0300128 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
Julian Brostcfba6782015-01-12 00:58:06 +0100171
172Intel ME Applications
173=====================
Oren Weil6624fc22011-05-15 13:43:39 +0300174
Julian Brost21ef5672015-01-12 00:58:08 +0100175 1) Intel Local Management Service (Intel LMS)
Oren Weil6624fc22011-05-15 13:43:39 +0300176
Julian Brost21ef5672015-01-12 00:58:08 +0100177 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.
Oren Weil463ac7f2011-12-06 23:25:18 +0200183
Julian Brost21ef5672015-01-12 00:58:08 +0100184 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"
Oren Weil6624fc22011-05-15 13:43:39 +0300190
Julian Brost21ef5672015-01-12 00:58:08 +0100191 For downloading Intel LMS:
192 http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
Oren Weil6624fc22011-05-15 13:43:39 +0300193
Julian Brost21ef5672015-01-12 00:58:08 +0100194 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.
Oren Weil463ac7f2011-12-06 23:25:18 +0200199
Julian Brost21ef5672015-01-12 00:58:08 +0100200 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"
Oren Weil463ac7f2011-12-06 23:25:18 +0200205
Julian Brost21ef5672015-01-12 00:58:08 +0100206 2) Intel AMT Remote configuration using a Local Agent
Oren Weil6624fc22011-05-15 13:43:39 +0300207
Julian Brost21ef5672015-01-12 00:58:08 +0100208 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/
Oren Weil463ac7f2011-12-06 23:25:18 +0200221
Oren Weil6624fc22011-05-15 13:43:39 +0300222
Julian Brostcfba6782015-01-12 00:58:06 +0100223Intel AMT OS Health Watchdog
224============================
225
Oren Weil6624fc22011-05-15 13:43:39 +0300226The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
227Whenever the OS hangs or crashes, Intel AMT will send an event
Justin P. Mattock5f9092f32012-03-12 07:18:09 -0700228to 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.
Oren Weil463ac7f2011-12-06 23:25:18 +0200230
231The Intel AMT Watchdog is composed of two parts:
232 1) Firmware feature - receives the heartbeats
Oren Weil6624fc22011-05-15 13:43:39 +0300233 and sends an event when the heartbeats stop.
Tomas Winkler222818c2016-01-08 00:49:22 +0200234 2) Intel MEI iAMT watchdog driver - connects to the watchdog feature,
235 configures the watchdog and sends the heartbeats.
Oren Weil6624fc22011-05-15 13:43:39 +0300236
Tomas Winkler222818c2016-01-08 00:49:22 +0200237The Intel iAMT watchdog MEI driver uses the kernel watchdog API to configure
238the Intel AMT Watchdog and to send heartbeats to it. The default timeout of the
Oren Weil463ac7f2011-12-06 23:25:18 +0200239watchdog is 120 seconds.
Oren Weil6624fc22011-05-15 13:43:39 +0300240
Tomas Winkler222818c2016-01-08 00:49:22 +0200241If the Intel AMT is not enabled in the firmware then the watchdog client won't enumerate
242on the me client bus and watchdog devices won't be exposed.
Oren Weil6624fc22011-05-15 13:43:39 +0300243
Julian Brostcfba6782015-01-12 00:58:06 +0100244
245Supported Chipsets
Oren Weil6624fc22011-05-15 13:43:39 +0300246==================
Julian Brostcfba6782015-01-12 00:58:06 +0100247
Oren Weil6624fc22011-05-15 13:43:39 +03002487 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