|
|
@@ -2,40 +2,46 @@
|
|
|
//!
|
|
|
//! # What is semihosting?
|
|
|
//!
|
|
|
-//! "Semihosting is a mechanism that enables code running on a RISCV target to
|
|
|
-//! communicate and use the Input/Output facilities on a host computer that is
|
|
|
-//! running a debugger." - RISCV
|
|
|
+//! "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
|
|
|
//!
|
|
|
//! # Interface
|
|
|
//!
|
|
|
-//! Since semihosting operations are modeled as [system calls][sc], this crate
|
|
|
-//! exposes an untyped `syscall!` interface just like the [`sc`] crate does.
|
|
|
+//! 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.
|
|
|
+//!
|
|
|
+//! 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
|
|
|
//!
|
|
|
-//! This example will show how to print "Hello, world!" on the host.
|
|
|
+//! ## Using `hio::hstdout`
|
|
|
//!
|
|
|
-//! Target program:
|
|
|
+//! This example will demonstrate how to print formatted strings.
|
|
|
//!
|
|
|
-//! ```
|
|
|
-//! #[macro_use]
|
|
|
-//! extern crate riscv_semihosting;
|
|
|
+//! ```no_run
|
|
|
+//! use riscv_semihosting::hio;
|
|
|
+//! use core::fmt::Write;
|
|
|
//!
|
|
|
-//! fn main() {
|
|
|
-//! // File descriptor (on the host)
|
|
|
-//! const STDOUT: usize = 1; // NOTE the host stdout may not always be fd 1
|
|
|
-//! static MSG: &'static [u8] = b"Hello, world!\n";
|
|
|
+//! // This function will be called by the application
|
|
|
+//! fn print() -> Result<(), core::fmt::Error> {
|
|
|
+//! let mut stdout = hio::hstdout().map_err(|_| core::fmt::Error)?;
|
|
|
+//! let language = "Rust";
|
|
|
+//! let ranking = 1;
|
|
|
//!
|
|
|
-//! // Signature: fn write(fd: usize, ptr: *const u8, len: usize) -> usize
|
|
|
-//! let r = unsafe { syscall!(WRITE, STDOUT, MSG.as_ptr(), MSG.len()) };
|
|
|
+//! write!(stdout, "{} on embedded is #{}!", language, ranking)?;
|
|
|
+//!
|
|
|
+//! Ok(())
|
|
|
//! }
|
|
|
//! ```
|
|
|
//!
|
|
|
@@ -50,8 +56,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
|
|
|
@@ -63,24 +69,23 @@
|
|
|
//! 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:
|
|
|
//!
|
|
|
//! ``` text
|
|
|
//! $ arm-none-eabi-gdb hello-world
|
|
|
-//! # Connect to OpenOCD
|
|
|
+//! (gdb) # Connect to OpenOCD
|
|
|
//! (gdb) target remote :3333
|
|
|
//!
|
|
|
-//! # Enable OpenOCD's semihosting support
|
|
|
+//! (gdb) # Enable OpenOCD's semihosting support
|
|
|
//! (gdb) monitor arm semihosting enable
|
|
|
//!
|
|
|
-//! # Flash the program
|
|
|
+//! (gdb) # Flash the program
|
|
|
//! (gdb) load
|
|
|
//!
|
|
|
-//! # Run the program
|
|
|
+//! (gdb) # Run the program
|
|
|
//! (gdb) continue
|
|
|
//! ```
|
|
|
//!
|
|
|
@@ -89,9 +94,82 @@
|
|
|
//! ``` text
|
|
|
//! # openocd -f $INTERFACE -f $TARGET -l /tmp/openocd.log
|
|
|
//! (..)
|
|
|
-//! Hello, world!
|
|
|
+//! Rust on embedded is #1!
|
|
|
+//! ```
|
|
|
+//! ## Using the syscall interface
|
|
|
+//!
|
|
|
+//! This example will show how to print "Hello, world!" on the host.
|
|
|
+//!
|
|
|
+//! Target program:
|
|
|
+//!
|
|
|
+//! ```no_run
|
|
|
+//! use riscv_semihosting::syscall;
|
|
|
+//!
|
|
|
+//! // This function will be called by the application
|
|
|
+//! fn print() {
|
|
|
+//! // File descriptor (on the host)
|
|
|
+//! const STDOUT: usize = 1; // NOTE the host stdout may not always be fd 1
|
|
|
+//! static MSG: &'static [u8] = b"Hello, world!\n";
|
|
|
+//!
|
|
|
+//! // Signature: fn write(fd: usize, ptr: *const u8, len: usize) -> usize
|
|
|
+//! let r = unsafe { syscall!(WRITE, STDOUT, MSG.as_ptr(), MSG.len()) };
|
|
|
+//! }
|
|
|
+//! ```
|
|
|
+//! Output and monitoring proceed as in the above example.
|
|
|
+//!
|
|
|
+//! ## 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.
|
|
|
+//!
|
|
|
+//! Panics if `heprintln!` returns an error.
|
|
|
+//!
|
|
|
+//! Example:
|
|
|
+//!
|
|
|
+//! ```no_run
|
|
|
+//! const UUID: *mut u32 = 0x0009_FC70 as *mut u32;
|
|
|
+//! dbg!(UUID);
|
|
|
+//! let mut uuid: [u32; 4] = [0; 4];
|
|
|
+//! for i in 0..4 {
|
|
|
+//! dbg!(i);
|
|
|
+//! uuid[i] = unsafe { dbg!(UUID.offset(i as isize).read_volatile()) };
|
|
|
+//! }
|
|
|
+//! ```
|
|
|
+//! outputs
|
|
|
+//! ```text
|
|
|
+//! [examples/semihosting.rs:37] UUID = 0x0009fc70
|
|
|
+//! [examples/semihosting.rs:40] i = 0
|
|
|
+//! [examples/semihosting.rs:41] UUID.offset(i as isize).read_volatile() = 3370045464
|
|
|
+//! [examples/semihosting.rs:40] i = 1
|
|
|
+//! [examples/semihosting.rs:41] UUID.offset(i as isize).read_volatile() = 1426218275
|
|
|
+//! [examples/semihosting.rs:40] i = 2
|
|
|
+//! [examples/semihosting.rs:41] UUID.offset(i as isize).read_volatile() = 2422621116
|
|
|
+//! [examples/semihosting.rs:40] i = 3
|
|
|
+//! [examples/semihosting.rs:41] UUID.offset(i as isize).read_volatile() = 1044138593
|
|
|
//! ```
|
|
|
//!
|
|
|
+//! # Optional features
|
|
|
+//!
|
|
|
+//! ## `inline-asm`
|
|
|
+//!
|
|
|
+//! When this feature is enabled semihosting is implemented using inline assembly (`llvm_asm!`) and
|
|
|
+//! compiling this crate requires nightly.
|
|
|
+//!
|
|
|
+//! When this feature is disabled semihosting is implemented using FFI calls into an external
|
|
|
+//! assembly file and compiling this crate works on stable and beta.
|
|
|
+//!
|
|
|
+//! ## `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.
|
|
|
+//!
|
|
|
+//! ## `no-semihosting`
|
|
|
+//!
|
|
|
+//! When this feature is enabled, the underlying system calls are patched out.
|
|
|
+//!
|
|
|
//! # Reference
|
|
|
//!
|
|
|
//! For documentation about the semihosting operations, check:
|
|
|
@@ -101,69 +179,46 @@
|
|
|
//!
|
|
|
//! [pdf]: http://infocenter.arm.com/help/topic/com.arm.doc.dui0471e/DUI0471E_developing_for_arm_processors.pdf
|
|
|
|
|
|
+#![cfg_attr(feature = "inline-asm", feature(llvm_asm))]
|
|
|
#![deny(missing_docs)]
|
|
|
-#![deny(warnings)]
|
|
|
-#![feature(asm)]
|
|
|
#![no_std]
|
|
|
|
|
|
#[macro_use]
|
|
|
mod macros;
|
|
|
|
|
|
pub mod debug;
|
|
|
+#[doc(hidden)]
|
|
|
+pub mod export;
|
|
|
pub mod hio;
|
|
|
pub mod nr;
|
|
|
|
|
|
-/// The hint that differentiates the semihosting call.
|
|
|
-// WARNING: This variable is hardcoded in the asm! Don't forget to update
|
|
|
-// if it changes.
|
|
|
-pub const RISCV_SEMIHOSTING_CALL_NUMBER: usize = 7;
|
|
|
-
|
|
|
-/// Performs a semihosting operation, takes a pointer to an argument block
|
|
|
-#[inline]
|
|
|
-#[cfg(target_arch = "riscv")]
|
|
|
-pub unsafe fn syscall<T>(mut nr: usize, arg: &T) -> usize {
|
|
|
- // .option push
|
|
|
- // .option norvc
|
|
|
- asm!(r"
|
|
|
- slli x0, x0, 0x1f
|
|
|
- ebreak
|
|
|
- srai x0, x0, 0x7
|
|
|
- "
|
|
|
- : "+{x10}"(nr)
|
|
|
- : "{x11}"(arg)
|
|
|
- : "memory"
|
|
|
- : "volatile");
|
|
|
- // .option pop
|
|
|
- nr
|
|
|
+#[cfg(not(feature = "inline-asm"))]
|
|
|
+extern "C" {
|
|
|
+ fn __sh_syscall(nr: usize, arg: usize) -> usize;
|
|
|
}
|
|
|
|
|
|
/// Performs a semihosting operation, takes a pointer to an argument block
|
|
|
-#[cfg(not(target_arch = "riscv"))]
|
|
|
-pub unsafe fn syscall<T>(_nr: usize, _arg: &T) -> usize {
|
|
|
- 0
|
|
|
+#[inline(always)]
|
|
|
+pub unsafe fn syscall<T>(nr: usize, arg: &T) -> usize {
|
|
|
+ syscall1(nr, arg as *const T as usize)
|
|
|
}
|
|
|
|
|
|
/// Performs a semihosting operation, takes one integer as an argument
|
|
|
-#[inline]
|
|
|
-#[cfg(target_arch = "riscv")]
|
|
|
-pub unsafe fn syscall1(mut nr: usize, arg: usize) -> usize {
|
|
|
- // .option push
|
|
|
- // .option norvc
|
|
|
- asm!(r"
|
|
|
- slli x0, x0, 0x1f
|
|
|
- ebreak
|
|
|
- srai x0, x0, 0x7
|
|
|
- "
|
|
|
- : "+{x10}"(nr)
|
|
|
- : "{x11}"(arg)
|
|
|
- : "memory"
|
|
|
- : "volatile");
|
|
|
- // .option pop
|
|
|
- nr
|
|
|
-}
|
|
|
-
|
|
|
-/// Performs a semihosting operation, takes one integer as an argument
|
|
|
-#[cfg(not(target_arch = "riscv"))]
|
|
|
+#[inline(always)]
|
|
|
pub unsafe fn syscall1(_nr: usize, _arg: usize) -> usize {
|
|
|
- 0
|
|
|
+ match () {
|
|
|
+ #[cfg(all(feature = "inline-asm", not(feature = "no-semihosting")))]
|
|
|
+ () => {
|
|
|
+ let mut nr = _nr;
|
|
|
+ llvm_asm!("
|
|
|
+ slli x0, x0, 0x1f
|
|
|
+ ebreak
|
|
|
+ srai x0, x0, 0x7
|
|
|
+ " : "+{a0}"(nr) : "{a1}"(_arg) :: "volatile");
|
|
|
+ nr
|
|
|
+ }
|
|
|
+
|
|
|
+ #[cfg(feature = "no-semihosting")]
|
|
|
+ () => 0,
|
|
|
+ }
|
|
|
}
|
Jonathan Perkin