CPU implementation for running RIOT on a Linux and BSD. More...

Detailed Description

CPU implementation for running RIOT on a Linux and BSD.

Author: Ludwig Knüpfer ludwi.nosp@m.g.kn.nosp@m.uepfe.nosp@m.r@fu.nosp@m.-berl.nosp@m.in.d.nosp@m.e

The native CPU uses system calls to simulate hardware access.

Modules
	Linux User Mode GPIO Driver
	Implementation of GPIO access from Linux User Space.

	Linux User Mode SPI Driver
	Implementation of SPI access from Linux User Space.

	Native FS Integration
	Access to the host filesystem from RIOT native.

	Native extra API for EEPROM
	Implementation of EEPROM buffer persistence in file.

Files
file	architecture_arch.h
	Architecture details.

file	async_read.h
	Multiple asynchronous read on file descriptors.

file	atomic_utils_arch.h
	Implementation of fast atomic utility functions.

file	cpu.h
	Native CPU header.

file	cpu_conf.h
	Native CPU configuration.

file	native_cli_eui_provider.h
	Command-line EUI provider for native.

file	native_internal.h
	Native CPU internal symbols.

file	periph_conf.h
	Native CPU peripheral configuration.

file	periph_cpu.h
	CPU specific definitions for internal peripheral handling.

file	thread_arch.h
	Implementation of the kernels thread interface.

file	tty_uart.h
	UART implementation based on /dev/tty devices on host.

Data Structures
struct	async_read_t
	Interrupt callback information structure. More...

Macros
#define	ASYNC_READ_NUMOF 8
	Maximum number of file descriptors.

#define	CLOCK_CORECLOCK GHZ(1)
	System core clock in Hz. More...

#define	NATIVE_TIMER_MIN_RES 200
	Hardware timer clock skew avoidance.

#define	RANDOM_NUMOF (1U)
	Random Number Generator configuration.

#define	UART_NUMOF (1U)
	UART configuration.

#define	PWM_NUMOF (8U)
	PWM configuration.

#define	QDEC_NUMOF (8U)
	QDEC configuration.

#define	CPUID_LEN (4U)
	Length of the CPU_ID in octets.

#define	PM_NUM_MODES (1U)
	Power mode configuration.

#define	PROVIDES_PM_LAYERED_OFF
	We provide our own pm_off() function for the native CPU.

#define	PERIPH_TIMER_PROVIDES_SET
	Prevent shared timer functions from being used.

#define	EEPROM_SIZE (1024U) /* 1kB */
	EEPROM configuration.

Typedefs
typedef void(*	native_async_read_callback_t) (int fd, void *arg)
	asynchronous read callback type

Functions
void	native_breakpoint (void)
	raise SIGTRAP More...

void	native_async_read_setup (void)
	initialize asynchronous read system More...

void	native_async_read_cleanup (void)
	shutdown asynchronous read system More...

void	native_async_read_continue (int fd)
	resume monitoring of file descriptors More...

void	native_async_read_add_handler (int fd, void *arg, native_async_read_callback_t handler)
	start monitoring of file descriptor More...

void	native_async_read_remove_handler (int fd)
	stop monitoring of file descriptor More...

void	native_async_read_add_int_handler (int fd, void *arg, native_async_read_callback_t handler)
	start monitoring of file descriptor as interrupt More...

void	native_cli_add_eui64 (const char *s)
	parse a string as an EUI-64 and add it to the list of EUI-64s More...

int	native_cli_get_eui64 (uint8_t index, eui64_t *addr)
	Get a command-line provided EUI-64. More...

void	tty_uart_setup (uart_t uart, const char *name)
	register /dev/tty device to be used for UART More...

