qmk_firmware/internals_group_sam0_utils.md

group group_sam0_utils

Compiler abstraction layer and code utilities for Cortex-M0+ based Atmel SAM devices. This module provides various abstraction layers and utilities to make code compatible between different compilers.

Summary

Members	Descriptions
define UNUSED	Marking v as a unused parameter or value.
define barrier	Memory barrier.
define COMPILER_PRAGMA	Emit the compiler pragma arg.
define COMPILER_PACK_SET	Set maximum alignment for subsequent struct and union definitions to alignment.
define COMPILER_PACK_RESET	Set default alignment for subsequent struct and union definitions.
define Assert	This macro is used to test fatal errors.
define Long_call	Calls the routine at address addr.
define div_ceil	Calculate $ \left\lceil \frac{a}{b} \right\rceil $ using integer arithmetic.
define FUNC_PTR
define unused	Marking v as a unused parameter or value.
define MSB	Most significant byte of u16.
define LSB	Least significant byte of u16.
define MSH	Most significant half-word of u32.
define LSH	Least significant half-word of u32.
define MSB0W	Most significant byte of 1st rank of u32.
define MSB1W	Most significant byte of 2nd rank of u32.
define MSB2W	Most significant byte of 3rd rank of u32.
define MSB3W	Most significant byte of 4th rank of u32.
define LSB3W	Least significant byte of 4th rank of u32.
define LSB2W	Least significant byte of 3rd rank of u32.
define LSB1W	Least significant byte of 2nd rank of u32.
define LSB0W	Least significant byte of 1st rank of u32.
define MSW	Most significant word of u64.
define LSW	Least significant word of u64.
define MSH0	Most significant half-word of 1st rank of u64.
define MSH1	Most significant half-word of 2nd rank of u64.
define MSH2	Most significant half-word of 3rd rank of u64.
define MSH3	Most significant half-word of 4th rank of u64.
define LSH3	Least significant half-word of 4th rank of u64.
define LSH2	Least significant half-word of 3rd rank of u64.
define LSH1	Least significant half-word of 2nd rank of u64.
define LSH0	Least significant half-word of 1st rank of u64.
define MSB0D	Most significant byte of 1st rank of u64.
define MSB1D	Most significant byte of 2nd rank of u64.
define MSB2D	Most significant byte of 3rd rank of u64.
define MSB3D	Most significant byte of 4th rank of u64.
define MSB4D	Most significant byte of 5th rank of u64.
define MSB5D	Most significant byte of 6th rank of u64.
define MSB6D	Most significant byte of 7th rank of u64.
define MSB7D	Most significant byte of 8th rank of u64.
define LSB7D	Least significant byte of 8th rank of u64.
define LSB6D	Least significant byte of 7th rank of u64.
define LSB5D	Least significant byte of 6th rank of u64.
define LSB4D	Least significant byte of 5th rank of u64.
define LSB3D	Least significant byte of 4th rank of u64.
define LSB2D	Least significant byte of 3rd rank of u64.
define LSB1D	Least significant byte of 2nd rank of u64.
define LSB0D	Least significant byte of 1st rank of u64.
define LSB0	Least significant byte of 1st rank of u32.
define LSB1	Least significant byte of 2nd rank of u32.
define LSB2	Least significant byte of 3rd rank of u32.
define LSB3	Least significant byte of 4th rank of u32.
define MSB3	Most significant byte of 4th rank of u32.
define MSB2	Most significant byte of 3rd rank of u32.
define MSB1	Most significant byte of 2nd rank of u32.
define MSB0	Most significant byte of 1st rank of u32.
define FLASH_DECLARE
define FLASH_EXTERN
define PGM_READ_BYTE
define PGM_READ_WORD
define MEMCPY_ENDIAN
define PGM_READ_BLOCK
define CMD_ID_OCTET
define CPU_ENDIAN_TO_LE16
define CPU_ENDIAN_TO_LE32
define CPU_ENDIAN_TO_LE64
define LE16_TO_CPU_ENDIAN
define LE32_TO_CPU_ENDIAN
define LE64_TO_CPU_ENDIAN
define CLE16_TO_CPU_ENDIAN
define CLE32_TO_CPU_ENDIAN
define CLE64_TO_CPU_ENDIAN
define CCPU_ENDIAN_TO_LE16
define CCPU_ENDIAN_TO_LE32
define CCPU_ENDIAN_TO_LE64
define ADDR_COPY_DST_SRC_16
define ADDR_COPY_DST_SRC_64
public inline static void convert_64_bit_to_byte_array(uint64_t value,uint8_t * data)	Converts a 64-Bit value into a 8 Byte array.
public inline static void convert_16_bit_to_byte_array(uint16_t value,uint8_t * data)	Converts a 16-Bit value into a 2 Byte array.
public inline static void convert_spec_16_bit_to_byte_array(uint16_t value,uint8_t * data)
public inline static void convert_16_bit_to_byte_address(uint16_t value,uint8_t * data)
public inline static uint16_t convert_byte_array_to_16_bit(uint8_t * data)
public inline static uint32_t convert_byte_array_to_32_bit(uint8_t * data)
public inline static uint64_t convert_byte_array_to_64_bit(uint8_t * data)	Converts a 8 Byte array into a 64-Bit value.
struct StructPtr	Structure of pointers to 64-, 32-, 16- and 8-bit unsigned integers.
struct StructVPtr	Structure of pointers to volatile 64-, 32-, 16- and 8-bit unsigned integers.
struct StructCPtr	Structure of pointers to constant 64-, 32-, 16- and 8-bit unsigned integers.
struct StructCVPtr	Structure of pointers to constant volatile 64-, 32-, 16- and 8-bit unsigned integers.
union Union16	16-bit union.
union Union32	32-bit union.
union Union64	64-bit union.
union UnionPtr	Union of pointers to 64-, 32-, 16- and 8-bit unsigned integers.
union UnionVPtr	Union of pointers to volatile 64-, 32-, 16- and 8-bit unsigned integers.
union UnionCPtr	Union of pointers to constant 64-, 32-, 16- and 8-bit unsigned integers.
union UnionCVPtr	Union of pointers to constant volatile 64-, 32-, 16- and 8-bit unsigned integers.

