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]
34pub fn console_write(bytes: Physical<&[u8]>) -> SbiRet {
35    sbi_call_3(
36        EID_DBCN,
37        CONSOLE_WRITE,
38        bytes.num_bytes(),
39        bytes.phys_addr_lo(),
40        bytes.phys_addr_hi(),
41    )
42}
43
44/// Read bytes from the debug console into an output memory.
45///
46/// # Parameters
47///
48/// The `bytes` parameter specifies the output memory, including the maximum
49/// bytes which can be written, and its memory physical base address
50/// (both lower and upper bits).
51///
52/// # Non-blocking function
53///
54/// This is a non-blocking SBI call, and it will not write anything
55/// into the output memory if there are no bytes to be read in the
56/// debug console.
57///
58/// # Return value
59///
60/// The number of bytes read is returned in `SbiRet.value` and the
61/// possible return error codes returned in `SbiRet.error` are shown in
62/// the table below:
63///
64/// | Return code               | Description
65/// |:--------------------------|:----------------------------------------------
66/// | `SbiRet::success()`       | Bytes read successfully.
67/// | `SbiRet::invalid_param()` | The memory pointed to by `bytes` does not satisfy the requirements described in shared memory physical address range.
68/// | `SbiRet::failed()`        | Failed to read due to I/O errors.
69///
70/// This function is defined in RISC-V SBI Specification chapter 12.2.
71pub fn console_read(bytes: Physical<&mut [u8]>) -> SbiRet {
72    sbi_call_3(
73        EID_DBCN,
74        CONSOLE_READ,
75        bytes.num_bytes(),
76        bytes.phys_addr_lo(),
77        bytes.phys_addr_hi(),
78    )
79}
80
81/// Write a single byte to the debug console.
82///
83/// # Blocking function
84///
85/// This is a blocking SBI call, and it will only return after writing
86/// the specified byte to the debug console. It will also return with
87/// `SbiRet::failed()` if there are I/O errors.
88/// # Return value
89///
90/// The `SbiRet.value` is set to zero, and the possible return error
91/// codes returned in `SbiRet.error` are shown in the table below:
92///
93/// | Return code               | Description
94/// |:--------------------------|:----------------------------------------------
95/// | `SbiRet::success()`       | Byte written successfully.
96/// | `SbiRet::failed()`        | Failed to write the byte due to I/O errors.
97///
98/// This function is defined in RISC-V SBI Specification chapter 12.3.
99#[inline]
100pub fn console_write_byte(byte: u8) -> SbiRet {
101    sbi_call_1(EID_DBCN, CONSOLE_WRITE_BYTE, byte as usize)
102}
sbi_rt/dbcn.rs

sbi_rt/
dbcn.rs