GPIO Configuration
enum	gpio_mode_t { GPIO_IN = GPIOHANDLE_REQUEST_INPUT , GPIO_IN_PD = GPIOHANDLE_REQUEST_INPUT \| GPIOHANDLE_REQUEST_PULL_DOWN , GPIO_IN_PU = GPIOHANDLE_REQUEST_INPUT \| GPIOHANDLE_REQUEST_PULL_UP , GPIO_OUT = GPIOHANDLE_REQUEST_OUTPUT , GPIO_OD = GPIOHANDLE_REQUEST_OPEN_DRAIN , GPIO_OD_PU = GPIOHANDLE_REQUEST_OPEN_DRAIN \| GPIOHANDLE_REQUEST_PULL_UP , GPIO_IN , GPIO_IN_PD , GPIO_IN_PU , GPIO_OUT , GPIO_OD , GPIO_OD_PU }
	Available pin modes. More...

enum	gpio_flank_t { GPIO_ISC_BOTH = (0 << 4) , GPIO_ISC_RISING = (1 << 4) , GPIO_ISC_FALLING = (2 << 4) , GPIO_ISC_LOW_LEVEL = (3 << 4) , GPIO_INT_DISABLED_ALL = (1 << 3) , GPIO_INT0_VCT = (0 << 2) , GPIO_INT1_VCT = (1 << 2) , GPIO_LVL_OFF = (0 << 0) , GPIO_LVL_LOW = (1 << 0) , GPIO_LVL_MID = (2 << 0) , GPIO_LVL_HIGH = (3 << 0) , GPIO_FALLING = GPIO_ISC_FALLING \| GPIO_LVL_LOW , GPIO_RISING = GPIO_ISC_RISING \| GPIO_LVL_LOW , GPIO_BOTH = GPIO_ISC_BOTH \| GPIO_LVL_LOW , GPIO_FALLING = 0xff , GPIO_RISING = 0x00 , GPIO_BOTH = 0xab , GPIO_FALLING = GPIOEVENT_EVENT_FALLING_EDGE , GPIO_RISING = GPIOEVENT_EVENT_RISING_EDGE , GPIO_BOTH = GPIO_FALLING \| GPIO_RISING , GPIO_LEVEL_LOW = 0x1 , GPIO_LEVEL_HIGH = 0x2 , GPIO_FALLING = 0x4 , GPIO_RISING = 0x8 , GPIO_BOTH = 0xc , GPIO_FALLING = 0 , GPIO_RISING = 1 , GPIO_BOTH = 2 }
	An enum for the type of flank that emit interrupts. More...

#define	GPIO_PORT_SHIFT (24)
	The offset between Port and Pin.

#define	GPIO_PIN(port, pin) (gpio_t)((port << GPIO_PORT_SHIFT) \| pin)
	Define a custom GPIO_PIN macro for native.

#define	HAVE_GPIO_MODE_T
	Macro indicating whether GPIO modes are available on the native CPU.

#define	GPIOHANDLE_REQUEST_PULL_DOWN (0xFF)
	Pull-down.

#define	GPIOHANDLE_REQUEST_PULL_UP (0xFF)
	Pull-up.

#define	HAVE_GPIO_FLANK_T
	A macro indicating whether the native CPU supports GPIO edge behavior.

Internal native CPU API
typedef void(*	_native_callback_t) (void)
	Prototype for native's internal callbacks.

void	native_cpu_init (void)
	Initializes native CPU.

Native flash emulation
Use unusual parameters to trigger edge cases
char	_native_flash [FLASHPAGE_SIZE *FLASHPAGE_NUMOF]
	Emulated flash buffer.

#define	FLASHPAGE_SIZE (512)
	Size of a single emulated flash page.

#define	FLASHPAGE_NUMOF (32)
	Total number of emulated flash pages.

#define	FLASHPAGE_WRITE_BLOCK_ALIGNMENT (8)
	Flashpage alignment. More...

#define	FLASHPAGE_WRITE_BLOCK_SIZE (16)
	Flashpage block size. More...

#define	FLASHPAGE_ERASE_STATE (0x0)
	Value of bytes in erased flash. More...

#define	CPU_FLASH_BASE ((uintptr_t)_native_flash)
	Base buffer pointer to emulated flash.

Native Signal Handling
void	native_interrupt_init (void)
	Registers signal handlers for the native CPU.

int	native_register_interrupt (int sig, _native_callback_t handler)
	Register interrupt handler handler for interrupt signal. More...

