Skip to content

Latest commit

 

History

History
144 lines (107 loc) · 7.07 KB

chapter2.adoc

File metadata and controls

144 lines (107 loc) · 7.07 KB
Raw

The C HAL API

General Principles

Discovery of Fixed Platform Characteristics at Run-time

Since we assume that code is built for a specific platform, it is undesirable to use function-calls (rather than macros) to discover fixed platform characteristics; since this constitutes an unnecessary overhead. However, there may be circumstances where a BSP implementation wishes to supply code for this purpose. For this reason, APIs for discovery of some fixed platform characteristics have been implemented to look like a function call. The assumption is that in most cases these function calls can be optimized out by the compiler, leaving no overhead.

Distribution in Binary or Source Code Form

BSPs may be supplied either as source code, which the user builds into their system, or as a pre-built binary library. To support the latter case, pre-processor directives that are intended to change BSP behaviour (as listed in Global Definitions Set By Application Writers) must only be used in header files, not within the compiled C-code.

Thread Safety

All API functions shall be implemented in a way that supports simultaneous calls from multiple cores or software threads. This is supported through the use of an initialisation function which allocates a separate context space for each instance.

The single exception to this is the high-level console API.

Header Files

"Top-level" header files which would normally be included by application writers are indicated in bold in the table below. Others listed here are included from the top-level ones.

Header Supplied by Contents

csi_types.h

API

General-purpose definitions such as return codes, included from many other headers.

csi_ll.h

API

Low-level HAL API

csi_ll_csrs.h

API

Standard CSR definitions (auto-generated according to the RISC-V spec)

csi_ll_bsp_csrs.h

BSP

Custom CSR definitions

csi_ll_bsp_perip.h

BSP

Peripheral register definitions

csi_hl_interrupt_sources.h

API

Enumeration of standard interrupt sources

csi_hl_bsp_interrupts.h

BSP

Enumeration of platform-specific interrupt sources in the system

csi_ll_bsp_defs.h

BSP

Required macros to supplied by the BSP, picked up inline functions within API headers.

csi_hl_interrupts.h

API

High-level interrupt and timer API

csi_dl_uart.h

API

UART control API

csi_dl_bsp_uart.h

BSP

Declaration of UART instance context structure

csi_hl_console.h

API

High-level console API

All header files must be protected against multiple inclusion, by means of a define which takes the form of a capitalised version of the file name, with special characters replaced by underscores. For example a header file csi_ll_bsp_csrs.h will have contents of the form:

#ifndef CSI_LL_BSP_CSRS_H
#define CSI_LL_BSP_CSRS_H

// ... file contents

#endif // CSI_LL_BSP_CSRS_H

Definitions set by BSPs

The following macros must be defined by BSP authors and exposed in the specified header files:

Context Sizes

Some modules within the API will require a context space allocated via an initialisation function. BSPs will publish macros defining the required size of each such context space in bytes, either in csi_ll_bsp_defs.h or in the same header as the associated initialisation function.

CSRs (Control and Status Registers)

csi_ll_csrs.h lists indices and bitfield information for all the standard RISC-V CSRs. This file will be auto-generated from the repo https://github.com/riscv/riscv-opcodes, which acts as a Single Source of Truth for this information. Accordingly, the contents will align with https://github.com/riscv-software-src/riscv-isa-sim/blob/master/riscv/encoding.h (which forms part of the spike simulator).

In addition, csi_ll_bsp_csrs.h should enumerate all custom CSR names, addresses and bit-fields in a similar way. Custom CSR indices are prefixed CCSR_. Bit shifts for fields within custom CSRs are prefixed CCSR_SHIFT_, and masks for bitfields within custom CSRs are prefixed CCSR_MASK_.

Peripheral Registers

csi_ll_bsp_perip.h should publish macros listing all peripheral register names, addresses and bit-fields.

Peripheral register address definitions are prefixed PERIP_. Shifts and masks for bit-fields within those registers are prefixed PERIP_SHIFT_ and PERIP_MASK_ respectively.

Interrupts

csi_hl_interrupt_sources.h enumerates a set of standard interrupt sources, such as system timer, and hardware-generated exceptions.

csi_hl_bsp_interrupts.h should enumerate all platform-specific interrupts in the system, giving them unique identification numbers that follow on from the interrupt numbers in csi_hl_interrupt_sources.h.

The numerical values of these enumerations bear no relationship to hardware; they are simply unique numbers assigned arbitrarily to the interrupt sources, allowing them to be indexed by the software. The enumerations are prefixed INT_.

csi_hl_bsp_interrupts.h should also define the following macros and types:

Definition Type Purpose

CSI_MAX_INTERRUPT_PRIORITY

Macro

Number of of non-zero interrupt priorities available.

CSI_MAX_INTERRUPT_LEVEL

Macro

Number of non-zero interrupt levels available, or 0 if interrupt levels are not supported.

CSI_INTERRUPT_MCTX_MIN_SIZE_BYTES

Macro

Minimum size of M-mode context space for interrupt sub-system.

csi_timeout_t

struct

Context structure associated with a timeout.

(Note: interrupt priorities determine the order in which simultaneous interrupts at a given privilege level are handled, while interrupt levels determine which interrupts can preempt others, if supported: see interrupts module for details).

Global Definitions Set By Application Writers

The following macros may be defined globally by application writers, in order to change the behaviour of the underlying BSP code:

Macro Possible values Purpose

CSI_UPRINT_OUTPUT

CSI_UPRINTF_NONE / CSI_UPRINTF_SEMIHOST / CSI_UPRINTF_UART / CSI_UPRINTF_CIRCBUFF

Determines the text output mode of the csi_uprintf function.

  • CSI_UPRINTF_NONE=function has no effect;

  • CSI_UPRINTF_SEMIHOST=function routes to semihosting if available;

  • CSI_UPRINTF_UART=function routes to UART;

  • CSI_UPRINTF_CIRCBUFF=function routes to circular buffer.

See csi_uprintf (high-level console API) description for details. If the macro is undefined, behaviour defaults to CSI_UPRINTF_SEMIHOST, in which case behaviour is undefined if a semihosting mechanism is unavailable.

CSI_LOG_LEVEL

CSI_LOG_LEVEL_ERR / CSI_LOG_LEVEL_WARN / CSI_LOG_LEVEL_INFO / CSI_LOG_LEVEL_NONE

Determines the behaviour of the macros CSI_LOG_ERR, CSI_LOG_WARN and CSI_LOG_INFO. See documentation of these macros for details.