W3SLAV/micropython
1
Fork 0
mirror of https://github.com/W3SLAV/micropython.git synced 2025-06-19 12:05:32 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

shared/runtime/semihosting: Add RISC-V semihosting support.

Browse Source 
This adds a RISC-V RV32 semihosting implementation, with all defined
system calls exposed to the user.

Signed-off-by: Alessandro Gatti <a.gatti@frob.it>
This commit is contained in:
Alessandro Gatti 2024-05-22 10:50:20 +02:00 committed by Damien George
parent 90d50ce918
commit ace08c3978
2 changed files with 728 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

481
shared/runtime/semihosting_rv32.c Normal file
View File

@ -0,0 +1,481 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2024 Alessandro Gatti
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include <stdbool.h>
#include "semihosting_rv32.h"
#if !defined(__riscv) || !defined(__riscv_xlen) || (__riscv_xlen != 32)
#error "This semihosting support code is only available for RV32 targets."
#endif
// Features file magic header.
#define MAGIC_SIZE 4
#define MAGIC_0 0x53 // 'S'
#define MAGIC_1 0x48 // 'H'
#define MAGIC_2 0x46 // 'B'
#define MAGIC_3 0x42 // 'F'
#define CMDLINE_MIN_BUFFER_SIZE 80
#define SYS_OPEN 0x01
#define SYS_CLOSE 0x02
#define SYS_WRITEC 0x03
#define SYS_WRITE0 0x04
#define SYS_WRITE 0x05
#define SYS_READ 0x06
#define SYS_READC 0x07
#define SYS_ISERROR 0x08
#define SYS_ISTTY 0x09
#define SYS_SEEK 0x0A
#define SYS_FLEN 0x0C
#define SYS_TMPNAM 0x0D
#define SYS_REMOVE 0x0E
#define SYS_RENAME 0x0F
#define SYS_CLOCK 0x10
#define SYS_TIME 0x11
#define SYS_SYSTEM 0x12
#define SYS_ERRNO 0x13
#define SYS_GET_CMDLINE 0x15
#define SYS_HEAPINFO 0x16
#define SYS_EXIT 0x18
#define SYS_EXIT_EXTENDED 0x20
#define SYS_ELAPSED 0x30
#define SYS_TICKFREQ 0x31
// Extended features availability flags.
static bool exit_extended_available = false;
static bool split_stdout_stderr = false;
// Perform a semihosting call with the given call number and using the given
// parameters block.
int mp_semihosting_call(uint32_t num, void *arg);
// Convert the given fopen(3) open mode string into the appropriate integer
// value required by SYS_OPEN. If the mode is invalid, it will return -1.
static int mp_lookup_open_mode(const char *mode);
// Computes the length of the given string. If it gets passed a NULL pointer
// it will return -1.
static int mp_strlen(const char *string);
// Check which extended features are advertised by the host system.
static void mp_check_extended_features_availability(void);
// Write the given string to the host system's debug console.
static int mp_write_to_debug_console(const char *string, size_t length);
// The host system's STDOUT file handle.
int mp_semihosting_stdout = -1;
// The host system's STDERR file handle.
int mp_semihosting_stderr = -1;
int mp_semihosting_open(const char *file_name, const char *file_mode) {
if (file_name == NULL || file_mode == NULL) {
return -1;
}
int file_name_length = mp_strlen(file_name);
if (file_name_length <= 0) {
return -1;
}
int file_open_mode = mp_lookup_open_mode(file_mode);
if (file_open_mode < 0) {
return -1;
}
uint32_t arguments[3] = { (uintptr_t)file_name, file_open_mode, file_name_length };
return mp_semihosting_call(SYS_OPEN, arguments);
}
int mp_semihosting_close(int handle) {
uint32_t arguments[] = { handle };
return mp_semihosting_call(SYS_CLOSE, arguments);
}
void mp_semihosting_writec(char character) {
uint32_t arguments[] = { character };
mp_semihosting_call(SYS_WRITEC, arguments);
}
void mp_semihosting_write0(const char *string) {
if (string == NULL) {
return;
}
uint32_t arguments[] = { (uintptr_t)string };
mp_semihosting_call(SYS_WRITE0, arguments);
}
int mp_semihosting_write(int handle, const void *data, size_t length) {
if (data == NULL) {
return length;
}
if (length == 0) {
return 0;
}
uint32_t arguments[] = { handle, (uintptr_t)data, length };
return mp_semihosting_call(SYS_WRITE, arguments);
}
int mp_semihosting_read(int handle, void *data, size_t length) {
if (data == NULL) {
return -1;
}
if (length == 0) {
return 0;
}
uint32_t arguments[] = { handle, (uintptr_t)data, length };
return mp_semihosting_call(SYS_READ, arguments);
}
inline int mp_semihosting_readc(void) {
return mp_semihosting_call(SYS_READC, NULL);
}
int mp_semihosting_iserror(int code) {
uint32_t arguments[] = { code };
return mp_semihosting_call(SYS_ISERROR, arguments);
}
int mp_semihosting_istty(int handle) {
uint32_t arguments[] = { handle };
return mp_semihosting_call(SYS_ISTTY, arguments);
}
int mp_semihosting_seek(int handle, uint32_t offset) {
uint32_t arguments[] = { handle, offset };
return mp_semihosting_call(SYS_SEEK, arguments);
}
int mp_semihosting_flen(int handle) {
uint32_t arguments[] = { handle };
return mp_semihosting_call(SYS_FLEN, arguments);
}
int mp_semihosting_tmpnam(uint8_t identifier, void *buffer, size_t buffer_length) {
if (buffer == NULL || buffer_length == 0) {
return -1;
}
uint32_t arguments[] = { (uintptr_t)buffer, identifier, buffer_length };
return mp_semihosting_call(SYS_TMPNAM, arguments);
}
int mp_semihosting_remove(const char *file_name) {
if (file_name == NULL) {
return -1;
}
int file_name_length = mp_strlen(file_name);
if (file_name_length <= 0) {
return -1;
}
uint32_t arguments[] = { (uintptr_t)file_name, file_name_length };
return mp_semihosting_call(SYS_REMOVE, arguments);
}
int mp_semihosting_rename(const char *old_name, const char *new_name) {
if (old_name == NULL || new_name == NULL) {
return -1;
}
int old_name_length = mp_strlen(old_name);
if (old_name_length <= 0) {
return -1;
}
int new_name_length = mp_strlen(new_name);
if (new_name_length <= 0) {
return -1;
}
uint32_t arguments[] = {
(uintptr_t)old_name, old_name_length, (uintptr_t)new_name, new_name_length
};
return mp_semihosting_call(SYS_RENAME, arguments);
}
inline int mp_semihosting_clock(void) {
return mp_semihosting_call(SYS_CLOCK, NULL);
}
inline int mp_semihosting_time(void) {
return mp_semihosting_call(SYS_TIME, NULL);
}
int mp_semihosting_system(const char *command) {
if (command == NULL) {
return -1;
}
int command_length = mp_strlen(command);
if (command_length <= 0) {
return -1;
}
uint32_t arguments[] = { (uintptr_t)command, command_length };
return mp_semihosting_call(SYS_SYSTEM, arguments);
}
inline int mp_semihosting_errno(void) {
return mp_semihosting_call(SYS_ERRNO, NULL);
}
int mp_semihosting_get_cmdline(void *buffer, size_t buffer_length) {
if (buffer == NULL || buffer_length < CMDLINE_MIN_BUFFER_SIZE) {
return -1;
}
uint32_t arguments[] = { (uintptr_t)buffer, buffer_length };
return mp_semihosting_call(SYS_GET_CMDLINE, arguments);
}
void mp_semihosting_heapinfo(mp_semihosting_heap_info_t *block) {
if (block == NULL) {
return;
}
uint32_t arguments[] = { (uintptr_t)block };
mp_semihosting_call(SYS_HEAPINFO, arguments);
}
void mp_semihosting_exit(uint32_t code, uint32_t subcode) {
uint32_t arguments[] = { code, subcode };
mp_semihosting_call(SYS_EXIT, arguments);
for (;;) {}
}
void mp_semihosting_exit_extended(uint32_t code, uint32_t subcode) {
uint32_t arguments[] = { code, subcode };
mp_semihosting_call(SYS_EXIT_EXTENDED, arguments);
for (;;) {}
}
int mp_semihosting_elapsed(mp_semihosting_elapsed_ticks_t *ticks) {
if (ticks == NULL) {
return -1;
}
uint32_t arguments[] = { (uintptr_t)ticks };
return mp_semihosting_call(SYS_ELAPSED, arguments);
}
inline int mp_semihosting_tickfreq(void) {
return mp_semihosting_call(SYS_TICKFREQ, NULL);
}
void mp_semihosting_init() {
mp_check_extended_features_availability();
mp_semihosting_stdout = mp_semihosting_open(":tt", "w");
if (split_stdout_stderr) {
mp_semihosting_stderr = mp_semihosting_open(":tt", "a");
} else {
mp_semihosting_stderr = mp_semihosting_stdout;
}
}
void mp_check_extended_features_availability(void) {
int features_handle = mp_semihosting_open(":semihosting-features", "r");
if (features_handle < 0) {
return;
}
uint8_t magic_buffer[MAGIC_SIZE];
if (mp_semihosting_flen(features_handle) < sizeof(magic_buffer)) {
mp_semihosting_close(features_handle);
return;
}
if (mp_semihosting_read(features_handle, magic_buffer, sizeof(magic_buffer)) != 0) {
mp_semihosting_close(features_handle);
return;
}
if (magic_buffer[0] != MAGIC_0 ||
magic_buffer[1] != MAGIC_1 ||
magic_buffer[2] != MAGIC_2 ||
magic_buffer[3] != MAGIC_3) {
mp_semihosting_close(features_handle);
return;
}
uint8_t features_byte = 0;
if (mp_semihosting_read(features_handle, &features_byte, sizeof(features_byte)) != 0) {
mp_semihosting_close(features_handle);
return;
}
mp_semihosting_close(features_handle);
exit_extended_available = (features_byte & 0x01) != 0;
split_stdout_stderr = (features_byte & 0x02) != 0;
}
int mp_strlen(const char *string) {
int length = 0;
while (*string++ != 0) {
length += 1;
}
return length;
}
int mp_lookup_open_mode(const char *mode) {
if (mode == NULL) {
return -1;
}
int mode_found;
switch (mode[0]) {
case 'r':
mode_found = 0x00;
break;
case 'w':
mode_found = 0x04;
break;
case 'a':
mode_found = 0x08;
break;
default:
return -1;
}
switch (mode[1]) {
case 'b':
mode_found |= 0x01;
break;
case '+':
mode_found |= 0x02;
break;
case '\0':
return mode_found;
default:
return -1;
}
switch (mode[2]) {
case 'b':
if (mode_found & 0x01) {
// 'b' was already seen.
return -1;
}
mode_found |= 1;
break;
case '+':
if (mode_found & 0x02) {
// '+' was already seen.
return -1;
}
mode_found |= 2;
break;
case '\0':
return mode_found;
default:
return -1;
}
return mode[3] == '\0' ? mode_found : -1;
}
int mp_semihosting_call(uint32_t num, void *arg) {
register uint32_t call_number_register __asm__ ("x10") = num;
register void *arguments_register __asm__ ("x11") = arg;
__asm volatile (
".option push \n" // Transient options
".option norvc \n" // Do not emit compressed instructions
".align 4 \n" // 16 bytes alignment
"slli zero, zero, 0x1F \n" // Entry NOP
"ebreak \n" // Give control to the debugger
"srai zero, zero, 7 \n" // Semihosting call
".option pop \n" // Restore previous options set
: "+r" (call_number_register)
: "r" (arguments_register)
: "memory"
);
return call_number_register;
}
inline int mp_semihosting_rx_char() {
return mp_semihosting_call(SYS_READC, NULL);
}
int mp_write_to_debug_console(const char *string, size_t length) {
if (length == 0) {
return 0;
}
if (length == 1) {
mp_semihosting_writec(*string);
return 0;
}
return mp_semihosting_write(mp_semihosting_stdout, string, length);
}
void mp_semihosting_terminate(uint32_t code, uint32_t subcode) {
if (exit_extended_available) {
mp_semihosting_exit_extended(code, subcode);
} else {
mp_semihosting_exit(code, subcode);
}
}
int mp_semihosting_tx_strn(const char *string, size_t length) {
if (string == NULL) {
return -1;
}
return mp_write_to_debug_console(string, length);
}
int mp_semihosting_tx_strn_cooked(const char *string, size_t length) {
if (string == NULL) {
return -1;
}
if (length == 0) {
return 0;
}
size_t current_offset = 0;
for (size_t index = 0; index < length; index++) {
if (string[index] != '\n') {
continue;
}
mp_write_to_debug_console(string + current_offset, index - current_offset);
mp_semihosting_writec('\r');
current_offset = index;
}
return mp_write_to_debug_console(string + current_offset, length - current_offset);
}

