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