Members

define UNUSED

Marking v as a unused parameter or value.

define barrier

Memory barrier.

define COMPILER_PRAGMA

Emit the compiler pragma arg.

Parameters

• arg The pragma directive as it would appear after #pragma (i.e. not stringified).

define COMPILER_PACK_SET

Set maximum alignment for subsequent struct and union definitions to alignment.

define COMPILER_PACK_RESET

Set default alignment for subsequent struct and union definitions.

define Assert

This macro is used to test fatal errors.

The macro tests if the expression is false. If it is, a fatal error is detected and the application hangs up. If TEST_SUITE_DEFINE_ASSERT_MACRO is defined, a unit test version of the macro is used, to allow execution of further tests after a false expression.

Parameters

• expr Expression to evaluate and supposed to be nonzero.

define Long_call

Calls the routine at address addr.

It generates a long call opcode.

For example, Long_call(0x80000000) generates a software reset on a UC3 if it is invoked from the CPU supervisor mode.

Parameters

• addr Address of the routine to call.

It may be used as a long jump opcode in some special cases.

define div_ceil

Calculate $ \left\lceil \frac{a}{b} \right\rceil $ using integer arithmetic.

Parameters

• a An integer

• b Another integer

Returns

(a / b) rounded up to the nearest integer.

define FUNC_PTR

define unused

Marking v as a unused parameter or value.

define MSB

Most significant byte of u16.

define LSB

Least significant byte of u16.

define MSH

Most significant half-word of u32.

define LSH

Least significant half-word of u32.

define MSB0W

Most significant byte of 1st rank of u32.

define MSB1W

Most significant byte of 2nd rank of u32.

define MSB2W

Most significant byte of 3rd rank of u32.

define MSB3W

Most significant byte of 4th rank of u32.

define LSB3W

Least significant byte of 4th rank of u32.

define LSB2W

Least significant byte of 3rd rank of u32.

define LSB1W

Least significant byte of 2nd rank of u32.

define LSB0W

Least significant byte of 1st rank of u32.

define MSW

Most significant word of u64.

define LSW

Least significant word of u64.

define MSH0

Most significant half-word of 1st rank of u64.

define MSH1

Most significant half-word of 2nd rank of u64.

define MSH2

Most significant half-word of 3rd rank of u64.

define MSH3

Most significant half-word of 4th rank of u64.

define LSH3

Least significant half-word of 4th rank of u64.

define LSH2

Least significant half-word of 3rd rank of u64.

define LSH1

Least significant half-word of 2nd rank of u64.

define LSH0

Least significant half-word of 1st rank of u64.

define MSB0D

Most significant byte of 1st rank of u64.

define MSB1D

Most significant byte of 2nd rank of u64.

define MSB2D

Most significant byte of 3rd rank of u64.

define MSB3D

Most significant byte of 4th rank of u64.

define MSB4D

Most significant byte of 5th rank of u64.

define MSB5D

Most significant byte of 6th rank of u64.

define MSB6D

Most significant byte of 7th rank of u64.

define MSB7D

Most significant byte of 8th rank of u64.

define LSB7D

Least significant byte of 8th rank of u64.

define LSB6D

Least significant byte of 7th rank of u64.

define LSB5D

Least significant byte of 6th rank of u64.

define LSB4D

Least significant byte of 5th rank of u64.

define LSB3D

Least significant byte of 4th rank of u64.

define LSB2D

Least significant byte of 3rd rank of u64.

define LSB1D

Least significant byte of 2nd rank of u64.

define LSB0D

Least significant byte of 1st rank of u64.

define LSB0

Least significant byte of 1st rank of u32.

define LSB1

Least significant byte of 2nd rank of u32.

define LSB2

Least significant byte of 3rd rank of u32.

define LSB3

Least significant byte of 4th rank of u32.

define MSB3

