You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by an...@apache.org on 2022/03/17 10:50:13 UTC
[mynewt-nimble] 03/22: nimble/doc: Add documentation for HCI transport
This is an automated email from the ASF dual-hosted git repository.
andk pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mynewt-nimble.git
commit bb32f04b702e4cbf6f02ccff60d2ba5c9f94ad14
Author: Andrzej Kaczmarek <an...@codecoup.pl>
AuthorDate: Mon Mar 7 14:50:51 2022 +0100
nimble/doc: Add documentation for HCI transport
---
nimble/doc/transport.md | 189 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 189 insertions(+)
diff --git a/nimble/doc/transport.md b/nimble/doc/transport.md
new file mode 100644
index 0000000..cd14993
--- /dev/null
+++ b/nimble/doc/transport.md
@@ -0,0 +1,189 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+-->
+
+# NimBLE HCI transport
+
+## Overview
+
+Transport is split into host (HS) and controller (LL) sides. Those do not
+necessarily represent actual host/controller, they can be just interfaces to
+external host (e.g. UART or USB) or controller (e.g.IPC to LL running on
+another core).
+
+```
++----------+ +----------+
+| cmd pool | | evt pool |
++----------+ +----------+
+| acl pool | | acl pool |
++----------+ +----------+
+ || ||
++----+ +----+
+| | <--- ble_transport_to_ll_acl ---- | |
+| | <--- ble_transport_to_ll_evt ---- | |
+| HS | | LL |
+| | ---- ble_transport_to_ll_cmd ---> | |
+| | ---- ble_transport_to_ll_acl ---> | |
++----+ +----+
+```
+
+HS side allocates buffers for HCI commands and ACL data from dedicated pools
+using `ble_transport_alloc_cmd` and `ble_transport_alloc_acl_from_hs` calls
+respectively, then sends them to LL side using `ble_transport_to_ll_cmd` and
+`ble_transport_to_ll_acl`.
+
+Similarly, LL side allocates buffers for HCI events and ACL data from dedicated
+pools using `ble_transport_alloc_evt` and `ble_transport_alloc_acl_from_ll`
+calls respectively, then sends them to HS side using `ble_transport_to_hs_evt`
+and `ble_transport_to_hs_acl`.
+
+Both HCI command and events buffers are freed using `ble_transport_free`, ACL
+data are freed as regular `os_mbuf`.
+
+Selecting `native` transport for either HS or LL side will use actual NimBLE
+host or controller respectively directly instead of transport implementation.
+Both NimBLE host and controller do not use decidated pools for ACL data and
+allocate data directly from msys pool - relevant ACL pools will be disabled
+automatically.
+
+Actual transport implementation for each side can be set using `BLE_TRANSPORT_HS`
+and `BLE_TRANSPORT_LL` syscfg for HS and LL sides respectively. Selecting
+transport in either direction will automatically add dependencies to required
+transport implementation packages, there's no need to do this manually.
+Selecting `native` transport for HS and/or LL side will automatically add
+dependencies to NimBLE host and/or controller packages.
+
+The order of initialization is defined as follows:
+- `ble_transport_init` - generic transport initialization
+- `ble_transport_hs_init` - HS side initialization
+- `ble_transport_ll_init` - LL side initialization
+
+Initialization functions for HS and LL sides shall be implemented by transport
+implementation. There's no need to define those functions as sysinit stages
+since this is already done by generic transport implementation along with
+proper dependencies.
+
+
+## Application configuration
+
+To ensure that application can be easily run on different BSPs, it's strongly
+recommended not to put hard dependencies to any transport in `pkg.yml` and
+use automatic dependencies instead. That means an application that uses NimBLE
+host should only include `nimble/host` in its dependencies (i.e. no direct
+dependency to `nimble/controler` or any transport implementation). This will
+pull `nimble/transport` automatically, force `BLE_TRANSPORT_HS: native` and
+allow changing LL side using `BLE_TRANSPORT_LL` to any supported controller.
+
+
+## Multicore SoCs
+
+On multicore SoCs with dedicated application and network cores (e.g. nRF5340,
+DA1469x) NimBLE host and controller will run on different cores. In such setup
+application core uses LL transport implementation instead of an actual NimBLE
+controller and similarly network core uses HS transport implementation instead
+of NimBLE host. Both sides of transport implementation are provided by the same
+transport, e.g. `nrf5340` for nRF5340 or `dialog_cmac` for DA1469x, and exchange
+data via IPC. This process is transparent from application point of view,
+assuming it's properly configured (see above).
+
+```
+ Application core | Network core
++----+ +----+ | +----+ +----+
+| | | LL | | | HS | | |
+| | <- acl/evt -- | | | | | <- acl/evt -- | |
+| HS | | tr | <- ipc -> | tr | | LL |
+| | -- cmd/acl -> | an | | | an | -- cmd/acl -> | |
+| | | sp | | | sp | | |
++----+ +----+ | +----+ +----+
+```
+
+
+## Build configurations
+
+### Combined build
+
+This setup runs both NimBLE host and controller on the same core. It's a typical
+configuration when running application on SoCs like nRF51 or nRF52.
+
+Note: this is the default configuration, no need to set it explicitly.
+
+```yaml
+BLE_TRANSPORT_HS: native
+BLE_TRANSPORT_LL: native
+```
+
+### Controller-only build
+
+This setup makes NimBLE controller accessible to external host connected via
+e.g. UART or USB, so it can be used as an external Bluetooth LE controller.
+The controller runs on the same core as external interface. It's typically
+used with `blehci` application running on SoCs like nRF51 or nRF52.
+
+```yaml
+BLE_TRANSPORT_HS: uart
+BLE_TRANSPORT_LL: native
+```
+
+
+### Multicore build
+
+This is a variant of combined build but with NimBLE host and controller running
+on different cores, like e.g. nRF5340 or DA1469x. Application core can run
+any application while network core runs `blehci`.
+
+Note: BSPs for nRF5340 and DA1469x will automatically select proper transport
+ for LL side if NimBLE host or transport is included in build, so usually
+ there's no need to configure manually.
+
+#### Application core
+```yaml
+BLE_TRANSPORT_HS: native
+BLE_TRANSPORT_LL: dialog_cmac
+```
+
+#### Network core
+```yaml
+BLE_TRANSPORT_HS: dialog_cmac
+BLE_TRANSPORT_LL: native
+```
+
+
+### Bridge build
+
+This is a variant of controller-only build but with NimBLE controller running
+on different core than external interface used to access it, like e.g. nRF5340
+or DA1469x. In this setup both cores run `blehci` application.
+
+Note: BSPs for nRF5340 and DA1469x will automatically select proper transport
+ for LL side if NimBLE host or transport is included in build, so usually
+ there's only need to select required transport for external interface on
+ application core.
+
+#### Application core
+```yaml
+BLE_TRANSPORT_HS: uart
+BLE_TRANSPORT_LL: nrf5340
+```
+
+#### Network core
+```yaml
+BLE_TRANSPORT_HS: nrf5340
+BLE_TRANSPORT_LL: native
+```