Documentation/driver-api/mei/mei.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 Introduction
   4 ============
   5
   6 The Intel Management Engine (Intel ME) is an isolated and protected computing
   7 resource (Co-processor) residing inside certain Intel chipsets. The Intel ME
   8 provides support for computer/IT management and security features.
   9 The actual feature set depends on the Intel chipset SKU.
  10
  11 The Intel Management Engine Interface (Intel MEI, previously known as HECI)
  12 is the interface between the Host and Intel ME. This interface is exposed
  13 to the host as a PCI device, actually multiple PCI devices might be exposed.
  14 The Intel MEI Driver is in charge of the communication channel between
  15 a host application and the Intel ME features.
  16
  17 Each Intel ME feature, or Intel ME Client is addressed by a unique GUID and
  18 each client has its own protocol. The protocol is message-based with a
  19 header and payload up to maximal number of bytes advertised by the client,
  20 upon connection.
  21
  22 Intel MEI Driver
  23 ================
  24
  25 The driver exposes a character device with device nodes /dev/meiX.
  26
  27 An 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.
  30 The number of instances of an Intel ME feature that can be opened
  31 at the same time depends on the Intel ME feature, but most of the
  32 features allow only a single instance.
  33
  34 The driver is transparent to data that are passed between firmware feature
  35 and host application.
  36
  37 Because some of the Intel ME features can change the system
  38 configuration, the driver by default allows only a privileged
  39 user to access it.
  40
  41 The session is terminated calling :c:expr:`close(fd)`.
  42
  43 A code snippet for an application communicating with Intel AMTHI client:
  44
  45 In order to support virtualization or sandboxing a trusted supervisor
  46 can use :c:macro:`MEI_CONNECT_CLIENT_IOCTL_VTAG` to create
  47 virtual channels with an Intel ME feature. Not all features support
  48 virtual 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
  75 User space API
  76
  77 IOCTLs:
  78 =======
  79
  80 The Intel MEI Driver supports the following IOCTL commands:
  81
  82 IOCTL_MEI_CONNECT_CLIENT
  83 -------------------------
  84 Connect 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
 118 IOCTL_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
 151 IOCTL_MEI_NOTIFY_SET
 152 ---------------------
 153 Enable 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
 182 IOCTL_MEI_NOTIFY_GET
 183 --------------------
 184 Retrieve 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
 209 Supported Chipsets
 210 ==================
 211 82X38/X48 Express and newer
 212
 213 linux-mei@linux.intel.com