Lazuli
Data Structures | Typedefs | Functions | Variables
arch.h File Reference

Architecture Abstraction API. More...

#include <stdint.h>
#include <Lazuli/common.h>
#include <Lazuli/list.h>
#include <Lazuli/serial.h>
#include <Lazuli/sys/compiler.h>

Go to the source code of this file.

Data Structures

struct  U16DivisionResult
 Represents the result of a uin16_t division. More...
 

Typedefs

typedef uint8_t InterruptsStatus
 Define the type used to store interrupts status. More...
 

Functions

void Arch_InfiniteLoop (void)
 Function that loops forever, never returns.
 
void Arch_ResetSystem (void)
 Reset the whole system.
 
void Arch_RestoreContextAndReturnFromInterrupt (void *stackPointer)
 Restore the context of a previously saved task, and run it by returning from interrupt. More...
 
void Arch_StartRunning (void *stackPointer, size_t offsetOfPc)
 Start running the scheduler for the first time with the specified context. More...
 
void Arch_LoadFromProgmem (const void *source, void *destination, const size_t size)
 Copy bytes from program memory to RAM. More...
 
uint8_t Arch_LoadU8FromProgmem (const void *source)
 Return a byte stored in program memory. More...
 
uint16_t Arch_LoadU16FromProgmem (const void *source)
 Return a double-byte word stored in program memory. More...
 
void * Arch_LoadPointerFromProgmem (const void *source)
 Return a pointer stored in program memory. More...
 
void Arch_DisableInterrupts (void)
 Disable all interrupts.
 
void Arch_EnableInterrupts (void)
 Enable all interrupts.
 
InterruptsStatus Arch_DisableInterruptsGetStatus (void)
 Disable all interrupts and return the previous interrupts status. More...
 
void Arch_RestoreInterruptsStatus (const InterruptsStatus interruptsStatus)
 Restore a previously saved interrupts status. More...
 
bool Arch_AreInterruptsEnabled (void)
 Obtain a value indicating if global interrupts are enabled. More...
 
void Arch_InitIdleCpuMode (void)
 Initialize idle CPU modes.
 
void Arch_CpuSleep (void)
 Put the CPU to sleep according to the sleep settings.
 
void Arch_InitInstrumentation (void)
 Initialize the context switch instrumentation.
 
System timer
void Arch_InitSystemTimer (void)
 Initialize the system timer.
 
void Arch_StartSystemTimer (void)
 Start the system timer.
 
Mutex
bool Arch_TryAcquireLock (volatile uint8_t *const lock)
 Try to acquire a lock by atomically changing the value pointed by the lock parameter. More...
 
Serial
void Arch_GetSerialConfiguration (Lz_SerialConfiguration *const configuration)
 Retrieve the current configuration of the serial line. More...
 
void Arch_SetSerialConfiguration (const Lz_SerialConfiguration *const configuration)
 Configure the seria line according to the parameter. More...
 
void Arch_InitSerial (void)
 Initialize serial line with default configuration at system startup. More...
 
U16DivisionResult Arch_Divide_U16 (uint16_t numerator, uint16_t denominator)
 Perform the Euclidean division between two uint16_t operands. More...
 

Variables

void(*)(void) Arch_LoadFunctionPointerFromProgmem (const void *source)
 Return a function pointer stored in program memory. More...
 

Detailed Description

Architecture Abstraction API.

Provides a simple abstraction API to architecture specific functions. This is the API that must be re-implemented if porting to another platform.

This one is taylored after the AVR platform and can be subject to change if porting to another platform.

Definition in file arch.h.

Typedef Documentation

◆ InterruptsStatus

Define the type used to store interrupts status.

You shall ALWAYS set a variable of this type by calling Arch_DisableInterruptsGetStatus(), and NEVER modify its value manually.

Definition at line 154 of file arch.h.

Function Documentation

◆ Arch_RestoreContextAndReturnFromInterrupt()

void Arch_RestoreContextAndReturnFromInterrupt ( void *  stackPointer)

Restore the context of a previously saved task, and run it by returning from interrupt.

The context of a task is saved on its stack. Consists in restoring all of the registers (including the state register) and continue execution of the task by performing a return from interrupt, as the program counter has previously been saved on the stack by hardware.

Parameters
stackPointerThe stack pointer of the task to restore.

◆ Arch_StartRunning()

void Arch_StartRunning ( void *  stackPointer,
size_t  offsetOfPc 
)

Start running the scheduler for the first time with the specified context.

This function simply ignores all the registers in the context, and jumps directly to the saved return address.

