Crate cortex_m_semihosting [−] [src]
Semihosting for ARM Cortex-M processors
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
Interface
Since semihosting operations are modeled as system calls, this crate exposes an untyped
syscall!
interface just like the sc
crate does.
Forewarning
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.
Target program:
#[macro_use] extern crate cortex_m_semihosting; 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"; // Signature: fn write(fd: usize, ptr: *const u8, len: usize) -> usize let r = unsafe { syscall!(WRITE, STDOUT, MSG.as_ptr(), MSG.len()) }; }
On the host side:
$ openocd -f $INTERFACE -f $TARGET -l /tmp/openocd.log
Open On-Chip Debugger 0.9.0 (2016-04-27-23:18)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
# 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
$ tail -f /tmp/openocd.log
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : clock speed 950 kHz
Info : STLINK v1 JTAG v11 API v2 SWIM v0 VID 0x0483 PID 0x3744
Info : using stlink api v2
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.
Then, we run the program:
$ arm-none-eabi-gdb hello-world
# Connect to OpenOCD
(gdb) target remote :3333
# Enable OpenOCD's semihosting support
(gdb) monitor arm semihosting enable
# Flash the program
(gdb) load
# Run the program
(gdb) continue
And you'll see the output under OpenOCD's terminal
# openocd -f $INTERFACE -f $TARGET -l /tmp/openocd.log
(..)
Hello, world!
Cargo features
inline-asm
This feature is enabled by default.
When this feature is enabled semihosting is implemented using inline assembly (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.
Apart from the toolchain requirement, disabling inline-asm
requires arm-none-eabi-gcc
to be
installed on the host. Also, disabling inline-asm
imposes an overhead of an extra function
call on each semihosting call compared to having inline-asm
enabled.
Reference
For documentation about the semihosting operations, check:
'Chapter 8 - Semihosting' of the 'ARM Compiler toolchain Version 5.0' manual.
Modules
debug |
Interacting with debugging agent |
hio |
Host I/O |
nr |
Semihosting operations |
Macros
syscall |
Variable argument version of |
syscall1 |
Macro version of |
Functions
syscall⚠ |
Performs a semihosting operation, takes a pointer to an argument block |
syscall1⚠ |
Performs a semihosting operation, takes one integer as an argument |