145 lines
6.8 KiB
Markdown
145 lines
6.8 KiB
Markdown
# BTC.sh — Development Notes
|
||
|
||
## Provenance
|
||
|
||
BTC.sh (Build Tool Chain) is a clean, cleanroom toolchain generation engine
|
||
derived from the cross-LFS methodology. The original architecture was based on
|
||
buildchain.sh by Charles M. "Chip" Coldwell at Harvard University:
|
||
|
||
http://frank.harvard.edu/~coldwell/toolchain/buildchain.sh
|
||
|
||
The script has been substantially rewritten and extended by the DCOSNET project
|
||
(2012–2026). All modern cross-compilation, forensic stamping, and thermal
|
||
sentinel features are original work.
|
||
|
||
## Design Principles
|
||
|
||
### Target-Host Separation
|
||
|
||
The host machine is always an average x86_64 system. Target architectures are
|
||
cross-compiled via sysroot, following the CLFS (Cross Linux From Scratch) and
|
||
Buildroot target configuration methodology. The host compiler is never used to
|
||
produce target binaries — every target has its own dedicated cross-toolchain.
|
||
|
||
### Table-Driven Target Registry
|
||
|
||
All 22 targets are defined in a single associative array
|
||
(`BTC_TARGETS[]`). Each entry specifies eleven fields in pipe-delimited format:
|
||
|
||
arch|multilib_arch|march|ISA|abi|libc|endian|family|description|min_kernel|gcc_extra
|
||
|
||
This design follows PEP 868 (table-driven configuration) and MISRA-C
|
||
(separation of data from logic). Adding a new target requires one array
|
||
assignment — no control-flow changes.
|
||
|
||
### Volatile Cleanroom Compilation
|
||
|
||
All compilation occurs in a ramfs mount. This provides zero I/O wear on host
|
||
storage and guarantees a pristine build environment on every invocation. The
|
||
ramfs is mounted at the start of the build phase and unmounted after the
|
||
toolchain is packaged into its golden image tarball.
|
||
|
||
### Silicon Identity (Forensic Stamping)
|
||
|
||
Every binary produced by a BTC-built toolchain carries two immutable
|
||
identifiers:
|
||
|
||
1. **ELF `.note.BTC` section** — note name "DCOSNET", note type 0xB7C
|
||
(vendor-specific), containing a pipe-delimited string with org, kernel
|
||
version, target ID, march, ISA, sys_label, build stage, signature tier,
|
||
and the active signature token.
|
||
2. **Extended attributes (xattr)** — four attributes written to the
|
||
binary file:
|
||
- `user.btc.identity` — `BTC-<SYS_LABEL>-<v_linux>-<sig_tier>`
|
||
- `user.btc.hash` — SHA-256 of the stamped binary
|
||
- `user.btc.sig.tier` — `poly` | `tpm` | `cluster`
|
||
- `user.btc.sig.token` — the active signature token
|
||
|
||
These stamps allow any binary to be traced back to the exact build environment,
|
||
toolchain version, and source tree that produced it.
|
||
|
||
### Dual C Library Strategy
|
||
|
||
- **x86_64 targets**: glibc — full POSIX compatibility for workstation and
|
||
server deployments.
|
||
- **ARM, MIPS, TILE targets**: musl — lightweight, statically-linkable C
|
||
library suitable for embedded cross-compilation and minimal rootfs images.
|
||
|
||
## ISA Tiers
|
||
|
||
BTC.sh classifies targets by instruction set capability. The ISA tier
|
||
determines the optimization flags passed to GCC:
|
||
|
||
| ISA Tier | Targets | Flags |
|
||
|--------------|----------------------------------------------|------------------------------------|
|
||
| AVX512 | skylake-x, skylake-server, znver4 | -mavx512f -mavx512dq -mavx512vl -mavx512bw |
|
||
| AVX2 | haswell, haswell-ep, skylake, znver1–3, | -mavx2 |
|
||
| | apu-zn1–zn4 | |
|
||
| SSE4_2 | atom-silvermont, atom-goldmont, | -msse4.2 |
|
||
| | atom-tremont, atom-sierraforest | |
|
||
| NEON | armv7 | -mfpu=neon -mfloat-abi=hard |
|
||
| MIPS32 | mipselr2 | (march set per target) |
|
||
| TILE | tilegx | (arch set per target) |
|
||
|
||
The SSE4_2 tier exists because Intel Atom and AMD APU low-power cores lack
|
||
AVX support. GCC is configured with `--with-arch=<march>` in both Stage 1
|
||
and Stage 2 to ensure the cross-compiler defaults to the correct target
|
||
microarchitecture. `--with-cpu=<march>` is added for x86_64 targets only —
|
||
ARM, MIPS, and TILE backends reject `--with-cpu=<arch>` (they want a CPU
|
||
name like `cortex-a9`, not an architecture name like `armv7-a`) and instead
|
||
carry their per-target `--with-*` hints via `BTC_T_GCC_EXTRA`.
|
||
|
||
## LFS Base Standards
|
||
|
||
BTC.sh follows Linux From Scratch 13.0 stable (released 2024-09-01), bumped
|
||
forward to the latest point releases actually downloadable from upstream
|
||
mirrors as of v0.4.2:
|
||
|
||
- Binutils 2.46.1 (LFS 13.0 ships 2.46)
|
||
- GCC 15.3.0 (LFS 13.0 ships 14.2.0; bumped to 15.3.0 for znver4 /
|
||
sierraforest march support and GCC 15 stricter
|
||
const-correctness — requires `-Wno-error` for
|
||
libxcrypt 4.5.2, which `f_libxcrypt()` already passes)
|
||
- Glibc 2.43 (LFS 13.0 ships 2.41)
|
||
- musl 1.2.6 (LFS 13.0 ships 1.2.5)
|
||
- Linux 7.1.7 (latest 7.1.x point release; LFS 13.0 ships 6.10)
|
||
- Tile-Gx override: Linux 5.4.302 LTS + GCC 10.3.0 (mainline dropped
|
||
tile in Linux 5.9 / GCC 12)
|
||
|
||
## C Library Selection Rationale
|
||
|
||
- **glibc** is used for x86_64 targets (including Atom and APU) because
|
||
deployment environments typically have full development infrastructure,
|
||
large rootfs, and require maximum POSIX compatibility.
|
||
- **musl** is used for ARM, MIPS, and TILE targets where disk space is
|
||
constrained and static linking is frequently required for embedded
|
||
deployment.
|
||
|
||
## Research References
|
||
|
||
The following resources informed the BTC.sh architecture. They are listed for
|
||
attribution purposes and are not directly incorporated into the script:
|
||
|
||
- Cross Linux From Scratch 1.0.0 — http://cross-lfs.org/view/1.0.0/x86_64-64/
|
||
- Kernel header installation — Documentation/make/headers_install.txt
|
||
- GNU toolchain / glibc building — devpit.org, chschneider.eu/linux/tfs/
|
||
- GNU Embedded Programming — www.bravegnu.org/gnu-eprog/
|
||
- ttylinux xbuildroot scripts (CLFS methodology reference)
|
||
- Source Mage GNU/Linux — relevant spell build logic
|
||
- Chip Coldwell's buildchain.sh — http://frank.harvard.edu/~coldwell/toolchain
|
||
|
||
## Source Cache Policy
|
||
|
||
BTC.sh caches all downloaded source tarballs locally under `/opt/BTC/src/`
|
||
to avoid placing unnecessary load on upstream hosting infrastructure.
|
||
Automated bulk downloads should be rate-limited and sources retained after
|
||
initial fetch. The cache is reused across builds; the integrity check in
|
||
`_archive_sane()` automatically discards and re-fetches corrupted archives
|
||
on the next run.
|
||
|
||
## License
|
||
|
||
BTC.sh is released under the GNU Affero General Public License v3.0 (AGPL-3.0).
|
||
Per Section 13, the build includes an interactive notice at runtime. If you
|
||
modify and provide this build as a network service, you are legally obligated
|
||
to provide the Corresponding Source to your users. |