0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 Introduction
0004 ============
0005
0006 The Intel Management Engine (Intel ME) is an isolated and protected computing
0007 resource (Co-processor) residing inside certain Intel chipsets. The Intel ME
0008 provides support for computer/IT management and security features.
0009 The actual feature set depends on the Intel chipset SKU.
0010
0011 The Intel Management Engine Interface (Intel MEI, previously known as HECI)
0012 is the interface between the Host and Intel ME. This interface is exposed
0013 to the host as a PCI device, actually multiple PCI devices might be exposed.
0014 The Intel MEI Driver is in charge of the communication channel between
0015 a host application and the Intel ME features.
0016
0017 Each Intel ME feature, or Intel ME Client is addressed by a unique GUID and
0018 each client has its own protocol. The protocol is message-based with a
0019 header and payload up to maximal number of bytes advertised by the client,
0020 upon connection.
0021
0022 Intel MEI Driver
0023 ================
0024
0025 The driver exposes a character device with device nodes /dev/meiX.
0026
0027 An application maintains communication with an Intel ME feature while
0028 /dev/meiX is open. The binding to a specific feature is performed by calling
0029 :c:macro:`MEI_CONNECT_CLIENT_IOCTL`, which passes the desired GUID.
0030 The number of instances of an Intel ME feature that can be opened
0031 at the same time depends on the Intel ME feature, but most of the
0032 features allow only a single instance.
0033
0034 The driver is transparent to data that are passed between firmware feature
0035 and host application.
0036
0037 Because some of the Intel ME features can change the system
0038 configuration, the driver by default allows only a privileged
0039 user to access it.
0040
0041 The session is terminated calling :c:expr:`close(fd)`.
0042
0043 A code snippet for an application communicating with Intel AMTHI client:
0044
0045 In order to support virtualization or sandboxing a trusted supervisor
0046 can use :c:macro:`MEI_CONNECT_CLIENT_IOCTL_VTAG` to create
0047 virtual channels with an Intel ME feature. Not all features support
0048 virtual channels such client with answer EOPNOTSUPP.
0049
0050 .. code-block:: C
0051
0052 struct mei_connect_client_data data;
0053 fd = open(MEI_DEVICE);
0054
0055 data.d.in_client_uuid = AMTHI_GUID;
0056
0057 ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
0058
0059 printf("Ver=%d, MaxLen=%ld\n",
0060 data.d.in_client_uuid.protocol_version,
0061 data.d.in_client_uuid.max_msg_length);
0062
0063 [...]
0064
0065 write(fd, amthi_req_data, amthi_req_data_len);
0066
0067 [...]
0068
0069 read(fd, &amthi_res_data, amthi_res_data_len);
0070
0071 [...]
0072 close(fd);
0073
0074
0075 User space API
0076
0077 IOCTLs:
0078 =======
0079
0080 The Intel MEI Driver supports the following IOCTL commands:
0081
0082 IOCTL_MEI_CONNECT_CLIENT
0083 -------------------------
0084 Connect to firmware Feature/Client.
0085
0086 .. code-block:: none
0087
0088 Usage:
0089
0090 struct mei_connect_client_data client_data;
0091
0092 ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &client_data);
0093
0094 Inputs:
0095
0096 struct mei_connect_client_data - contain the following
0097 Input field:
0098
0099 in_client_uuid - GUID of the FW Feature that needs
0100 to connect to.
0101 Outputs:
0102 out_client_properties - Client Properties: MTU and Protocol Version.
0103
0104 Error returns:
0105
0106 ENOTTY No such client (i.e. wrong GUID) or connection is not allowed.
0107 EINVAL Wrong IOCTL Number
0108 ENODEV Device or Connection is not initialized or ready.
0109 ENOMEM Unable to allocate memory to client internal data.
0110 EFAULT Fatal Error (e.g. Unable to access user input data)
0111 EBUSY Connection Already Open
0112
0113 :Note:
0114 max_msg_length (MTU) in client properties describes the maximum
0115 data that can be sent or received. (e.g. if MTU=2K, can send
0116 requests up to bytes 2k and received responses up to 2k bytes).
0117
0118 IOCTL_MEI_CONNECT_CLIENT_VTAG:
0119 ------------------------------
0120
0121 .. code-block:: none
0122
0123 Usage:
0124
0125 struct mei_connect_client_data_vtag client_data_vtag;
0126
0127 ioctl(fd, IOCTL_MEI_CONNECT_CLIENT_VTAG, &client_data_vtag);
0128
0129 Inputs:
0130
0131 struct mei_connect_client_data_vtag - contain the following
0132 Input field:
0133
0134 in_client_uuid - GUID of the FW Feature that needs
0135 to connect to.
0136 vtag - virtual tag [1, 255]
0137
0138 Outputs:
0139 out_client_properties - Client Properties: MTU and Protocol Version.
0140
0141 Error returns:
0142
0143 ENOTTY No such client (i.e. wrong GUID) or connection is not allowed.
0144 EINVAL Wrong IOCTL Number or tag == 0
0145 ENODEV Device or Connection is not initialized or ready.
0146 ENOMEM Unable to allocate memory to client internal data.
0147 EFAULT Fatal Error (e.g. Unable to access user input data)
0148 EBUSY Connection Already Open
0149 EOPNOTSUPP Vtag is not supported
0150
0151 IOCTL_MEI_NOTIFY_SET
0152 ---------------------
0153 Enable or disable event notifications.
0154
0155
0156 .. code-block:: none
0157
0158 Usage:
0159
0160 uint32_t enable;
0161
0162 ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
0163
0164
0165 uint32_t enable = 1;
0166 or
0167 uint32_t enable[disable] = 0;
0168
0169 Error returns:
0170
0171
0172 EINVAL Wrong IOCTL Number
0173 ENODEV Device is not initialized or the client not connected
0174 ENOMEM Unable to allocate memory to client internal data.
0175 EFAULT Fatal Error (e.g. Unable to access user input data)
0176 EOPNOTSUPP if the device doesn't support the feature
0177
0178 :Note:
0179 The client must be connected in order to enable notification events
0180
0181
0182 IOCTL_MEI_NOTIFY_GET
0183 --------------------
0184 Retrieve event
0185
0186 .. code-block:: none
0187
0188 Usage:
0189 uint32_t event;
0190 ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
0191
0192 Outputs:
0193 1 - if an event is pending
0194 0 - if there is no even pending
0195
0196 Error returns:
0197 EINVAL Wrong IOCTL Number
0198 ENODEV Device is not initialized or the client not connected
0199 ENOMEM Unable to allocate memory to client internal data.
0200 EFAULT Fatal Error (e.g. Unable to access user input data)
0201 EOPNOTSUPP if the device doesn't support the feature
0202
0203 :Note:
0204 The client must be connected and event notification has to be enabled
0205 in order to receive an event
0206
0207
0208
0209 Supported Chipsets
0210 ==================
0211 82X38/X48 Express and newer
0212
0213 linux-mei@linux.intel.com
