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