docs(standards): binder runtime layering, bitness & kernel requirements (#662) - #663
Closed
Ulrond wants to merge 4 commits into
Closed
docs(standards): binder runtime layering, bitness & kernel requirements (#662)#663Ulrond wants to merge 4 commits into
Ulrond wants to merge 4 commits into
Conversation
…ts (#662) Document the MW/vendor binder architecture: each layer builds and ships its own bitness-matched libbinder (MW 32-bit via TARGET_LIB32_VERSION, vendor at its own bitness) and they communicate over the kernel binder driver (IPC), which bridges 32/64 — because in-process linking cannot cross ELF bitness. Covers the bitness rule, kernel config/device-node (binderfs >=5.0 vs static), 32-bit-userspace-on-64-bit-kernel compat, and a placeholder for the pinned minimum-kernel feature matrix (tracked by the #662 libbinder audit).
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new Standards document to clarify how Binder userspace runtimes are delivered across independently mounted MW (/mw) and vendor (/vendor) layers when their processes may differ in bitness, and summarizes the related kernel provisioning expectations. The page is integrated into the MkDocs navigation so it appears under Hardware Abstraction Layer → Standards.
Changes:
- Added
docs/standards/binder_runtime_and_bitness.mddocumenting MW/vendor Binder runtime layering, cross-bitness IPC boundary, and kernel requirements. - Wired the new document into the MkDocs nav under Standards.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| mkdocs.yml | Adds the new “Binder Runtime & Bitness” page to the Standards nav. |
| docs/standards/binder_runtime_and_bitness.md | New standards documentation describing Binder runtime layering/bitness and kernel provisioning guidance. |
Comment on lines
+42
to
+46
| ```text | ||
| CONFIG_ANDROID_BINDER_IPC=y | ||
| CONFIG_ANDROID_BINDER_DEVICES="binder,hwbinder,vndbinder" # static device nodes | ||
| CONFIG_ANDROID_BINDERFS=y # kernels >= 5.0 (binderfs) | ||
| ``` |
| CONFIG_ANDROID_BINDERFS=y # kernels >= 5.0 (binderfs) | ||
| ``` | ||
|
|
||
| - **Device node.** The runtime opens `/dev/binder`. On kernels **≥ 5.0** this may be provided via **binderfs** (`mount -t binder binder /dev/binderfs`); on earlier kernels it is a **static device node** created from `CONFIG_ANDROID_BINDER_DEVICES`. |
…sion (#662) The supported floor is kernel 4.9 (hard requirement), through 5.16+. Record that the AOSP-13 libbinder runtime degrades gracefully across the range (newer ioctls are guarded), and that the real constraint is protocol-version / struct-ABI match. Flag that native.patch currently disables the pre-5.16 fallback definitions and breaks 4.9 builds (linux_binder_idl#35), and that Docker cannot test kernel versions — verification needs a QEMU/KVM matrix. Normalised tables.
5 tasks
Make explicit that static binder device nodes (CONFIG_ANDROID_BINDER_DEVICES) and binderfs (>=5.0) are ALTERNATIVE provisioning routes, not both required; and that binderfs creates the node under its mount (e.g. /dev/binderfs/binder) which the platform symlinks to /dev/binder.
Comment on lines
+73
to
+76
| ## Supported kernel range | ||
|
|
||
| **The supported floor is kernel 4.9**, through 5.16 and later. | ||
|
|
| | All-32-bit userspace | 32-bit | 32-bit | 7 | `BINDER_IPC_32BIT=1` | `CONFIG_ANDROID_BINDER_IPC_32BIT=y` | | ||
| | Mixed (32-bit MW + 64-bit vendor) | 32-bit | 64-bit | 8 | 32-bit compile, `BINDER_IPC_32BIT` unset | `CONFIG_ANDROID_BINDER_IPC_32BIT` unset | | ||
|
|
||
| > **Build gap.** linux_binder_idl currently couples `TARGET_LIB32_VERSION=ON` to `-DBINDER_IPC_32BIT=1` (`CMakeLists.txt:702-707`), so it can only produce the **protocol-7** 32-bit build. The **mixed** configuration needs a 32-bit compile with **protocol 8** (`BINDER_IPC_32BIT` unset). Decoupling the compile bitness from the protocol flag is tracked in linux_binder_idl#35. Until then, a 32-bit MW cannot share a kernel with a 64-bit vendor. |
| The upstream AOSP `android-13.0.0_r74` libbinder runtime works across this range: nothing it uses unconditionally is newer than the range, and newer ioctls (process-freeze ~5.10, oneway-spam-detection ~5.11) are runtime-guarded, so on older kernels they degrade non-fatally — `BINDER_SET_CONTEXT_MGR_EXT` (~4.19) falls back to `BINDER_SET_CONTEXT_MGR`, freeze/node-info ioctls return errors only to explicit opt-in callers, and the binderfs probe returns false. The governing constraint is **protocol-version + struct-ABI match**, not individual ioctl availability — libbinder hard-fails the driver open if the kernel's `BINDER_VERSION` is not exactly its own. | ||
|
|
||
| !!! warning "Port patch must honour the 4.9 floor" | ||
| `native.patch` currently disables the pre-5.16 fallback definitions in `binder_module.h` on a "require 5.16+" assumption, which **breaks builds against 4.9 kernel headers**. The fallback shims must be restored so the runtime builds against both old and new headers — tracked in linux_binder_idl#35. |
#662) Fully qualify + link the external references so they resolve in MkDocs: linux_binder_idl repo, its CMakeLists.txt coupling, native.patch (which lives in linux_binder_idl, not this repo), and linux_binder_idl#35. The kernel-4.9 floor is intentional (per the agreed decision); the migration-guide.md '5.10+' Copilot flagged is illustrative example content (a fictional 'Boot HAL v3 Release Notes' block), not a repo baseline — left unchanged.
Collaborator
Author
|
Relocated to linux_binder_idl — this is a binder build/runtime topic (per-layer libbinder build, bitness, protocol version, kernel range), so it belongs with the binder toolchain, not rdk-halif-aidl standards docs. Folded into linux_binder_idl/BUILD.md via rdkcentral/linux_binder_idl#44 (issue rdkcentral/linux_binder_idl#43), on the 2.5.0 milestone. The mixed protocol-8 build gap is now tracked properly in rdkcentral/linux_binder_idl#42. Closing here. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #662.
Adds
docs/standards/binder_runtime_and_bitness.mddocumenting the MW/vendor binder architecture:TARGET_LIB32_VERSION=ON), vendor at its own bitness — and they communicate over the kernel binder driver (IPC), which bridges 32/64. In-process linking can't cross ELF bitness, so the cross-bitness split is necessarily an IPC boundary.Wired into the mkdocs nav under Standards.
Follow-up commit will fill the feature matrix once the AOSP-13 libbinder ioctl audit completes.