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:func:`close(int fd)`.
  42
  43 A code snippet for an application communicating with Intel AMTHI client:
  44
  45 .. code-block:: C
  46
  47         struct mei_connect_client_data data;
  48         fd = open(MEI_DEVICE);
  49
  50         data.d.in_client_uuid = AMTHI_GUID;
  51
  52         ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
  53
  54         printf("Ver=%d, MaxLen=%ld\n",
  55                data.d.in_client_uuid.protocol_version,
  56                data.d.in_client_uuid.max_msg_length);
  57
  58         [...]
  59
  60         write(fd, amthi_req_data, amthi_req_data_len);
  61
  62         [...]
  63
  64         read(fd, &amthi_res_data, amthi_res_data_len);
  65
  66         [...]
  67         close(fd);
  68
  69
  70 User space API
  71
  72 IOCTLs:
  73 =======
  74
  75 The Intel MEI Driver supports the following IOCTL commands:
  76
  77 IOCTL_MEI_CONNECT_CLIENT
  78 -------------------------
  79 Connect to firmware Feature/Client.
  80
  81 .. code-block:: none
  82
  83         Usage:
  84
  85         struct mei_connect_client_data client_data;
  86
  87         ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &client_data);
  88
  89         Inputs:
  90
  91         struct mei_connect_client_data - contain the following
  92         Input field:
  93
  94                 in_client_uuid -        GUID of the FW Feature that needs
  95                                         to connect to.
  96          Outputs:
  97                 out_client_properties - Client Properties: MTU and Protocol Version.
  98
  99          Error returns:
 100
 101                 ENOTTY  No such client (i.e. wrong GUID) or connection is not allowed.
 102                 EINVAL  Wrong IOCTL Number
 103                 ENODEV  Device or Connection is not initialized or ready.
 104                 ENOMEM  Unable to allocate memory to client internal data.
 105                 EFAULT  Fatal Error (e.g. Unable to access user input data)
 106                 EBUSY   Connection Already Open
 107
 108 :Note:
 109         max_msg_length (MTU) in client properties describes the maximum
 110         data that can be sent or received. (e.g. if MTU=2K, can send
 111         requests up to bytes 2k and received responses up to 2k bytes).
 112
 113
 114 IOCTL_MEI_NOTIFY_SET
 115 ---------------------
 116 Enable or disable event notifications.
 117
 118
 119 .. code-block:: none
 120
 121         Usage:
 122
 123                 uint32_t enable;
 124
 125                 ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
 126
 127
 128                 uint32_t enable = 1;
 129                 or
 130                 uint32_t enable[disable] = 0;
 131
 132         Error returns:
 133
 134
 135                 EINVAL  Wrong IOCTL Number
 136                 ENODEV  Device  is not initialized or the client not connected
 137                 ENOMEM  Unable to allocate memory to client internal data.
 138                 EFAULT  Fatal Error (e.g. Unable to access user input data)
 139                 EOPNOTSUPP if the device doesn't support the feature
 140
 141 :Note:
 142         The client must be connected in order to enable notification events
 143
 144
 145 IOCTL_MEI_NOTIFY_GET
 146 --------------------
 147 Retrieve event
 148
 149 .. code-block:: none
 150
 151         Usage:
 152                 uint32_t event;
 153                 ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
 154
 155         Outputs:
 156                 1 - if an event is pending
 157                 0 - if there is no even pending
 158
 159         Error returns:
 160                 EINVAL  Wrong IOCTL Number
 161                 ENODEV  Device is not initialized or the client not connected
 162                 ENOMEM  Unable to allocate memory to client internal data.
 163                 EFAULT  Fatal Error (e.g. Unable to access user input data)
 164                 EOPNOTSUPP if the device doesn't support the feature
 165
 166 :Note:
 167         The client must be connected and event notification has to be enabled
 168         in order to receive an event
 169
 170
 171
 172 Supported Chipsets
 173 ==================
 174 82X38/X48 Express and newer
 175
 176 linux-mei@linux.intel.com