Documentation/driver-api/mei/mei-client-bus.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ==============================================
   4 Intel(R) Management Engine (ME) Client bus API
   5 ==============================================
   6
   7
   8 Rationale
   9 =========
  10
  11 The MEI character device is useful for dedicated applications to send and receive
  12 data to the many FW appliance found in Intel's ME from the user space.
  13 However, for some of the ME functionalities it makes sense to leverage existing software
  14 stack and expose them through existing kernel subsystems.
  15
  16 In order to plug seamlessly into the kernel device driver model we add kernel virtual
  17 bus abstraction on top of the MEI driver. This allows implementing Linux kernel drivers
  18 for the various MEI features as a stand alone entities found in their respective subsystem.
  19 Existing device drivers can even potentially be re-used by adding an MEI CL bus layer to
  20 the existing code.
  21
  22
  23 MEI CL bus API
  24 ==============
  25
  26 A driver implementation for an MEI Client is very similar to any other existing bus
  27 based device drivers. The driver registers itself as an MEI CL bus driver through
  28 the ``struct mei_cl_driver`` structure defined in :file:`include/linux/mei_cl_bus.c`
  29
  30 .. code-block:: C
  31
  32         struct mei_cl_driver {
  33                 struct device_driver driver;
  34                 const char *name;
  35
  36                 const struct mei_cl_device_id *id_table;
  37
  38                 int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id *id);
  39                 int (*remove)(struct mei_cl_device *dev);
  40         };
  41
  42
  43
  44 The mei_cl_device_id structure defined in :file:`include/linux/mod_devicetable.h` allows a
  45 driver to bind itself against a device name.
  46
  47 .. code-block:: C
  48
  49         struct mei_cl_device_id {
  50                 char name[MEI_CL_NAME_SIZE];
  51                 uuid_le uuid;
  52                 __u8    version;
  53                 kernel_ulong_t driver_info;
  54         };
  55
  56 To actually register a driver on the ME Client bus one must call the :c:func:`mei_cl_add_driver`
  57 API. This is typically called at module initialization time.
  58
  59 Once the driver is registered and bound to the device, a driver will typically
  60 try to do some I/O on this bus and this should be done through the :c:func:`mei_cl_send`
  61 and :c:func:`mei_cl_recv` functions. More detailed information is in :ref:`api` section.
  62
  63 In order for a driver to be notified about pending traffic or event, the driver
  64 should register a callback via :c:func:`mei_cl_devev_register_rx_cb` and
  65 :c:func:`mei_cldev_register_notify_cb` function respectively.
  66
  67 .. _api:
  68
  69 API:
  70 ----
  71 .. kernel-doc:: drivers/misc/mei/bus.c
  72     :export: drivers/misc/mei/bus.c
  73
  74
  75
  76 Example
  77 =======
  78
  79 As a theoretical example let's pretend the ME comes with a "contact" NFC IP.
  80 The driver init and exit routines for this device would look like:
  81
  82 .. code-block:: C
  83
  84         #define CONTACT_DRIVER_NAME "contact"
  85
  86         static struct mei_cl_device_id contact_mei_cl_tbl[] = {
  87                 { CONTACT_DRIVER_NAME, },
  88
  89                 /* required last entry */
  90                 { }
  91         };
  92         MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
  93
  94         static struct mei_cl_driver contact_driver = {
  95                 .id_table = contact_mei_tbl,
  96                 .name = CONTACT_DRIVER_NAME,
  97
  98                 .probe = contact_probe,
  99                 .remove = contact_remove,
 100         };
 101
 102         static int contact_init(void)
 103         {
 104                 int r;
 105
 106                 r = mei_cl_driver_register(&contact_driver);
 107                 if (r) {
 108                         pr_err(CONTACT_DRIVER_NAME ": driver registration failed\n");
 109                         return r;
 110                 }
 111
 112                 return 0;
 113         }
 114
 115         static void __exit contact_exit(void)
 116         {
 117                 mei_cl_driver_unregister(&contact_driver);
 118         }
 119
 120         module_init(contact_init);
 121         module_exit(contact_exit);
 122
 123 And the driver's simplified probe routine would look like that:
 124
 125 .. code-block:: C
 126
 127         int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id)
 128         {
 129                 [...]
 130                 mei_cldev_enable(dev);
 131
 132                 mei_cldev_register_rx_cb(dev, contact_rx_cb);
 133
 134                 return 0;
 135         }
 136
 137 In the probe routine the driver first enable the MEI device and then registers
 138 an rx handler which is as close as it can get to registering a threaded IRQ handler.
 139 The handler implementation will typically call :c:func:`mei_cldev_recv` and then
 140 process received data.
 141
 142 .. code-block:: C
 143
 144         #define MAX_PAYLOAD 128
 145         #define HDR_SIZE 4
 146         static void conntact_rx_cb(struct mei_cl_device *cldev)
 147         {
 148                 struct contact *c = mei_cldev_get_drvdata(cldev);
 149                 unsigned char payload[MAX_PAYLOAD];
 150                 ssize_t payload_sz;
 151
 152                 payload_sz = mei_cldev_recv(cldev, payload,  MAX_PAYLOAD)
 153                 if (reply_size < HDR_SIZE) {
 154                         return;
 155                 }
 156
 157                 c->process_rx(payload);
 158
 159         }
 160
 161 MEI Client Bus Drivers
 162 ======================
 163
 164 .. toctree::
 165    :maxdepth: 2
 166
 167    hdcp
 168    nfc