sbi_rt/
dbcn.rs

1//! Chapter 12. Debug Console Extension (EID #0x4442434E "DBCN")
2use crate::binary::{sbi_call_1, sbi_call_3};
3use sbi_spec::{
4    binary::{Physical, SbiRet},
5    dbcn::{CONSOLE_READ, CONSOLE_WRITE, CONSOLE_WRITE_BYTE, EID_DBCN},
6};
7
8/// Write bytes to the debug console from input memory.
9///
10/// # Parameters
11///
12/// The `bytes` parameter specifies the input memory, including its length
13/// and memory physical base address (both lower and upper bits).
14///
15/// # Non-blocking function
16///
17/// This is a non-blocking SBI call, and it may do partial or no write operations if
18/// the debug console is not able to accept more bytes.
19///
20/// # Return value
21///
22/// The number of bytes written is returned in `SbiRet.value` and the
23/// possible return error codes returned in `SbiRet.error` are shown in
24/// the table below:
25///
26/// | Return code               | Description
27/// |:--------------------------|:----------------------------------------------
28/// | `SbiRet::success()`       | Bytes written successfully.
29/// | `SbiRet::invalid_param()` | The memory pointed to by `bytes` does not satisfy the requirements described in shared memory physical address range.
30/// | `SbiRet::failed()`        | Failed to write due to I/O errors.
31///
32/// This function is defined in RISC-V SBI Specification chapter 12.1.
33#[inline]
34#[doc(alias = "sbi_debug_console_write")]
35pub fn console_write(bytes: Physical<&[u8]>) -> SbiRet {
36    sbi_call_3(
37        EID_DBCN,
38        CONSOLE_WRITE,
39        bytes.num_bytes(),
40        bytes.phys_addr_lo(),
41        bytes.phys_addr_hi(),
42    )
43}
44
45/// Read bytes from the debug console into an output memory.
46///
47/// # Parameters
48///
49/// The `bytes` parameter specifies the output memory, including the maximum
50/// bytes which can be written, and its memory physical base address
51/// (both lower and upper bits).
52///
53/// # Non-blocking function
54///
55/// This is a non-blocking SBI call, and it will not write anything
56/// into the output memory if there are no bytes to be read in the
57/// debug console.
58///
59/// # Return value
60///
61/// The number of bytes read is returned in `SbiRet.value` and the
62/// possible return error codes returned in `SbiRet.error` are shown in
63/// the table below:
64///
65/// | Return code               | Description
66/// |:--------------------------|:----------------------------------------------
67/// | `SbiRet::success()`       | Bytes read successfully.
68/// | `SbiRet::invalid_param()` | The memory pointed to by `bytes` does not satisfy the requirements described in shared memory physical address range.
69/// | `SbiRet::failed()`        | Failed to read due to I/O errors.
70///
71/// This function is defined in RISC-V SBI Specification chapter 12.2.
72#[doc(alias = "sbi_debug_console_read")]
73pub fn console_read(bytes: Physical<&mut [u8]>) -> SbiRet {
74    sbi_call_3(
75        EID_DBCN,
76        CONSOLE_READ,
77        bytes.num_bytes(),
78        bytes.phys_addr_lo(),
79        bytes.phys_addr_hi(),
80    )
81}
82
83/// Write a single byte to the debug console.
84///
85/// # Blocking function
86///
87/// This is a blocking SBI call, and it will only return after writing
88/// the specified byte to the debug console. It will also return with
89/// `SbiRet::failed()` if there are I/O errors.
90/// # Return value
91///
92/// The `SbiRet.value` is set to zero, and the possible return error
93/// codes returned in `SbiRet.error` are shown in the table below:
94///
95/// | Return code               | Description
96/// |:--------------------------|:----------------------------------------------
97/// | `SbiRet::success()`       | Byte written successfully.
98/// | `SbiRet::failed()`        | Failed to write the byte due to I/O errors.
99///
100/// This function is defined in RISC-V SBI Specification chapter 12.3.
101#[inline]
102#[doc(alias = "sbi_debug_console_write_byte")]
103pub fn console_write_byte(byte: u8) -> SbiRet {
104    sbi_call_1(EID_DBCN, CONSOLE_WRITE_BYTE, byte as usize)
105}
sbi_rt/dbcn.rs

sbi_rt/
dbcn.rs
