ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Remove shall, whole lotta other changes. Not done yet.

pull/7417/head
Melinda Weed 2018-07-09 15:06:11 +03:00
parent 7a8cc0243f
commit bae4c89d0f
1 changed files with 133 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

282
features/FEATURE_BLE/targets/TARGET_CORDIO/doc/PortingGuide.md
View File

@ -1,91 +1,94 @@
# Porting guide
# Porting guide
Enabling the mbed BLE Cordio port for a given target is a two step process:
* The target shall be configured to include Cordio BLE port and Cordio libraries
during the build process.
* An implementation of the `CordioHCIDriver` class targeting the bluetooth
controller used shall be provided.
There are two main steps to enable the Mbed BLE Cordio port for a given target:
## Target configuration
1. Configure the target to include Cordio BLE port and Cordio libraries
during the build process.
This step happens in the file defining all mbed os targets. The file is located
in `targets/target.json`.
1. Implement `CordioHCIDriver` class targeting the Bluetooth controller.
### Add BLE feature
[[[Do we want something like this at the beginning? Why not just give the steps, instead of summarizing them?]]]
First of all support for BLE has to be added to the target. This is achieved by
adding the string `BLE` in the list of `features` of the target. Once this
value has been added the sources of BLE api are added to the list of sources
compiled for the target.
## Configure the target
```json
Define all Mbed OS targets in the `targets/target.json` file:
* Add BLE support to the target:
* Add the string `BLE` to the target's list of `features`. This adds the BLE API sources to the list of sources compiled for the target.
```
"TARGET_NAME": {
"features": ["target features ...", "BLE"]
}
```
### Include Cordio BLE implementation
### Include Cordio BLE implementation
The target should also compile the sources of the BLE Cordio port. It is
achieved by adding the string `CORDIO` in the list of the `extra_labels`
property of the target.
* Compile the BLE Cordio port sources:
```json
[[[sources?]]]
* Add the string `CORDIO` to the `extra_labels` property of the JSON file.
```
"TARGET_NAME": {
"extra_labels": ["target extra labels ...", "CORDIO"],
"features": ["target features ...", "BLE"]
}
```
## CordioHCIDriver implementation:
## Implement CordioHCIDriver:
A port shall include an HCI driver for the BLE module used by the target and
a factory function which create the BLE instance used by the user of BLE API.
Include an HCI driver for the BLE module used by the target and a factory function which creates the BLE instance used by the user of the BLE API.
### Create source folder
### Create source folder
The port shall live in the folder of BLE API which host targets port :
`features/FEATURE_BLE/targets`.
Create a `TARGET_<target name>` folder.
To isolate the port code from other code a folder containing the port code has
to be created. The name of this folder shall start with `TARGET_` and end with
The port shall live in the folder of BLE API which host targets port :
`features/FEATURE_BLE/targets`.
You need to create a folder containing the port code to isolate it from other code. Name
To isolate the port code from other code, a folder containing the port code has
to be created. The name of this folder shall start with `TARGET_` and end with
the target name in capital.
### Create the HCI driver
The HCI driver is split in two entities: one which handle HCI communication with
the Bluetooth module and the other handling the initialization, reset sequence
The HCI driver is split in two entities: one which handle HCI communication with
the Bluetooth module and the other handling the initialization, reset sequence
and memory dedicated for the Bluetooth controller.
More information about the architecture can be found in the
More information about the architecture can be found in the
[HCI abstraction architecture](HCIAbstraction.md) document.
#### HCITransport
#### HCITransport
> **Note:** If the Bluetooth controller uses an H4 communication interface and
the host exposes serial flow control in mbed then this step can be skipped and
the class `ble::vendor::cordio::H4TransportDriver` can be used as the transport
driver.
<span class="notes">**Note:** If the Bluetooth controller uses an H4 communication interface and
the host exposes serial flow control in Mbed, then you can skip this step. Use the class `ble::vendor::cordio::H4TransportDriver` as the transport
driver.</span>
An empty transport driver can be coded as:
You can code an empty transport driver as:
```c++
```
#include "CordioHCITransportDriver.h"
namespace ble {
namespace ble {
namespace vendor {
namespace target_name {
namespace target_name {
class TransportDriver : public cordio::CordioHCITransportDriver {
public:
class TransportDriver : public cordio::CordioHCITransportDriver {
public:
TransportDriver(/* specific constructor arguments*/);
virtual ~TransportDriver();
virtual void initialize();
virtual void terminate();
virtual void terminate();
virtual uint16_t write(uint8_t packet_type, uint16_t len, uint8_t *data);
private:
@ -97,40 +100,42 @@ private:
} // namespace ble
```
It shall inherits publicly from the base class `CordioHCITransportDriver`.
It inherits publicly from the base class `CordioHCITransportDriver`.
* **Initialization/termination:** The functions `initialize` and `terminate` are
responsible for initializing and terminating the transport driver. It is not
[[[still don't know what this means]]]
* **Initialization/termination:** The functions `initialize` and `terminate` are
responsible for initializing and terminating the transport driver. It is not
necessary to initialize the transport in the constructor.
* **Sending data** The function `write` shall sends data in input to the
Bluetooth controller and return the number of bytes in the `data` buffer sent.
Depending on the type of transport being implemented, the packet `type` might
* **Sending data** The function `write` shall sends data in input to the
Bluetooth controller and return the number of bytes in the `data` buffer sent.
Depending on the type of transport being implemented, the packet `type` might
have to be sent to the controller before the packet data.
* **Receiving data**: HCI data from the Bluetooth controller shall be injected
in the system by invoking the function `on_data_received`. This function is
a static one and is provided by the base class. Its prototype is:
* **Receiving data**: HCI data from the Bluetooth controller shall be injected
in the system by invoking the function `on_data_received` injects . This function is
a static one and is provided by the base class. Its prototype is:
```c++
```
void on_data_received(uint8_t* data_received, uint16_t length_of_data_received);
```
#### HCIDriver
#### HCIDriver
The skeleton of driver is:
The skeleton of driver is:
```c++
```
#include "CordioHCIDriver.h"
namespace ble {
namespace ble {
namespace vendor {
namespace target_name {
namespace target_name {
class HCIDriver : public cordio::CordioHCIDriver {
public:
class HCIDriver : public cordio::CordioHCIDriver {
public:
HCIDriver(
cordio::CordioHCITransportDriver& transport_driver,
cordio::CordioHCITransportDriver& transport_driver,
/* specific constructor arguments*/
);
@ -144,7 +149,7 @@ public:
virtual void start_reset_sequence();
virtual void handle_reset_sequence(uint8_t *msg);
virtual void handle_reset_sequence(uint8_t \*msg);
private:
// private driver declarations
};
@ -154,21 +159,16 @@ private:
} // namespace ble
```
##### Initialization process
##### Initialization process
The initialization/termination process is achieved by the couple of functions
`do_initialize` and `do_terminate`. Those function manages the state of the
bluetooth controller.
The functions `do_initialize` and `do_terminate` handle initialization and termination processes. These functions manage the state of the Bluetooth controller.
> **Important:** It is unnecessary to initialize or terminate the hci transport
in those function because it is handled by the base class. The HCI transport is
initialized right before the call to `do_initialize` and is terminated right
after the call to `do_terminate`.
<span class="notes">**Note:** It is unnecessary to initialize or terminate the HCI transport in those function because it is handled by the base class. The HCI transport is initialized right before the call to `do_initialize` and is terminated right
after the call to `do_terminate`.</span>
##### Memory pool
##### Memory pool
The implementation of the function `get_buffer_pool_description` in the base
class will return a buffer of 1040 bytes divided in different memory pools:
The function `get_buffer_pool_description` in the base class returns a buffer of 1040 bytes divided in different memory pools:
| Chunk size (bytes) | Number of chunks |
|--------------------|------------------|
@ -178,11 +178,11 @@ class will return a buffer of 1040 bytes divided in different memory pools:
| 128 | 2 |
| 272 | 1 |
A port shall override this function if the memory provided by the base class
doesn't match what is required by the Bluetooth controller driven.
A port overrides this function if the memory provided by the base class
doesn't match what is required by the Bluetooth controller driver.
```c++
buf_pool_desc_t CordioHCIDriver::get_buffer_pool_description() {
```
buf_pool_desc_t CordioHCIDriver::get_buffer_pool_description() {
static uint8_t buffer[/* buffer size */];
static const wsfBufPoolDesc_t pool_desc[] = {
{ /* chunk size */, /* number of chunks */ },
@ -195,70 +195,70 @@ buf_pool_desc_t CordioHCIDriver::get_buffer_pool_description() {
};
return buf_pool_desc_t(buffer, pool_desc);
}
}
```
##### Reset sequence
##### Reset sequence
The reset sequence process is handled by three functions:
The reset sequence process is handled by three functions:
* `start_reset_sequence`: This function start the process. The basic
implementation sends an HCI reset command to the Bluetooth controller. The
* `start_reset_sequence`: This function start the process. The basic
implementation sends an HCI reset command to the Bluetooth controller. The
function shall be overridden in the driver if the bluetooth controller requires
more than just sending the standard reset command.
more than just sending the standard reset command.
* `handle_reset_sequence`: Entry point to the state machine handling the reset
process. Every time an HCI packet is received during the reset sequence, this
function is called with the HCI packet received. It's purpose is to prepare the
process. Every time an HCI packet is received during the reset sequence, this
function is called with the HCI packet received. Its purpose is to prepare the
Bluetooth controller and set the parameters the stack needs to operate properly.
This function can be overridden if necessary.
* `signal_reset_sequence_done`: This function shall be called once the reset
* `signal_reset_sequence_done`: This function shall be called once the reset
sequence is achieved. It cannot be overridden.
###### Controller parameters to set
###### Controller parameters to set
This instruct the controller which events are relevant for the stack.
The following parameters should be set in the controller (if supported):
* event mask: The reset sequence should issue the call
The following parameters should be set in the controller (if supported):
* event mask: The reset sequence should issue the call
`HciSetEventMaskCmd((uint8_t *) hciEventMask)`
* LE event mask: The call `HciLeSetEventMaskCmd((uint8_t *) hciLeEventMask)`
* LE event mask: The call `HciLeSetEventMaskCmd((uint8_t *) hciLeEventMask)`
should be issued.
* 2nd page of events mask: Can be achieved by invoking
* 2nd page of events mask: Can be achieved by invoking
`HciSetEventMaskPage2Cmd((uint8_t *) hciEventMaskPage2)`.
###### Stack runtime parameters
Some stack parameters shall be acquired at runtime from the controller:
Some stack parameters shall be acquired at runtime from the controller:
* Bluetooth address: Can be queried with `HciReadBdAddrCmd`. Response shall be
* Bluetooth address: Can be queried with `HciReadBdAddrCmd`. Response shall be
copied into `hciCoreCb.bdAddr` with `BdaCpy`.
* Buffer size of the controller: Can be obtained by `HciLeReadBufSizeCmd`. The
return parameter *HC_ACL_Data_Packet_Length* shall be copied into
`hciCoreCb.bufSize` and the response parameter
`HC_Synchronous_Data_Packet_Length`shall be copied into `hciCoreCb.numBufs`.
* Buffer size of the controller: Can be obtained by `HciLeReadBufSizeCmd`. The
return parameter *HC_ACL_Data_Packet_Length* shall be copied into
`hciCoreCb.bufSize` and the response parameter
`HC_Synchronous_Data_Packet_Length` shall be copied into `hciCoreCb.numBufs`.
The value of `hciCoreCb.availBufs` shall be initialized with `hciCoreCb.numBufs`.
* Supported state: Queried with `HciLeReadSupStatesCmd`, the response shall go
* Supported state: Queried with `HciLeReadSupStatesCmd`, the response shall go
into `hciCoreCb.leStates`.
* Whitelist size: Queried with `HciLeReadWhiteListSizeCmd` the response shall go
into `hciCoreCb.whiteListSize`.
* LE features supported: Obtained with `HciLeReadLocalSupFeatCmd`. The response
* LE features supported: Obtained with `HciLeReadLocalSupFeatCmd`. The response
shall be stored into `hciCoreCb.leSupFeat`.
* Resolving list size: Obtained with `hciCoreReadResolvingListSize`. The response
shall go into `hciCoreCb.resListSize`.
* Max data length: Acquired with `hciCoreReadMaxDataLen`. The response parameter
`supportedMaxTxOctets` and `supportedMaxTxTime` shall be pass to the function
`supportedMaxTxOctets` and `supportedMaxTxTime` shall be pass to the function
`HciLeWriteDefDataLen`.
The default implementation is:
The default implementation is:
```c++
void HCIDriver::handle_reset_sequence(uint8_t *pMsg) {
// only accept command complete event:
if (*pMsg != HCI_CMD_CMPL_EVT) {
```
void HCIDriver::handle_reset_sequence(uint8_t *pMsg) {
// only accept command complete event:
if (*pMsg != HCI_CMD_CMPL_EVT) {
return;
}
@ -277,30 +277,30 @@ void HCIDriver::handle_reset_sequence(uint8_t *pMsg) {
case HCI_OPCODE_RESET:
/* initialize rand command count */
randCnt = 0;
// set the event mask to control which events are generated by the
// set the event mask to control which events are generated by the
// controller for the host
HciSetEventMaskCmd((uint8_t *) hciEventMask);
break;
case HCI_OPCODE_SET_EVENT_MASK:
// set the event mask to control which LE events are generated by
// set the event mask to control which LE events are generated by
// the controller for the host
HciLeSetEventMaskCmd((uint8_t *) hciLeEventMask);
break;
case HCI_OPCODE_LE_SET_EVENT_MASK:
// set the event mask to control which events are generated by the
// set the event mask to control which events are generated by the
// controller for the host (2nd page of flags )
HciSetEventMaskPage2Cmd((uint8_t *) hciEventMaskPage2);
break;
case HCI_OPCODE_SET_EVENT_MASK_PAGE2:
// Ask the Bluetooth address of the controller
// Ask the Bluetooth address of the controller
HciReadBdAddrCmd();
break;
case HCI_OPCODE_READ_BD_ADDR:
// Store the Bluetooth address in the stack runtime parameter
// Store the Bluetooth address in the stack runtime parameter
BdaCpy(hciCoreCb.bdAddr, pMsg);
// Read the size of the buffer of the controller
@ -315,23 +315,23 @@ void HCIDriver::handle_reset_sequence(uint8_t *pMsg) {
/* initialize ACL buffer accounting */
hciCoreCb.availBufs = hciCoreCb.numBufs;
// read the states and state combinations supported by the link
// read the states and state combinations supported by the link
// layer of the controller
HciLeReadSupStatesCmd();
break;
case HCI_OPCODE_LE_READ_SUP_STATES:
// store supported state and combination in the runtime parameters
// store supported state and combination in the runtime parameters
// of the stack
memcpy(hciCoreCb.leStates, pMsg, HCI_LE_STATES_LEN);
// read the total of whitelist entries that can be stored in the
// read the total of whitelist entries that can be stored in the
// controller.
HciLeReadWhiteListSizeCmd();
break;
case HCI_OPCODE_LE_READ_WHITE_LIST_SIZE:
// store the number of whitelist entries in the stack runtime
// store the number of whitelist entries in the stack runtime
// parameters
BSTREAM_TO_UINT8(hciCoreCb.whiteListSize, pMsg);
@ -343,17 +343,17 @@ void HCIDriver::handle_reset_sequence(uint8_t *pMsg) {
// Store the set of LE features supported by the controller
BSTREAM_TO_UINT16(hciCoreCb.leSupFeat, pMsg);
// read the total number of address translation entries which can be
// read the total number of address translation entries which can be
// stored in the controller resolving list.
hciCoreReadResolvingListSize();
break;
case HCI_OPCODE_LE_READ_RES_LIST_SIZE:
// store the number of address translation entries in the stack
// store the number of address translation entries in the stack
// runtime parameter
BSTREAM_TO_UINT8(hciCoreCb.resListSize, pMsg);
// read the Controller’s maximum supported payload octets and packet
// read the Controller’s maximum supported payload octets and packet
// duration times for transmission and reception
hciCoreReadMaxDataLen();
break;
@ -392,11 +392,11 @@ void HCIDriver::handle_reset_sequence(uint8_t *pMsg) {
HciLeRandCmd();
}
break;
case HCI_OPCODE_LE_READ_MAX_ADV_DATA_LEN:
case HCI_OPCODE_LE_READ_NUM_SUP_ADV_SETS:
case HCI_OPCODE_LE_READ_PER_ADV_LIST_SIZE:
// handle extended command
// handle extended command
if (hciCoreCb.extResetSeq)
{
/* send next extended command in sequence */
@ -462,21 +462,21 @@ static void hciCoreReadResolvingListSize(void)
### HCI accessor function
The HCI driver is injected in the `CordioBLE` class at construction site.
Given that the CordioBLE class doesn't know what class shall be used to
construct the driver nor it knows how to construct it, the port shall provide a
function returning a reference to the HCI driver.
The HCI driver is injected in the `CordioBLE` class at construction site.
Given that the CordioBLE class doesn't know what class shall be used to
construct the driver nor it knows how to construct it, the port shall provide a
function returning a reference to the HCI driver.
This function lives in the global namespace and its signature is:
This function lives in the global namespace and its signature is:
```c++
```
ble::vendor::cordio::CordioHCIDriver& ble_cordio_get_hci_driver();
```
A common implementation might be:
A common implementation might be:
```c++
ble::vendor::cordio::CordioHCIDriver& ble_cordio_get_hci_driver() {
```
ble::vendor::cordio::CordioHCIDriver& ble_cordio_get_hci_driver() {
static ble::vendor::target_name::TransportDriver transport_driver(
/* transport parameters */
);
@ -491,36 +491,20 @@ ble::vendor::cordio::CordioHCIDriver& ble_cordio_get_hci_driver() {
### Tests
Greentea tests are bundled with the cordio port of BLE API to ensure that the transport driver works as expected as well as validate the cordio stack initialization. You can run them with the following command:
Greentea tests are bundled with the Cordio port of the BLE API so the transport driver works as expected as well as validate the Cordio stack initialization. You can run them with the following command:
```
mbed test -t <toolchain> -m <target> -n mbed-os-features-feature_ble-targets-target_cordio-tests-cordio_hci-driver,mbed-os-features-feature_ble-targets-target_cordio-tests-cordio_hci-transport
```
* mbed-os-features-feature_ble-targets-target_cordio-tests-cordio_hci-transport: Ensure that the transport is able to send an HCI reset command and receive the corresponding HCI status event.
* mbed-os-features-feature_ble-targets-target_cordio-tests-cordio_hci-driver: Runs the whole initialization process then ensure the cordio stack has been properly initialized by the HCI driver.
* `mbed-os-features-feature_ble-targets-target_cordio-tests-cordio_hci-transport`: Ensures that the transport is able to send an HCI reset command and receive the corresponding HCI status event.
* `mbed-os-features-feature_ble-targets-target_cordio-tests-cordio_hci-driver`: Runs the whole initialization process then ensure the Cordio stack has been properly initialized by the HCI driver.
### Tools
The application [mbed-os-cordio-hci-passthrough](https://github.com/ARMmbed/mbed-os-cordio-hci-passthrough) can be used to _proxify_ a Bluetooth controller connected to an mbed board.
The application [mbed-os-cordio-hci-passthrough](https://github.com/ARMmbed/mbed-os-cordio-hci-passthrough) can be used to _proxify_ a Bluetooth controller connected to an Mbed board.
Bytes sent by the host over the board serial are forwarded to the controller with the help of the `HCITransportDriver` while bytes sent by the controller are sent back to the host through the board serial.
This application can be used to validate the transport driver and debug the initialization process on a PC host.