int	native_unregister_interrupt (int sig)
	Unregister interrupt handler for interrupt signal. More...

void	_native_sig_leave_tramp (void)
	Switches to ISR context, then enables IRQ and returns to userspace. More...

System Calls
We wrap system calls and syscall-invoking library calls to ensure no context switches occur during a system call.
static void	_native_pending_syscalls_up (void)
	Increment spending system call counter.

static void	_native_pending_syscalls_down (void)
	Decrements pending system call counter.

void	_native_init_syscalls (void)
	Registers system calls. More...

Native Context Switching
volatile uintptr_t	_native_user_fptr
	Points to instruction in userspace where RIOT left off and switched to ISR context.

volatile int	_native_in_isr
	A boolean variable indicating whether program execution currently takes place in an ISR context.

char	_isr_stack [THREAD_STACKSIZE_DEFAULT]
	Stack used in ISR context.

ucontext_t *	_native_isr_context
	ISR context.

static void	_native_isr_context_make (void(*func)(void))
	Makes ISR context so that execution continues at `func` when the context is applied. More...

static ucontext_t *	_native_user_context (void)
	Retrieves user context. More...

static uintptr_t	cpu_get_caller_pc (void)
	Gets the address the callee will return to.

#define	CPU_HAS_UNALIGNED_ACCESS
	The CPU supports unaligned memory access. More...

Native Read/Write Methods
ssize_t	_native_read (int fd, void *buf, size_t count)
	Reads file, populates given buffer.

ssize_t	_native_write (int fd, const void *buf, size_t count)
	Writes given data into file.

ssize_t	_native_writev (int fildes, const struct iovec *iov, int iovcnt)
	Performs a vectored write operation.

Context accessors
static uintptr_t	_context_get_fptr (ucontext_t *context)
	Retrieves function pointer generated during calls to `makecontext`/`setcontext`/`swapcontext` More...

static void	_context_set_fptr (ucontext_t *context, uintptr_t func)
	Retrieves function pointer generated during calls to `makecontext`/`setcontext`/`swapcontext` More...

64-bit support for makecontext
void	_start_task_func64 (void)
	Invokes thread task function. More...

static void	makecontext64 (ucontext_t context, void(func)(void), void *arg)
	Like `makecontext`, allows 64-bit wide function argument on 64-bit platforms. More...

#define	THREAD_STACKSIZE_DEFAULT (8192)
	CPU-specific default stack sizes. More...

#define	THREAD_STACKSIZE_IDLE (THREAD_STACKSIZE_DEFAULT)
	Default size of idle thread stack.

#define	THREAD_EXTRA_STACKSIZE_PRINTF (4096)
	Extra stack buffer capacity needed for `printf`

#define	THREAD_EXTRA_STACKSIZE_PRINTF_FLOAT (4096)
	Extra stack buffer capacity needed for `printf` in floating-point operations.

#define	THREAD_STACKSIZE_MINIMUM (THREAD_STACKSIZE_DEFAULT)
	Minimum thread size.

#define	ISR_STACKSIZE (THREAD_STACKSIZE_DEFAULT)
	Size of stack used in ISR context.

Networking constants
#define	NATIVE_ETH_PROTO 0x1234
	Native internal Ethernet protocol number.

Timer peripheral configuration
#define	TIMER_NUMOF (1U)

#define	TIMER_CHANNEL_NUMOF (1U)
	Number of timer channels.

<tt>xtimer</tt> configuration
timer_set_absolute has a high margin for possible underflow if set with value not far in the future. To prevent this, we set high backoff values here.
#define	XTIMER_BACKOFF 200

#define	XTIMER_ISR_BACKOFF 200

SPI configuration (Linux host only)
#define	SPI_NUMOF (1U)
	Amount of SPI devices. More...

#define	SPI_MAXCS (4U)
	Maximum amount of chip select lines per bus. More...

#define	SPI_HWCS(x) (UINT_MAX - SPI_MAXCS + x)
	Hardware chip select access macro. More...

SPI Configuration
#define	PERIPH_SPI_NEEDS_TRANSFER_BYTE
	Use the common `transfer_byte` SPI function.