Most significant byte of 4th rank of u32.

define MSB2

Most significant byte of 3rd rank of u32.

define MSB1

Most significant byte of 2nd rank of u32.

define MSB0

Most significant byte of 1st rank of u32.

define FLASH_DECLARE

define FLASH_EXTERN

define PGM_READ_BYTE

define PGM_READ_WORD

define MEMCPY_ENDIAN

define PGM_READ_BLOCK

define CMD_ID_OCTET

define CPU_ENDIAN_TO_LE16

define CPU_ENDIAN_TO_LE32

define CPU_ENDIAN_TO_LE64

define LE16_TO_CPU_ENDIAN

define LE32_TO_CPU_ENDIAN

define LE64_TO_CPU_ENDIAN

define CLE16_TO_CPU_ENDIAN

define CLE32_TO_CPU_ENDIAN

define CLE64_TO_CPU_ENDIAN

define CCPU_ENDIAN_TO_LE16

define CCPU_ENDIAN_TO_LE32

define CCPU_ENDIAN_TO_LE64

define ADDR_COPY_DST_SRC_16

define ADDR_COPY_DST_SRC_64

public inline static void convert_64_bit_to_byte_array(uint64_t value,uint8_t * data)

Converts a 64-Bit value into a 8 Byte array.

Parameters

• value 64-Bit value

• data Pointer to the 8 Byte array to be updated with 64-Bit value

public inline static void convert_16_bit_to_byte_array(uint16_t value,uint8_t * data)

Converts a 16-Bit value into a 2 Byte array.

Parameters

• value 16-Bit value

• data Pointer to the 2 Byte array to be updated with 16-Bit value

public inline static void convert_spec_16_bit_to_byte_array(uint16_t value,uint8_t * data)

public inline static void convert_16_bit_to_byte_address(uint16_t value,uint8_t * data)

public inline static uint16_t convert_byte_array_to_16_bit(uint8_t * data)

public inline static uint32_t convert_byte_array_to_32_bit(uint8_t * data)

public inline static uint64_t convert_byte_array_to_64_bit(uint8_t * data)

Converts a 8 Byte array into a 64-Bit value.

Parameters

• data Specifies the pointer to the 8 Byte array

Returns

64-Bit value

struct StructPtr

Structure of pointers to 64-, 32-, 16- and 8-bit unsigned integers.

Summary

Members	Descriptions
public int64_t * s64ptr
public uint64_t * u64ptr
public int32_t * s32ptr
public uint32_t * u32ptr
public int16_t * s16ptr
public uint16_t * u16ptr
public int8_t * s8ptr
public uint8_t * u8ptr

Members

public int64_t * s64ptr

public uint64_t * u64ptr

public int32_t * s32ptr

public uint32_t * u32ptr

public int16_t * s16ptr

public uint16_t * u16ptr

public int8_t * s8ptr

public uint8_t * u8ptr

struct StructVPtr

Structure of pointers to volatile 64-, 32-, 16- and 8-bit unsigned integers.

Summary

Members	Descriptions
public int64_t * s64ptr
public uint64_t * u64ptr
public int32_t * s32ptr
public uint32_t * u32ptr
public int16_t * s16ptr
public uint16_t * u16ptr
public int8_t * s8ptr
public uint8_t * u8ptr

Members

public int64_t * s64ptr

public uint64_t * u64ptr

public int32_t * s32ptr

public uint32_t * u32ptr

public int16_t * s16ptr

public uint16_t * u16ptr

public int8_t * s8ptr

public uint8_t * u8ptr

struct StructCPtr

Structure of pointers to constant 64-, 32-, 16- and 8-bit unsigned integers.

Summary

Members	Descriptions
public const int64_t * s64ptr
public const uint64_t * u64ptr
public const int32_t * s32ptr
public const uint32_t * u32ptr
public const int16_t * s16ptr
public const uint16_t * u16ptr
public const int8_t * s8ptr
public const uint8_t * u8ptr

Members

public const int64_t * s64ptr

public const uint64_t * u64ptr

public const int32_t * s32ptr

public const uint32_t * u32ptr

public const int16_t * s16ptr

public const uint16_t * u16ptr

public const int8_t * s8ptr

public const uint8_t * u8ptr

struct StructCVPtr

Structure of pointers to constant volatile 64-, 32-, 16- and 8-bit unsigned integers.

Summary

Members	Descriptions
public const volatile int64_t * s64ptr
public const volatile uint64_t * u64ptr
public const volatile int32_t * s32ptr
public const volatile uint32_t * u32ptr
public const volatile int16_t * s16ptr
public const volatile uint16_t * u16ptr
public const volatile int8_t * s8ptr
public const volatile uint8_t * u8ptr

Members

public const volatile int64_t * s64ptr

public const volatile uint64_t * u64ptr

public const volatile int32_t * s32ptr

public const volatile uint32_t * u32ptr

public const volatile int16_t * s16ptr

public const volatile uint16_t * u16ptr

public const volatile int8_t * s8ptr

public const volatile uint8_t * u8ptr