12 Debug Console Extension (EID #0x4442434E "DBCN")

The debug console extension defines a generic mechanism for debugging and boot-time early prints from supervisor-mode software.

This extension replaces the legacy console putchar (EID #0x01) and console getchar (EID #0x02) extensions. The debug console extension allows supervisor-mode software to write or read multiple bytes in a single SBI call.

If the underlying physical console has extra bits for error checking (or correction) then these extra bits should be handled by the SBI implementation.

note

It is recommended that bytes sent/received using the debug console extension follow UTF-8 character encoding.

12.1 Function: Console Write (FID #0)

struct sbiret sbi_debug_console_write(unsigned long num_bytes,
                                      unsigned long base_addr_lo,
                                      unsigned long base_addr_hi)

Write bytes to the debug console from input memory.

The num_bytes parameter specifies the number of bytes in the input memory. The physical base address of the input memory is represented by two XLEN bits wide parameters. The base_addr_lo parameter specifies the lower XLEN bits and the base_addr_hi parameter specifies the upper XLEN bits of the input memory physical base address.

This is a non-blocking SBI call and it may do partial/no writes if the debug console is not able to accept more bytes.

The number of bytes written is returned in sbiret.uvalue and the possible error codes returned in sbiret.error are shown in Table 50 below.

Table 50. Debug Console Write Errors

Error code	Description
SBI_SUCCESS	Bytes written successfully.
SBI_ERR_INVALID_PARAM	The memory pointed to by the num_bytes, base_addr_lo, and base_addr_hi parameters does not satisfy the requirements described in the Section 3.2
SBI_ERR_DENIED	Writes to the debug console is not allowed.
SBI_ERR_FAILED	Failed to write due to I/O errors.

12.2 Function: Console Read (FID #1)

struct sbiret sbi_debug_console_read(unsigned long num_bytes,
                                      unsigned long base_addr_lo,
                                      unsigned long base_addr_hi)

Read bytes from the debug console into an output memory.

The num_bytes parameter specifies the maximum number of bytes which can be written into the output memory. The physical base address of the output memory is represented by two XLEN bits wide parameters. The base_addr_lo parameter specifies the lower XLEN bits and the base_addr_hi parameter specifies the upper XLEN bits of the output memory physical base address.

This is a non-blocking SBI call and it will not write anything into the output memory if there are no bytes to be read in the debug console.

The number of bytes read is returned in sbiret.uvalue and the possible error codes returned in sbiret.error are shown in Table 51 below.

Table 51. Debug Console Read Errors

Error code	Description
SBI_SUCCESS	Bytes read successfully.
SBI_ERR_INVALID_PARAM	The memory pointed to by the num_bytes, base_addr_lo, and base_addr_hi parameters does not satisfy the requirements described in the Section 3.2
SBI_ERR_DENIED	Reads from the debug console is not allowed.
SBI_ERR_FAILED	Failed to read due to I/O errors.

12.3 Function: Console Write Byte (FID #2)

struct sbiret sbi_debug_console_write_byte(uint8_t byte)

Write a single byte to the debug console.

This is a blocking SBI call and it will only return after writing the specified byte to the debug console. It will also return, with SBI_ERR_FAILED, if there are I/O errors.

The sbiret.uvalue is set to zero and the possible error codes returned in sbiret.error are shown in Table 52 below.

Table 52. Debug Console Write Byte Errors

Error code	Description
SBI_SUCCESS	Byte written successfully.
SBI_ERR_DENIED	Write to the debug console is not allowed.
SBI_ERR_FAILED	Failed to write the byte due to I/O errors.

12.4 Function Listing

Table 53. DBCN Function List

Function Name	SBI Version	FID	EID
sbi_debug_console_write	2.0	0	0x4442434E
sbi_debug_console_read	2.0	1	0x4442434E
sbi_debug_console_write_byte	2.0	2	0x4442434E