Mistake on this page?
Report an issue in GitHub or email us
CordioHCIDriver.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2017-2017 ARM Limited
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 #ifndef IMPL_HCI_DRIVER_H_
19 #define IMPL_HCI_DRIVER_H_
20 
21 #include <cstddef>
22 #include <cstdint>
23 #include "platform/Callback.h"
24 #include "ble/common/BLETypes.h"
25 #include "ble/driver/CordioHCITransportDriver.h"
26 #include "ble/common/blecommon.h"
27 
28 // FIXME: make this invisible!
29 #include "wsf_buf.h"
30 
31 namespace ble {
32 
33 /**
34  * Contain description of the memory pool used by the Cordio stack.
35  */
37  /**
38  * Create a new memory pool description
39  * @param buffer the Buffer used by the memory pool.
40  * @param pool_desc How the memory is split
41  */
42  template<size_t BufferSize, size_t PoolCount>
44  uint8_t (&buffer)[BufferSize],
45  const wsfBufPoolDesc_t (&pool_desc)[PoolCount]
46  ) : buffer_memory(buffer), buffer_size(BufferSize),
47  pool_description(pool_desc), pool_count(PoolCount)
48  {
49  }
50 
51  uint8_t* buffer_memory; /// Pointer to the buffer memory
52  size_t buffer_size; /// Size of the buffer
53  const wsfBufPoolDesc_t* pool_description; /// Pointer to the first element describing the pool
54  size_t pool_count; /// Number of pools
55 };
56 
57 /**
58  * Base class of the HCI driver use by the BLE port of the Cordio stack.
59  * This class provide to the stack:
60  * - The buffer necessary to run BLE API
61  * - The reset sequence of the BLE module
62  * - Access to the write function of the underlying HCITransport driver.
63  */
65 
66  // hook for internal tests and passthrough driver
67  friend class CordioHCIHook;
68 
69 public:
70  /**
71  * Construct a new instance of an HCI driver.
72  * @param transport_driver The driver used to communicate with the chip.
73  */
74  CordioHCIDriver(CordioHCITransportDriver& transport_driver);
75 
76  /**
77  * Driver destructor
78  */
79  virtual ~CordioHCIDriver() = default;
80 
81  /**
82  * Return the set of memory pool which will be used by the Cordio stack
83  */
84  virtual buf_pool_desc_t get_buffer_pool_description() = 0;
85 
86  /**
87  * Initialize the HCI driver.
88  * This function start by initializing the transport driver then it delegates
89  * what's remain of the initialization to the function do_initialize.
90  */
91  void initialize();
92 
93  /**
94  * Termination of the driver.
95  * It call in sequence:
96  * - do_terminate
97  * - terminate the transport driver.
98  */
99  void terminate();
100 
101  /**
102  * Start the reset sequence of the BLE module.
103  */
104  virtual void start_reset_sequence();
105 
106  /**
107  * Handle HCI messages received during the reset sequence.
108  *
109  * @param msg The HCI message received.
110  * @note The driver should signal to the stack that the initialization
111  * sequence is done by calling the function: signal_reset_sequence_done.
112  */
113  virtual void handle_reset_sequence(uint8_t *msg);
114 
115  /**
116  * Get the random static address of the controller
117  *
118  * @return false if the address has not been set and true otherwise.
119  */
120  virtual bool get_random_static_address(ble::address_t& address);
121 
122  /**
123  * Signal to the stack that the reset sequence has been done.
124  */
125  void signal_reset_sequence_done();
126 
127  /**
128  * Write data in the transport channel.
129  *
130  * @param type The type of packet to transmit. It might be an HCI command
131  * packet, ACL packet or EVT packet. Depending on the type of transport
132  * it can prefix the packet itself.
133  * @param len Number of bytes to transmit.
134  * @param pData pointer to the data to transmit.
135  *
136  * @return The number of bytes which have been transmited.
137  */
138  uint16_t write(uint8_t type, uint16_t len, uint8_t *pData);
139 
140  /**
141  * React to host stack inactivity.
142  *
143  * The host stack invoke this function when it is inactive. It allows a
144  * driver to put its controller to sleep if all the conditions are met.
145  *
146  * Any call to write signals to the driver that the host stack is active.
147  */
148  virtual void on_host_stack_inactivity();
149 
150  /* BLE Tester commands */
151 
152  /**
153  * This will be called by host part of the stack to indicate the end of the test.
154  *
155  * @param success True if the TEST END command was a success.
156  * @param packets Number of packets received during the test.
157  * @return BLE_ERROR_NONE on success.
158  */
159  void handle_test_end(bool success, uint16_t packets);
160 
161  /** Callback to inform the caller of the result of the test, the parameters are success and the
162  * number of packets received.
163  */
165 
166  /**
167  * Start BLE receiver test. Call rf_test_end when you want to stop.
168  * @param test_end_handler Handler that will be called with the number of packets received.
169  * @param channel Channel to use.
170  * @return BLE_ERROR_NONE on success.
171  */
172  ble_error_t rf_test_start_le_receiver_test(test_end_handler_t test_end_handler, uint8_t channel);
173 
174  /**
175  * Start BLE transmitter test. Call rf_test_end when you want to stop.
176  * @param test_end_handler Handler that will be called with status and the number of packets set to 0.
177  * @param channel Channel to use.
178  * @param length Size of payload.
179  * @param type Type of pattern to transmit @see BLE spec Volume 6 Part F, Section 4.1.5.
180  * @return BLE_ERROR_NONE on success.
181  */
182  ble_error_t rf_test_start_le_transmitter_test(test_end_handler_t test_end_handler, uint8_t channel,
183  uint8_t length, uint8_t type);
184 
185  /**
186  * Complete the test. This will trigger the end test event which will call handle_test_end
187  * @return BLE_ERROR_NONE on success.
188  */
189  ble_error_t rf_test_end();
190 
191  /**
192  * Set desired transmit power. Value equal or bigger will be used from available levels.
193  * Consult chip documentation for available values. Actual TX power is not guaranteed
194  * and is down to the implementation.
195  *
196  * @param level_db Signal level in dBm.
197  * @return BLE_ERROR_NONE on success.
198  */
199  virtual ble_error_t set_tx_power(int8_t level_db);
200 
201 protected:
202  /**
203  * Return a default set of memory pool that the Cordio stack can use.
204  * This function can be used to implement get_buffer_pool_description().
205  */
206  buf_pool_desc_t get_default_buffer_pool_description();
207 
208  /**
209  * Allows the driver to set a random static address. Unlike the HCI command
210  * this function reports the random static address to the whole BLE system.
211  * @param random_static_address The random static address to set.
212  */
213  void set_random_static_address(const ble::address_t& random_static_address);
214 
215 private:
216  /**
217  * Initialize the chip.
218  * The transport is up at that time.
219  */
220  virtual void do_initialize() = 0;
221 
222  /**
223  * Terminate the driver
224  */
225  virtual void do_terminate() = 0;
226 
227 protected:
228  test_end_handler_t _test_end_handler;
229 private:
230  CordioHCITransportDriver& _transport_driver;
231 };
232 
233 } // namespace ble
234 
235 #endif /* IMPL_HCI_DRIVER_H_ */
Contain description of the memory pool used by the Cordio stack.
Buffer pool descriptor structure.
Definition: wsf_buf.h:81
Base class of the HCI transport driver.
buf_pool_desc_t(uint8_t(&buffer)[BufferSize], const wsfBufPoolDesc_t(&pool_desc)[PoolCount])
Create a new memory pool description.
MAC address data type.
Buffer pool service.
Base class of the HCI driver use by the BLE port of the Cordio stack.
size_t buffer_size
Pointer to the buffer memory.
mbed::Callback< void(bool, uint16_t)> test_end_handler_t
Callback to inform the caller of the result of the test, the parameters are success and the number of...
size_t pool_count
Pointer to the first element describing the pool.
const wsfBufPoolDesc_t * pool_description
Size of the buffer.
Entry namespace for all BLE API definitions.
ble_error_t
Error codes for the BLE API.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.