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