Data Structures
struct	rt_ipc_object
struct	rt_semaphore
struct	rt_mutex
struct	rt_mailbox
struct	rt_messagequeue
Defines
#define	RT_IPC_FLAG_FIFO 0x00
#define	RT_IPC_FLAG_PRIO 0x01
#define	RT_IPC_CMD_UNKNOWN 0x00
#define	RT_IPC_CMD_RESET 0x01
#define	RT_WAITING_FOREVER -1
#define	RT_WAITING_NO 0
#define	RT_EVENT_FLAG_AND 0x01
#define	RT_EVENT_FLAG_OR 0x02
#define	RT_EVENT_FLAG_CLEAR 0x04
Functions
rt_inline rt_err_t	rt_ipc_object_init (struct rt_ipc_object *ipc)
rt_inline rt_err_t	rt_ipc_list_suspend (rt_list_t list, struct rt_thread thread, rt_uint8_t flag)
rt_inline rt_err_t	rt_ipc_list_resume (rt_list_t *list)
rt_inline rt_err_t	rt_ipc_list_resume_all (rt_list_t *list)
rt_err_t	rt_sem_init (rt_sem_t sem, const char *name, rt_uint32_t value, rt_uint8_t flag)
rt_err_t	rt_sem_detach (rt_sem_t sem)
rt_sem_t	rt_sem_create (const char *name, rt_uint32_t value, rt_uint8_t flag)
rt_err_t	rt_sem_delete (rt_sem_t sem)
rt_err_t	rt_sem_take (rt_sem_t sem, rt_int32_t time)
rt_err_t	rt_sem_trytake (rt_sem_t sem)
rt_err_t	rt_sem_release (rt_sem_t sem)
rt_err_t	rt_sem_control (rt_sem_t sem, rt_uint8_t cmd, void *arg)
rt_err_t	rt_mutex_init (rt_mutex_t mutex, const char *name, rt_uint8_t flag)
rt_err_t	rt_mutex_detach (rt_mutex_t mutex)
rt_mutex_t	rt_mutex_create (const char *name, rt_uint8_t flag)
rt_err_t	rt_mutex_delete (rt_mutex_t mutex)
rt_err_t	rt_mutex_take (rt_mutex_t mutex, rt_int32_t time)
rt_err_t	rt_mutex_release (rt_mutex_t mutex)
rt_err_t	rt_mutex_control (rt_mutex_t mutex, rt_uint8_t cmd, void *arg)
rt_err_t	rt_event_init (rt_event_t event, const char *name, rt_uint8_t flag)
rt_err_t	rt_event_detach (rt_event_t event)
rt_event_t	rt_event_create (const char *name, rt_uint8_t flag)
rt_err_t	rt_event_delete (rt_event_t event)
rt_err_t	rt_event_send (rt_event_t event, rt_uint32_t set)
rt_err_t	rt_event_recv (rt_event_t event, rt_uint32_t set, rt_uint8_t option, rt_int32_t timeout, rt_uint32_t *recved)
rt_err_t	rt_event_control (rt_event_t event, rt_uint8_t cmd, void *arg)
rt_err_t	rt_mb_init (rt_mailbox_t mb, const char name, void msgpool, rt_size_t size, rt_uint8_t flag)
rt_err_t	rt_mb_detach (rt_mailbox_t mb)
rt_mailbox_t	rt_mb_create (const char *name, rt_size_t size, rt_uint8_t flag)
rt_err_t	rt_mb_delete (rt_mailbox_t mb)
rt_err_t	rt_mb_send_wait (rt_mailbox_t mb, rt_uint32_t value, rt_int32_t timeout)
rt_err_t	rt_mb_send (rt_mailbox_t mb, rt_uint32_t value)
rt_err_t	rt_mb_recv (rt_mailbox_t mb, rt_uint32_t *value, rt_int32_t timeout)
rt_err_t	rt_mb_control (rt_mailbox_t mb, rt_uint8_t cmd, void *arg)
rt_err_t	rt_mq_init (rt_mq_t mq, const char name, void msgpool, rt_size_t msg_size, rt_size_t pool_size, rt_uint8_t flag)
rt_err_t	rt_mq_detach (rt_mq_t mq)
rt_mq_t	rt_mq_create (const char *name, rt_size_t msg_size, rt_size_t max_msgs, rt_uint8_t flag)
rt_err_t	rt_mq_delete (rt_mq_t mq)
rt_err_t	rt_mq_send (rt_mq_t mq, void *buffer, rt_size_t size)
rt_err_t	rt_mq_urgent (rt_mq_t mq, void *buffer, rt_size_t size)
rt_err_t	rt_mq_recv (rt_mq_t mq, void *buffer, rt_size_t size, rt_int32_t timeout)
rt_err_t	rt_mq_control (rt_mq_t mq, rt_uint8_t cmd, void *arg)

