CPU

API for accessing CPU capabilities.

Typedefs

typedef void (*metal_exception_handler_t)(struct metal_cpu *cpu, int ecode)

Function signature for exception handlers.

Functions

struct metal_cpu *metal_cpu_get(unsigned int hartid)

Get a reference to a CPU hart.

Return

A pointer to the CPU device handle

Parameters

  • hartid: The ID of the desired CPU hart

int metal_cpu_get_current_hartid(void)

Get the hartid of the CPU hart executing this function.

Return

The hartid of the current CPU hart

int metal_cpu_get_num_harts(void)

Get the number of CPU harts.

Return

The number of CPU harts

__inline__ unsigned long long metal_cpu_get_timer(struct metal_cpu *cpu)

Get the CPU cycle count timer value.

Get the value of the cycle count timer for a given CPU

Return

The value of the CPU cycle count timer

Parameters

  • cpu: The CPU device handle

__inline__ unsigned long long metal_cpu_get_timebase(struct metal_cpu *cpu)

Get the timebase of the CPU.

Get the value of the timebase of the cycle count timer

Return

The value of the cycle count timer timebase

Parameters

  • cpu: The CPU device handle

__inline__ unsigned long long metal_cpu_get_mtime(struct metal_cpu *cpu)

Get the value of the mtime RTC.

Get the value of the mtime real-time clock. The CPU interrupt controller must be initialized before this function is called or the return value will be 0.

Return

The value of mtime, or 0 if failure

Parameters

  • cpu: The CPU device handle

__inline__ int metal_cpu_set_mtimecmp(struct metal_cpu *cpu, unsigned long long time)

Set the value of the RTC mtimecmp RTC.

Set the value of the mtime real-time clock compare register. The CPU interrupt controller must be initialized before this function is called or the return value will be -1;

Return

The value of mtimecmp or -1 if error

Parameters

  • cpu: The CPU device handle

  • time: The value to set the compare register to

__inline__ struct metal_interrupt *metal_cpu_timer_interrupt_controller(struct metal_cpu *cpu)

Get a reference to RTC timer interrupt controller.

Get a reference to the interrupt controller for the real-time clock interrupt. The controller returned by this function must be initialized before any interrupts are registered or enabled with it.

Return

A pointer to the timer interrupt handle

Parameters

  • cpu: The CPU device handle

__inline__ int metal_cpu_timer_get_interrupt_id(struct metal_cpu *cpu)

Get the RTC timer interrupt id.

Get the interrupt ID of the real-time clock interrupt

Return

The timer interrupt ID

Parameters

  • cpu: The CPU device handle

__inline__ struct metal_interrupt *metal_cpu_software_interrupt_controller(struct metal_cpu *cpu)

Get a reference to the software interrupt controller.

Get a reference to the interrupt controller for the software/inter-process interrupt. The controller returned by this function must be initialized before any interrupts are registered or enabled with it.

Return

A pointer to the software interrupt handle

Parameters

  • cpu: The CPU device handle

__inline__ int metal_cpu_software_get_interrupt_id(struct metal_cpu *cpu)

Get the software interrupt id.

Get the interrupt ID for the software/inter-process interrupt

Return

the software interrupt ID

Parameters

  • cpu: The CPU device handle

__inline__ int metal_cpu_software_set_ipi(struct metal_cpu *cpu, int hartid)

Set the inter-process interrupt for a hart.

Trigger a software/inter-process interrupt for a hart. The CPU interrupt controller for the CPU handle passed to this function must be initialized before this function is called.

Return

0 upon success

Parameters

  • cpu: The CPU device handle

  • hartid: The CPU hart ID to be interrupted

__inline__ int metal_cpu_software_clear_ipi(struct metal_cpu *cpu, int hartid)

Clear the inter-process interrupt for a hart.

Clear the software/inter-process interrupt for a hart. The CPU interrupt controller for the CPU handle passed to this function must be initialized before this function is called.

Return

0 upon success

Parameters

  • cpu: The CPU device handle

  • hartid: The CPU hart ID to clear

__inline__ int metal_cpu_get_msip(struct metal_cpu *cpu, int hartid)

Get the value of MSIP for the given hart.

Get the value of the machine software interrupt pending bit for the given hart. The CPU interrupt controller for the CPU handle passed as argument to this function must be initialized before this function is called.

Return

0 upon success

Parameters

  • cpu: the CPU device handle

  • hartid: The CPU hart to read

__inline__ struct metal_interrupt *metal_cpu_interrupt_controller(struct metal_cpu *cpu)

Get the interrupt controller for the CPU.

Get the CPU interrupt controller. The controller returned by this function must be initialized before any interrupts are registered or enabled and before any exception handlers are registered with this CPU.

Return

The handle for the CPU interrupt controller

Parameters

  • cpu: The CPU device handle

__inline__ int metal_cpu_exception_register(struct metal_cpu *cpu, int ecode, metal_exception_handler_t handler)

Register an exception handler.

Register an exception handler for the CPU. The CPU interrupt controller must be initialized before this function is called.

Return

0 upon success

Parameters

  • cpu: The CPU device handle

  • ecode: The exception code to register a handler for

  • handler: Callback function for the exception handler

__inline__ int metal_cpu_get_instruction_length(struct metal_cpu *cpu, uintptr_t epc)

Get the length of an instruction in bytes.

Get the length of an instruction in bytes.

On RISC-V platforms, this is useful for detecting whether an instruction is compressed (2 bytes long) or uncompressed (4 bytes long).

This function is useful in conjuction with metal_cpu_get_exception_pc() and metal_cpu_set_exception_pc() in order to cause the exception handler to return execution after the faulting instruction.

Return

the length of the instruction in bytes

Parameters

  • cpu: The CPU device handle

  • epc: The address of the instruction to measure

__inline__ uintptr_t metal_cpu_get_exception_pc(struct metal_cpu *cpu)

Get the program counter of the current exception.

This function must be called within an exception handler. The behavior is undefined outside of an exception handler.

Return

The value of the program counter at the time of the exception

Parameters

  • cpu: The CPU device handle

__inline__ int metal_cpu_set_exception_pc(struct metal_cpu *cpu, uintptr_t epc)

Set the exception program counter.

This function must be called within an exception handler. The behavior is undefined outside of an exception handler.

This function can be used to cause an exception handler to return execution to an address other than the one that caused the exception.

Return

0 upon success

Parameters

  • cpu: the CPU device handle

  • epc: The address to set the exception program counter to

__inline__ struct metal_buserror *metal_cpu_get_buserror(struct metal_cpu *cpu)

Get the handle for the hart’s bus error unit.

Return

A pointer to the bus error unit handle

Parameters

  • cpu: The CPU device handle

struct metal_cpu
#include <cpu.h>

A device handle for a CPU hart.