Intel Management Engine Client bus API

MEI Client bus가 필요한 이유

MEI character device는 전용 userspace application이 Intel ME의 여러 firmware appliance와 자료를 주고받는 데 유용합니다.

일부 ME 기능은 기존 software stack을 활용해 기존 kernel subsystem으로 노출하는 편이 적합합니다.

Kernel device·driver model에 자연스럽게 연결하기 위해 MEI driver 위에 kernel virtual bus abstraction을 추가합니다. 각 MEI 기능을 해당 subsystem의 독립 Linux kernel driver로 구현할 수 있습니다.

기존 driver code에 MEI CL bus layer를 추가해 재사용할 가능성도 있습니다.

.. SPDX-License-Identifier: GPL-2.0

==============================================
Intel(R) Management Engine (ME) Client bus API
==============================================


Rationale
=========

The MEI character device is useful for dedicated applications to send and receive
data to the many FW appliance found in Intel's ME from the user space.
However, for some of the ME functionalities it makes sense to leverage existing software
stack and expose them through existing kernel subsystems.

In order to plug seamlessly into the kernel device driver model we add kernel virtual
bus abstraction on top of the MEI driver. This allows implementing Linux kernel drivers
for the various MEI features as a stand alone entities found in their respective subsystem.
Existing device drivers can even potentially be re-used by adding an MEI CL bus layer to
the existing code.

MEI CL bus driver model

MEI Client driver 구현은 다른 bus 기반 device driver와 비슷합니다. Driver는 `mei_cl_driver` 구조체로 MEI CL bus driver를 등록합니다.

`mei_cl_driver`는 일반 `device_driver`, 이름, `mei_cl_device_id` table, `probe()`와 `remove()` callback을 포함합니다.

`include/linux/mod_devicetable.h`의 `mei_cl_device_id`는 name, UUID, protocol version과 `driver_info`로 driver를 device에 bind합니다.

Module 초기화 시 `mei_cl_add_driver()` API로 driver를 ME Client bus에 등록합니다.

등록·binding 후 I/O는 `mei_cl_send()`와 `mei_cl_recv()`로 수행합니다.

Pending traffic과 event를 통지받으려면 각각 `mei_cl_devev_register_rx_cb()`와 `mei_cldev_register_notify_cb()`로 callback을 등록합니다.

MEI CL bus API
==============

A driver implementation for an MEI Client is very similar to any other existing bus
based device drivers. The driver registers itself as an MEI CL bus driver through
the ``struct mei_cl_driver`` structure defined in :file:`include/linux/mei_cl_bus.c`

.. code-block:: C

        struct mei_cl_driver {
                struct device_driver driver;
                const char *name;

                const struct mei_cl_device_id *id_table;

                int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id *id);
                int (*remove)(struct mei_cl_device *dev);
        };



The mei_cl_device_id structure defined in :file:`include/linux/mod_devicetable.h` allows a
driver to bind itself against a device name.

.. code-block:: C

        struct mei_cl_device_id {
                char name[MEI_CL_NAME_SIZE];
                uuid_le uuid;
                __u8    version;
                kernel_ulong_t driver_info;
        };

To actually register a driver on the ME Client bus one must call the :c:func:`mei_cl_add_driver`
API. This is typically called at module initialization time.

Once the driver is registered and bound to the device, a driver will typically
try to do some I/O on this bus and this should be done through the :c:func:`mei_cl_send`
and :c:func:`mei_cl_recv` functions. More detailed information is in :ref:`api` section.

In order for a driver to be notified about pending traffic or event, the driver
should register a callback via :c:func:`mei_cl_devev_register_rx_cb` and
:c:func:`mei_cldev_register_notify_cb` function respectively.

.. _api:

MEI CL bus API

MEI Client bus의 exported API는 `drivers/misc/mei/bus.c`의 kernel-doc에서 제공합니다.

API:
----
.. kernel-doc:: drivers/misc/mei/bus.c
    :export: drivers/misc/mei/bus.c

Contact driver 등록 예제

가상 `contact` NFC IP 예제는 `mei_cl_device_id` table의 이름으로 device를 match하고 마지막에 빈 sentinel entry를 둡니다. `MODULE_DEVICE_TABLE(mei_cl, ...)`로 module device table을 공개합니다.

`mei_cl_driver`에는 ID table, driver 이름, `contact_probe`와 `contact_remove` callback을 지정합니다.

Module init은 `mei_cl_driver_register()`로 driver를 등록하고 실패하면 오류를 기록해 반환합니다. Module exit은 `mei_cl_driver_unregister()`로 등록을 해제합니다.

Example
=======

As a theoretical example let's pretend the ME comes with a "contact" NFC IP.
The driver init and exit routines for this device would look like:

.. code-block:: C

        #define CONTACT_DRIVER_NAME "contact"

        static struct mei_cl_device_id contact_mei_cl_tbl[] = {
                { CONTACT_DRIVER_NAME, },

                /* required last entry */
                { }
        };
        MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);

        static struct mei_cl_driver contact_driver = {
                .id_table = contact_mei_tbl,
                .name = CONTACT_DRIVER_NAME,

                .probe = contact_probe,
                .remove = contact_remove,
        };

        static int contact_init(void)
        {
                int r;

                r = mei_cl_driver_register(&contact_driver);
                if (r) {
                        pr_err(CONTACT_DRIVER_NAME ": driver registration failed\n");
                        return r;
                }

                return 0;
        }

        static void __exit contact_exit(void)
        {
                mei_cl_driver_unregister(&contact_driver);
        }

        module_init(contact_init);
        module_exit(contact_exit);

Probe와 RX callback 예제

단순화된 probe는 먼저 `mei_cldev_enable(dev)`로 MEI device를 활성화하고 `mei_cldev_register_rx_cb()`로 RX handler를 등록합니다. 이는 threaded IRQ handler 등록과 가장 비슷한 동작입니다.

RX handler는 보통 `mei_cldev_recv()`로 payload를 받고 처리합니다.

예제 callback은 `mei_cldev_get_drvdata()`로 driver 상태를 얻고 최대 128 byte payload를 수신합니다. Header 크기보다 짧으면 반환하고 그렇지 않으면 driver의 receive 처리로 전달합니다.

And the driver's simplified probe routine would look like that:

.. code-block:: C

        int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id)
        {
                [...]
                mei_cldev_enable(dev);

                mei_cldev_register_rx_cb(dev, contact_rx_cb);

                return 0;
        }

In the probe routine the driver first enable the MEI device and then registers
an rx handler which is as close as it can get to registering a threaded IRQ handler.
The handler implementation will typically call :c:func:`mei_cldev_recv` and then
process received data.

.. code-block:: C

        #define MAX_PAYLOAD 128
        #define HDR_SIZE 4
        static void conntact_rx_cb(struct mei_cl_device *cldev)
        {
                struct contact *c = mei_cldev_get_drvdata(cldev);
                unsigned char payload[MAX_PAYLOAD];
                ssize_t payload_sz;

                payload_sz = mei_cldev_recv(cldev, payload,  MAX_PAYLOAD)
                if (reply_size < HDR_SIZE) {
                        return;
                }

                c->process_rx(payload);

        }

MEI Client Bus driver 문서

MEI Client Bus driver 하위 문서는 HDCP와 NFC client driver를 연결합니다.

MEI Client Bus Drivers
======================

.. toctree::
   :maxdepth: 2

   hdcp
   nfc