Mailboxes

Collaboration diagram for Mailboxes:

Functions
err_t	sys_mbox_new (sys_mbox_t *mbox, int size)
void	sys_mbox_post (sys_mbox_t *mbox, void *msg)
err_t	sys_mbox_trypost (sys_mbox_t *mbox, void *msg)
err_t	sys_mbox_trypost_fromisr (sys_mbox_t *mbox, void *msg)
u32_t	sys_arch_mbox_fetch (sys_mbox_t *mbox, void **msg, u32_t timeout)
u32_t	sys_arch_mbox_tryfetch (sys_mbox_t *mbox, void **msg)
void	sys_mbox_free (sys_mbox_t *mbox)
int	sys_mbox_valid (sys_mbox_t *mbox)
void	sys_mbox_set_invalid (sys_mbox_t *mbox)

Detailed Description

Mailboxes should be implemented as a queue which allows multiple messages to be posted (implementing as a rendez-vous point where only one message can be posted at a time can have a highly negative impact on performance). A message in a mailbox is just a pointer, nothing more.

Function Documentation

sys_arch_mbox_fetch()

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

Blocks the thread until a message arrives in the mailbox, but does not block the thread longer than "timeout" milliseconds (similar to the sys_arch_sem_wait() function). If "timeout" is 0, the thread should be blocked until a message arrives. The "msg" argument is 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. The return values are the same as for the sys_arch_sem_wait() function: SYS_ARCH_TIMEOUT if there was a timeout, any other value if a messages is received.

Note that a function with a similar name, sys_mbox_fetch(), is implemented by lwIP.

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

SYS_ARCH_TIMEOUT on timeout, any other value if a message has been received

Definition at line 183 of file sys_arch.c.

{
    LARGE_INTEGER LargeTimeout, PreWaitTime, PostWaitTime;
    UINT64 TimeDiff;
    NTSTATUS Status;
    PVOID Message;
    PLWIP_MESSAGE_CONTAINER Container;
    PLIST_ENTRY Entry;
    KIRQL OldIrql;
    PVOID WaitObjects[] = {&mbox->Semaphore, &TerminationEvent};
 
    LargeTimeout.QuadPart = Int32x32To64(timeout, -10000);
 
    KeQuerySystemTime(&PreWaitTime);
 
    Status = KeWaitForMultipleObjects(2,
                                      WaitObjects,
                                      WaitAny,
                                      Executive,
                                      KernelMode,
                                      FALSE,
                                      timeout != 0 ? &LargeTimeout : NULL,
                                      NULL);
 
    if (Status == STATUS_WAIT_0)
    {
        KeAcquireSpinLock(&mbox->Lock, &OldIrql);
        ASSERT(!IsListEmpty(&mbox->ListHead));
        Entry = RemoveHeadList(&mbox->ListHead);
        KeReleaseSpinLock(&mbox->Lock, OldIrql);
 
        Container = CONTAINING_RECORD(Entry, LWIP_MESSAGE_CONTAINER, ListEntry);
        Message = Container->Message;
        ExFreePool(Container);
 
        if (msg)
            *msg = Message;
 
        KeQuerySystemTime(&PostWaitTime);
        TimeDiff = PostWaitTime.QuadPart - PreWaitTime.QuadPart;
        TimeDiff /= 10000;
 
        return TimeDiff;
    }
    else if (Status == STATUS_WAIT_1)
    {
        /* DON'T remove ourselves from the thread list! */
        PsTerminateSystemThread(STATUS_SUCCESS);
 
        /* We should never get here! */
        ASSERT(FALSE);
 
        return 0;
    }
 
    return SYS_ARCH_TIMEOUT;
}

Referenced by sys_arch_mbox_tryfetch().

sys_arch_mbox_tryfetch()

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

This is similar to sys_arch_mbox_fetch, however if a message is not present in the mailbox, it immediately returns with the code SYS_MBOX_EMPTY. On success 0 is returned. To allow for efficient implementations, this can be defined as a function-like macro in sys_arch.h instead of a normal function. For example, a naive implementation could be: #define sys_arch_mbox_tryfetch(mbox,msg) sys_arch_mbox_fetch(mbox,msg,1) although this would introduce unnecessary delays.

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