247
shared/runtime/semihosting_rv32.h Normal file
View File

@ -0,0 +1,247 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2024 Alessandro Gatti
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef MICROPY_INCLUDED_SHARED_RUNTIME_SEMIHOSTING_RV32_H
#define MICROPY_INCLUDED_SHARED_RUNTIME_SEMIHOSTING_RV32_H
/*
* To integrate semihosting, make sure to call mp_semihosting_init() first.
* Then, if the host system's STDOUT should be used instead of a UART, replace
* mp_hal_stdin_rx_chr and similar calls in mphalport.c with the semihosting
* equivalents.
*
* At runtime, make sure that the debugger is attached and semihosting is
* enabled on its end. The terminal must be configured in raw mode with local
* echo disabled, on Linux this can be done with "stty raw -echo" on the
* command line.
*/
/*
* This follows the RISC-V Semihosting specification version 0.3.
*
* That document can be downloaded from
* https://github.com/riscv-non-isa/riscv-semihosting/releases/
*
* Version 0.3 claims that the current RISC-V Semihosting implementation
* should follow Arm's, and more precisely the "Semihosting for AArch32
* and AArch64" document, revision 2023Q3.
*/
#include <stddef.h>
#include <stdint.h>
#include <stdnoreturn.h>
// A container for heap and stack pointers as returned by SYS_HEAPINFO.
typedef struct {
void *heap_base;
void *heap_limit;
void *stack_base;
void *stack_limit;
} mp_semihosting_heap_info_t;
// A 64-bits value indicating how many ticks were counted since the target
// image's execution started.
typedef struct {
uint32_t low;
uint32_t high;
} mp_semihosting_elapsed_ticks_t;
// The host system's STDOUT file handle.
extern int mp_semihosting_stdout;
// The host system's STDERR file handle. If the host system does not support
// explicit STDOUT and STDERR handles, this handle will be aliased to STDOUT
// instead.
extern int mp_semihosting_stderr;
/*
* Even though exit codes from 0x20000 to 0x20007 are part of the original Arm
* specification document, they are omitted due to them being tied to hardware
* events. Whilst some of them may still have a meaning on the RISC-V
* platform, it is not yet clear which ones are available and which ones are
* not. Thus, only "soft" error codes are provided here although the SYS_EXIT
* and SYS_EXIT_EXTENDED semihosting calls accept any 32-bits integer as an
* exit code.
*/
enum {
MP_SEMIHOSTING_EXIT_BREAKPOINT = 0x20020,
MP_SEMIHOSTING_EXIT_WATCHPOINT,
MP_SEMIHOSTING_EXIT_STEP_COMPLETE,
MP_SEMIHOSTING_EXIT_RUNTIME_ERROR_UNKNOWN,
MP_SEMIHOSTING_EXIT_INTERNAL_ERROR,
MP_SEMIHOSTING_EXIT_USER_INTERRUPTION,
MP_SEMIHOSTING_EXIT_APPLICATION_EXIT,
MP_SEMIHOSTING_EXIT_STACK_OVERFLOW,
MP_SEMIHOSTING_EXIT_DIVISION_BY_ZERO,
MP_SEMIHOSTING_EXIT_OS_SPECIFIC
};
// Initialises semihosting support.
void mp_semihosting_init();
// Read a character from the host system's STDIN stream.
int mp_semihosting_rx_char();
// Write the given string to the host system's STDOUT stream.
int mp_semihosting_tx_strn(const char *string, size_t length);
// Write the given string to the host system's STDOUT stream, writing a CR byte
// before each LF byte to be written.
int mp_semihosting_tx_strn_cooked(const char *string, size_t length);
// Terminates execution with the given code and an optional subcode. This
// will choose the appropriate semihosting call (either SYS_EXIT or
// SYS_EXIT_EXTENDED) depending on the host system's reported capabilities.
noreturn void mp_semihosting_terminate(uint32_t code, uint32_t subcode);
// Direct semihosting calls access.
// Open a file on the host system with the given name and file mode.
// The file mode follows fopen(3)'s syntax. The function will return -1 if it
// failed to open the required file, or a file handle number if the operation
// succeeded. To see why the operation failed, call mp_semihosting_errno.
int mp_semihosting_open(const char *file_name, const char *file_mode);
// Close a file previously opened with mp_semihosting_open. If the file cannot
// be closed, the function will return -1, otherwise it will return 0. To see
// why the operation failed, call mp_semihosting_errno.
int mp_semihosting_close(int handle);
// Write the given character to the host system's STDOUT file handle.
void mp_semihosting_writec(char character);
// Write the given NULL-terminated string to the host system's STDOUT file
// handle.
void mp_semihosting_write0(const char *string);
// Write the given buffer to the given host system file handle. The function
// will return how many characters were left to be written (0 if the operation
// wrote the whole buffer), or -1 if the input buffer pointer is NULL.
int mp_semihosting_write(int handle, const void *data, size_t length);
// Read from the given host system file handle into the given buffer. The
// function will return how many characters were left to be read (0 if the
// operation read whole buffer), or -1 if the input buffer pointer is NULL.
int mp_semihosting_read(int handle, void *data, size_t length);
// Read a single character from the host system's STDIN file handle.
int mp_semihosting_readc(void);
// Check whether the given result code represents an error. The function will
// return a non-zero value if the code is indeed an error, or zero otherwise.
int mp_semihosting_iserror(int code);
// Check whether the given host system file handle is mapped to an interactive
// device. The function will return 1 if the handle is mapped to an
// interactive device, 0 if it is mapped to a regular file, and anything else
// if an error occurred.
int mp_semihosting_istty(int handle);
// Move the file pointer on the given host system's file handle to the given
// absolute offset (in bytes). The function will return 0 if the file pointer
// was moved to the requested position, or a negative value if it was not
// possible to do so. To see why the operation failed, call
// mp_semihosting_errno.
int mp_semihosting_seek(int handle, uint32_t offset);
// Get the length (in bytes) of the host system's file mapped to the given
// handle. The function will return a negative value if an error occurred, or
// the requested file's length (in bytes).
int mp_semihosting_flen(int handle);
// Create a temporary file on the host system. The function requires a file
// identifier between 0 and 255 (inclusive) that will be bound to the requested
// temporary file. Subsequent calls to mp_semihosting_tmpnam with the same
// identifier will always return the same host system file name. On success,
// the function will fill the given buffer with the host system's file name,
// and will return 0. If the buffer pointer is NULL, the buffer name area is
// too small, or the operation failed on the host system's end, the function
// will return -1 instead. Make sure that the buffer is big enough to contain
// a host system's full path name.
int mp_semihosting_tmpnam(uint8_t identifier, void *buffer, size_t buffer_length);
// Delete a file on the host system's matching the given file name. The
// function will return 0 if the deletion operation succeeded, or a host system
// dependent error code instead.
int mp_semihosting_remove(const char *file_name);
// Rename a file on the host system's name matching the given file name to the
// new chosen name. The function will return 0 if the rename operation
// succeeded, or a host system dependent error code instead.
int mp_semihosting_rename(const char *old_name, const char *new_name);
// Get how many hundredths of a second passed since execution started. If an
// error occurred whilst retrieving clock value, the function will return -1.
int mp_semihosting_clock(void);
// Get the host system's clock in seconds since midnight of January 1st, 1970
// at UTC.
int mp_semihosting_time(void);
// Execute the given command on the host system. The function will return the
// command's result code retrieved on the host system.
int mp_semihosting_system(const char *command);
// Get the last operation's status code. The function will return the host
// system's errno variable contents, and can be used to see the exact result
// code for failed I/O operations.
int mp_semihosting_errno(void);
// Get the host system's command line that started execution of the target
// image. The function will fill the given buffer with the command line
// arguments passed to the target executable. The function will return 0 on
// success, or -1 if it failed. Make sure that the buffer can contain at
// least 80 bytes, as it is the minimum supported size defined by the
// specifications document.
int mp_semihosting_get_cmdline(void *buffer, size_t buffer_length);
// Fill the given heap info structure with the system's stack and heap
// start/end addresses.
void mp_semihosting_heapinfo(mp_semihosting_heap_info_t *block);
// Terminate the execution with the given reason code and optional subcode.
// This should be preferred over mp_semihosting_exit_extended if the host
// system does not support the SYS_EXIT_EXTENDED semihosting call. In doubt
// use mp_semihosting_terminate instead.
noreturn void mp_semihosting_exit(uint32_t code, uint32_t subcode);
// Terminate the execution with the given reason code and optional subcode.
// This should be preferred over mp_semihosting_exit if the host system
// supports this semihosting call. In doubt use mp_semihosting_terminate
// instead.
noreturn void mp_semihosting_exit_extended(uint32_t code, uint32_t subcode);
// Fill the given structure with how many ticks were counted since execution
// started. On success, the function will return 0, or -1 if it was not
// possible to compute the ticks count.
int mp_semihosting_elapsed(mp_semihosting_elapsed_ticks_t *ticks);
// Get the system's tick frequency. If this value is not known, the function
// will return -1 instead.
int mp_semihosting_tickfreq(void);
#endif // MICROPY_INCLUDED_SHARED_SEMIHOSTING_RUNTIME_RV32_H