lwip/lwip-1.4.1-dev/src/include/lwip/sys.h File Reference

#include "lwip/opt.h"
#include "lwip/err.h"
#include "arch/sys_arch.h"

Macros
#define	SYS_ARCH_DEC(var, val)
#define	SYS_ARCH_DECL_PROTECT(lev)
	SYS_LIGHTWEIGHT_PROT define SYS_LIGHTWEIGHT_PROT in lwipopts.h if you want inter-task protection for certain critical regions during buffer allocation, deallocation and memory allocation and deallocation. More...
#define	SYS_ARCH_GET(var, ret)
#define	SYS_ARCH_INC(var, val)
#define	SYS_ARCH_PROTECT(lev)
#define	SYS_ARCH_SET(var, val)
#define	SYS_ARCH_TIMEOUT   0xffffffffUL
	Return code for timeouts from sys_arch_mbox_fetch and sys_arch_sem_wait. More...
#define	SYS_ARCH_UNPROTECT(lev)
#define	SYS_MBOX_EMPTY   SYS_ARCH_TIMEOUT
	sys_mbox_tryfetch() returns SYS_MBOX_EMPTY if appropriate. More...
#define	sys_mbox_fetch(mbox, msg)   sys_arch_mbox_fetch(mbox, msg, 0)
#define	sys_mbox_tryfetch(mbox, msg)   sys_arch_mbox_tryfetch(mbox, msg)
	For now, we map straight to sys_arch implementation. More...
#define	sys_sem_wait(sem)   sys_arch_sem_wait(sem, 0)
	Wait for a semaphore - forever/no timeout. More...

Typedefs
typedef void(*	lwip_thread_fn )(void *arg)
	Function prototype for thread functions. More...

Functions
u32_t	sys_arch_mbox_fetch (sys_mbox_t *mbox, void **msg, u32_t timeout)
	Wait for a new message to arrive in the mbox. More...
u32_t	sys_arch_mbox_tryfetch (sys_mbox_t *mbox, void **msg)
	Wait for a new message to arrive in the mbox. More...
u32_t	sys_arch_sem_wait (sys_sem_t *sem, u32_t timeout)
	Wait for a semaphore for the specified timeout. More...
void	sys_init (void)
	Initialize the sys_arch layer. More...
u32_t	sys_jiffies (void)
	Ticks/jiffies since power up. More...
void	sys_mbox_free (sys_mbox_t *mbox)
	Delete an mbox. More...
err_t	sys_mbox_new (sys_mbox_t *mbox, int size)
	Create a new mbox of specified size. More...
void	sys_mbox_post (sys_mbox_t *mbox, void *msg)
	Post a message to an mbox - may not fail -> blocks if full, only used from tasks not from ISR. More...
void	sys_mbox_set_invalid (sys_mbox_t *mbox)
	Set an mbox invalid so that sys_mbox_valid returns 0. More...
err_t	sys_mbox_trypost (sys_mbox_t *mbox, void *msg)
	Try to post a message to an mbox - may fail if full or ISR. More...
int	sys_mbox_valid (sys_mbox_t *mbox)
	Check if an mbox is valid/allocated: return 1 for valid, 0 for invalid. More...
void	sys_msleep (u32_t ms)
	Sleep for some ms. More...
void	sys_mutex_free (sys_mutex_t *mutex)
	Delete a semaphore. More...
void	sys_mutex_lock (sys_mutex_t *mutex)
	Lock a mutex. More...
err_t	sys_mutex_new (sys_mutex_t *mutex)
	Define LWIP_COMPAT_MUTEX if the port has no mutexes and binary semaphores should be used instead. More...
void	sys_mutex_set_invalid (sys_mutex_t *mutex)
	Set a mutex invalid so that sys_mutex_valid returns 0. More...
void	sys_mutex_unlock (sys_mutex_t *mutex)
	Unlock a mutex. More...
int	sys_mutex_valid (sys_mutex_t *mutex)
	Check if a mutex is valid/allocated: return 1 for valid, 0 for invalid. More...
