Intel Management Engine Interface

Intel ME와 MEI

Intel Management Engine은 일부 Intel chipset 안에 있는 격리·보호된 co-processor 자원입니다. Computer·IT 관리와 security 기능을 제공하며 실제 기능 집합은 chipset SKU에 따라 달라집니다.

Intel Management Engine Interface는 이전에 HECI로 불렸으며 host와 Intel ME 사이의 interface입니다. Host에는 하나 이상의 PCI device로 노출될 수 있습니다.

Intel MEI driver는 host application과 Intel ME feature 사이의 통신 channel을 담당합니다.

각 Intel ME feature 또는 client는 고유 GUID로 주소를 지정하며 자체 protocol을 가집니다. Protocol은 header와 payload를 가진 message 기반이며 연결 시 client가 알린 최대 byte 수까지 payload를 전송할 수 있습니다.

.. SPDX-License-Identifier: GPL-2.0

Introduction
============

The Intel Management Engine (Intel ME) is an isolated and protected computing
resource (Co-processor) residing inside certain Intel chipsets. The Intel ME
provides support for computer/IT management and security features.
The actual feature set depends on the Intel chipset SKU.

The Intel Management Engine Interface (Intel MEI, previously known as HECI)
is the interface between the Host and Intel ME. This interface is exposed
to the host as a PCI device, actually multiple PCI devices might be exposed.
The Intel MEI Driver is in charge of the communication channel between
a host application and the Intel ME features.

Each Intel ME feature, or Intel ME Client is addressed by a unique GUID and
each client has its own protocol. The protocol is message-based with a
header and payload up to maximal number of bytes advertised by the client,
upon connection.

MEI character device와 보안

Driver는 `/dev/meiX` character device node를 노출합니다. Application은 node를 열어 둔 동안 Intel ME feature와 통신을 유지합니다.

특정 feature binding은 원하는 GUID를 전달하는 `MEI_CONNECT_CLIENT_IOCTL`로 수행합니다. 동시에 열 수 있는 instance 수는 feature마다 다르지만 대부분 하나만 허용합니다.

Driver는 firmware feature와 host application 사이에서 전달되는 data 내용을 해석하지 않습니다.

일부 Intel ME feature가 system 구성을 바꿀 수 있으므로 기본적으로 privileged user만 접근할 수 있습니다. Session은 `close(fd)`로 종료합니다.

Virtualization 또는 sandboxing에서는 trusted supervisor가 `MEI_CONNECT_CLIENT_IOCTL_VTAG`로 virtual channel을 만들 수 있습니다. 지원하지 않는 feature는 `EOPNOTSUPP`를 반환합니다.

Intel MEI Driver
================

The driver exposes a character device with device nodes /dev/meiX.

An application maintains communication with an Intel ME feature while
/dev/meiX is open. The binding to a specific feature is performed by calling
:c:macro:`MEI_CONNECT_CLIENT_IOCTL`, which passes the desired GUID.
The number of instances of an Intel ME feature that can be opened
at the same time depends on the Intel ME feature, but most of the
features allow only a single instance.

The driver is transparent to data that are passed between firmware feature
and host application.

Because some of the Intel ME features can change the system
configuration, the driver by default allows only a privileged
user to access it.

The session is terminated calling :c:expr:`close(fd)`.

A code snippet for an application communicating with Intel AMTHI client:

In order to support virtualization or sandboxing a trusted supervisor
can use :c:macro:`MEI_CONNECT_CLIENT_IOCTL_VTAG` to create
virtual channels with an Intel ME feature. Not all features support
virtual channels such client with answer EOPNOTSUPP.

AMTHI client 통신 예제

예제 application은 MEI device를 열고 `mei_connect_client_data`의 input UUID를 `AMTHI_GUID`로 설정합니다.

`IOCTL_MEI_CONNECT_CLIENT`로 연결한 뒤 firmware가 반환한 protocol version과 최대 message 길이를 확인합니다.

이후 request를 `write()`하고 response를 `read()`한 뒤 file descriptor를 닫아 session을 종료합니다.

.. code-block:: C

        struct mei_connect_client_data data;
        fd = open(MEI_DEVICE);

        data.d.in_client_uuid = AMTHI_GUID;

        ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);

        printf("Ver=%d, MaxLen=%ld\n",
               data.d.in_client_uuid.protocol_version,
               data.d.in_client_uuid.max_msg_length);

        [...]

        write(fd, amthi_req_data, amthi_req_data_len);

        [...]

        read(fd, &amthi_res_data, amthi_res_data_len);

        [...]
        close(fd);

IOCTL_MEI_CONNECT_CLIENT

`IOCTL_MEI_CONNECT_CLIENT`는 firmware feature·client에 연결합니다. `mei_connect_client_data`를 전달하며 input의 `in_client_uuid`가 대상 GUID입니다.

Output `out_client_properties`에는 client MTU와 protocol version이 들어갑니다. `max_msg_length`는 한 번에 보내거나 받을 수 있는 최대 data 길이입니다.

오류는 잘못된 GUID 또는 금지된 연결의 `ENOTTY`, 잘못된 ioctl 번호의 `EINVAL`, 준비되지 않은 장치·연결의 `ENODEV`, 내부 자료 할당 실패의 `ENOMEM`, userspace 자료 접근 같은 치명적 오류의 `EFAULT`, 이미 열린 연결의 `EBUSY`입니다.