#define	PERIPH_SPI_NEEDS_TRANSFER_REG
	Use the common `transfer_reg` SPI function.

#define	PERIPH_SPI_NEEDS_TRANSFER_REGS
	Use the common `transfer_regs` SPI function.

Macro Definition Documentation

◆ CLOCK_CORECLOCK

#define CLOCK_CORECLOCK GHZ(1)

System core clock in Hz.

1GHz is an arbitrary value used for compatibility with other platforms.

Definition at line 31 of file periph_conf.h.

◆ CPU_HAS_UNALIGNED_ACCESS

#define CPU_HAS_UNALIGNED_ACCESS

The CPU supports unaligned memory access.

Even if the underlying architecture does not support it, the kernel will take care of it.

Definition at line 42 of file cpu.h.

◆ FLASHPAGE_ERASE_STATE

#define FLASHPAGE_ERASE_STATE (0x0)

Value of bytes in erased flash.

The flash is set to this constant when you call flashpage_erase.

Definition at line 136 of file cpu_conf.h.

◆ FLASHPAGE_WRITE_BLOCK_ALIGNMENT

#define FLASHPAGE_WRITE_BLOCK_ALIGNMENT (8)

Flashpage alignment.

The address passed to flashpage_write must be a multiple of this constant.

Definition at line 117 of file cpu_conf.h.

◆ FLASHPAGE_WRITE_BLOCK_SIZE

#define FLASHPAGE_WRITE_BLOCK_SIZE (16)

Flashpage block size.

When writing to flash, the data size must be a multiple of this constant.

See also: flashpage_write

Definition at line 127 of file cpu_conf.h.

◆ SPI_HWCS

#define SPI_HWCS ( x ) (UINT_MAX - SPI_MAXCS + x)

Hardware chip select access macro.

The amount of available hardware chip select lines depends on the SPI_MAXCS parameter. If the line is actually available at runtime depends of whether a --spi startup parameter with the corresponding SPI device and HWCS-line parameter has been given.

Definition at line 123 of file periph_conf.h.

◆ SPI_MAXCS

#define SPI_MAXCS (4U)

Maximum amount of chip select lines per bus.

Allows up to SPI_MAXCS hardware cable select lines per SPI device. The n-th hardware select line can be used with the SPI_HWCS macro.

Definition at line 112 of file periph_conf.h.

◆ SPI_NUMOF

#define SPI_NUMOF (1U)

Amount of SPI devices.

Allows up to SPI_NUMOF SPI devices with each having up to SPI_MAXCS hardware cable select lines. Assignment to hardware devices can be configured at runtime using the --spi startup parameter.

Can be overridden during compile time with a -DSPI_NUMOF=n flag.

Definition at line 102 of file periph_conf.h.

◆ THREAD_STACKSIZE_DEFAULT

#define THREAD_STACKSIZE_DEFAULT (8192)

CPU-specific default stack sizes.

Todo:: TODO: tighten stack sizes

Default size of a thread stack

Definition at line 38 of file cpu_conf.h.

Enumeration Type Documentation

◆ gpio_flank_t

enum gpio_flank_t

An enum for the type of flank that emit interrupts.

Enumerator
GPIO_ISC_BOTH	emit interrupt on both flanks (default)
GPIO_ISC_RISING	emit interrupt on rising flank
GPIO_ISC_FALLING	emit interrupt on falling flank
GPIO_ISC_LOW_LEVEL	emit interrupt on low level
GPIO_INT_DISABLED_ALL	disable all interrupts
GPIO_INT0_VCT	enable interrupt on Vector 0 (default)
GPIO_INT1_VCT	enable interrupt on Vector 1
GPIO_LVL_OFF	interrupt disabled (default)
GPIO_LVL_LOW	interrupt low level
GPIO_LVL_MID	interrupt medium level
GPIO_LVL_HIGH	interrupt higher
GPIO_FALLING	emit interrupt on falling flank
GPIO_RISING	emit interrupt on rising flank
GPIO_BOTH	not supported -> random value
GPIO_FALLING	emit interrupt on falling flank
GPIO_RISING	emit interrupt on rising flank
GPIO_BOTH	emit interrupt on both flanks
GPIO_LEVEL_LOW	emit interrupt level-triggered on low input
GPIO_LEVEL_HIGH	emit interrupt level-triggered on low input
GPIO_FALLING	emit interrupt on falling flank
GPIO_RISING	emit interrupt on rising flank
GPIO_BOTH	emit interrupt on both flanks
GPIO_FALLING	emit interrupt on falling flank
GPIO_RISING	emit interrupt on rising flank
GPIO_BOTH	emit interrupt on both flanks

