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.

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.
void	Arch_StartRunning (void *stackPointer, size_t offsetOfPc)
	Start running the scheduler for the first time with the specified context.
void	Arch_LoadFromProgmem (const void *source, void *destination, const size_t size)
	Copy bytes from program memory to RAM.
uint8_t	Arch_LoadU8FromProgmem (const void *source)
	Return a byte stored in program memory.
uint16_t	Arch_LoadU16FromProgmem (const void *source)
	Return a double-byte word stored in program memory.
void *	Arch_LoadPointerFromProgmem (const void *source)
	Return a pointer stored in program memory.
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.
void	Arch_RestoreInterruptsStatus (const InterruptsStatus interruptsStatus)
	Restore a previously saved interrupts status.
bool	Arch_AreInterruptsEnabled (void)
	Obtain a value indicating if global interrupts are enabled.
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.
Serial
void	Arch_GetSerialConfiguration (Lz_SerialConfiguration *const configuration)
	Retrieve the current configuration of the serial line.
void	Arch_SetSerialConfiguration (const Lz_SerialConfiguration *const configuration)
	Configure the serial line according to the parameter.
void	Arch_InitSerial (void)
	Initialize serial line with default configuration at system startup.
U16DivisionResult	Arch_Divide_U16 (uint16_t numerator, uint16_t denominator)
	Perform the Euclidean division between two uint16_t operands.

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

Detailed Description

Architecture Abstraction API.

Copyright

2017-2020, Remi Andruccioli remi..nosp@m.andr.nosp@m.uccio.nosp@m.li@g.nosp@m.mail..nosp@m.com

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 tailored after the AVR platform and can be subject to change if porting to another platform.

Definition in file arch.h.

Typedef Documentation

InterruptsStatus

typedef uint8_t 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

stackPointer

The 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

stackPointer	The stack pointer of the task to run, containing its prepared context.
offsetOfPc	The 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

source	A pointer to the source address in program memory.
destination	A pointer to the destination address in RAM.
size	The 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

source

A 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

source

A 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

source

A 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

interruptsStatus

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

void Arch_InitIdleCpuMode

(

void

)

Initialize idle CPU modes.

Definition at line 27 of file arch.c.

Arch_CpuSleep()

void Arch_CpuSleep

(

void

)

Put the CPU to sleep according to the sleep settings.

Definition at line 60 of file arch.c.

Arch_InitInstrumentation()

void Arch_InitInstrumentation

(

void

)

Initialize the context switch instrumentation.

Definition at line 69 of file arch.c.

Arch_InitSystemTimer()

void Arch_InitSystemTimer

(

void

)

Initialize the system timer.

Definition at line 33 of file timer_counter_1.c.

Arch_StartSystemTimer()

void Arch_StartSystemTimer

(

void

)

Start the system timer.

Definition at line 48 of file timer_counter_1.c.

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

lock	A 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

configuration

A 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 serial line according to the parameter.

Parameters

configuration

A pointer to an existing Lz_SerialConfiguration containing 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

numerator	The numerator of the division.
denominator	The 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)

(

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

source

A 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.