214 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3Introduction4============5 6The Intel Management Engine (Intel ME) is an isolated and protected computing7resource (Co-processor) residing inside certain Intel chipsets. The Intel ME8provides 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 exposed13to the host as a PCI device, actually multiple PCI devices might be exposed.14The Intel MEI Driver is in charge of the communication channel between15a host application and the Intel ME features.16 17Each Intel ME feature, or Intel ME Client is addressed by a unique GUID and18each client has its own protocol. The protocol is message-based with a19header and payload up to maximal number of bytes advertised by the client,20upon connection.21 22Intel MEI Driver23================24 25The driver exposes a character device with device nodes /dev/meiX.26 27An application maintains communication with an Intel ME feature while28/dev/meiX is open. The binding to a specific feature is performed by calling29:c:macro:`MEI_CONNECT_CLIENT_IOCTL`, which passes the desired GUID.30The number of instances of an Intel ME feature that can be opened31at the same time depends on the Intel ME feature, but most of the32features allow only a single instance.33 34The driver is transparent to data that are passed between firmware feature35and host application.36 37Because some of the Intel ME features can change the system38configuration, the driver by default allows only a privileged39user 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 supervisor46can use :c:macro:`MEI_CONNECT_CLIENT_IOCTL_VTAG` to create47virtual channels with an Intel ME feature. Not all features support48virtual channels such client with answer EOPNOTSUPP.49 50.. code-block:: C51 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 API76 77IOCTLs:78=======79 80The Intel MEI Driver supports the following IOCTL commands:81 82IOCTL_MEI_CONNECT_CLIENT83-------------------------84Connect to firmware Feature/Client.85 86.. code-block:: none87 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 following97 Input field:98 99 in_client_uuid - GUID of the FW Feature that needs100 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 Number108 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 Open112 113:Note:114 max_msg_length (MTU) in client properties describes the maximum115 data that can be sent or received. (e.g. if MTU=2K, can send116 requests up to bytes 2k and received responses up to 2k bytes).117 118IOCTL_MEI_CONNECT_CLIENT_VTAG:119------------------------------120 121.. code-block:: none122 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 following132 Input field:133 134 in_client_uuid - GUID of the FW Feature that needs135 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 == 0145 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 Open149 EOPNOTSUPP Vtag is not supported150 151IOCTL_MEI_NOTIFY_SET152---------------------153Enable or disable event notifications.154 155 156.. code-block:: none157 158 Usage:159 160 uint32_t enable;161 162 ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);163 164 165 uint32_t enable = 1;166 or167 uint32_t enable[disable] = 0;168 169 Error returns:170 171 172 EINVAL Wrong IOCTL Number173 ENODEV Device is not initialized or the client not connected174 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 feature177 178:Note:179 The client must be connected in order to enable notification events180 181 182IOCTL_MEI_NOTIFY_GET183--------------------184Retrieve event185 186.. code-block:: none187 188 Usage:189 uint32_t event;190 ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);191 192 Outputs:193 1 - if an event is pending194 0 - if there is no even pending195 196 Error returns:197 EINVAL Wrong IOCTL Number198 ENODEV Device is not initialized or the client not connected199 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 feature202 203:Note:204 The client must be connected and event notification has to be enabled205 in order to receive an event206 207 208 209Supported Chipsets210==================21182X38/X48 Express and newer212 213linux-mei@linux.intel.com214