User space API

IOCTLs:
=======

The Intel MEI Driver supports the following IOCTL commands:

IOCTL_MEI_CONNECT_CLIENT
-------------------------
Connect to firmware Feature/Client.

.. code-block:: none

        Usage:

        struct mei_connect_client_data client_data;

        ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &client_data);

        Inputs:

        struct mei_connect_client_data - contain the following
        Input field:

                in_client_uuid -        GUID of the FW Feature that needs
                                        to connect to.
         Outputs:
                out_client_properties - Client Properties: MTU and Protocol Version.

         Error returns:

                ENOTTY  No such client (i.e. wrong GUID) or connection is not allowed.
                EINVAL        Wrong IOCTL Number
                ENODEV        Device or Connection is not initialized or ready.
                ENOMEM        Unable to allocate memory to client internal data.
                EFAULT        Fatal Error (e.g. Unable to access user input data)
                EBUSY        Connection Already Open

:Note:
        max_msg_length (MTU) in client properties describes the maximum
        data that can be sent or received. (e.g. if MTU=2K, can send
        requests up to bytes 2k and received responses up to 2k bytes).

IOCTL_MEI_CONNECT_CLIENT_VTAG

`IOCTL_MEI_CONNECT_CLIENT_VTAG`는 `mei_connect_client_data_vtag`를 사용해 virtual channel을 연결합니다.

입력에는 firmware feature GUID와 1에서 255 사이의 `vtag`가 있으며, 출력에는 client MTU와 protocol version이 들어갑니다.

일반 연결 오류 외에 tag가 0이면 `EINVAL`, feature가 virtual tag를 지원하지 않으면 `EOPNOTSUPP`를 반환합니다.

IOCTL_MEI_CONNECT_CLIENT_VTAG:
------------------------------

.. code-block:: none

        Usage:

        struct mei_connect_client_data_vtag client_data_vtag;

        ioctl(fd, IOCTL_MEI_CONNECT_CLIENT_VTAG, &client_data_vtag);

        Inputs:

        struct mei_connect_client_data_vtag - contain the following
        Input field:

                in_client_uuid -  GUID of the FW Feature that needs
                                  to connect to.
                vtag - virtual tag [1, 255]

         Outputs:
                out_client_properties - Client Properties: MTU and Protocol Version.

         Error returns:

                ENOTTY No such client (i.e. wrong GUID) or connection is not allowed.
                EINVAL Wrong IOCTL Number or tag == 0
                ENODEV Device or Connection is not initialized or ready.
                ENOMEM Unable to allocate memory to client internal data.
                EFAULT Fatal Error (e.g. Unable to access user input data)
                EBUSY  Connection Already Open
                EOPNOTSUPP Vtag is not supported

IOCTL_MEI_NOTIFY_SET

`IOCTL_MEI_NOTIFY_SET`은 event notification을 활성화하거나 비활성화합니다. `uint32_t enable` 값 1은 활성화, 0은 비활성화입니다.

잘못된 ioctl은 `EINVAL`, 장치가 초기화되지 않았거나 client가 연결되지 않았으면 `ENODEV`, 내부 할당 실패는 `ENOMEM`, 치명적 userspace 접근 오류는 `EFAULT`, 기능 미지원은 `EOPNOTSUPP`입니다.

Notification event를 활성화하려면 client가 먼저 연결되어 있어야 합니다.

IOCTL_MEI_NOTIFY_SET
---------------------
Enable or disable event notifications.


.. code-block:: none

        Usage:

                uint32_t enable;

                ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);


                uint32_t enable = 1;
                or
                uint32_t enable[disable] = 0;

        Error returns:


                EINVAL        Wrong IOCTL Number
                ENODEV        Device  is not initialized or the client not connected
                ENOMEM        Unable to allocate memory to client internal data.
                EFAULT        Fatal Error (e.g. Unable to access user input data)
                EOPNOTSUPP if the device doesn't support the feature

:Note:
        The client must be connected in order to enable notification events

IOCTL_MEI_NOTIFY_GET

`IOCTL_MEI_NOTIFY_GET`은 pending event 상태를 가져옵니다. Output은 event가 대기 중이면 1, 없으면 0입니다.

오류 조건은 `NOTIFY_SET`과 동일하게 `EINVAL`, `ENODEV`, `ENOMEM`, `EFAULT`, `EOPNOTSUPP`입니다.

Event를 받으려면 client가 연결되어 있고 event notification도 활성화되어 있어야 합니다.

IOCTL_MEI_NOTIFY_GET
--------------------
Retrieve event

.. code-block:: none

        Usage:
                uint32_t event;
                ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);

        Outputs:
                1 - if an event is pending
                0 - if there is no even pending

        Error returns:
                EINVAL        Wrong IOCTL Number
                ENODEV        Device is not initialized or the client not connected
                ENOMEM        Unable to allocate memory to client internal data.
                EFAULT        Fatal Error (e.g. Unable to access user input data)
                EOPNOTSUPP if the device doesn't support the feature

:Note:
        The client must be connected and event notification has to be enabled
        in order to receive an event

지원 chipset과 연락처

MEI driver는 82X38/X48 Express 이후 chipset을 지원합니다.

관련 연락처는 `linux-mei@linux.intel.com`입니다.

Supported Chipsets
==================
82X38/X48 Express and newer

linux-mei@linux.intel.com