u32_t	sys_now (void)
	Returns the current time in milliseconds, may be the same as sys_jiffies or at least based on it. More...
void	sys_sem_free (sys_sem_t *sem)
	Delete a semaphore. More...
err_t	sys_sem_new (sys_sem_t *sem, u8_t count)
	Create a new semaphore. More...
void	sys_sem_set_invalid (sys_sem_t *sem)
	Set a semaphore invalid so that sys_sem_valid returns 0. More...
void	sys_sem_signal (sys_sem_t *sem)
	Signals a semaphore. More...
int	sys_sem_valid (sys_sem_t *sem)
	Check if a semaphore is valid/allocated: return 1 for valid, 0 for invalid. More...
sys_thread_t	sys_thread_new (const char *name, lwip_thread_fn thread, void *arg, int stacksize, int prio)
	The only thread function: Creates a new thread. More...

#define SYS_ARCH_DEC	(		var,
			val
	)

Value:

do { \
                                SYS_ARCH_DECL_PROTECT(old_level); \
                                SYS_ARCH_PROTECT(old_level); \
                                var -= val; \
                                SYS_ARCH_UNPROTECT(old_level); \
                              } while(0)

#define SYS_ARCH_DECL_PROTECT

(

lev

)

SYS_LIGHTWEIGHT_PROT define SYS_LIGHTWEIGHT_PROT in lwipopts.h if you want inter-task protection for certain critical regions during buffer allocation, deallocation and memory allocation and deallocation.

#define SYS_ARCH_GET	(		var,
			ret
	)

Value:

do { \
                                SYS_ARCH_DECL_PROTECT(old_level); \
                                SYS_ARCH_PROTECT(old_level); \
                                ret = var; \
                                SYS_ARCH_UNPROTECT(old_level); \
                              } while(0)

#define SYS_ARCH_INC	(		var,
			val
	)

Value:

do { \
                                SYS_ARCH_DECL_PROTECT(old_level); \
                                SYS_ARCH_PROTECT(old_level); \
                                var += val; \
                                SYS_ARCH_UNPROTECT(old_level); \
                              } while(0)

#define SYS_ARCH_PROTECT

(

lev

)

#define SYS_ARCH_SET	(		var,
			val
	)

Value:

do { \
                                SYS_ARCH_DECL_PROTECT(old_level); \
                                SYS_ARCH_PROTECT(old_level); \
                                var = val; \
                                SYS_ARCH_UNPROTECT(old_level); \
                              } while(0)

#define SYS_ARCH_TIMEOUT   0xffffffffUL

Return code for timeouts from sys_arch_mbox_fetch and sys_arch_sem_wait.

#define SYS_ARCH_UNPROTECT

(

lev

)

#define SYS_MBOX_EMPTY   SYS_ARCH_TIMEOUT

sys_mbox_tryfetch() returns SYS_MBOX_EMPTY if appropriate.

For now we use the same magic value, but we allow this to change in future.

#define sys_mbox_fetch	(		mbox,
			msg
	)		sys_arch_mbox_fetch(mbox, msg, 0)

#define sys_mbox_tryfetch	(		mbox,
			msg
	)		sys_arch_mbox_tryfetch(mbox, msg)

For now, we map straight to sys_arch implementation.

#define sys_sem_wait

(

sem

)

sys_arch_sem_wait(sem, 0)

Wait for a semaphore - forever/no timeout.

typedef void(* lwip_thread_fn)(void *arg)

Function prototype for thread functions.

u32_t sys_arch_mbox_fetch	(	sys_mbox_t *	mbox,
		void **	msg,
		u32_t	timeout
	)

Wait for a new message to arrive in the mbox.

Parameters

mbox	mbox to get a message from
msg	pointer where the message is stored
timeout	maximum time (in milliseconds) to wait for a message (0 = wait forever)

Returns

time (in milliseconds) waited for a message, may be 0 if not waited or SYS_ARCH_TIMEOUT on timeout The returned time has to be accurate to prevent timer jitter!

