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(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()

Get the hartid of the CPU hart executing this function.

Return
The hartid of the current CPU hart

int metal_cpu_get_num_harts()

Get the number of CPU harts.

Return
The number of CPU harts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

struct metal_cpu
#include <cpu.h>

A device handle for a CPU hart.