Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions docs/content/software/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,13 @@ and events.
The host owns [`RenderScratch`](src:firmware/obc-render/src/lib.rs) and lends it to each render
call. The memory a frame needs is therefore not part of application state.

Four foundation crates carry no policy:
Five foundation crates carry no policy:

- [`obc-formats`](src:firmware/obc-formats) defines the persistent byte constants and byte I/O.
- [`obc-map-scene`](src:firmware/obc-map-scene) separates map sources from the renderer.
- [`obc-elevation`](src:firmware/obc-elevation) reads terrain and applies the shared elevation rules.
- [`obc-crc`](src:firmware/obc-crc) is the one CRC-32.
- [`obc-ports`](src:firmware/obc-ports) defines the semantic host interfaces.
- [`obc-map-scene`](src:firmware/obc-map-scene) separates map sources from the renderer.
- [`obc-file-source`](src:host/obc-file-source) gives the host tools a file as a byte source.

## Four hosts, one core

Expand Down
4 changes: 3 additions & 1 deletion docs/design/foundations.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,9 @@ The system depends on no other system. Its tests use `obcm-testkit` from map rea
| A trip start record never replaces a finished trip record. | `a_start_record_moves_the_stored_record_and_never_replaces_it` in [`trip_progress.rs`](../../firmware/obc-formats/src/trip_progress.rs) |
| A map style stays at 12 bytes or less, because a source keeps 256 of them in RAM. | `size_of::<Style>` in [`lib.rs`](../../firmware/obc-map-scene/src/lib.rs) (a `const` assert) |
| A file source refuses a read past the end of the file. | `reads_at_an_offset_and_refuses_the_end` in [`lib.rs`](../../host/obc-file-source/src/lib.rs) |
| A foundation crate depends only on `heapless`, `libm` and other foundation crates. | `check_closed_dependencies` in [`check_dependencies.py`](../../firmware/tools/check_dependencies.py) |

The `no_std` and `forbid(unsafe_code)` attributes in each crate root are checked by the compiler. No check yet stops a crate with product policy from being added as a dependency of these crates. The findings issue asks for one.
The `no_std` and `forbid(unsafe_code)` attributes in each crate root are checked by the compiler. `cairn check` refuses a dependency on a crate of another system, and `check_closed_dependencies` refuses a third-party crate other than `heapless` and `libm`.

## Decisions

Expand All @@ -56,6 +57,7 @@ The `no_std` and `forbid(unsafe_code)` attributes in each crate root are checked
- **The `obc-ports` traits are synchronous and own no driver.** A sensor poll takes the newest value from a mailbox that the board fills. It does not start a bus transfer. So the app core runs the same way on the device, in the simulators and in tests, and needs no executor.
- **The `MapScene` walk methods are generic, not trait objects.** The renderer calls them once for each feature in a frame. A generic call is compiled for each concrete source, so the hot loop pays no dynamic dispatch.
- **`obc-file-source` is a separate host crate.** A host tool that needs to read a file takes this crate without taking a reader, a packer or a renderer with it.
- **The sound cue (`Cue`) crosses the port.** The app chooses which cue plays. Each platform ([`sound.rs`](../../firmware/obc-platform/src/sound.rs)) chooses how it sounds.

## Words it introduces