Wait for a new message to arrive in the mbox.

Parameters

mbox	Pointer to the mailbox.
msg	A result parameter that is set by the function (i.e., by doing "*msg = ptr"). The "msg" parameter maybe NULL to indicate that the message should be dropped. 0 indicates the thread should be blocked until a message arrives.

Returns

Number of milliseconds spent waiting or SYS_ARCH_TIMEOUT if there was a timeout.

Wait for a new message to arrive in the mbox.

Parameters

mbox	Pointer to the mailbox.
msg	A result parameter that is set by the function (i.e., by doing "*msg = ptr"). The "msg" parameter maybe NULL to indicate that the message should be dropped. 0 indicates the thread should be blocked until a message arrives.

Returns

Number of milliseconds spent waiting or SYS_ARCH_TIMEOUT if there was a timeout. Or ERR_MEM if invalid pointer to message box.

References ERR_MEM, NULL, pdFALSE, portTICK_RATE_MS, portTickType, SYS_ARCH_BLOCKING_TICKTIMEOUT, SYS_ARCH_TIMEOUT, xQueueReceive, and xTaskGetTickCount().

u32_t sys_arch_mbox_tryfetch	(	sys_mbox_t *	mbox,
		void **	msg
	)

Wait for a new message to arrive in the mbox.

Parameters

mbox	mbox to get a message from
msg	pointer where the message is stored

Returns

0 (milliseconds) if a message has been received or SYS_MBOX_EMPTY if the mailbox is empty

Wait for a new message to arrive in the mbox.

On success 0 is returned.

Parameters

mbox	Pointer to the mailbox.
msg	A result parameter that is set by the function (i.e., by doing "*msg = ptr"). The "msg" parameter maybe NULL to indicate that the message should be dropped.

Returns

Number of milliseconds spent waiting or SYS_ARCH_TIMEOUT if there was a timeout. Or ERR_MEM if invalid pointer to message box.

References NULL, pdFALSE, SYS_MBOX_EMPTY, and xQueueReceive.

u32_t sys_arch_sem_wait	(	sys_sem_t *	sem,
		u32_t	timeout
	)

Wait for a semaphore for the specified timeout.

Parameters

sem	the semaphore to wait for
timeout	timeout in milliseconds to wait (0 = wait forever)

Returns

time (in milliseconds) waited for the semaphore or SYS_ARCH_TIMEOUT on timeout

Wait for a semaphore for the specified timeout.

Note that there is another function sys_sem_wait in sys.c, but it is a wrapper for the sys_arch_sem_wait function. Please note that it is important for the semaphores to return an accurate count of elapsed milliseconds, since they are used to schedule timers in lwIP.

Parameters

sem	Pointer to the semaphore.
timeout	The timeout parameter specifies how many milliseconds the function should block before returning; if the function times out, it should return SYS_ARCH_TIMEOUT. If timeout=0, then the function should block indefinitely. If the function acquires the semaphore, it should return how many milliseconds expired while waiting for the semaphore.

Returns

SYS_ARCH_TIMEOUT if times out otherwise return the milliseconds expired while waiting for the semaphore.

Wait for a semaphore for the specified timeout.

Note that there is another function sys_sem_wait in sys.c, but it is a wrapper for the sys_arch_sem_wait function. Please note that it is important for the semaphores to return an accurate count of elapsed milliseconds, since they are used to schedule timers in lwIP.

Parameters

sem	Pointer to the semaphore.
timeout	The timeout parameter specifies how many milliseconds the function should block before returning; if the function times out, it should return SYS_ARCH_TIMEOUT. If timeout=0, then the function should block indefinitely. If the function acquires the semaphore, it should return how many milliseconds expired while waiting for the semaphore.

Returns

SYS_ARCH_TIMEOUT if times out, ERR_MEM for semaphore erro otherwise return the milliseconds expired while waiting for the semaphore.

