pal/jieli: Add the br23 BLE Host provider

[idy]

Background

GizOS already owns the AC695N (br23) JieLi platform, pi32v2 toolchain, repository-owned native project, generic reference firmware, and native_component_src/jieli/br23/h2_pal_core. BLE remains unsupported in the public br23 composition.

The pinned AC695N SDK exposes a BTstack-derived LE host surface through public headers and exported symbols: legacy advertising and connection control, ATT/GATT server callbacks and notify/indicate, MTU and connection updates, Security Manager events, and the LE device database. This is sufficient to implement the peripheral subset of the current h2_pal_ble.h contract without depending on SDK demo code or private HCI entry points.

Goal

Add a reusable JieLi br23 BLE Host provider for the current PAL contract. It must implement start/stop, legacy advertising-set lifecycle, peripheral connections, GATT server registration and access routing, notify/indicate, MTU and connection updates, explicit pairing configuration, bonding cleanup, deterministic event delivery, and teardown. Host tests use a fake SDK port, while the generic AC695N reference firmware proves native SDK composition and symbol linkage.

Non-goals

• Do not add board, product, provisioning, application protocol, service UUID, device-name, passkey, or persistent identity policy.
• Do not claim radio interoperability, RF performance, phone compatibility, or device-level acceptance from the generic reference target.
• Do not implement Classic Bluetooth, A2DP, HFP, SPP, TWS, a replacement host stack, or private HCI controller entry points.
• Do not implement central scanning/GATT-client capability, Extended Advertising, multiple advertising sets, or LE Coded PHY when the SDK host surface cannot satisfy the contract; return explicit unsupported results.
• Do not change the portable BLE PAL contract or add AC791N support.
• Do not add H2Loader transport, flashing, or downstream product workflows.

Code Changes Tree

native_component_src/jieli/br23/h2_pal_ble/BUILD.bazel                                 # define the native provider, host-fake library, and deterministic host test targets
native_component_src/jieli/br23/h2_pal_ble/include/h2_jieli_br23_ble.h                 # declare provider configuration, construction, lifecycle, and BLE Host PAL access
native_component_src/jieli/br23/h2_pal_ble/include/h2_jieli_br23_ble_sdk_port.h        # declare the minimal SDK-independent LE host, ATT, GATT, SM, and bond-store port
native_component_src/jieli/br23/h2_pal_ble/src/h2_jieli_br23_ble_sdk_port.c            # bind the port to the pinned SDK public BLE host APIs and normalize callback events
native_component_src/jieli/br23/h2_pal_ble/src/h2_jieli_br23_platform_ble.c             # implement Host lifecycle, advertising, connection state, event dispatch, MTU, PHY, and update operations
native_component_src/jieli/br23/h2_pal_ble/src/h2_jieli_br23_ble_gatt.c                 # map PAL service definitions to ATT handles and route read, write, notify, indicate, and CCC state
native_component_src/jieli/br23/h2_pal_ble/src/h2_jieli_br23_ble_pairing.c              # implement explicit pairing policy, SM event mapping, bond enumeration, and bond deletion
native_component_src/jieli/br23/h2_pal_ble/tests/include/h2_jieli_br23_ble_sdk_fake.h   # expose deterministic connection, ATT, MTU, pairing, buffer, and failure injection controls
native_component_src/jieli/br23/h2_pal_ble/tests/src/h2_jieli_br23_ble_sdk_fake.c       # implement the host fake and serialized SDK callback event source
native_component_src/jieli/br23/h2_pal_ble/tests/src/test_jieli_br23_ble.c              # cover advertising, GATT, connection, pairing, timeout, disconnect, unsupported, and teardown behavior
boards/ac695n_chip/ac695n/layouts/compile_only/include/app_config.h                     # enable only the SDK LE host facilities required to compile and link the public provider
boards/ac695n_chip/ac695n/layouts/compile_only/project.mk                               # add the exact public SDK BLE sources, headers, archives, and linker inputs required by the provider
projects/e2e/apps/pal/app/BUILD.bazel                                                   # compile the reusable BLE E2E suite and its host tests into the public PAL E2E package
projects/e2e/apps/pal/app/include/h2_pal_e2e.h                                          # add BLE suite and case identifiers plus board-neutral peer-driven configuration
projects/e2e/apps/pal/app/src/h2_pal_ble_e2e.h                                          # declare the reusable BLE E2E runner interface
projects/e2e/apps/pal/app/src/h2_pal_ble_e2e.c                                          # exercise advertise, connect, GATT write, notify, MTU, pairing, disconnect, and cleanup through PAL only
projects/e2e/apps/pal/app/src/h2_pal_e2e.c                                              # register BLE cases without assuming that every target provides BLE
projects/e2e/apps/pal/app/tests/test_h2_pal_ble_e2e.c                                   # verify timeouts, peer-absent SKIP, event matching, cleanup, and unsupported-provider behavior
projects/e2e/targets/jieli_firmware/reference-smoke/ac695n_reference/BUILD.bazel         # add the br23 BLE provider to the generic native link graph
projects/e2e/targets/jieli_firmware/reference-smoke/ac695n_reference/src/reference_launcher.c # construct a compile-only provider configuration and retain a link probe without claiming radio success
guides/zh/developing/components.md                                                      # list the new public br23 BLE component in the component inventory
guides/zh/developing/components/jieli.md                                                # document capability mapping, event context, unsupported operations, SDK boundary, and validation limits

