From 3b95202154b04deca0d53705bb8d7cd12e55afb8 Mon Sep 17 00:00:00 2001 From: Melinda Weed Date: Tue, 14 Aug 2018 10:55:39 +0300 Subject: [PATCH] Final review and grammatical changes --- .../targets/TARGET_CORDIO/doc/PortingGuide.md | 43 ++++++++----------- 1 file changed, 18 insertions(+), 25 deletions(-) diff --git a/features/FEATURE_BLE/targets/TARGET_CORDIO/doc/PortingGuide.md b/features/FEATURE_BLE/targets/TARGET_CORDIO/doc/PortingGuide.md index ee758a8bec..2b8c0abc3f 100644 --- a/features/FEATURE_BLE/targets/TARGET_CORDIO/doc/PortingGuide.md +++ b/features/FEATURE_BLE/targets/TARGET_CORDIO/doc/PortingGuide.md @@ -41,17 +41,18 @@ Include an HCI driver for the BLE module used by the target, and a factory funct 1. Navigate to the folder of the BLE API that hosts the target port `features/FEATURE_BLE/targets`. -1. Create a folder containing the port code to isolate it from other code. Begin this folder's name with `TARGET_` and the rest of the name in capital letters. +1. Create a folder containing the port code to isolate it from other code. + * Begin this folder's name with `TARGET_` and the rest of the name in capital letters. #### Create the HCI driver -The HCI driver is split in two entities. One handles HCI communication with the Bluetooth module. The other handles initialization, reset sequence, and memory dedicated to the Bluetooth controller. +The HCI driver is split into two entities. One handles HCI communication with the Bluetooth module. The other handles the initialization, reset sequence, and memory dedicated to the Bluetooth controller. More information about the architecture can be found in [HCI abstraction architecture](HCIAbstraction.md). #### HCITransport -**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. +**Note:** If the Bluetooth controller uses an H4 communication interface and the host exposes serial flow control in Mbed, you can skip this step. Use the class `ble::vendor::cordio::H4TransportDriver` as the transport driver. To code an empty transport driver: @@ -85,9 +86,11 @@ private: It inherits publicly from the base class `CordioHCITransportDriver`. +##### Functions + * **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` 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 you implement, you may need to send the packet `type` to the controller before the packet data. +* **Sending data**: The function `write` sends data as input to the Bluetooth controller and returns the number of bytes in the `data` buffer sent. Depending on the type of transport you implement, you may need to send the packet `type` to the controller before the packet data. * **Receiving data**: Inject HCI data from the Bluetooth controller to the system by calling `on_data_received`. This is a static function provided by the base class. @@ -239,20 +242,17 @@ 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 - // controller for the host. + // 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 - // the controller for the host. + // 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 - // controller for the host (2nd page of flags). + // 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; @@ -277,24 +277,20 @@ 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 - // layer of the controller. + // 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 - // of the stack. + // 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 - // controller. + // 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 - // parameters. + // Store the number of whitelist entries in the stack runtime parameters. BSTREAM_TO_UINT8(hciCoreCb.whiteListSize, pMsg); // Read the LE features supported by the controller. @@ -305,18 +301,15 @@ 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 - // stored in the controller resolving list. + // 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 - // runtime parameter. + // 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 - // duration times for transmission and reception. + // Read the Controller’s maximum supported payload octets and packet duration times for transmission and reception. hciCoreReadMaxDataLen(); break; @@ -450,7 +443,7 @@ ble::vendor::cordio::CordioHCIDriver& ble_cordio_get_hci_driver() { ### Tests -We bundle Greentea tests with the Cordio port of the BLE API, so the transport driver works, as well as validation of Cordio stack initialization. You can run these tests with the following command: +We bundle Greentea tests with the Cordio port of the BLE API, so the transport driver and validation of Cordio stack initialization both work. You can run these tests with the following command: ``` mbed test -t -m -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