Merge pull request #3 from FawazTirmizi/rivos/main

Documentation and repository clean-up

Author: Disasm

CHANGELOG.md

@@ -5,155 +5,25 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
-## [v0.4.1] - 2020-10-20
-
-0.4.1 was yanked because the pre-built binaries contain conflicting symbols
-with a supported version of cortex-m.
-
-- Fix missing prebuilt binaries (#271)
-
-## [v0.4.0] - 2020-10-14
-
-v0.4.0 was yanked because it did not include the required pre-built binaries
-in the final crate.
-
-- Moved into cortex-m repository
-- Merge `HStdout` and `HStderr` into one type: `HostStream`
-- Support cortex-m v0.7
-- Semihosting macros no longer return a Result, instead errors are ignored.
-
-## [v0.3.7] - 2020-12-02
-
-- Replaces the yanked v0.3.6 by reverting #48, so the semihosting macros
-  continue to return a Result.
-
-## [v0.3.6] - 2020-12-01
-
-v0.3.6 was yanked because it incorrectly included #48, which was a breaking
-change.
-
-### Added
-
-- Update cortex-m dependency to support version 0.7.
-- Add `no-semihosting` feature to disable all semihosting calls.
-
-## [v0.3.5] - 2019-08-29
-
-### Added
-
-- Adds a feature to work around JLink quirks
-- Adds a dbg! macro using heprintln
-- Added thumbv8m.main support on stable
-
-### Fixed
-
-- Now Rust 2018 edition
-
-## [v0.3.4] - 2019-08-13
-
-### Fixed
-
-- Support for thumbv8 mainline hf target
-
-## [v0.3.3] - 2019-04-22
-
-### Added
-
-- Adds support for thumbv8 and cortex-m v0.6.0
-
-## [v0.3.2] - 2018-11-04
-
-### Added
-
-- Added a family of `hprint` macros for printing to the host standard output /
-  error via globally shared `HStdout` / `HStderr` handles .
-
-## [v0.3.1] - 2018-08-27
-
-### Changed
-
-- This crate no longer depends on `arm-none-eabi-gcc`.
-
-## [v0.3.0] - 2018-05-10
-
-### Changed
-
-- [breaking-change] `inline-asm` is no longer a default feature (i.e. a feature that's enabled by
-  default). The consequence is that this crate now compiles on 1.27 (beta) by default, and opting
-  into `inline-asm` requires nightly.
-
-## [v0.2.1] - 2018-04-25
-
-### Added
-
-- An opt-out "inline-asm" Cargo feature. When this feature is disabled semihosting is implemented
-  using an external assembly file instead of using the unstable inline assembly (`asm!`) feature
-  meaning that this crate can be compiled on stable.
-
-## [v0.2.0] - 2017-07-07
-
-### Added
-
-- `exit` and `report_exception` syscalls
-
-- `HStdout` and `HStderr` structs that represent handles to the host stdout and
-  stderr stream respectively.
-
-### Changed
-
-- [breaking-change] The `io` module has been renamed to `hio` to reflect that
-  this is I/O *on the host*.
-
-### Removed
-
-- [breaking-change] the family of `write` functions in the `io` module. Instead
-  use `HStdout` / `HStderr` and its `write_all` method and `fmt::Write`
-  implementation.
-
-- [breaking-change] the `hprint!` family of macros. Instead use `HStdout` and
-  the standard `write!` macro.
-
-## [v0.1.3] - 2017-02-27
-
-### Added
-
-- A family of `ewrite` functions and `ehprint!` macros to write to the host's
-  stderr.
-
-### Fixed
-
-- `write_all` logic when a single write doesn't write all the buffer bytes
-
-## [v0.1.2] - 2017-02-15
-
-### Fixed
-
-- the `hprintln!` macro when called without arguments.
-
-## [v0.1.1] - 2017-01-22
-
-### Added
-
-- Expose a family of `write` functions to write to the host's stdout without
-  going through the `hprint!` macros.
-
-## v0.1.0 - 2017-01-22
+- Bring in API changes from
+  [cortex-m-semihosting](https://github.com/rust-embedded/cortex-m/tree/master/cortex-m-semihosting),
+  including:
+    - Addition of the `hprint`, `hprintln`, `heprint`, `heprintln`, and `dbg`
+      macros.
+        - `hprint` and `heprintln` print to host stdout without and with a
+          newline, respectively.
+        - `heprint` and `heprintln` do the same, except to host stderr.
+        - `dbg` works exactly like
+          [`std::dbg`](https://doc.rust-lang.org/std/macro.dbg.html).
+    - `HStdout` and `HStderr` have been combined into `HostStream`.
+    - `inline-asm` feature removed, switched to stabilized inline asm and MSRV
+      bumped to 1.59.0
+- Clean up documentation, removing unnecessary references to
+  cortex-m-semihosting and improving clarity.
+
+## [v0.0.1] - 2018-02-27
 
 - Initial release
 
-[Unreleased]: https://github.com/rust-embedded/cortex-m/compare/c-m-sh-v0.4.1...HEAD
-[v0.4.1]: https://github.com/rust-embedded/cortex-m/compare/c-m-sh-v0.4.0...c-m-sh-v0.4.1
-[v0.4.0]: https://github.com/rust-embedded/cortex-m/compare/c-m-sh-v0.3.5...c-m-sh-v0.4.0
-[v0.3.7]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.3.6...v0.3.7
-[v0.3.6]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.3.5...v0.3.6
-[v0.3.5]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.3.4...v0.3.5
-[v0.3.4]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.3.3...v0.3.4
-[v0.3.3]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.3.2...v0.3.3
-[v0.3.2]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.3.1...v0.3.2
-[v0.3.1]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.3.0...v0.3.1
-[v0.3.0]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.2.1...v0.3.0
-[v0.2.1]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.2.0...v0.2.1
-[v0.2.0]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.1.3...v0.2.0
-[v0.1.3]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.1.2...v0.1.3
-[v0.1.2]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.1.1...v0.1.2
-[v0.1.1]: https://github.com/rust-embedded/cortex-m-semihosting/compare/v0.1.0...v0.1.1
+[Unreleased]: https://github.com/riscv-rust/riscv-semihosting/compare/cb1afe4002d576b87bfd4c199f42a43815984ce4..HEAD
+[v0.0.1]: https://github.com/riscv-rust/riscv-semihosting/tree/cb1afe4002d576b87bfd4c199f42a43815984ce4

Cargo.toml

@@ -2,6 +2,7 @@
 authors = [
     "The Cortex-M Team <[email protected]>",
     "Jorge Aparicio <[email protected]>",
+    "The RISC-V Team <[email protected]>",
 ]
 description = "Semihosting for RISCV processors"
 documentation = "https://docs.rs/riscv-semihosting"
@@ -12,7 +13,8 @@ name = "riscv-semihosting"
 readme = "README.md"
 repository = "https://github.com/riscv-rust/riscv-semihosting"
 version = "0.0.1"
-edition = "2018"
+edition = "2021"
+rust-version = "1.59.0"
 
 [features]
 default = ["jlink-quirks"]

README.md

@@ -1,13 +1,17 @@
-[![crates.io](https://img.shields.io/crates/v/cortex-m-semihosting.svg)](https://crates.io/crates/cortex-m-semihosting)
-[![crates.io](https://img.shields.io/crates/d/cortex-m-semihosting.svg)](https://crates.io/crates/cortex-m-semihosting)
+# `riscv-semihosting`
 
-# `cortex-m-semihosting`
+> Semihosting for RISC-V processors
 
-> Semihosting for ARM Cortex-M processors
+This is a fork of the
+[cortex-m-semihosting](https://docs.rs/cortex-m-semihosting) crate with changes
+to support the RISC-V Semihosting Specification as documented
+[here](https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc)
 
-This project is developed and maintained by the [Cortex-M team][team].
-
-## [Documentation](https://docs.rs/cortex-m-semihosting)
+This crate can be used in exactly the same way as cortex-m-semihosting, simply
+by changing calls to `cortex_m_semihosting::*` to `riscv_semihosting::*`. Given
+this, the
+[cortex-m-semihosting documentation](https://docs.rs/cortex-m-semihosting) is
+generally sufficient for using this library.
 
 # Minimum Supported Rust Version (MSRV)
 
@@ -20,7 +24,8 @@ Licensed under either of
 
 - Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or
   http://www.apache.org/licenses/LICENSE-2.0)
-- MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT)
+- MIT license ([LICENSE-MIT](../LICENSE-MIT) or
+  http://opensource.org/licenses/MIT)
 
 at your option.
 
@@ -33,8 +38,8 @@ dual licensed as above, without any additional terms or conditions.
 ## Code of Conduct
 
 Contribution to this crate is organized under the terms of the [Rust Code of
-Conduct][CoC], the maintainer of this crate, the [Cortex-M team][team], promises
+Conduct][CoC], the maintainer of this crate, the [RISC-V team][team], promises
 to intervene to uphold that code of conduct.
 
 [CoC]: ../CODE_OF_CONDUCT.md
-[team]: https://github.com/rust-embedded/wg#the-cortex-m-team
+[team]: https://github.com/rust-embedded/wg#the-risc-v-team

src/lib.rs

@@ -2,26 +2,32 @@
 //!
 //! # What is semihosting?
 //!
-//! "Semihosting is a mechanism that enables code running on an ARM target to communicate and use
-//! the Input/Output facilities on a host computer that is running a debugger." - ARM
+//! "Semihosting is a technique where an application running in a debug or
+//! simulation environment can access elements of the system hosting the
+//! debugger or simulator including console, file system, time and other
+//! functions. This allows for diagnostics, interaction and measurement of a
+//! target system without requiring significant infrastructure to exist in that
+//! target environment." - RISC-V Semihosting Spec
 //!
 //! # Interface
 //!
 //! This crate provides implementations of
-//! [`core::fmt::Write`](https://doc.rust-lang.org/core/fmt/trait.Write.html), so you can use it,
-//! in conjunction with
-//! [`core::format_args!`](https://doc.rust-lang.org/core/macro.format_args.html) or the [`write!` macro](https://doc.rust-lang.org/core/macro.write.html), for user-friendly construction and printing of formatted strings.
+//! [`core::fmt::Write`](https://doc.rust-lang.org/core/fmt/trait.Write.html),
+//! so you can use it, in conjunction with
+//! [`core::format_args!`](https://doc.rust-lang.org/core/macro.format_args.html)
+//! or the [`write!` macro](https://doc.rust-lang.org/core/macro.write.html),
+//! for user-friendly construction and printing of formatted strings.
 //!
-//! Since semihosting operations are modeled as [system calls][sc], this crate exposes an untyped
-//! `syscall!` interface just like the [`sc`] crate does.
+//! Since semihosting operations are modeled as [system calls][sc], this crate
+//! exposes an untyped `syscall!` interface just like the [`sc`] crate does.
 //!
 //! [sc]: https://en.wikipedia.org/wiki/System_call
 //! [`sc`]: https://crates.io/crates/sc
 //!
 //! # Forewarning
 //!
-//! Semihosting operations are *very* slow. Like, each WRITE operation can take hundreds of
-//! milliseconds.
+//! Semihosting operations are *very* slow. Like, each WRITE operation can take
+//! hundreds of milliseconds.
 //!
 //! # Example
 //!
@@ -56,8 +62,8 @@
 //! # the command will block at this point
 //! ```
 //!
-//! The OpenOCD logs will be redirected to `/tmp/openocd.log`. You can view those logs in "real
-//! time" using `tail`
+//! The OpenOCD logs will be redirected to `/tmp/openocd.log`. You can view
+//! those logs in "real time" using `tail`
 //!
 //! ``` text
 //! $ tail -f /tmp/openocd.log
@@ -69,8 +75,9 @@
 //! Info : nrf51.cpu: hardware has 4 breakpoints, 2 watchpoints
 //! ```
 //!
-//! Alternatively you could omit the `-l` flag from the `openocd` call, and the `tail -f` command
-//! but the OpenOCD output will have intermingled in it logs from its normal operation.
+//! Alternatively you could omit the `-l` flag from the `openocd` call, and the
+//! `tail -f` command but the OpenOCD output will have intermingled in it logs
+//! from its normal operation.
 //!
 //! Then, we run the program:
 //!
@@ -119,9 +126,9 @@
 //!
 //! ## The `dbg!` macro
 //!
-//! Analogous to [`std::dbg`](https://doc.rust-lang.org/std/macro.dbg.html) the macro
-//! `dbg!` returns a given expression and prints it using `heprintln!` including context
-//! for quick and dirty debugging.
+//! Analogous to [`std::dbg`](https://doc.rust-lang.org/std/macro.dbg.html) the
+//! macro `dbg!` returns a given expression and prints it using `heprintln!`
+//! including context for quick and dirty debugging.
 //!
 //! Panics if `heprintln!` returns an error.
 //!
@@ -153,23 +160,22 @@
 //!
 //! ## `jlink-quirks`
 //!
-//! When this feature is enabled, return values above `0xfffffff0` from semihosting operation
-//! `SYS_WRITE` (0x05) are interpreted as if the entire buffer had been written. The current
-//! latest version 6.48b of J-Link exhibits such behaviour, causing a panic if this feature
-//! is not enabled.
+//! When this feature is enabled, return values above `0xfffffff0` from
+//! semihosting operation `SYS_WRITE` (0x05) are interpreted as if the entire
+//! buffer had been written. The current latest version 6.48b of J-Link exhibits
+//! such behaviour, causing a panic if this feature is not enabled.
 //!
 //! ## `no-semihosting`
 //!
 //! When this feature is enabled, the underlying system calls are patched out.
 //!
 //! # Reference
 //!
-//! For documentation about the semihosting operations, check:
-//!
-//! 'Chapter 8 - Semihosting' of the ['ARM Compiler toolchain Version 5.0'][pdf]
-//! manual.
-//!
-//! [pdf]: http://infocenter.arm.com/help/topic/com.arm.doc.dui0471e/DUI0471E_developing_for_arm_processors.pdf
+//! For documentation about the semihosting operations, check
+//! ['Semihosting for AArch32 and AArch64'](https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst).
+//! The RISC-V Semihosting spec is identical to Arm's with the exception of the
+//! assembly sequence necessary to trigger a semihosting call, so their
+//! documentation is sufficient.
 
 #![deny(missing_docs)]
 #![no_std]

src/nr.rs

@@ -1,6 +1,10 @@
 //! Semihosting operations
+//!
+//! The details of what each operation does can be found in the
+//! [ARM Semihosting Specification](https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst#semihosting-operations).
+//! The RISC-V Semihosting operations are identiacal to ARM's, so their
+//! documentation is sufficient.
 
-// TODO document
 #![allow(missing_docs)]
 
 pub const CLOCK: usize = 0x10;