Detailed Description

RT-Thread operating system supports the traditional semaphore and mutex.

Mutex objects use inherited priority to prevent priority reversion.
The semaphore release action is safe for interrupt service routine.

Moreover, the blocked queue for thread to obtain semaphore or mutex can be sorted by priority or FIFO. There are two flags to indicate this mechanism.

RT_IPC_FLAG_FIFO when the resource is available, thread pended on this resource at first would get the resource.
RT_IPC_FLAG_PRIO when the resource is available, thread pended on this resource who had the most high priority would get the resource.

RT-Thread operating systems supports event/fast event, mail box and message queue.

The event mechanism is used to awake a thead by setting one or more corresponding bit of a binary number when an event ocurs.
The fast event supports event thread queue. Once a one bit event occurs, the corresponding blocked thread can be found out timing accurately, then will be waked up.
In mailbox, the mail length is fixed to 4 byte, which is more effective than message queue.
The send action for communication facilities is also safe for interrupt service routine.

Define Documentation

#define RT_IPC_FLAG_FIFO 0x00

IPC flags and control command definitions FIFOed IPC. Inter-Thread Communication.

#define RT_IPC_FLAG_PRIO 0x01

PRIOed IPC. Inter-Thread Communication.

#define RT_IPC_CMD_UNKNOWN 0x00

unknown IPC command

#define RT_IPC_CMD_RESET 0x01

reset IPC object

#define RT_WAITING_FOREVER -1

Block forever until get resource.

#define RT_WAITING_NO 0

Non-block.

#define RT_EVENT_FLAG_AND 0x01

flag defintions in event logic and

#define RT_EVENT_FLAG_OR 0x02

logic or

#define RT_EVENT_FLAG_CLEAR 0x04

clear flag

Function Documentation

rt_inline rt_err_t rt_ipc_object_init ( struct rt_ipc_object * ipc )

This function will initialize an IPC object

Parameters:

ipc	the IPC object

Returns:: the operation status, RT_EOK on successful

rt_inline rt_err_t rt_ipc_list_suspend	(	rt_list_t *	list,
		struct rt_thread *	thread,
		rt_uint8_t	flag
	)

This function will suspend a thread to a specified list. IPC object or some double-queue object (mailbox etc.) contains this kind of list.

Parameters:

list	the IPC suspended thread list
thread	the thread object to be suspended
flag	the IPC object flag, which shall be RT_IPC_FLAG_FIFO/RT_IPC_FLAG_PRIO.

Returns:: the operation status, RT_EOK on successful

rt_inline rt_err_t rt_ipc_list_resume ( rt_list_t * list )

This function will resume the first thread in the list of a IPC object:

remove the thread from suspend queue of IPC object
put the thread into system ready queue

Parameters:

list	the thread list

Returns:: the operation status, RT_EOK on successful

rt_inline rt_err_t rt_ipc_list_resume_all ( rt_list_t * list )

This function will resume all suspended threads in a list, including suspend list of IPC object and private list of mailbox etc.

Parameters:

list	of the threads to resume

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_sem_init	(	rt_sem_t	sem,
		const char *	name,
		rt_uint32_t	value,
		rt_uint8_t	flag
	)

This function will initialize a semaphore and put it under control of resource management.

Parameters:

sem	the semaphore object
name	the name of semaphore
value	the init value of semaphore
flag	the flag of semaphore

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_sem_detach ( rt_sem_t sem )

This function will detach a semaphore from resource management

Parameters:

sem	the semaphore object

Returns:: the operation status, RT_EOK on successful

See also:: rt_sem_delete

rt_sem_t rt_sem_create	(	const char *	name,
		rt_uint32_t	value,
		rt_uint8_t	flag
	)

This function will create a semaphore from system resource

Parameters:

name	the name of semaphore
value	the init value of semaphore
flag	the flag of semaphore

Returns:: the created semaphore, RT_NULL on error happen

See also:: rt_sem_init

rt_err_t rt_sem_delete ( rt_sem_t sem )

This function will delete a semaphore object and release the memory

Parameters:

sem	the semaphore object

Returns:: the error code

See also:: rt_sem_detach

rt_err_t rt_sem_take	(	rt_sem_t	sem,
		rt_int32_t	time
	)

This function will take a semaphore, if the semaphore is unavailable, the thread shall wait for a specified time.

Parameters:

sem	the semaphore object
time	the waiting time

Returns:: the error code

rt_err_t rt_sem_trytake ( rt_sem_t sem )