Definition at line 242 of file sys_arch.c.

{
    if (sys_arch_mbox_fetch(mbox, msg, 1) != SYS_ARCH_TIMEOUT)
        return 0;
    else
        return SYS_MBOX_EMPTY;
}

Referenced by sys_arch_mbox_fetch().

sys_mbox_free()

void sys_mbox_free

(

sys_mbox_t *

mbox

)

Deallocates a mailbox. 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	mbox to delete

Definition at line 158 of file sys_arch.c.

{
    ASSERT(IsListEmpty(&mbox->ListHead));
 
    sys_mbox_set_invalid(mbox);
}

sys_mbox_new()

err_t sys_mbox_new	(	sys_mbox_t *	mbox,
		int	size
	)

Creates an empty mailbox for maximum "size" elements. Elements stored in mailboxes are pointers. You have to define macros "_MBOX_SIZE" in your lwipopts.h, or ignore this parameter in your implementation and use a default size. If the mailbox has been created, ERR_OK should be returned. Returning any other error will provide a hint what went wrong, but except for assertions, no real error handling is implemented.

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

Definition at line 134 of file sys_arch.c.

{
    KeInitializeSpinLock(&mbox->Lock);
 
    InitializeListHead(&mbox->ListHead);
 
    KeInitializeSemaphore(&mbox->Semaphore, 0, MAXLONG);
 
    mbox->Valid = 1;
 
    return ERR_OK;
}

Referenced by tcpip_init().

sys_mbox_post()

void sys_mbox_post	(	sys_mbox_t *	mbox,
		void *	msg
	)

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

Parameters

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

Definition at line 166 of file sys_arch.c.

{
    PLWIP_MESSAGE_CONTAINER Container;
 
    Container = ExAllocatePool(NonPagedPool, sizeof(*Container));
    ASSERT(Container);
 
    Container->Message = msg;
 
    ExInterlockedInsertTailList(&mbox->ListHead,
                                &Container->ListEntry,
                                &mbox->Lock);
 
    KeReleaseSemaphore(&mbox->Semaphore, IO_NO_INCREMENT, 1, FALSE);
}

Referenced by sys_mbox_trypost(), tcpip_api_call(), tcpip_callback(), tcpip_callback_wait(), and tcpip_send_msg_wait_sem().

sys_mbox_set_invalid()

void sys_mbox_set_invalid

(

sys_mbox_t *

mbox

)

Invalidate a mailbox so that sys_mbox_valid() returns 0. ATTENTION: This does NOT mean that the mailbox shall be deallocated: sys_mbox_free() is always called before calling this function! This may also be a define, in which case the function is not prototyped.

Definition at line 152 of file sys_arch.c.

{
    mbox->Valid = 0;
}

Referenced by sys_mbox_free().

sys_mbox_trypost()

err_t sys_mbox_trypost	(	sys_mbox_t *	mbox,
		void *	msg
	)

Try to post a message to an mbox - may fail if full. Can be used from ISR (if the sys arch layer allows this). Returns ERR_MEM if it is full, else, ERR_OK if the "msg" is posted.

Parameters

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

Definition at line 251 of file sys_arch.c.

{
    sys_mbox_post(mbox, msg);
 
    return ERR_OK;
}

Referenced by sys_mbox_trypost_fromisr(), tcpip_callbackmsg_trycallback(), tcpip_inpkt(), and tcpip_try_callback().

sys_mbox_trypost_fromisr()

err_t sys_mbox_trypost_fromisr	(	sys_mbox_t *	mbox,
		void *	msg
	)

Try to post a message to an mbox - may fail if full. To be be used from ISR. Returns ERR_MEM if it is full, else, ERR_OK if the "msg" is posted.

Parameters

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

Definition at line 287 of file sys_arch.c.

{
  return sys_mbox_trypost(q, msg);
}

sys_mbox_valid()

int sys_mbox_valid

(

sys_mbox_t *

mbox

)

Returns 1 if the mailbox is valid, 0 if it is not valid. When using pointers, a simple way is to check the pointer for != NULL. When directly using OS structures, implementing this may be more complex. This may also be a define, in which case the function is not prototyped.

Definition at line 147 of file sys_arch.c.

{
    return mbox->Valid;
}