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