Definition at line 105 of file periph_cpu.h.

◆ gpio_mode_t

enum gpio_mode_t

Available pin modes.

Generally, a pin can be configured to be input or output. In output mode, a pin can further be put into push-pull or open drain configuration. Though this is supported by most platforms, this is not always the case, so driver implementations may return an error code if a mode is not supported.

Enumerator
GPIO_IN	configure as input without pull resistor
GPIO_IN_PD	configure as input with pull-down resistor
GPIO_IN_PU	configure as input with pull-up resistor
GPIO_OUT	configure as output in push-pull mode
GPIO_OD	configure as output in open-drain mode without pull resistor
GPIO_OD_PU	configure as output in open-drain mode with pull resistor enabled

Definition at line 88 of file periph_cpu.h.

Function Documentation

◆ _context_get_fptr()

static uintptr_t _context_get_fptr ( ucontext_t * context )

inlinestatic

Retrieves function pointer generated during calls to makecontext/setcontext/swapcontext

Parameters

context ucontext_t

Returns: Function pointer (does not need to be start of a function, points to instruction)

Definition at line 38 of file ucontext.h.

◆ _context_set_fptr()

static void _context_set_fptr	(	ucontext_t *	context,
		uintptr_t	func
	)

inlinestatic

Retrieves function pointer generated during calls to makecontext/setcontext/swapcontext

Parameters

context	`ucontext_t`
func	Function pointer

Definition at line 61 of file ucontext.h.

◆ _native_init_syscalls()

void _native_init_syscalls ( void )

Registers system calls.

Wraps syscall functions from the standard library.

◆ _native_isr_context_make()

static void _native_isr_context_make ( void(*)(void) func )

inlinestatic

Makes ISR context so that execution continues at func when the context is applied.

Parameters

func	Function executed when `_native_isr_context` is applied

Definition at line 241 of file native_internal.h.

◆ _native_sig_leave_tramp()

void _native_sig_leave_tramp ( void )

Switches to ISR context, then enables IRQ and returns to userspace.

Note: This function is implemented in assembly.

◆ _native_user_context()

static ucontext_t* _native_user_context ( void )

inlinestatic

Retrieves user context.

Returns: ucontext_t

Definition at line 254 of file native_internal.h.

◆ _start_task_func64()

void _start_task_func64 ( void )

Invokes thread task function.

This function fixes the otherwise necessary cast from void* to int of the thread task function pointer. We pass the task func and its argument in registers. See makecontext64.

◆ makecontext64()

static void makecontext64	(	ucontext_t *	context,
		void(*)(void)	func,
		void *	arg
	)

inlinestatic

Like makecontext, allows 64-bit wide function argument on 64-bit platforms.

Parameters

context	`ucontext_t`
func	Function to be executed when context is applied
arg	Function argument, previously limited to `int` width, can now be up to 64 bits wide on 64-bit platforms

Internally, we circumvent the 32-bit int limitation by passing the parameter in a register. This is done using a custom function defined in native.S

Definition at line 106 of file ucontext.h.

◆ native_async_read_add_handler()

void native_async_read_add_handler	(	int	fd,
		void *	arg,
		native_async_read_callback_t	handler
	)

start monitoring of file descriptor

Parameters

[in]	fd	The file descriptor to monitor
[in]	arg	Pointer to be passed as arguments to the callback
[in]	handler	The callback function to be called when the file descriptor is ready to read.

◆ native_async_read_add_int_handler()

