From b97a2f7042796d32fc123aaa7990eda73d506f66 Mon Sep 17 00:00:00 2001 From: bunnie Date: Tue, 27 Sep 2022 16:30:57 +0800 Subject: [PATCH] bump rev and update readme --- utralib/Cargo.toml | 2 +- utralib/README.md | 49 +++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 45 insertions(+), 6 deletions(-) diff --git a/utralib/Cargo.toml b/utralib/Cargo.toml index 8717e31a4..d4f99779c 100644 --- a/utralib/Cargo.toml +++ b/utralib/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "utralib" -version = "0.1.0" +version = "0.1.1" authors = ["Sean Cross ", "bunnie "] edition = "2018" license = "MIT OR Apache-2.0" diff --git a/utralib/README.md b/utralib/README.md index 339118a84..77552bfa7 100644 --- a/utralib/README.md +++ b/utralib/README.md @@ -1,7 +1,46 @@ -# UTRA +# UTRA (Unambiguous Thin Register Abstraction) Library Crate -The meat of this directory is auto-generated by svd2utra. Documentation -on this API is also located in that directory. +`utralib` is responsible for mapping a hardware target specification +to the set of physical memory locations used by the hardware. -The UTRA is published to crates.io to correspond to a given SoC version -so that crates may depend upon it without referring to a local path. \ No newline at end of file +The mapping is derived from an [SVD](https://www.keil.com/pack/doc/CMSIS/SVD/html/svd_Format_pg.html) +file. SVD files are XML descriptions of a set of registers and fields that +has been adopted by LiteX, but is also broadly used by other silicon +vendors such as [ST](https://github.com/tinygo-org/stm32-svd). + +Rust strongly discourages [auto-generated source content](https://github.com/rust-lang/cargo/issues/5073) +so this crate pre-generates the various configurations from SVD files +and stores them in the directory "generated". + +However, the generated UTRA descriptions will automatically +regenerate if the source SVD files are modified, so during development +one may replace an SVD file and expect that the generated.rs files +should automatically update to reflect the changed SVD file. + +## Target selection + +Target selection is done with a pair of flags, one which specifies +the general target, and the other which whittles it down to a revision +of the target. + +For traditional silicon platforms, the revision almost never changes. +For FPGA platforms, the revision can change and the convention adopted +here is to use the short 32-bit gitrev to specify a revision. Because +the 32-bit namespace is fairly small, the target name is still bundled +in with the revision specifier. + +Thus, to fully specify a Precursor target, one will need to pass two +flags: + +- `--features precursor`: specifies the target +- `--features precursor-c809403`: specifies the revision + +The target specifier is meant to simplify top-level crate decisions +about which module to use to implement hardware features. + +The revision is provided for very specific situations where a hardware +feature may or may not be present in a specific revision of an FPGA SoC. + +The feature system could also be (ab)used to, for example, specify +an STM32 family and then the specific chip configuration of that family +with the revision. \ No newline at end of file