Design

Provider and SDK boundary

h2_jieli_br23_ble_sdk_port.c is the only provider translation unit that includes JieLi LE host headers. It translates SDK packet callbacks into provider-owned typed events. Advertising, connection tables, ATT handle mapping, Security Manager state, timeout handling, and cleanup depend only on the minimal port so host tests execute production state machines.

Construction receives explicit capacity limits and storage required by the SDK host. It does not embed application UUIDs, names, passkeys, identity records, or product policy. SDK demo sources are reference evidence only and are not compiled.

Peripheral and GATT behavior

The provider exposes one legacy advertising set through both the compatibility operations and handle-scoped advertising-set API. Unsupported set counts or Extended Advertising inputs fail explicitly. Start/stop and set destruction are idempotent at stable boundaries and preserve handle ownership through asynchronous completion.

PAL GATT service definitions are converted into a deterministic ATT database before Host start or at the documented disconnected rebuild boundary. Read and write callbacks receive borrowed storage only during dispatch. Notify returns backpressure without hidden retries; indicate waits for the matching confirmation or a bounded timeout. Disconnect clears connection-scoped CCC state and pending sends.

Pairing and events

Pairing is disabled until the caller provides an explicit PAL pairing configuration. Security Manager events map to PAL system events without silently downgrading Secure Connections or MITM requirements. Bond enumeration and deletion use the SDK LE device database while application identity policy remains outside the provider.

SDK callbacks execute on the BLE task. The provider documents callback context, performs no unbounded work or allocation in the callback, serializes lifecycle transitions, and guarantees that stop removes callbacks and releases state before returning. Late events after stop are ignored safely.

Public validation boundary

Host tests prove the state machines with a deterministic fake. The generic AC695N reference firmware proves that the pinned SDK headers, archives, configuration, symbols, and provider graph link. The reusable BLE E2E suite is peer-driven and reports missing peer actions as SKIP rather than PASS; actual radio and phone interoperability belong to a board-owned consumer.

Test And Acceptance Criteria

Acceptance Criteria

• The public br23 BLE provider implements the documented peripheral subset of the current h2_pal_ble_vtable_t; every unsupported operation returns a stable explicit result.
• Host tests cover advertising encoding/lifecycle, connection/disconnection, GATT handle mapping, offset reads/writes, CCC state, notify backpressure, indicate confirmation/timeout, MTU, connection update, pairing success/rejection, bond cleanup, late events, repeated stop, and allocation cleanup.
• SDK headers are isolated to the SDK-port translation unit; provider logic and tests build on Linux, macOS, and Windows host configurations.
• The generic AC695N reference firmware links the provider through the pinned SDK and repository-owned native project without compiling an SDK demo application.
• The public BLE E2E suite uses only PAL plus caller/peer input and records absent or incomplete peer interaction as SKIP or FAIL, never PASS.
• Public component and JieLi guides document supported and unsupported operations, callback context, lifecycle, pairing boundary, and host/link-only validation boundary.

Validation

bazel mod deps --lockfile_mode=error
bazel test --config=linux_x86_64 //native_component_src/jieli/br23/h2_pal_ble/... //projects/e2e/apps/pal/app/...
bazel test --config=macos_arm64 //native_component_src/jieli/br23/h2_pal_ble/... //projects/e2e/apps/pal/app/...
bazel test --config=windows_x86_64 //native_component_src/jieli/br23/h2_pal_ble/... //projects/e2e/apps/pal/app/...
. ../firmwares-devenv/export.sh
bazel build --config=ac695n //projects/e2e/targets/jieli_firmware/reference-smoke/ac695n_reference:firmware
bazel build --config=ac695n //...
make bazel-test-downstream-consumer
make guides-build
git diff --check

• Record the exact pinned AC695N SDK identity and native-link result.
• Mark radio discovery, phone interoperability, negotiated timing/MTU, pairing UX, and reconnect validation DEVICE_ONLY; none is required to establish the public provider's host semantics and native linkability.