1Intel(R) Management Engine (ME) Client bus API 2=============================================== 3 4 5Rationale 6========= 7MEI misc character device is useful for dedicated applications to send and receive 8data to the many FW appliance found in Intel's ME from the user space. 9However for some of the ME functionalities it make sense to leverage existing software 10stack and expose them through existing kernel subsystems. 11 12In order to plug seamlessly into the kernel device driver model we add kernel virtual 13bus abstraction on top of the MEI driver. This allows implementing linux kernel drivers 14for the various MEI features as a stand alone entities found in their respective subsystem. 15Existing device drivers can even potentially be re-used by adding an MEI CL bus layer to 16the existing code. 17 18 19MEI CL bus API 20=========== 21A driver implementation for an MEI Client is very similar to existing bus 22based device drivers. The driver registers itself as an MEI CL bus driver through 23the mei_cl_driver structure: 24 25struct mei_cl_driver { 26 struct device_driver driver; 27 const char *name; 28 29 const struct mei_cl_device_id *id_table; 30 31 int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id *id); 32 int (*remove)(struct mei_cl_device *dev); 33}; 34 35struct mei_cl_id { 36 char name[MEI_NAME_SIZE]; 37 kernel_ulong_t driver_info; 38}; 39 40The mei_cl_id structure allows the driver to bind itself against a device name. 41 42To actually register a driver on the ME Client bus one must call the mei_cl_add_driver() 43API. This is typically called at module init time. 44 45Once registered on the ME Client bus, a driver will typically try to do some I/O on 46this bus and this should be done through the mei_cl_send() and mei_cl_recv() 47routines. The latter is synchronous (blocks and sleeps until data shows up). 48In order for drivers to be notified of pending events waiting for them (e.g. 49an Rx event) they can register an event handler through the 50mei_cl_register_event_cb() routine. Currently only the MEI_EVENT_RX event 51will trigger an event handler call and the driver implementation is supposed 52to call mei_recv() from the event handler in order to fetch the pending 53received buffers. 54 55 56Example 57======= 58As a theoretical example let's pretend the ME comes with a "contact" NFC IP. 59The driver init and exit routines for this device would look like: 60 61#define CONTACT_DRIVER_NAME "contact" 62 63static struct mei_cl_device_id contact_mei_cl_tbl[] = { 64 { CONTACT_DRIVER_NAME, }, 65 66 /* required last entry */ 67 { } 68}; 69MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl); 70 71static struct mei_cl_driver contact_driver = { 72 .id_table = contact_mei_tbl, 73 .name = CONTACT_DRIVER_NAME, 74 75 .probe = contact_probe, 76 .remove = contact_remove, 77}; 78 79static int contact_init(void) 80{ 81 int r; 82 83 r = mei_cl_driver_register(&contact_driver); 84 if (r) { 85 pr_err(CONTACT_DRIVER_NAME ": driver registration failed\n"); 86 return r; 87 } 88 89 return 0; 90} 91 92static void __exit contact_exit(void) 93{ 94 mei_cl_driver_unregister(&contact_driver); 95} 96 97module_init(contact_init); 98module_exit(contact_exit); 99 100And the driver's simplified probe routine would look like that: 101 102int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id) 103{ 104 struct contact_driver *contact; 105 106 [...] 107 mei_cl_enable_device(dev); 108 109 mei_cl_register_event_cb(dev, contact_event_cb, contact); 110 111 return 0; 112 } 113 114In the probe routine the driver first enable the MEI device and then registers 115an ME bus event handler which is as close as it can get to registering a 116threaded IRQ handler. 117The handler implementation will typically call some I/O routine depending on 118the pending events: 119 120#define MAX_NFC_PAYLOAD 128 121 122static void contact_event_cb(struct mei_cl_device *dev, u32 events, 123 void *context) 124{ 125 struct contact_driver *contact = context; 126 127 if (events & BIT(MEI_EVENT_RX)) { 128 u8 payload[MAX_NFC_PAYLOAD]; 129 int payload_size; 130 131 payload_size = mei_recv(dev, payload, MAX_NFC_PAYLOAD); 132 if (payload_size <= 0) 133 return; 134 135 /* Hook to the NFC subsystem */ 136 nfc_hci_recv_frame(contact->hdev, payload, payload_size); 137 } 138} 139