References ERR_MEM, NULL, pdFALSE, portTICK_RATE_MS, portTickType, SYS_ARCH_BLOCKING_TICKTIMEOUT, SYS_ARCH_TIMEOUT, xSemaphoreTake, and xTaskGetTickCount().

void sys_init

(

void

)

Initialize the sys_arch layer.

u32_t sys_jiffies

(

void

)

Ticks/jiffies since power up.

void sys_mbox_free

(

sys_mbox_t *

mbox

)

Delete an mbox.

Parameters

mbox	mbox to delete

Delete an mbox.

If there are messages still present in the mailbox when the mailbox is deallocated, it is an indication of a programming error in lwIP and the developer should be notified.

Parameters

mbox	Pointer to the new mailbox.

References NULL, SYS_MBOX_NULL, and vQueueDelete().

err_t sys_mbox_new	(	sys_mbox_t *	mBoxNew,
		int	size
	)

Create a new mbox of specified size.

Parameters

mbox	pointer to the mbox to create
size	(minimum) number of messages in this mbox

Returns

ERR_OK if successful, another err_t otherwise

Create a new mbox of specified size.

Elements stored in mailboxes are pointers.

Parameters

mBoxNew	Pointer to the new mailbox.
size	Maximum "size" elements.

Returns

ERR_OK if successfull or ERR_MEM on error.

References ERR_MEM, ERR_OK, NULL, SYS_MBOX_NULL, and xQueueCreate.

void sys_mbox_post	(	sys_mbox_t *	mbox,
		void *	msg
	)

Post a message to an mbox - may not fail -> blocks if full, only used from tasks not from ISR.

Parameters

mbox	mbox to posts the message
msg	message to post (ATTENTION: can be NULL)

Post a message to an mbox - may not fail -> blocks if full, only used from tasks not from ISR.

This function have to block until the "msg" is really posted.

Parameters

mbox	Pointer to the mailbox.
msg	Pointer to the message to be post.

References NULL, pdTRUE, SYS_ARCH_BLOCKING_TICKTIMEOUT, and xQueueSend.

void sys_mbox_set_invalid

(

sys_mbox_t *

mbox

)

Set an mbox invalid so that sys_mbox_valid returns 0.

Set an mbox invalid so that sys_mbox_valid returns 0.

Parameters

mbox	Pointer to the mailbox.

References NULL.

err_t sys_mbox_trypost	(	sys_mbox_t *	mbox,
		void *	msg
	)

Try to post a message to an mbox - may fail if full or ISR.

Parameters

mbox	mbox to posts the message
msg	message to post (ATTENTION: can be NULL)

Try to post a message to an mbox - may fail if full or ISR.

Parameters

mbox	Pointer to the mailbox.
msg	Pointer to the message to be post.

Returns

ERR_MEM if the mailbox is full otherwise ERR_OK if the "msg" is posted.

References ERR_MEM, ERR_OK, errQUEUE_FULL, NULL, xQueueSend, and xQueueSendFromISR.

int sys_mbox_valid

(

sys_mbox_t *

mbox

)

Check if an mbox is valid/allocated: return 1 for valid, 0 for invalid.

Check if an mbox is valid/allocated: return 1 for valid, 0 for invalid.

Parameters

mbox	Pointer to the mailbox.

Returns

Mailbox for valid, 0 for invalid.

void sys_msleep

(

u32_t

ms

)

Sleep for some ms.

Timeouts are NOT processed while sleeping.

Parameters

ms	number of milliseconds to sleep

References ERR_OK, sys_arch_sem_wait(), sys_sem_free(), and sys_sem_new().

void sys_mutex_free

(

sys_mutex_t *

mutex

)

Delete a semaphore.

Parameters

mutex	the mutex to delete
mutex	the mutex to delete.

void sys_mutex_lock

(

sys_mutex_t *

mutex

)

Lock a mutex.

Parameters

mutex	the mutex to lock
mutex	the mutex to lock.

err_t sys_mutex_new

(

sys_mutex_t *

mutex

)

