405
Chapter 16
µC/OS-II Reference Manual
This chapter provides a reference to µC/OS-II services. Each of the user-accessible kernel services is presented
in alphabetical order. The following information is provided for each of the services:
• A brief description
• The function prototype
• The filename of the source code
• The
#define constant needed to enable the code for the service
• A description of the arguments passed to the function
• A description of the returned value(s)
• Specific notes and warnings on using the service
• One or two examples of how to use the function
406
OS_ENTER_CRITICAL()
OS_EXIT_CRITICAL()
Chapter File Called from Code enabled by
3
OS_CPU.H
Task or ISR N/A
OS_ENTER_CRITICAL() and OS_EXIT_CRITICAL() are macros used to disable and enable, respectively, the
processor’s interrupts.
Arguments
none
Returned Values
none
Notes/Warnings
1. These macros must be used in pairs.
2. If
OS_CRITICAL_METHOD is set to 3, your code is assumed to have allocated local storage for a variable of
type
OS_CPU_SR, which is called cpu_sr, as follows
#if OS_CRITICAL_METHOD == 3 /* Allocate storage for CPU status reg. */
OS_CPU_SR cpu_sr;
#endif
Example
void TaskX(void *p_arg)
{
#if OS_CRITICAL_METHOD == 3
OS_CPU_SR cpu_sr = 0;
#endif
for (;;) {
.
.
OS_ENTER_CRITICAL(); /* Disable interrupts */
. /* Access critical code */
OS_EXIT_CRITICAL(); /* Enable interrupts */
.
.
}
}
407
OSEventNameGet()
INT8U OSEventNameGet(OS_EVENT *pevent,
INT8U *pname,
INT8U *perr);
Chapter File Called from Code enabled by
New in V2.60
OS_CORE.C
Task
OS_EVENT_NAME_SIZE
OSEventNameGet() allows you to obtain the name that you assigned to a semaphore, a mutex, a mailbox or a
message queue. The name is an ASCII string and the size of the name can contain up to
OS_EVENT_NAME_SIZE characters (including the NUL termination). This function is typically used by a
debugger to allow associating a name to a resource.
Arguments
pevent is a pointer to the event control block. pevent can point either to a semaphore, a mutex, a
mailbox or a queue. Where this function is concerned, the actual type is irrelevant. This
pointer is returned to your application when the semaphore, mutex, mailbox or queue is created
(see
OSSemCreate(), OSMutexCreate(), OSMboxCreate() and OSQCreate()).
pname is a pointer to an ASCII string that will receive the name of the semaphore, mutex, mailbox or
queue. The string must be able to hold at least
OS_EVENT_NAME_SIZE characters (including
the
NUL character).
perr a pointer to an error code and can be any of the following:
OS_ERR_NONE If the name of the semaphore, mutex, mailbox or queue was
copied to the array pointed to by
pname.
OS_ERR_EVENT_TYPE You are not pointing to either a semaphore, mutex, mailbox or
message queue.
OS_ERR_PEVENT_NULL You passed a NULL pointer for pevent.
OS_ERR_NAME_GET_ISR You tried calling this function from an ISR.
Returned Values
The size of the ASCII string placed in the array pointed to by pname or 0 if an error is encountered.
408
Notes/Warnings
1. The semaphore, mutex, mailbox or message queue must be created before you can use this function and
obtain the name of the resource.
Example
INT8U PrinterSemName[30];
OS_EVENT *PrinterSem;
void Task (void *p_arg)
{
INT8U err;
INT8U size;
(void)p_arg;
for (;;) {
size = OSEventNameGet(PrinterSem, &PrinterSemName[0], &err);
.
.
}
}
409
OSEventNameSet()
void OSEventNameSet(OS_EVENT *pevent,
INT8U *pname,
INT8U *perr);
Chapter File Called from Code enabled by
New in V2.60
OS_CORE.C
Task
OS_EVENT_NAME_SIZE
OSEventNameSet() allows you to assign a name to a semaphore, a mutex, a mailbox or a message queue.
The name is an ASCII string and the size of the name can contain up to
OS_EVENT_NAME_SIZE characters
(including the
NUL termination). This function is typically used by a debugger to allow associating a name to a
resource.
Arguments
pevent is a pointer to the event control block that you want to name. pevent can point either to a
semaphore, a mutex, a mailbox or a queue. Where this function is concerned, the actual type is
irrelevant. This pointer is returned to your application when the semaphore, mutex, mailbox or
queue is created (see
OSSemCreate(), OSMutexCreate(), OSMboxCreate() and
OSQCreate()).
pname is a pointer to an ASCII string that contains the name for the resource. The size of the string
must be smaller than or equal to
OS_EVENT_NAME_SIZE characters (including the NUL
character).
perr a pointer to an error code and can be any of the following:
OS_ERR_NONE If the name of the semaphore, mutex, mailbox or queue was
copied to the array pointed to by
pname.
OS_ERR_EVENT_TYPE You are not pointing to either a semaphore, mutex, mailbox or
message queue.
OS_ERR_PEVENT_NULL You passed a NULL pointer for pevent.
OS_ERR_NAME_SET_ISR You called this function from an ISR.
Returned Values
none
Notes/Warnings
1. The semaphore, mutex, mailbox or message queue must be created before you can use this function and set
the name of the resource.