Parameters
stackPointerThe stack pointer of the task to run, containing its prepared context.
offsetOfPcThe offset of the PC member in the TaskContextLayout structure (i.e. the saved context of the task).

◆ Arch_LoadFromProgmem()

void Arch_LoadFromProgmem ( const void *  source,
void *  destination,
const size_t  size 
)

Copy bytes from program memory to RAM.

Parameters
sourceA pointer to the source address in program memory.
destinationA pointer to the destination address in RAM.
sizeThe number of bytes to copy.

◆ Arch_LoadU8FromProgmem()

uint8_t Arch_LoadU8FromProgmem ( const void *  source)

Return a byte stored in program memory.

Warning
The return type is unsigned.
Parameters
sourceA pointer to the byte stored in program memory.
Returns
The byte value stored at the address contained in source parameter.

◆ Arch_LoadU16FromProgmem()

uint16_t Arch_LoadU16FromProgmem ( const void *  source)

Return a double-byte word stored in program memory.

Warning
The return type is unsigned.
Parameters
sourceA pointer to the word stored in program memory.
Returns
The word value stored at the address contained in source parameter.

◆ Arch_LoadPointerFromProgmem()

void* Arch_LoadPointerFromProgmem ( const void *  source)

Return a pointer stored in program memory.

Parameters
sourceA pointer to the pointer stored in program memory.
Returns
The pointer value stored at the address contained in source parameter.

◆ Arch_DisableInterruptsGetStatus()

InterruptsStatus Arch_DisableInterruptsGetStatus ( void  )

Disable all interrupts and return the previous interrupts status.

Returns
The previous global interrupts status.

◆ Arch_RestoreInterruptsStatus()

void Arch_RestoreInterruptsStatus ( const InterruptsStatus  interruptsStatus)

Restore a previously saved interrupts status.

Parameters
interruptsStatusA previously saved InterruptsStatus.

◆ Arch_AreInterruptsEnabled()

bool Arch_AreInterruptsEnabled ( void  )

Obtain a value indicating if global interrupts are enabled.

Returns
: - true if global interrupts are enabled
  • false if global interrupts are disabled

◆ Arch_TryAcquireLock()

bool Arch_TryAcquireLock ( volatile uint8_t *const  lock)

Try to acquire a lock by atomically changing the value pointed by the lock parameter.

Parameters
lockA pointer to the lock.
Returns
- true if the lock was free, hence it could be acquired
  • false if the lock wasn't free, hence it couldn't be acquired

◆ Arch_GetSerialConfiguration()

void Arch_GetSerialConfiguration ( Lz_SerialConfiguration *const  configuration)

Retrieve the current configuration of the serial line.

Parameters
configurationA pointer to an allocated Lz_SerialConfiguration used to store the configuration.

Definition at line 441 of file usart.c.

◆ Arch_SetSerialConfiguration()

void Arch_SetSerialConfiguration ( const Lz_SerialConfiguration *const  configuration)

Configure the seria line according to the parameter.

Parameters
configurationA pointer to an existing Lz_SerialConfiguration containg the full configuration to set up the serial line.

Definition at line 451 of file usart.c.

◆ Arch_InitSerial()

void Arch_InitSerial ( void  )

Initialize serial line with default configuration at system startup.

< member: enableFlags

< member: stopBits

< member: parityBits

< member: size

< member: speed

Definition at line 480 of file usart.c.

◆ Arch_Divide_U16()

U16DivisionResult Arch_Divide_U16 ( uint16_t  numerator,
uint16_t  denominator 
)

Perform the Euclidean division between two uint16_t operands.

Parameters
numeratorThe numerator of the division.
denominatorThe denominator of the division.
Returns
A U16DivisionResult by value. The strange function prototype is inherited from libc's div().
Warning
As no hardware exception is provided on the AVR architecture. This function is written to never fail, even if you perform a division by zero. In that case the return value will be filled with zeros. So check the denominator before calling this function.

Variable Documentation

◆ Arch_LoadFunctionPointerFromProgmem

void(*)(void) Arch_LoadFunctionPointerFromProgmem(const void *source)

Return a function pointer stored in program memory.

Warning
To use this function with a different prototype than void (*)(void), the return value must be cast to the appropriate function pointer type. We can't use Arch_LoadPointerFromProgmem() to do the same thing because ISO C forbids assignment between function pointer and 'void *', and conversion of object pointer to function pointer type.
Parameters
sourceA pointer to the function pointer stored in program memory.
Returns
The function pointer value stored at the address contained in source parameter.

Definition at line 133 of file arch.h.