Define LWIP_COMPAT_MUTEX if the port has no mutexes and binary semaphores should be used instead.

Create a new mutex

Parameters

mutex

pointer to the mutex to create

Returns

a new mutex

Create a new mutex.

Parameters

mutex

Pointer to the mutex to create.

Returns

A new mutex.

void sys_mutex_set_invalid

(

sys_mutex_t *

mutex

)

Set a mutex invalid so that sys_mutex_valid returns 0.

Parameters

mutex

Pointer to the mutex.

References NULL.

void sys_mutex_unlock

(

sys_mutex_t *

mutex

)

Unlock a mutex.

Parameters

mutex	the mutex to unlock
mutex	the mutex to unlock.

int sys_mutex_valid

(

sys_mutex_t *

mutex

)

Check if a mutex is valid/allocated: return 1 for valid, 0 for invalid.

Check if a mutex is valid/allocated: return 1 for valid, 0 for invalid.

Parameters

mutex

Pointer to the mutex.

Returns

Valid mutex number or 0 for invalid.

u32_t sys_now

(

void

)

Returns the current time in milliseconds, may be the same as sys_jiffies or at least based on it.

Returns the current time in milliseconds, may be the same as sys_jiffies or at least based on it.

References xTaskGetTickCount().

void sys_sem_free

(

sys_sem_t *

sem

)

Delete a semaphore.

Parameters

sem	semaphore to delete

Delete a semaphore.

Parameters

sem	Pointer to the semaphore.

References NULL, SYS_SEM_NULL, and vQueueDelete().

err_t sys_sem_new	(	sys_sem_t *	sem,
		u8_t	count
	)

Create a new semaphore.

Parameters

sem	pointer to the semaphore to create
count	initial count of the semaphore

Returns

ERR_OK if successful, another err_t otherwise

Create a new semaphore.

Parameters

sem	Pointer to the semaphore.
count	Initial state of the semaphore.

Returns

ERR_OK for OK, other value indicates error.

References ERR_MEM, ERR_OK, NULL, SYS_SEM_NULL, vSemaphoreCreateBinary, and xSemaphoreTake.

void sys_sem_set_invalid

(

sys_sem_t *

sem

)

Set a semaphore invalid so that sys_sem_valid returns 0.

Set a semaphore invalid so that sys_sem_valid returns 0.

Parameters

sem	Pointer to the semaphore.

References NULL.

void sys_sem_signal

(

sys_sem_t *

sem

)

Signals a semaphore.

Parameters

sem	the semaphore to signal

Signals a semaphore.

Parameters

sem	Pointer to the semaphore.

References NULL, and xSemaphoreGive.

int sys_sem_valid

(

sys_sem_t *

sem

)

Check if a semaphore is valid/allocated: return 1 for valid, 0 for invalid.

Check if a semaphore is valid/allocated: return 1 for valid, 0 for invalid.

Check if a sempahore is valid/allocated: return 1 for valid, 0 for invalid.

Parameters

sem	Pointer to the semaphore.

Returns

Semaphore number on valid, 0 for invalid.

sys_thread_t sys_thread_new	(	const char *	name,
		lwip_thread_fn	thread,
		void *	arg,
		int	stacksize,
		int	prio
	)

The only thread function: Creates a new thread.

Parameters

name	human-readable name for the thread (used for debugging purposes)
thread	thread-function
arg	parameter passed to 'thread'
stacksize	stack size in bytes for the new thread (may be ignored by ports)
prio	priority of the new thread (may be ignored by ports)

The only thread function: Creates a new thread.

Both the id and the priority are system dependent.

Parameters

name	Pointer to the thread name.
thread	Thread function.
arg	Argument will be passed into the thread().
stacksize	Stack size of the thread.
prio	Thread priority.

Returns

The id of the new thread.

References NULL, pdPASS, SYS_ARCH_DECL_PROTECT, SYS_ARCH_PROTECT, SYS_ARCH_UNPROTECT, and xTaskCreate.