From 659796916a272d1f6986b72f08eb039a2db890b7 Mon Sep 17 00:00:00 2001 From: bunnie Date: Mon, 15 Jan 2024 02:16:43 +0800 Subject: [PATCH] chore: cleanup typos in docs, comments --- CONTRIBUTING.md | 2 +- RELEASE-v0.9.md | 13 +++++++------ apps/README.md | 6 +++--- docs/flash.md | 4 ++-- docs/syscalls.md | 2 +- loader/README.md | 2 +- precursors/README.md | 2 +- services/README.md | 2 +- services/pddb/README.md | 2 +- services/pddb/src/backend/pagetable.rs | 2 +- services/pddb/src/backend/types.rs | 2 +- services/root-keys/README.md | 4 ++-- svd2utra/README.md | 12 ++++++------ tools/README.md | 2 +- 14 files changed, 29 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f573e6db..b7a7b47ea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,7 +80,7 @@ Using GPG is a complex subject. Here are some pointers for further information: * [Debian Keysigning HOWTO](https://wiki.debian.org/Keysigning) * If you create a new key please ensure that the RSA key length is at least 4096 bits and configured for [SHA-2](https://www.debian-administration.org/users/dkg/weblog/48) - * If you use **caff** (from [signing-party](https://packages.debian.org/sid/signing-party)) to sign and distrubute signatures please verify that the *separate* [caff configuration is accurate](https://github.com/tmarble/kspsig). + * If you use **caff** (from [signing-party](https://packages.debian.org/sid/signing-party)) to sign and distribute signatures please verify that the *separate* [caff configuration is accurate](https://github.com/tmarble/kspsig). You can export your GPG public key to a file for use with Github as follows (assuming your GPG key id is 0xCAFED00D): diff --git a/RELEASE-v0.9.md b/RELEASE-v0.9.md index f6bfa5ea6..d20ff3f42 100644 --- a/RELEASE-v0.9.md +++ b/RELEASE-v0.9.md @@ -13,7 +13,7 @@ in the APIs. Thus, we refer you to the [0.8 release notes](https://github.com/be for examples of idiomatic ways to write code for Xous. ## Major new features of 0.9 -- Xous now targets `riscv32-imac-uknown-xous-elf` instead of `riscv32-imac-unknown-none-elf`. +- Xous now targets `riscv32-imac-unknown-xous-elf` instead of `riscv32-imac-unknown-none-elf`. - `cargo xtask`, when run interactively, will offer to install the `xous` target. - Kernel debug primitives are accessible via the kernel console - GDB improvements @@ -69,7 +69,7 @@ for examples of idiomatic ways to write code for Xous. - No COM-based inter-chip communication yet ## New in 0.9.5 -- `modals` server for a simple "Pure Rust" API for creating dialog boxes and getting user input. See the `tests.rs` file for some examples how to use the applcation calls. +- `modals` server for a simple "Pure Rust" API for creating dialog boxes and getting user input. See the `tests.rs` file for some examples how to use the application calls. ## New in 0.9.6 - Networking: DNS, UDP, Ping and TCP @@ -134,13 +134,14 @@ for examples of idiomatic ways to write code for Xous. - `pddb` revision bumped to v2.1: - A first problem was identified where a key was being re-used between the ECB page table cipher and the AES-GCM-SIV data cipher - HKDF is now used to derive two separate keys for each - - A second problem was identified where the virtual page number was being stored as a fully expanded address in the paget able, and not as a page number. Due to the compressed encoding of the page table entry, this means that the virtual address space would be shrunk by ~4000x. This is now fixed, so we have the full as-designed virtual memory space once again. + - A second problem was identified where the virtual page number was being stored as a fully expanded address in the page + table, and not as a page number. Due to the compressed encoding of the page table entry, this means that the virtual address space would be shrunk by ~4000x. This is now fixed, so we have the full as-designed virtual memory space once again. - A migration routine was created to go from v1 -> v2 databases. It automatically detects the older version and attempts to guide the user through a migration. Although we don't have many users and databases today, this is a "best practice" for breaking revisions and this serves as a basis for forward-looking changes that are migrateable. - Various fixes and improvements to the USB update scripts to improve reliability. - Graphical panic outputs: when there is a panic, you get a "Guru Meditation" error box plus the panic message. - Currently all panics are hard crashes - Most of the time the system will reboot itself within a few seconds of displaying the panic - - There will be occassions where you will need to insert a paperclip into the reset port on the lower right hand corner to recover from the panic. + - There will be occasions where you will need to insert a paperclip into the reset port on the lower right hand corner to recover from the panic. - If you get a panic, please snap a photo of it and drop it in a new issue in the `xous-core` repo, along with a description of what you were doing at the time. ## New in 0.9.9 @@ -161,7 +162,7 @@ perform the Xous firmware upgrade. This requires running manual update commands, - Issue #162 and #159: fix bugs with condvar support. condvar IDs are now serial, so re-allocations are not a problem, and the routine to remove old ones from the notification table now looks at the correct sender ID. - Add `ceil`, `floor`, and `trunc` (f32 and f64) variants to the built-ins list (this is a `std` lib update, in 1.61.0.2) - Add CI test automation facilities - CI infra now drives actual hardware through `expect` scripts, instead of just doing simulation checks -- Vendor in `getrandom` so we can support a Xous API for the crate, allowing us access some of the more modern rustcrypto APIs. This is necssary for `randcore` 0.6 compatibility. `randcore` 0.5 APIs are retained by integrating them directly into the TRNG object. +- Vendor in `getrandom` so we can support a Xous API for the crate, allowing us access some of the more modern rustcrypto APIs. This is necessary for `randcore` 0.6 compatibility. `randcore` 0.5 APIs are retained by integrating them directly into the TRNG object. - Update AES API level to 0.8, and cipher dependency to 0.4 (on rootkeys). This was necessary to get CBC support for AES, which is needed for FIDO2. This *should* have no user-facing impact. - `vault` app: a user authentication management app is now ready for Alpha testing. It aims to provide FIDO2, TOTP, and stored password DB functions. - U2F/FIDO2 are a vendor-in of Google OpenSK's FIDO2 implementation. The code basically passes the CTAP2 test suite (https://github.com/google/CTAP2-test-tool) ("basically passes" in that the timeouts tests fail because they aren't automated to not "press the button" when timeouts are being tested). @@ -229,7 +230,7 @@ perform the Xous firmware upgrade. This requires running manual update commands, - Net fixes (`std` testbench compliance): - added loopback interface by "faking it" over the COM as smoltcp does not yet have the feature (loops back packets and ARP packets) - `net test` command added when the nettest feature is turned on - - get error codes into compliance with library expcectations + - get error codes into compliance with library expectations - add nonblocking feature - fix Peek - fix short reads -- no more discarding of excess data when the read buffer is shorter than the data in the buffer diff --git a/apps/README.md b/apps/README.md index 78d68df19..61a611183 100644 --- a/apps/README.md +++ b/apps/README.md @@ -21,9 +21,9 @@ Each entry for an app needs a record in `manifest.json` with this format: "context_name": "freeform name", "menu_name": { "appmenu.app_name": { - "en": "app name in english", - "ja": "app name in japanese", - "zh": "app name in chinese", + "en": "app name in English", + "ja": "app name in Japanese", + "zh": "app name in Chinese", "en-tts": "app name for the blind" } } diff --git a/docs/flash.md b/docs/flash.md index fea2b7b27..9d6652322 100644 --- a/docs/flash.md +++ b/docs/flash.md @@ -26,7 +26,7 @@ image stays resident. This means no space is allocated in FLASH for hibernation Finally, everything in the memory layout up until the PDDB is considered to be largely static data, only written during firmware and software updates. Therefore, no provision -exists for sector-sparing or weare levelling; we instead rely on the 100k-cycle write +exists for sector-sparing or wear levelling; we instead rely on the 100k-cycle write endurance of the underlying hardware. The PDDB itself will have to implement some form of wear leveling, however. @@ -143,7 +143,7 @@ The csr.csv block is further structured as follows: Prior to the creation of the PDDB, some hard-coded audio data is loaded for development purposes. -This documents their location in FLASH. The samples are shorter than the allocated regions, but the WAV headers encode their actual lenth. +This documents their location in FLASH. The samples are shorter than the allocated regions, but the WAV headers encode their actual length. ``` +-----------+----------------------------------------+ diff --git a/docs/syscalls.md b/docs/syscalls.md index 56fde1b7e..2d05487c9 100644 --- a/docs/syscalls.md +++ b/docs/syscalls.md @@ -72,7 +72,7 @@ When returning, a memory buffer may be required. The contents of this buffer wil ## Syscall Types -Syscalls use specialised types, many of which are backed by `usize`. For example, a `MemoryAddress` is a `NoneZeroUsize`, which is the same size as `usize`. In this manner, programs can ensure that memory addresses cannot be `NULL`. +Syscalls use specialized types, many of which are backed by `usize`. For example, a `MemoryAddress` is a `NoneZeroUsize`, which is the same size as `usize`. In this manner, programs can ensure that memory addresses cannot be `NULL`. ## Syscall Support Types diff --git a/loader/README.md b/loader/README.md index 6402b622e..16b5b1917 100644 --- a/loader/README.md +++ b/loader/README.md @@ -22,7 +22,7 @@ or `riscv32imac-unknown-none-elf` target for Rust. ${target_arch}` 5. Get an executable binary: `riscv64-unknown-elf-gcc -O binary target/${target}/xous-stage1 xous-stage1.bin` - + If you have made changes to the [assembly trampoline](https://github.com/betrusted-io/xous-core/blob/master/loader/src/asm.S) which sets up the loader, you will need to manually rebuild this, by running [assemble.sh](https://github.com/betrusted-io/xous-core/blob/master/loader/assemble.sh). This will replace a set of objects in the [`bin`](https://github.com/betrusted-io/xous-core/tree/master/loader/bin) directory. diff --git a/precursors/README.md b/precursors/README.md index a8e3488b7..919e2b477 100644 --- a/precursors/README.md +++ b/precursors/README.md @@ -2,7 +2,7 @@ The .wav files included here are meant for audio testing only and are intended to be bundled into the final distribution. Developers who want to use this for testing will need to manually stage and load -these samples into the correct location in the FLASH. See +these samples into the correct location in the FLASH. See https://github.com/betrusted-io/xous-core/blob/master/docs/flash.md for the locations of the samples. diff --git a/services/README.md b/services/README.md index bacf526b3..fcc2db5f9 100644 --- a/services/README.md +++ b/services/README.md @@ -80,7 +80,7 @@ Here are a list of application servers, implemented and projected, and their fun - `net` -- manages connections to the Internet - `wifi` -- manages wifi configuration - `power` -- intermediates requests to the backlight, battery status, charging, RTC, etc. -- `accel` -- intermedates requests to the accelerometer +- `accel` -- intermediates requests to the accelerometer - `audio` -- intermediates requests to the audio hardware. Does stream mixing, etc. - `usb` -- handles USB connections - `credentials` -- trusted PIN/password entry mechanism, manages currently activated credentials diff --git a/services/pddb/README.md b/services/pddb/README.md index a6aea0ce3..271cdde7a 100644 --- a/services/pddb/README.md +++ b/services/pddb/README.md @@ -1,6 +1,6 @@ # PDDB -Please refer to the Xous Book for the [authoratative documentation on the PDDB](https://betrusted.io/xous-book/ch09-00-pddb-overview.html). +Please refer to the Xous Book for the [authoritative documentation on the PDDB](https://betrusted.io/xous-book/ch09-00-pddb-overview.html). Alternatively, documentation for the PDDB can be found in the headers of the source files: diff --git a/services/pddb/src/backend/pagetable.rs b/services/pddb/src/backend/pagetable.rs index dd9f0c31c..3a8ec6a93 100644 --- a/services/pddb/src/backend/pagetable.rs +++ b/services/pddb/src/backend/pagetable.rs @@ -32,7 +32,7 @@ impl Default for PtFlags { /// /// Contains the address map of the corresponding entry, /// plus a nonce, and a checksum. Due to the Page Table being deliberately -/// srtuctured to have invalid entries that don't decrypt correctly, you +/// structured to have invalid entries that don't decrypt correctly, you /// can't use a chaining approach. Thus these entries are encrypted closer to /// an ECB-style, thus an embedded nonce is necessary to keep identical entries /// from appearing the same in the ciphertext domain. diff --git a/services/pddb/src/backend/types.rs b/services/pddb/src/backend/types.rs index 95ac0dcce..d9b96033a 100644 --- a/services/pddb/src/backend/types.rs +++ b/services/pddb/src/backend/types.rs @@ -197,7 +197,7 @@ mod tests { } /// This test exists because nothing in the bitfield spec explicitly requires that a true maps to a 1. /// In fact a lot of code would work just fine if you mapped true to 0 and false to 1: if you're just - /// using the generated getter and setter, it woudln't matter. + /// using the generated getter and setter, it wouldn't matter. /// However, in our application, we fully expect a true to be a 1. This test exists to ensure this /// seemingly obvious but not explicitly stated fact always remains true. #[test] diff --git a/services/root-keys/README.md b/services/root-keys/README.md index 345f29df8..556fe6884 100644 --- a/services/root-keys/README.md +++ b/services/root-keys/README.md @@ -38,7 +38,7 @@ This server, `keys`, has the following responsibilities: - Boot PIN code: secures the root application keys - Update passphrase: secures updates - The passwords are prompted automatically by `keys` as a result of third-party API calls requesting services of `keys` that would require their entry. - - Passwords are hashed with `bcrypt` prior to use. In line with [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) reccommendations, we opt to use the older, battle-tested `bcrypt` algorithm because the limited memory of Precursor does not allow us to use other algorithms with parameters that impart substial security advantages. + - Passwords are hashed with `bcrypt` prior to use. In line with [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) reccommendations, we opt to use the older, battle-tested `bcrypt` algorithm because the limited memory of Precursor does not allow us to use other algorithms with parameters that impart substantial security advantages. - The passwords are entered via simple pop-up modal dialog boxes that plug directly into the `keys` memory space - Listens to the susres server to enforce password retirement policies - Plaintext copies of the password are mapped into a deliberate page of memory that is zero-ized on `Drop`, `suspend`, or other system states depending upon user policy. @@ -58,6 +58,6 @@ This server, `keys`, has the following responsibilities: Shortcomings: - Anyone can attempt to initiate an update by calling the library API on `keys`. However, the update can not proceed without user consent via password. - - Fonts are mapped into the `gfx-server` memory space, which complicates loader.bin verification and validation. It also creates a potential for exploits that swap out fonts to create false messagse to users. + - Fonts are mapped into the `gfx-server` memory space, which complicates loader.bin verification and validation. It also creates a potential for exploits that swap out fonts to create false messages to users. - There's a lot of complexity in this server, which makes it harder to analyze; see "Background" section above, for a discussion of the trade-offs that lead to this decision. diff --git a/svd2utra/README.md b/svd2utra/README.md index b86f61f32..be07af509 100644 --- a/svd2utra/README.md +++ b/svd2utra/README.md @@ -13,7 +13,7 @@ PAC generated using [svd2rust](https://crates.io/crates/svd2rust): ``` // this seems clear -- as long as all the bit fields are specified // (they actually aren't, so some non-obvious things are happening) - p.POWER.power.write(|w| + p.POWER.power.write(|w| w.discharge().bit(true) .soc_on().bit(false) .kbddrive().bit(true) @@ -23,10 +23,10 @@ PAC generated using [svd2rust](https://crates.io/crates/svd2rust): // what should this do? // 1. just set the discharge bit to true and everything else to zero? // 2. read the register first, change only the discharge bit to true, leaving the rest unchanged? - p.POWER.power.write(|w| + p.POWER.power.write(|w| w.discharge().bit(true) ); - + // answer: it does (1). You need to use the `modify()` function to have (2) happen. ``` @@ -43,15 +43,15 @@ the rest of the contents are zero? These types of ambiguity make it hard to audit code, especially for experts in systems programming who are not also experts in Rust. -The primary trade-off for achieving unambiguity and thinness is less +The primary trade-off for achieving unambiguousness and thinness is less type checking and type hardening, because we are not fully taking -advantage of the advanced syntax features of Rust. +advantage of the advanced syntax features of Rust. That being said, a certain degree of deliberate malleability in the register abstraction is desired to assist with security-oriented audits: for a security audit, it is often just as important to ask what the undefined bits do, as it is to check the settings of the -defined bits. Malleabilty allows an auditor to quickly create targeted +defined bits. Malleability allows an auditor to quickly create targeted tests that exercise undefined bits. Existing Rust-based access crates create strict types that eliminate the class of errors where constants defined for one register are used in an incorrect type of register, diff --git a/tools/README.md b/tools/README.md index 6af2f534c..f54bdb88c 100644 --- a/tools/README.md +++ b/tools/README.md @@ -10,7 +10,7 @@ can use. It contains a number of programs: -* **copy-object**: A reimplementation of `objcopy` +* **copy-object**: A re-implementation of `objcopy` * **create-image**: Tool used to create a boot args struct for Xous * **make-tags**: Test program used to create raw boot arg tags * **read-tags**: Test program to verify the tags were created