This function will try to take a semaphore and immediately return

Parameters:

sem	the semaphore object

Returns:: the error code

rt_err_t rt_sem_release ( rt_sem_t sem )

This function will release a semaphore, if there are threads suspended on semaphore, it will be waked up.

Parameters:

sem	the semaphore object

Returns:: the error code

rt_err_t rt_sem_control	(	rt_sem_t	sem,
		rt_uint8_t	cmd,
		void *	arg
	)

This function can get or set some extra attributions of a semaphore object.

Parameters:

sem	the semaphore object
cmd	the execution command
arg	the execution argument

Returns:: the error code

rt_err_t rt_mutex_init	(	rt_mutex_t	mutex,
		const char *	name,
		rt_uint8_t	flag
	)

This function will initialize a mutex and put it under control of resource management.

Parameters:

mutex	the mutex object
name	the name of mutex
flag	the flag of mutex

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_mutex_detach ( rt_mutex_t mutex )

This function will detach a mutex from resource management

Parameters:

mutex the mutex object

Returns:: the operation status, RT_EOK on successful

See also:: rt_mutex_delete

rt_mutex_t rt_mutex_create	(	const char *	name,
		rt_uint8_t	flag
	)

This function will create a mutex from system resource

Parameters:

name	the name of mutex
flag	the flag of mutex

Returns:: the created mutex, RT_NULL on error happen

See also:: rt_mutex_init

rt_err_t rt_mutex_delete ( rt_mutex_t mutex )

This function will delete a mutex object and release the memory

Parameters:

mutex the mutex object

Returns:: the error code

See also:: rt_mutex_detach

rt_err_t rt_mutex_take	(	rt_mutex_t	mutex,
		rt_int32_t	time
	)

This function will take a mutex, if the mutex is unavailable, the thread shall wait for a specified time.

Parameters:

mutex	the mutex object
time	the waiting time

Returns:: the error code

rt_err_t rt_mutex_release ( rt_mutex_t mutex )

This function will release a mutex, if there are threads suspended on mutex, it will be waked up.

Parameters:

mutex the mutex object

Returns:: the error code

rt_err_t rt_mutex_control	(	rt_mutex_t	mutex,
		rt_uint8_t	cmd,
		void *	arg
	)

This function can get or set some extra attributions of a mutex object.

Parameters:

mutex	the mutex object
cmd	the execution command
arg	the execution argument

Returns:: the error code

rt_err_t rt_event_init	(	rt_event_t	event,
		const char *	name,
		rt_uint8_t	flag
	)

This function will initialize an event and put it under control of resource management.

Parameters:

event	the event object
name	the name of event
flag	the flag of event

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_event_detach ( rt_event_t event )

This function will detach an event object from resource management

Parameters:

event the event object

Returns:: the operation status, RT_EOK on successful

rt_event_t rt_event_create	(	const char *	name,
		rt_uint8_t	flag
	)

This function will create an event object from system resource

Parameters:

name	the name of event
flag	the flag of event

Returns:: the created event, RT_NULL on error happen

rt_err_t rt_event_delete ( rt_event_t event )

This function will delete an event object and release the memory

Parameters:

event the event object

Returns:: the error code

rt_err_t rt_event_send	(	rt_event_t	event,
		rt_uint32_t	set
	)

This function will send an event to the event object, if there are threads suspended on event object, it will be waked up.

Parameters:

event	the event object
set	the event set

Returns:: the error code

rt_err_t rt_event_recv	(	rt_event_t	event,
		rt_uint32_t	set,
		rt_uint8_t	option,
		rt_int32_t	timeout,
		rt_uint32_t *	recved
	)

This function will receive an event from event object, if the event is unavailable, the thread shall wait for a specified time.

Parameters:

event	the fast event object
set	the interested event set
option	the receive option
timeout	the waiting time
recved	the received event

Returns:: the error code

rt_err_t rt_event_control	(	rt_event_t	event,
		rt_uint8_t	cmd,
		void *	arg
	)

This function can get or set some extra attributions of an event object.

Parameters:

event	the event object
cmd	the execution command
arg	the execution argument

Returns:: the error code

rt_err_t rt_mb_init	(	rt_mailbox_t	mb,
		const char *	name,
		void *	msgpool,
		rt_size_t	size,
		rt_uint8_t	flag
	)

This function will initialize a mailbox and put it under control of resource management.

Parameters:

mb	the mailbox object
name	the name of mailbox
msgpool	the begin address of buffer to save received mail
size	the size of mailbox
flag	the flag of mailbox

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_mb_detach ( rt_mailbox_t mb )

This function will detach a mailbox from resource management

