consortium_data/lib.rs
1// Copyright 2026 Ethan Wu
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15// SPDX-License-Identifier: Apache-2.0
16
17//! Static chip data for the Consortium project, embedded at compile time.
18//!
19//! This crate owns the chip-family databases (`database/memory/*.yaml`), the
20//! generated per-core chip dumps (`database/chip/*.json`), and the extracted
21//! peripheral register definitions (`database/peri/`).
22//! It also owns the resolvers that turn a `[profile] chip` part number into a
23//! parsed [`database::ChipDatabase`] or a per-core [`chipmap::ChipMap`].
24//!
25//! # Why it is embedded rather than read from disk
26//!
27//! `csti` is installed as a binary and run from a user's project directory, which
28//! has no `database/` in it. Chip YAML and JSON are therefore compiled in through
29//! `include_str!`. Linux device-tree sources are intentionally not bundled; the
30//! build reads them from the checkout passed to `csti build --linux`.
31//!
32//! # What each module resolves
33//!
34//! | Module | Source | Answers |
35//! | ------------ | ---------------------------- | ------------------------------------ |
36//! | [`database`] | `database/memory/*.yaml` | What does this chip *family* offer — coprocessors, memory regions and aliases, peripherals, doorbells? |
37//! | [`chipmap`] | `database/chip/*.json` | What can *one core* reach — peripheral MMIO bases and NVIC numbers? |
38//!
39//! The split between the first two matters. A family database says the chip *has* an
40//! LPUART2; a chip map says *this core* can see it. Because there is one JSON file
41//! per core, the set of peripherals in a core's file **is** the set that core can
42//! reach — which is exactly the filter `consortium-cfg` applies when validating
43//! `[peripheral.<name>] owner`.
44//!
45//! The same chip dumps also feed `scripts/pac/gen_interrupts.py` and
46//! `scripts/pac/gen_peripherals.py`, which generate the PAC's interrupt tables and
47//! the chip HAL's singleton map. One source for all three is what keeps a HAL
48//! singleton, a PAC interrupt number, and a validated manifest in agreement.
49//!
50//! # Generated and imported data
51//!
52//! Treat everything under `database/` as **generated or vendored**, not authored.
53//! Change the generation workflow (the `just pac-*` recipes and `scripts/pac/`)
54//! rather than editing a large data file by hand.
55//!
56//! Schema types come from `consortium-cfg-common`, which exists partly so this crate
57//! can deserialize into them without depending on the codegen crate that depends on
58//! it.
59//!
60pub mod chipmap;
61pub mod database;
62mod error;
63
64pub use error::DataError;