1.. SPDX-License-Identifier: GPL-2.0 2 3============================================== 4Intel(R) Management Engine (ME) Client bus API 5============================================== 6 7 8Rationale 9========= 10 11The MEI character device is useful for dedicated applications to send and receive 12data to the many FW appliance found in Intel's ME from the user space. 13However, for some of the ME functionalities it makes sense to leverage existing software 14stack and expose them through existing kernel subsystems. 15 16In order to plug seamlessly into the kernel device driver model we add kernel virtual 17bus abstraction on top of the MEI driver. This allows implementing Linux kernel drivers 18for the various MEI features as a stand alone entities found in their respective subsystem. 19Existing device drivers can even potentially be re-used by adding an MEI CL bus layer to 20the existing code. 21 22 23MEI CL bus API 24============== 25 26A driver implementation for an MEI Client is very similar to any other existing bus 27based device drivers. The driver registers itself as an MEI CL bus driver through 28the ``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 44The mei_cl_device_id structure defined in :file:`include/linux/mod_devicetable.h` allows a 45driver 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 56To actually register a driver on the ME Client bus one must call the :c:func:`mei_cl_add_driver` 57API. This is typically called at module initialization time. 58 59Once the driver is registered and bound to the device, a driver will typically 60try to do some I/O on this bus and this should be done through the :c:func:`mei_cl_send` 61and :c:func:`mei_cl_recv` functions. More detailed information is in :ref:`api` section. 62 63In order for a driver to be notified about pending traffic or event, the driver 64should 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 69API: 70---- 71.. kernel-doc:: drivers/misc/mei/bus.c 72 :export: drivers/misc/mei/bus.c 73 74 75 76Example 77======= 78 79As a theoretical example let's pretend the ME comes with a "contact" NFC IP. 80The 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 123And 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 137In the probe routine the driver first enable the MEI device and then registers 138an rx handler which is as close as it can get to registering a threaded IRQ handler. 139The handler implementation will typically call :c:func:`mei_cldev_recv` and then 140process 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 161MEI Client Bus Drivers 162====================== 163 164.. toctree:: 165 :maxdepth: 2 166 167 hdcp 168 nfc 169