Expand Down
2 changes: 1 addition & 1 deletion firmware/obc-app/src/easier.rs
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@ impl App {
/// selected candidate widens the map, so it holds still while trials run.
pub fn assistant_easier_bounds(
&mut self,
source: obc_formats::assistant::PayloadFingerprint,
source: obc_formats::navigator::PayloadFingerprint,
bounds: obc_map_scene::BBox,
) {
if self.easier.phase == Phase::Rebuild && self.assistant_preview().is_some_and(|p| p.source == source) {
Expand Down
2 changes: 1 addition & 1 deletion firmware/obc-app/src/find_place.rs
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ pub struct FindState {
profile: crate::settings::BikeType,
local: Option<(u8, u16)>,
selected_review: bool,
invalid_visit: Option<obc_formats::assistant::PayloadFingerprint>,
invalid_visit: Option<obc_formats::navigator::PayloadFingerprint>,
pub(crate) resume_offer: bool,
/// The catalog row the standing checkpoint names, so the Resume card can say which route.
pub(crate) resume_route: Option<u8>,
Expand Down
4 changes: 2 additions & 2 deletions firmware/obc-app/src/navigator/review.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ use super::NavigatorError;
use crate::device_core::{MetadataTag, OperationToken, StoreIdentity};
use crate::settings::BikeType;
use crate::CatalogObjectId;
use obc_formats::assistant::{NavigatorCheckpoint, PayloadFingerprint};
use obc_formats::navigator::{NavigatorCheckpoint, PayloadFingerprint};
use obc_formats::obcr::RouteSourceKey;

pub const REVIEW_ALONG_TOLERANCE_M: u32 = 50;
Expand Down Expand Up @@ -223,7 +223,7 @@ impl ReviewState {

use super::{NavigatorMachine, PlanFamily, PlanPhase};
use crate::metadata::{MetadataError, MetadataOutcome};
use obc_formats::assistant::JourneyPhase;
use obc_formats::navigator::JourneyPhase;

impl NavigatorMachine {
/// A measuring request starts its leg wherever the caller says; a route starts at the rider.
Expand Down
8 changes: 4 additions & 4 deletions firmware/obc-app/src/navigator/visit.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
//! Visit requests and phase progress stay in Navigator. Geometry is accepted once.
use super::{review::AfterCheckpoint, NavigatorMachine, ReviewContext, ReviewPurpose, ReviewStatus};
use obc_formats::assistant::JourneyPhase;
use obc_formats::navigator::JourneyPhase;
use obc_formats::obcm::PoiMetadata;
use obc_route::visit::VisitTarget;
use obc_route::RouteReader;
Expand Down Expand Up @@ -203,7 +203,7 @@ impl crate::App {
pub fn set_assistant_preview_shape(
&mut self,
token: crate::device_core::OperationToken<crate::device_core::NavigatorTag>,
source: obc_formats::assistant::PayloadFingerprint,
source: obc_formats::navigator::PayloadFingerprint,
points: &[(i32, i32)],
) -> bool {
if !self.navigator.accepts(&super::NavigatorOutcome::ReviewReady { token })
Expand Down Expand Up @@ -366,7 +366,7 @@ impl crate::App {
pub fn bind_visit_sources(
&mut self,
scope: crate::device_core::StoreRevision,
original: Option<obc_formats::assistant::PayloadFingerprint>,
original: Option<obc_formats::navigator::PayloadFingerprint>,
avoidance: bool,
) -> bool {
if !self.navigator.visit.needs_bind {
Expand Down Expand Up @@ -521,8 +521,8 @@ mod tests {
use super::*;
use crate::device_core::{MetadataTag, TokenSource};
use crate::metadata::MetadataOutcome;
use obc_formats::assistant::{NavigatorCheckpoint, PayloadFingerprint};
use obc_formats::io::{ByteSink, Error, SliceSource};
use obc_formats::navigator::{NavigatorCheckpoint, PayloadFingerprint};
use obc_formats::obcr::{RouteSourceKey, VisitDescriptor};

#[derive(Default)]
Expand Down
16 changes: 5 additions & 11 deletions firmware/obc-crc/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -105,13 +105,6 @@ impl Crc32 {
pub fn finalize(&self) -> u32 {
self.state ^ 0xFFFF_FFFF
}

/// One-shot convenience: the CRC-32 of a whole buffer.
pub fn checksum(bytes: &[u8]) -> u32 {
let mut h = Self::new();
h.update(bytes);
h.finalize()
}
}

impl Default for Crc32 {
Expand All @@ -122,7 +115,9 @@ impl Default for Crc32 {

/// One-shot CRC-32/IEEE over `data`.
pub fn crc32(data: &[u8]) -> u32 {
Crc32::checksum(data)
let mut h = Crc32::new();
h.update(data);
h.finalize()
}

#[cfg(test)]
Expand All @@ -134,7 +129,6 @@ mod tests {
#[test]
fn check_value() {
assert_eq!(crc32(b"123456789"), 0xCBF4_3926);
assert_eq!(Crc32::checksum(b"123456789"), 0xCBF4_3926);
}

#[test]
Expand Down Expand Up @@ -166,7 +160,7 @@ mod tests {
let snapshot = h;
let mut resumed = snapshot;
resumed.update(&data[50..]);
assert_eq!(resumed.finalize(), Crc32::checksum(&data));
assert_eq!(resumed.finalize(), crc32(&data));
}

#[test]
Expand All @@ -176,6 +170,6 @@ mod tests {
prefix.update(&data[..73]);
let mut resumed = Crc32::from_checksum(prefix.finalize());
resumed.update(&data[73..]);
assert_eq!(resumed.finalize(), Crc32::checksum(&data));
assert_eq!(resumed.finalize(), crc32(&data));
}
}
15 changes: 5 additions & 10 deletions firmware/obc-formats/src/articles.rs
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
//! Shared, self-contained multilingual article bundles. Photos belong to the enclosing place.
use crate::{
io::rd_u32,
obcm::landmarks::{ContentRef, MAX_ATTRIBUTION_BYTES, MAX_TEXT_BYTES, MAX_TEXT_PAGES},
};
use crate::obcm::landmarks::{ContentRef, MAX_ATTRIBUTION_BYTES, MAX_TEXT_BYTES, MAX_TEXT_PAGES};

/// The device UI order is checked against this mapping by obc-app.
pub const LANGUAGES: [[u8; 2]; 4] = [*b"en", *b"de", *b"fr", *b"es"];
Expand All @@ -24,18 +21,16 @@ impl ArticleVariant {
(LANGUAGES.contains(&language) && (1..=MAX_TEXT_PAGES).contains(&bytes[2]) && bytes[3] == 0).then(|| Self {
language,
text_pages: bytes[2],
text: ContentRef { offset: rd_u32(bytes, 4), len: rd_u32(bytes, 8) },
attribution: ContentRef { offset: rd_u32(bytes, 12), len: rd_u32(bytes, 16) },
text: ContentRef::decode(bytes, 4),
attribution: ContentRef::decode(bytes, 12),
})
}
pub fn encode(&self) -> [u8; VARIANT_LEN] {
let mut bytes = [0; VARIANT_LEN];
bytes[..2].copy_from_slice(&self.language);
bytes[2] = self.text_pages;
for (at, reference) in [(4, self.text), (12, self.attribution)] {
bytes[at..at + 4].copy_from_slice(&reference.offset.to_le_bytes());
bytes[at + 4..at + 8].copy_from_slice(&reference.len.to_le_bytes());
}
self.text.encode(&mut bytes, 4);
self.attribution.encode(&mut bytes, 12);
bytes
}
}
7 changes: 3 additions & 4 deletions firmware/obc-formats/src/cache.rs
Original file line number Diff line number Diff line change
Expand Up @@ -215,10 +215,9 @@ fn rrip_victim(slots: &mut [IndexBlock]) -> usize {
/// index. Input is `(is_empty, stamp)` per slot in slot order, where `stamp` is whatever monotonic
/// recency counter the caller writes on access.
///
/// The LRU counterpart of [`rrip_victim`], shared because it was the one eviction rule written
/// twice. A rule, not a cache: both callers keep their own slots, keys, payloads and I/O. An empty
/// iterator answers `0`, an out-of-range index the caller must not dereference; both embedding
/// caches have `SLOTS >= 1`.
/// The LRU counterpart of [`rrip_victim`]. A rule, not a cache: both callers keep their own slots,
/// keys, payloads and I/O. An empty iterator answers `0`, an out-of-range index the caller must
/// not dereference; both embedding caches have `SLOTS >= 1`.
pub fn lru_victim<S: Ord>(slots: impl Iterator<Item = (bool, S)>) -> usize {
let mut victim = 0usize;
let mut lowest: Option<S> = None;
Expand Down
2 changes: 1 addition & 1 deletion firmware/obc-formats/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@
extern crate std;

pub mod articles;
pub mod assistant;
pub mod bike;
pub mod cache;
pub mod grid;
pub mod io;
pub mod navigator;
pub mod obcm;
pub mod obcr;
pub mod obct;
Expand Down
4 changes: 2 additions & 2 deletions firmware/obc-formats/src/obcm/landmarks.rs
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,11 @@ impl ContentRef {
self.offset == 0 && self.len == 0
}

fn decode(bytes: &[u8], at: usize) -> Self {
pub(crate) fn decode(bytes: &[u8], at: usize) -> Self {
Self { offset: rd_u32(bytes, at), len: rd_u32(bytes, at + 4) }
}

fn encode(self, bytes: &mut [u8], at: usize) {
pub(crate) fn encode(self, bytes: &mut [u8], at: usize) {
bytes[at..at + 4].copy_from_slice(&self.offset.to_le_bytes());
bytes[at + 4..at + 8].copy_from_slice(&self.len.to_le_bytes());
}
Expand Down
10 changes: 3 additions & 7 deletions firmware/obc-formats/src/obcm/peaks.rs
Original file line number Diff line number Diff line change
Expand Up @@ -46,18 +46,14 @@ impl Record {
pub fn decode(bytes: &[u8; RECORD_LEN]) -> Self {
Self {
id: bytes[..32].try_into().unwrap(),
content: core::array::from_fn(|i| ContentRef {
offset: rd_u32(bytes, 32 + i * 8),
len: rd_u32(bytes, 36 + i * 8),
}),
content: core::array::from_fn(|i| ContentRef::decode(bytes, 32 + i * 8)),
}
}
pub fn encode(self) -> [u8; RECORD_LEN] {
let mut bytes = [0; RECORD_LEN];
bytes[..32].copy_from_slice(&self.id);
for (i, r) in self.content.iter().enumerate() {
bytes[32 + i * 8..36 + i * 8].copy_from_slice(&r.offset.to_le_bytes());
bytes[36 + i * 8..40 + i * 8].copy_from_slice(&r.len.to_le_bytes());
for (i, r) in self.content.into_iter().enumerate() {
r.encode(&mut bytes, 32 + i * 8);
}
bytes
}
Expand Down
5 changes: 3 additions & 2 deletions firmware/obc-formats/src/obcr.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
use crate::io::{validate_prefix, DecodeError};

pub const MAGIC: &[u8; 4] = b"OBCR";
/// The one accepted route version. Older files must be re-imported.
/// The one accepted route version; the header check refuses every other.
pub const VERSION: u8 = 5;
/// The header's ride core — every field the geometry path needs.
pub const HEADER_LEN: usize = 112;
Expand Down Expand Up @@ -38,7 +38,8 @@ pub const VISIT_DESCRIPTOR_LEN: usize = 80;
pub const FACTS_POLICY: u16 = 1;
pub const WAYPOINT_ELE_NONE: i16 = i16::MIN;
/// The waypoint category byte for "no category", the diamond every hand-placed waypoint renders
/// as. `1..=6` are the OBCM `PoiCategory` wire ids; any other value reads as generic.
/// as. Any other byte that is an OBCM `PoiCategory` wire id reads as that category; the rest
/// read as generic. The GPX import writes only `0..=6`.
pub const WAYPOINT_CATEGORY_GENERIC: u8 = 0;

pub fn validate_header_prefix(bytes: &[u8]) -> Result<u8, DecodeError> {
Expand Down
2 changes: 1 addition & 1 deletion firmware/obc-fw-nrf54l/src/flat_store.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1471,7 +1471,7 @@ pub(crate) fn route_heads(
pub(crate) fn route_fingerprint(
store: &FlatStore<FlatCard>,
id: u64,
) -> Option<obc_formats::assistant::PayloadFingerprint> {
) -> Option<obc_formats::navigator::PayloadFingerprint> {
let meta = store
.find_entry(|meta| meta.kind == ObjectKind::Route && meta.id.0 == id && meta.flags.is_route_head())
.ok()?;
Expand Down
2 changes: 1 addition & 1 deletion firmware/obc-fw-nrf54l/src/ride.rs
Original file line number Diff line number Diff line change
Expand Up @@ -667,7 +667,7 @@ pub(crate) async fn run_app(
// The in-flight route plan's bookkeeping: `Some` while a plan is being stepped, one bounded step
// per pass. It guards the planner slot's initialization.
let mut nav_run: Option<NavRun> = None;
let mut review_publication: Option<obc_formats::assistant::PayloadFingerprint> = None;
let mut review_publication: Option<obc_formats::navigator::PayloadFingerprint> = None;
let mut review_original: Option<obc_storage::flat::StoreSource<'static, crate::flat_store::FlatCard>> = None;
let mut detour = crate::detour::Executor::new();
let mut visit = crate::visit::Executor::new();
Expand Down
3 changes: 2 additions & 1 deletion firmware/obc-ports/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,8 @@ impl DateTime {
Self::from_unix_clamped(self.pinned().to_unix_i64() + offset as i64 * 60)
}

/// Unix seconds at this stamp's `HH:MM:00`, interpreting it as UTC.
/// Unix seconds at this stamp's `HH:MM:00`, interpreting it as UTC. The `u32` wraps after
/// 2106-02-07; `to_unix_i64` is the full form.
pub fn to_unix(self) -> u32 {
self.to_unix_i64() as u32
}
Expand Down
4 changes: 2 additions & 2 deletions firmware/obc-route/src/reader.rs
Original file line number Diff line number Diff line change
Expand Up @@ -883,7 +883,7 @@ pub struct Waypoint {
pub lat: i32,
/// Elevation in meters; [`WAYPOINT_ELE_NONE`](obc_formats::obcr::WAYPOINT_ELE_NONE) when the source carried none.
pub ele: i16,
/// The stored category byte: `0` is generic and `1..=6` are the [`PoiCategory`] wire ids.
/// The stored category byte: `0` is generic and the [`PoiCategory`] wire ids are categories.
/// Kept raw so a rewrite carries an unknown value through byte for byte.
pub category_id: u8,
/// Lateral offset from the route line, meters. Positive is right of the direction of travel
Expand All @@ -894,7 +894,7 @@ pub struct Waypoint {
}

impl Waypoint {
/// The typed category, or `None` for generic, which also covers a byte outside `1..=6`.
/// The typed category, or `None` for generic, which also covers a byte that is no [`PoiCategory`] id.
#[inline]
pub fn category(&self) -> Option<PoiCategory> {
PoiCategory::from_id(self.category_id)
Expand Down
2 changes: 1 addition & 1 deletion firmware/obc-storage/src/flat/metadata.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ use super::{
StoreError, StoreId,
};

use obc_formats::assistant::{NavigatorCheckpoint, PayloadFingerprint, CHECKPOINT_LEN, CHECKPOINT_VERSION};
use obc_formats::navigator::{NavigatorCheckpoint, PayloadFingerprint, CHECKPOINT_LEN, CHECKPOINT_VERSION};
use obc_formats::trip_progress::{TripProgress, MAX_RECORDS, RECORD_LEN};

pub const HEADER_LEN: usize = 32;
Expand Down
4 changes: 2 additions & 2 deletions firmware/obc-storage/src/flat/metadata/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -380,7 +380,7 @@ pub(super) fn checkpoint(route: EntryMeta, original: Option<EntryMeta>) -> Navig
occurrence: 2,
lon: 8_000_000,
lat: 47_000_000,
phase: obc_formats::assistant::JourneyPhase::Following,
phase: obc_formats::navigator::JourneyPhase::Following,
unresolved_avoidance: false,
selection: false,
lower_m: 0,
Expand All @@ -399,7 +399,7 @@ fn checkpoint_rows_reconcile_and_capacity_preserve_each_other() {
occurrence: 0,
lon: 0,
lat: 0,
phase: obc_formats::assistant::JourneyPhase::Following,
phase: obc_formats::navigator::JourneyPhase::Following,
unresolved_avoidance: false,
selection: false,
lower_m: 0,
Expand Down
2 changes: 1 addition & 1 deletion firmware/obc-storage/src/flat/raw.rs
Original file line number Diff line number Diff line change
Expand Up @@ -47,5 +47,5 @@ pub fn is_zero(bytes: &[u8], off: usize, len: usize) -> bool {

/// The one CRC of this format: CRC-32/IEEE, `crc32("123456789") = 0xCBF43926`.
pub fn crc32(bytes: &[u8]) -> u32 {
obc_crc::Crc32::checksum(bytes)
obc_crc::crc32(bytes)
}
4 changes: 2 additions & 2 deletions firmware/obc-storage/src/flat/route_cleanup.rs
Original file line number Diff line number Diff line change
Expand Up @@ -113,14 +113,14 @@ mod tests {
let accepted = route(&store, None);
let named = route(&store, None);
let moved = route(&store, None);
let checkpoint = obc_formats::assistant::NavigatorCheckpoint {
let checkpoint = obc_formats::navigator::NavigatorCheckpoint {
route: fingerprint(accepted),
original: Some(fingerprint(named)),
progress_m: 0,
occurrence: 0,
lon: 0,
lat: 0,
phase: obc_formats::assistant::JourneyPhase::Following,
phase: obc_formats::navigator::JourneyPhase::Following,
unresolved_avoidance: false,
selection: false,
lower_m: 0,
Expand Down
6 changes: 3 additions & 3 deletions firmware/obc-storage/src/flat/source.rs
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ impl<D: BlockDevice> FlatStore<D> {
mod tests {
use std::vec;

use obc_crc::Crc32;
use obc_crc::crc32;

use super::*;
use crate::flat::layout::{Geometry, EXTENT_AREA};
Expand Down Expand Up @@ -255,7 +255,7 @@ mod tests {
store.patch_allocation(&allocation, 0, &header).expect("an appended header remains patchable");
assert_eq!(
store.allocation_crc(&allocation).expect("the live allocation hashes"),
Crc32::checksum(&expected),
crc32(&expected),
"the checksum covers the patched bytes and the unflushed tail",
);

Expand All @@ -267,7 +267,7 @@ mod tests {
kind: ObjectKind::Route,
flags: EntryFlags::NONE,
payload_len: LEN as u64,
payload_crc: Crc32::checksum(&expected),
payload_crc: crc32(&expected),
name: DisplayName::new("computed").expect("a short name"),
};
store.commit(&[Mutation::Put { meta, source: PutSource::Fresh(allocation) }]).expect("the route publishes");
Expand Down
Loading
Loading