Parameters:

mb	the mailbox object

Returns:: the operation status, RT_EOK on successful

rt_mailbox_t rt_mb_create	(	const char *	name,
		rt_size_t	size,
		rt_uint8_t	flag
	)

This function will create a mailbox object from system resource

Parameters:

name	the name of mailbox
size	the size of mailbox
flag	the flag of mailbox

Returns:: the created mailbox, RT_NULL on error happen

rt_err_t rt_mb_delete ( rt_mailbox_t mb )

This function will delete a mailbox object and release the memory

Parameters:

mb	the mailbox object

Returns:: the error code

rt_err_t rt_mb_send_wait	(	rt_mailbox_t	mb,
		rt_uint32_t	value,
		rt_int32_t	timeout
	)

This function will send a mail to mailbox object. If the mailbox is full, current thread will be suspended until timeout.

Parameters:

mb	the mailbox object
value	the mail
timeout	the waiting time

Returns:: the error code

rt_err_t rt_mb_send	(	rt_mailbox_t	mb,
		rt_uint32_t	value
	)

This function will send a mail to mailbox object, if there are threads suspended on mailbox object, it will be waked up. This function will return immediately, if you want blocking send, use rt_mb_send_wait instead.

Parameters:

mb	the mailbox object
value	the mail

Returns:: the error code

rt_err_t rt_mb_recv	(	rt_mailbox_t	mb,
		rt_uint32_t *	value,
		rt_int32_t	timeout
	)

This function will receive a mail from mailbox object, if there is no mail in mailbox object, the thread shall wait for a specified time.

Parameters:

mb	the mailbox object
value	the received mail will be saved in
timeout	the waiting time

Returns:: the error code

rt_err_t rt_mb_control	(	rt_mailbox_t	mb,
		rt_uint8_t	cmd,
		void *	arg
	)

This function can get or set some extra attributions of a mailbox object.

Parameters:

mb	the mailbox object
cmd	the execution command
arg	the execution argument

Returns:: the error code

rt_err_t rt_mq_init	(	rt_mq_t	mq,
		const char *	name,
		void *	msgpool,
		rt_size_t	msg_size,
		rt_size_t	pool_size,
		rt_uint8_t	flag
	)

This function will initialize a message queue and put it under control of resource management.

Parameters:

mq	the message object
name	the name of message queue
msgpool	the beginning address of buffer to save messages
msg_size	the maximum size of message
pool_size	the size of buffer to save messages
flag	the flag of message queue

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_mq_detach ( rt_mq_t mq )

This function will detach a message queue object from resource management

Parameters:

mq	the message queue object

Returns:: the operation status, RT_EOK on successful

rt_mq_t rt_mq_create	(	const char *	name,
		rt_size_t	msg_size,
		rt_size_t	max_msgs,
		rt_uint8_t	flag
	)

This function will create a message queue object from system resource

Parameters:

name	the name of message queue
msg_size	the size of message
max_msgs	the maximum number of message in queue
flag	the flag of message queue

Returns:: the created message queue, RT_NULL on error happen

rt_err_t rt_mq_delete ( rt_mq_t mq )

This function will delete a message queue object and release the memory

Parameters:

mq	the message queue object

Returns:: the error code

rt_err_t rt_mq_send	(	rt_mq_t	mq,
		void *	buffer,
		rt_size_t	size
	)

This function will send a message to message queue object, if there are threads suspended on message queue object, it will be waked up.

Parameters:

mq	the message queue object
buffer	the message
size	the size of buffer

Returns:: the error code

rt_err_t rt_mq_urgent	(	rt_mq_t	mq,
		void *	buffer,
		rt_size_t	size
	)

This function will send urgently a message to message queue object, which means the message will be inserted to the head of message queue. If there are threads suspended on message queue object, it will be waked up.

Parameters:

mq	the message queue object
buffer	the message
size	the size of buffer

Returns:: the error code

rt_err_t rt_mq_recv	(	rt_mq_t	mq,
		void *	buffer,
		rt_size_t	size,
		rt_int32_t	timeout
	)

This function will receive a message from message queue object, if there is no message in message queue object, the thread shall wait for a specified time.

Parameters:

mq	the message queue object
buffer	the received message will be saved in
size	the size of buffer
timeout	the waiting time

Returns:: the error code

rt_err_t rt_mq_control	(	rt_mq_t	mq,
		rt_uint8_t	cmd,
		void *	arg
	)

This function can get or set some extra attributions of a message queue object.

Parameters:

mq	the message queue object
cmd	the execution command
arg	the execution argument

Returns:: the error code

Data Structures

Defines

Functions

Detailed Description

Define Documentation

Function Documentation