void native_async_read_add_int_handler	(	int	fd,
		void *	arg,
		native_async_read_callback_t	handler
	)

start monitoring of file descriptor as interrupt

Parameters

[in]	fd	The file descriptor to monitor
[in]	arg	Pointer to be passed as arguments to the callback
[in]	handler	The callback function to be called when the file descriptor is ready to read.

◆ native_async_read_cleanup()

void native_async_read_cleanup ( void )

shutdown asynchronous read system

This deregisters SIGIO signal handler.

◆ native_async_read_continue()

void native_async_read_continue ( int fd )

resume monitoring of file descriptors

Call this function after reading file descriptors.

Parameters

[in] fd The file descriptor to monitor

◆ native_async_read_remove_handler()

void native_async_read_remove_handler ( int fd )

stop monitoring of file descriptor

Parameters

[in] fd The file descriptor to stop monitoring

◆ native_async_read_setup()

void native_async_read_setup ( void )

initialize asynchronous read system

This registers SIGIO signal handler.

◆ native_breakpoint()

void native_breakpoint ( void )

raise SIGTRAP

   We must not include signal.h directly into RIOT application namespace.

◆ native_cli_add_eui64()

void native_cli_add_eui64 ( const char * s )

parse a string as an EUI-64 and add it to the list of EUI-64s

Parameters

[in] s EUI-64 as hexadecimal string representation

◆ native_cli_get_eui64()

int native_cli_get_eui64	(	uint8_t	index,
		eui64_t *	addr
	)

Get a command-line provided EUI-64.

Parameters

	index	index of ZEP device
[out]	addr	user supplied EUI-64

Returns: 0 on success, negatvie if no more EUIs are available.

◆ native_register_interrupt()

int native_register_interrupt	(	int	sig,
		_native_callback_t	handler
	)

Register interrupt handler handler for interrupt signal.

Parameters

sig	Signal number
handler	Signal action function

Returns: 0 on success, negative number otherwise.

◆ native_unregister_interrupt()

int native_unregister_interrupt ( int sig )

Unregister interrupt handler for interrupt signal.

Parameters

sig	Signal number

Returns: 0 on success, negative number otherwise.

◆ tty_uart_setup()

void tty_uart_setup	(	uart_t	uart,
		const char *	name
	)

register /dev/tty device to be used for UART

Parameters

[in]	uart	UART id
[in]	name	path name for /dev/tty device

Detailed Description

Modules

Files

Data Structures

Macros

Typedefs

Functions

GPIO Configuration

Internal native CPU API

Native flash emulation

Native Signal Handling

System Calls

Native Context Switching

Native Read/Write Methods

Context accessors

64-bit support for makecontext

Networking constants

Timer peripheral configuration

<tt>xtimer</tt> configuration

SPI configuration (Linux host only)

SPI Configuration

Macro Definition Documentation

◆ CLOCK_CORECLOCK

◆ CPU_HAS_UNALIGNED_ACCESS

◆ FLASHPAGE_ERASE_STATE

◆ FLASHPAGE_WRITE_BLOCK_ALIGNMENT

◆ FLASHPAGE_WRITE_BLOCK_SIZE

◆ SPI_HWCS

◆ SPI_MAXCS

◆ SPI_NUMOF

◆ THREAD_STACKSIZE_DEFAULT

Enumeration Type Documentation

◆ gpio_flank_t

◆ gpio_mode_t

Function Documentation

◆ _context_get_fptr()

◆ _context_set_fptr()

◆ _native_init_syscalls()

◆ _native_isr_context_make()

◆ _native_sig_leave_tramp()

◆ _native_user_context()

◆ _start_task_func64()

◆ makecontext64()

◆ native_async_read_add_handler()

◆ native_async_read_add_int_handler()

◆ native_async_read_cleanup()

◆ native_async_read_continue()

◆ native_async_read_remove_handler()

◆ native_async_read_setup()

◆ native_breakpoint()

◆ native_cli_add_eui64()

◆ native_cli_get_eui64()

◆ native_register_interrupt()

◆ native_unregister_interrupt()

◆ tty_uart_setup()