1 /** @file
2 * @brief Bluetooth HCI driver API.
3 */
4
5 /*
6 * Copyright (c) 2015-2016 Intel Corporation
7 *
8 * SPDX-License-Identifier: Apache-2.0
9 */
10 #ifndef __BT_HCI_DRIVER_H
11 #define __BT_HCI_DRIVER_H
12
13 /**
14 * @brief HCI drivers
15 * @defgroup bt_hci_driver HCI drivers
16 * @ingroup bluetooth
17 * @{
18 */
19
20 #include <stdbool.h>
21 #include <net/buf.h>
22 #include <bluetooth/buf.h>
23
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
28 enum {
29 /* The host should never send HCI_Reset */
30 BT_QUIRK_NO_RESET = BIT(0),
31 };
32
33 /**
34 * @brief Check if an HCI event is high priority or not.
35 *
36 * Helper for the HCI driver to know which events are ok to be passed
37 * through the RX thread and which must be given to bt_recv_prio() from
38 * another context (e.g. ISR). If this function returns true it's safe
39 * to pass the event through the RX thread, however if it returns false
40 * then this risks a deadlock.
41 *
42 * @param evt HCI event code.
43 *
44 * @return true if the event can be processed in the RX thread, false
45 * if it cannot.
46 */
bt_hci_evt_is_prio(u8_t evt)47 static inline bool bt_hci_evt_is_prio(u8_t evt)
48 {
49 switch (evt) {
50 case BT_HCI_EVT_CMD_COMPLETE:
51 case BT_HCI_EVT_CMD_STATUS:
52 #if defined(CONFIG_BT_CONN)
53 case BT_HCI_EVT_NUM_COMPLETED_PACKETS:
54 #endif
55 return true;
56 default:
57 return false;
58 }
59 }
60
61 /**
62 * @brief Receive data from the controller/HCI driver.
63 *
64 * This is the main function through which the HCI driver provides the
65 * host with data from the controller. The buffer needs to have its type
66 * set with the help of bt_buf_set_type() before calling this API. This API
67 * should not be used for so-called high priority HCI events, which should
68 * instead be delivered to the host stack through bt_recv_prio().
69 *
70 * @param buf Network buffer containing data from the controller.
71 *
72 * @return 0 on success or negative error number on failure.
73 */
74 int bt_recv(struct net_buf *buf);
75
76 /**
77 * @brief Receive high priority data from the controller/HCI driver.
78 *
79 * This is the same as bt_recv(), except that it should be used for
80 * so-called high priority HCI events. There's a separate
81 * bt_hci_evt_is_prio() helper that can be used to identify which events
82 * are high priority.
83 *
84 * As with bt_recv(), the buffer needs to have its type set with the help of
85 * bt_buf_set_type() before calling this API. The only exception is so called
86 * high priority HCI events which should be delivered to the host stack through
87 * bt_recv_prio() instead.
88 *
89 * @param buf Network buffer containing data from the controller.
90 *
91 * @return 0 on success or negative error number on failure.
92 */
93 int bt_recv_prio(struct net_buf *buf);
94
95 /** Possible values for the 'bus' member of the bt_hci_driver struct */
96 enum bt_hci_driver_bus {
97 BT_HCI_DRIVER_BUS_VIRTUAL = 0,
98 BT_HCI_DRIVER_BUS_USB = 1,
99 BT_HCI_DRIVER_BUS_PCCARD = 2,
100 BT_HCI_DRIVER_BUS_UART = 3,
101 BT_HCI_DRIVER_BUS_RS232 = 4,
102 BT_HCI_DRIVER_BUS_PCI = 5,
103 BT_HCI_DRIVER_BUS_SDIO = 6,
104 BT_HCI_DRIVER_BUS_SPI = 7,
105 BT_HCI_DRIVER_BUS_I2C = 8,
106 };
107
108 /**
109 * @brief Abstraction which represents the HCI transport to the controller.
110 *
111 * This struct is used to represent the HCI transport to the Bluetooth
112 * controller.
113 */
114 struct bt_hci_driver {
115 /** Name of the driver */
116 const char *name;
117
118 /** Bus of the transport (BT_HCI_DRIVER_BUS_*) */
119 enum bt_hci_driver_bus bus;
120
121 /** Specific controller quirks. These are set by the HCI driver
122 * and acted upon by the host. They can either be statically
123 * set at buildtime, or set at runtime before the HCI driver's
124 * open() callback returns.
125 */
126 bt_u32_t quirks;
127
128 /**
129 * @brief Open the HCI transport.
130 *
131 * Opens the HCI transport for operation. This function must not
132 * return until the transport is ready for operation, meaning it
133 * is safe to start calling the send() handler.
134 *
135 * If the driver uses its own RX thread, i.e.
136 * CONFIG_BT_RECV_IS_RX_THREAD is set, then this
137 * function is expected to start that thread.
138 *
139 * @return 0 on success or negative error number on failure.
140 */
141 int (*open)(void);
142
143 /**
144 * @brief Send HCI buffer to controller.
145 *
146 * Send an HCI command or ACL data to the controller. The exact
147 * type of the data can be checked with the help of bt_buf_get_type().
148 *
149 * @note This function must only be called from a cooperative thread.
150 *
151 * @param buf Buffer containing data to be sent to the controller.
152 *
153 * @return 0 on success or negative error number on failure.
154 */
155 int (*send)(struct net_buf *buf);
156 };
157
158 /**
159 * @brief Register a new HCI driver to the Bluetooth stack.
160 *
161 * This needs to be called before any application code runs. The bt_enable()
162 * API will fail if there is no driver registered.
163 *
164 * @param drv A bt_hci_driver struct representing the driver.
165 *
166 * @return 0 on success or negative error number on failure.
167 */
168 int bt_hci_driver_register(const struct bt_hci_driver *drv);
169
170 #ifdef __cplusplus
171 }
172 #endif
173
174 /**
175 * @}
176 */
177
178 #endif /* __BT_HCI_DRIVER_H */
179