To this for beginners at the the fastest to understand real time operating system belongs µC/OS from Jean J. Labrosse ( see http://www.micrium.com ).
It can administer up to 63 applikationtasks with ever different priorities and belongs to the real time operating systems with the lowest storage demand.
pC/OS was based on the original version µC/OS 1.00 from the Embedded Systems Programming Magazine(1992) developed further.

Since is exchanged by direct transfer of pointers in the original version data between the tasks, and consequently no guarantee for the free usability of the sending-buffers after transfer to another task exists and, much important, the recipient a pointer in the data field of another tasks gets (pointer-error / longitudinal mistake / manipulations among others) I altered the mechanisms for Message-Box and Queue accordingly in a way that the data about a kernel-internal Buffer now are handed over to the recipient. This means that the kernel copies to transferring data into an individual buffer and this copies also again itself with transfer to the recipient in the buffer prepared through the recipient. This admittedly entails a higher storage demand for Queue, secures the processes for it most extensive, however (for real-mode) of each other from. Kernel constants were transferred in the CODE-Area for security reasons furthermore. Furthermore I have add pipes, eventgroups., timerservice and dynamic memory management. In order to declare these alterations unequivocally, I have the name, ajar at the always bigger nascent original "µC/OS", on pC/OS like "pico-C.." altered.

Special to:  Priority Inversion, the problem and the solutions (actual only in german - sorry !)


known bugs:
If a task with lower priority waits for a recource, and a task with higher priority this recource places, so the asleep Task is put into the ready-state. Since the task with higher priority further-runs, this cannot finish reading again the same recource since the lower task 'prematurely' comes with implementation with the return-code OS_TIMEOUT back otherwise.

Configuration of the kernel

The pC/OS kernel can be configured in addition to the to-use hardware port some numbers of ways to configure Services/IPCs as well as to reduce the memory requirements - code-size for the compilers "unused code" may not clearly identify and RAM - available.
These are in the file "OS_cfg.h" together.

to OS_MAX_TASKS and OS_MIN_PRIO:
If a system is needed with 5 tasks, 2 of which tasks are using a shared mutex, you need OS_MAX_TASKS = 7 (including a Mutex and Idle-Task) and OS_MIN_PRIO = 8 whereas the Idle-Task then gets the prio 7 and all other Tasks and the Mutex gets higher priorities (0..6). If the timer-service should used too, it must be this timer task additionally involved.

Task-Control

Initialize the Kernel and installs the Idle-Task. This function must be called before all other kernelservices at the system initialization once.

none

none

void main(void) { . . OS_Init(); . . OS_Start(); }

starts the kernel. This function activates the sheduler.

none

none

void main(void) { . . OS_Init(); . . OS_Start(); }

Installs a new Task. This function initializes the Task-Control-Block and writes down the new Task with his Stack and the call parameters. This can from main() take place out in term during the initialization as well as another Task.
If the optional feature "OS_STK_CHECK_EN" (Stack-end check) is used, the kernel requires an additional pointer to the stack end.

*dptr	pointer to task-code
*data	pointer to parameter of this task
*pstk	pointer to stack of this task
*pstkend	pointer to end-of-stack of this task
prio	priority of this task

OS_NO_ERR	Task successfully positioned
OS_PRIO_EXIST	under this priority, already a Task exists
OS_PRIO_INVALID	this priority is reserved for the Idle-Task or the value of priority is bigger than OS_MIN_PRIO

OS_STK_TYPE Task1Stack[STK_SIZE]; U08 Task1Data; void OS_FAR Task1(void *data); // forward declaration . . void main(void) { U08 state; . . OS_Init(); . state = OS_TaskCreate(Task1, (void *)&Task1Data, (void *)&Task1Stack[STK_SIZE], 18); . OS_Start(); } . . void OS_FAR Task1(void *data) { . . while(1) { . . . } }

Change the priority of the current Tasks.
This function can be used in order to change the priority of the tasks on reason of an event for example.

newp	new priority of this task

OS_NO_ERR	Priority successfully altered
OS_PRIO_EXIST	under this priority, already a task exists
OS_PRIO_INVALID	this priority is reserved for the Idle-Task or the value of priority is bigger than OS_MIN_PRIO
OS_MUX_USED	to change Task have a Mutex occupied

void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_ChangePrio(38); . } }

Change the priority of a Tasks. This function can be used in order to change the priority of a running/ready tasks on reason of an event for example.
The priority of Tasks, waiting on a resource (Semaphore/Queue/Pipe/..) can not altered, because this state is visible for the kernel but not the exact resource itself.

oldp	actual/old priority of the task
newp	new priority of the task

OS_NO_ERR	Priority successfully altered
OS_PRIO_EXIST	under this priority, already a task exists
OS_PRIO_INVALID	this priority is reserved for the Idle-Task or the value of priority is bigger than OS_MIN_PRIO
OS_TASK_NOT_RDY	the Task is not in RUNNING/READY-state and so the priority can not altered
OS_MUX_USED	to change Task have a Mutex occupied

void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TaskChangePrio(38, 25); . } }

Delete the given task.
This function can be used, about for example on reason of an event the task too ending/clearing. This task is distant from the Task-Control-Table afterwards. Allocated resources of the tasks are not released automatically on that occasion.
In order to later be able to execute this task again, it must be positioned again by means of OS_TaskCreate regularly.
Tasks, waiting on a resource (Semaphore/Queue/Pipe/..) can not be deleted, because this state is visible for the kernel but not the exact resource itself.

prio	priority of the task to delete

OS_NO_ERR	Task deleted
OS_TASK_NOT_RDY	the Task is not in RUNNING/READY-state and so the task can not be deleted
OS_MUX_USED	to change Task have a Mutex occupied

void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TaskDelete(OS_PRIO_SELF); . } }

Delete the given task by unique ID.
This function can be used, about for example on reason of an event the task too ending/clearing. This task is distant from the Task-Control-Table afterwards. Allocated resources of the tasks are not released automatically on that occasion.
In order to later be able to execute this task again, it must be positioned again by means of OS_TaskCreate regularly.
Tasks, waiting on a resource (Semaphore/Queue/Pipe/..) can not be deleted, because this state is visible for the kernel but not the exact resource itself.

id	unique ID of the task to delete

OS_NO_ERR	Task deleted
OS_TASK_NOT_EXIST	the specified task does not exist
OS_TASK_NOT_RDY	the Task is not in RUNNING/READY-state and so the task can not be deleted
OS_MUX_USED	to change Task have a Mutex occupied

void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TaskIdDelete(3); . } }

Returns the current status of the given task.

prio	priority of the task

status

see "TASK STATUS", Bitmask

void OS_FAR Task1(void *data) { U08 status; . . while(1) { . status = OS_TaskGetStatus(6); . } }

Returns the current status of the given task by unique ID.

id	unique ID of the task

status

see "TASK STATUS", Bitmask

void OS_FAR Task1(void *data) { U08 status; . . while(1) { . status = OS_TaskIdGetStatus(2); . } }

Returns the unique-ID to the specified tasks. These can later be used to e.g. a task - even if his priority have changed or has just a mutex in use - a violent end (see OS_TaskDestroy()).

prio	current priority of the task

ID	the unique-ID of this task

U08 idT1; void OS_FAR Task1(void *data) { . idT1 = OS_TaskGetID(OS_PRIO_SELF); . while(1) { . . } }

Returns the priority to the specified tasks by unique ID.

id	unique ID of the task

PRIO	the current priority of this task

U08 prioT1; void OS_FAR Task1(void *data) { . prioT1 = OS_TaskGetPrio(2); . while(1) { . . } }

Removes the specified task completely independently of his status. This feature can be used to e.g. on basis of an event the task is to cancel. This task is then from the Task-Control-Table, from possibly registered IPCs (Semaphore/MBox/Queue/Pipe/..) and the Memory Manager completely removed.
If the tasks at this stage, a mutex has occupied, it will be released and a user-callback function is called to make any necessary reinitialization of the affected hardware, etc. (see OSMutexReInitResource () in "pC_OS_userCB.c"). But this can be done only for one mutex (the last). If the task have two mutexes occupied, it is only the last released!
In order to later be able to execute this task again, it must be positioned again by means of OS_TaskCreate regularly.
ATTENTION:
During this task will be removed from the Task-Control-Table and from the IPCs all interrupts are blocked because a suitable event for this task could result in a access/update conflict. During the subsequent clean up the memory-manager the interrupts are allowed again but sheduling is suppressed to prevent a simultaneous re-booting this task using OS_TaskCreate() (priority of this task).

id	unique-ID of the task to destroy

OS_NO_ERR	task completely removed
OS_TASK_NOT_EXIST	the specified task does not exist
OS_TASK_NOT_RDY	the task could not be completely removed from the IPCs or a mutex
OS_MEM_ERR	during deallocating the memory allocations of this task an error occurs

void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TaskIdDestroy(2); . } }

suspends a task from the implementation through the kernel.
This function can be used in order to deactivate a task for a time on reason of an event for example.

prio	priority of task to suspending

OS_NO_ERR	Task successfully suspended
OS_SUSPEND_IDLE	the Idle-Task cannot be suspended
OS_PRIO_INVALID	the value of priority is bigger than OS_MIN_PRIO
OS_TASK_SUSP_PRIO	under this priority, no Task is registered
OS_MUX_USED	to change Task have a Mutex occupied

void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TaskSuspend(24); . } }

suspends a task given by unique ID from the implementation through the kernel.
This function can be used in order to deactivate a task for a time on reason of an event for example.

id	unique ID of task to suspending

OS_NO_ERR	Task successfully suspended
OS_SUSPEND_IDLE	the Idle-Task cannot be suspended
OS_TASK_SUSP_PRIO	under this priority, no Task is registered
OS_MUX_USED	to change Task have a Mutex occupied

void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TaskIdSuspend(4); . } }

Reactivate a suspended Task. This function can be used in order to activate a suspended task again on reason of an event for example.

prio	priority of suspended task

OS_NO_ERR	Task successfully reactivated
OS_TASK_NOT_SUSP	the Task is not suspended
OS_PRIO_INVALID	the value of priority is bigger than OS_MIN_PRIO
OS_TASK_NOT_EXIST	under this priority, no Task is registered
OS_MUX_USED	to change Task have a Mutex occupied

void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TaskResume(24); . } }

Reactivate a suspended Task by given unique ID. This function can be used in order to activate a suspended task again on reason of an event for example.

id	unique ID of suspended task

OS_NO_ERR	Task successfully reactivated
OS_TASK_NOT_SUSP	the Task is not suspended
OS_TASK_NOT_EXIST	under this priority, no Task is registered
OS_MUX_USED	to change Task have a Mutex occupied

void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TaskIdResume(4); . } }

If puts the current task for kernel-ticks sleeps. This function can be used in order to let pass a defined time on reason of an event for example.
ATTENTION! With the parameter OS_SUSPEND (0), the Task for always is deactivated and can never be activated again.

ticks

kernel-ticks as sleeping-time ( 1...65535 )

none

void OS_FAR Task1(void *data) { . . while(1) { . OS_TimeDly(200); . } }

If the wait prematurely breaks off of a tasks. This function can be used in order to prematurely activate an asleep task again on reason of an event for example.

prio	priority of sleeping task

OS_NO_ERR	Task successfully wakened
OS_TIME_NOT_DLY	the task doesn't sleep
OS_PRIO_INVALID	the value of priority is bigger than OS_MIN_PRIO
OS_TASK_NOT_EXIST	under this priority, no task is registered

void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TimeDlyResume(24); . } }

If the wait prematurely breaks off of a tasks by unique ID. This function can be used in order to prematurely activate an asleep task again on reason of an event for example.

id	unique ID of sleeping task

OS_NO_ERR	Task successfully wakened
OS_TIME_NOT_DLY	the task doesn't sleep
OS_TASK_NOT_EXIST	under this id, no task is registered

void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TimeDlyIdResume(4); . } }

If turns off the sheduler.
This function can be used, about for example atomic (not under-breakable) to be able to execute processes, without task-switches. Interrupts still is served.

none

none

void OS_FAR Task1(void *data) { . . while(1) { . OS_Lock(); . . // not under-breakable part . OS_Unlock(); . } }

If switches on the sheduler again.
This function is used, about for example atomic (not under-breakable) to complete processes and to make a taskswitch again possible.

none

none

void OS_FAR Task1(void *data) { . . while(1) { . OS_Lock(); . . // not under-breakable part . OS_Unlock(); . } }

It returns a pointer on the kernelrevision (NULL-terminated ASCII-array).

none

*pointer

pointer to the address of array

void OS_FAR Task1(void *data) { U08 OS_FAR *Revision; . . while(1) { . Revision = OS_GetRev(); . } }

Dynamic-Memory

Initialize the dynamic memory management.
This function must be called for the dynamic memory management at the system initialization once. The functions of the vigorous memory management can be used also without current kernel.
ATTENTION! It is executed no checkup of the storage area.

*mp	startaddress of memory-pool (known by Linker)
size	size of memory-pool in bytes

OS_NO_ERR	Memory pool positioned
OS_MEM_ERR	one of the parameters is ZERO

void main(void) { U08 state; . . // Memory: 512k - 64k(near) state = OS_MemoryInit((OS_MEM OS_HUGE *)(0x10000000), 458750); . . }

U08 memorypool[MEMSIZE]; void main(void) { U08 state; . state = OS_MemoryInit((OS_MEM OS_HUGE *)(memorypool), MEMSIZE); . . }

Allocation of a required memory area.

*MemPtr	pointer of pointer to get address of memory-area
size	size of needed memory in bytes

OS_NO_ERR	Store successfully allocated
OS_MEM_ERR	size is ZERO or bigger as storage area of the processor
OS_MEM_OVF	not sufficiently free storage

void OS_FAR Task1(void *data) { U08 OS_HUGE *Addr_p; U08 state; . . while(1) { . state = OS_MemAlloc(&Addr_p, 3800); . } }

Releases of an allocated memory area.

*MemPtr

pointer to address of memory-area

OS_NO_ERR	Store successfully released
OS_MEM_ERR	Pointer is ZERO or not a valid allocation found

void OS_FAR Task1(void *data) { U08 OS_HUGE *Addr_p; U08 state; . . while(1) { . state = OS_MemAlloc(&Addr_p, 3800); . . state = OS_MemFree((OS_MEM OS_HUGE *) Addr_p); . } }

Mailboxes

If initializes a Mailbox. Through a mailbox any kind of data can pass by a pointer. On this, the recipient receives a pointer in the data field of the sender!

*pmbox

pointer to Mailbox

OS_NO_ERR

Mailbox initialized

OS_MBOX MailBox1; void main(void) { U08 state; . . OS_Init(); . state = OS_MboxInit(&MailBox1); . }

Attendants on a message from a mailbox.
With OS_NO_SUSP, it immediately is come back even if no news was available and becomes with OS_SUSPEND as long as waited until a message is available, if necessary unending.

*pmbox	pointer to Mailbox
*msg	pointer to receiving pointer
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Message from Mailbox gotten
OS_MBOX_NODATA	no message in Mailbox (with OS_NO_SUSP)
OS_TIMEOUT	no message in Mailbox (after waits)

OS_MBOX MailBox1; void OS_FAR Task1(void *data) { U08 state; void *Message; . . while(1) { . state = OS_MboxPend(&MailBox1, &Message, 200); . } }

Abborts waiting of a receiving Tasks (highest waiting prio) on a Mailbox.
It is only the waiting task with the highest priority quasi "premature" to TimeOut forwarded.

*pmbox

pointer to Mailbox

OS_NO_ERR	pending of a task abborted
OS_TASK_NOT_EXIST	no pending task on this Maibox

OS_MBOX MailBox1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_MboxPendAbbort(&MailBox1); . } }

Sends a message into a Mailbox.
With OS_NO_SUSP, it immediately is come back even if the Mailbox was full and becomes with OS_SUSPEND as long as waited until the message can be written down, if necessary unending.

*pmbox	pointer to Mailbox
*msg	pointer to message
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Message in Mailbox sent
OS_MBOX_FULL	Mailbox fully (with OS_NO_SUSP)
OS_TIMEOUT	Mailbox fully (after waits)

OS_MBOX MailBox1; void OS_FAR Task1(void *data) { U08 state; U32 Message; . . while(1) { . Message = 0x3076; state = OS_MboxPost(&MailBox1, (void *)&Message, OS_SUSPEND); . } }

Abborts waiting of a sending Tasks (highest waiting prio) on a Mailbox.
It is only the waiting task with the highest priority quasi "premature" to TimeOut forwarded.

*pmbox

pointer to Mailbox

OS_NO_ERR	posting of a task abborted
OS_TASK_NOT_EXIST	no posting task on this Maibox

OS_MBOX MailBox1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_MboxPostAbbort(&MailBox1); . } }

Queues

Initialize a Queue. A Queue serves the byte-expels transfer of data at another process of the FIFO-prinzip.
Within this Queue can <size> byte through the kernel buffer <*buffer> at other processes is handed over.
The buffer can be generated through direct declaration (UBYTE buffer[size]) or through dynamic allocation. For the dynamic allocation in systems with segment-based memory management, the type declaration is OS_HUGE necessary in order to be able to go down well away with an area over segment borders.

*pq	pointer to Queue
*buffer	pointer to kernel-buffer
size	size of kernel-buffer in bytes

OS_NO_ERR

Queue initialized

OS_Q Queue1; U08 Q_Data1[256]; void main(void) { U08 state; . . OS_Init(); . state = OS_QueueInit(&Queue1, &Q_Data1[0], 256); . }

Retrieval of the status of a Queue.
Through this retrieval, miscellaneous parameters their initialization as well as their filling stand can be determined. Furthermore, the priority of the waiting tasks can be determined.

*pq	pointer to Queue
*size	pointer to variable will get the size
*used	pointer to variable will get the used-bytes at this time
*prio	pointer to variable will get the priority of waiting Task (if zero - no Task is waiting)

OS_NO_ERR

no mistake (for expansions)

OS_Q Queue1; void OS_FAR Task1(void *data) { U08 state; U16 size; U16 used; U08 prio; . . while(1) { . state = OS_QueueInfo(&Queue1, &size, &used, &prio); . } }

Attendants on one byte from a Queue.
With OS_NO_SUSP, it immediately is come back even if no bytes were available and become with OS_SUSPEND as long as waited until one byte is available, if necessary unending.

*pq	pointer to Queue
*msg	pointer to receiving Byte
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Byte from Queue gotten
OS_Q_NODATA	no byte in Queue (with OS_NO_SUSP)
OS_TIMEOUT	no byte in Queue (after waits)

OS_Q Queue1; void OS_FAR Task1(void *data) { U08 state; U08 Receive; . . while(1) { . state = OS_QueuePend(&Queue1, &Receive, 100); . } }

Abborts waiting of a receiving Tasks (highest waiting prio) on a Queue.
It is only the waiting task with the highest priority quasi "premature" to TimeOut forwarded.

*pq	pointer to Queue

OS_NO_ERR	pending of a task abborted
OS_TASK_NOT_EXIST	no pending task on this Queue

OS_Q Queue1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_QueuePendAbbort(&Queue1); . } }

Sends one byte into a Queue.
With OS_NO_SUSP, it immediately is come back even if the Queue was full and becomes with OS_SUSPEND as long as waited until the byte can be written down, if necessary unending.

*pq	pointer to Queue
msg	byte to send
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Byte in Queue sent
OS_Q_FULL	Queue fully (with OS_NO_SUSP)
OS_TIMEOUT	Queue fully (after waits)

OS_Q Queue1; void OS_FAR Task1(void *data) { U08 state; U08 Message; . . while(1) { . Message = 0x6A; state = OS_QueuePost(&Queue1, Message, 5000); . } }

Sends one byte at the beginning of a Queue. Consequently, this byte first is finished reading again by the recipient (cuts in line).
With OS_NO_SUSP, it immediately is come back even if the Queue was full and becomes with OS_SUSPEND as long as waited until the byte can be written down, if necessary unending.

*pq	pointer to Queue
msg	byte to send
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Byte in Queue sent
OS_Q_FULL	Queue fully (with OS_NO_SUSP)
OS_TIMEOUT

OS_Q Queue1; void OS_FAR Task1(void *data) { U08 state; U08 Message; . . while(1) { . Message = 0x2D; state = OS_QueueFrontPost(&Queue1, Message, OS_NO_SUSP); . } }

Abborts waiting of a sending Tasks (highest waiting prio) on a Queue.
It is only the waiting task with the highest priority quasi "premature" to TimeOut forwarded.

*pq	pointer to Queue

OS_NO_ERR	posting of a task abborted
OS_TASK_NOT_EXIST	no posting task on this Queue

OS_Q Queue1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_QueuePostAbbort(&Queue1); . } }

Deletes the content of a Queue and reactivates a waiting posting-process.
This function can be used to reactivate the datatransfer after a hang-on. The deleted data get lost on that occasion.

*pq	pointer to Queue

OS_NO_ERR

content of Queue deleted

OS_Q Queue1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . . state = OS_QueueClear(&Queue1); . } }

Pipes

Initialize a Pipe. A Pipe serves transfer of data of the package manners at another process of the FIFO-prinzip.
Within this Pipe can at most <deep> package with ever at most <size> byte one packet through the kenrnel-buffer <*buffer> at another process is handed over.
The Buffer can be generated through direct declaration (UBYTE Buffer[(size+2)*deep]) or through dynamic memory allocation. For the dynamic allocation in systems with segment-based memory management, the type declaration is OS_HUGE necessary in order to be able to go down well away with an area over segment borders. The additional length of 2 bytes per package is required for the storage of the package length.

*pp	pointer to Pipe
*buffer	pointer to kernel-buffer
size	max size of data-bytes per paket
deep	max pakets in pipe

OS_NO_ERR

Pipe initialized

OS_P Pipe1; U08 P_Data1[(MAXPAKET+2)*8]; void main(void) { U08 state; . . OS_Init(); . state = OS_PipeInit(&Pipe1, P_Data1, MAXPAKET+2, 8); . }

Retrieval of the status of a Pipe. Through this retrieval, miscellaneous parameters of their initialization as well as their filling stand can be determined. Furthermore, the priority of the waiting Tasks can be determined.

*pp	pointer to pipe
*size	pointer to variable will get the size per paket
*deep	pointer to variable will get the max pakets in pipe
*used	pointer to variable will get the used-pakets at this time
*prio	pointer to variable will get the priority of waiting Task (if zero - no Task is waiting)

OS_NO_ERR

no mistake (for expansions)

OS_P Pipe1; void OS_FAR Task1(void *data) { U08 state; U16 size; U08 deep; U08 used; U08 prio; . . while(1) { . state = OS_PipeInfo(&Pipe1, &size, &deep, &used, &prio); . } }

Attendants on a data package from a Pipe. The receiver-buffer must be included sufficiently big in order to be able to pick up the package. Since the receiver-buffer can also be dynamically allocated, the type declaration is OS_HUGE necessary on the other hand in order to be able to go down well away with an area over segment borders.
With OS_NO_SUSP, it immediately is come back even if no package was available and becomes with OS_SUSPEND as long as waited until one package is available, if necessary unending.

*pp	pointer to pipe
*msg	pointer to receiving array
*lng	pointer to variable will get the lenght of paket
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Package from Pipe gotten
OS_P_NODATA	no package in Pipe (with OS_NO_SUSP)
OS_TIMEOUT	no package in Pipe (after waits)

OS_P Pipe1; void OS_FAR Task1(void *data) { U08 state; U16 rLenght; U08 Receive[1024]; . . while(1) { . state = OS_PipePend(&Pipe1, Receive, &rLenght, OS_SUSPEND); . } }

Abborts waiting of a receiving Tasks (highest waiting prio) on a Pipe.
It is only the waiting task with the highest priority quasi "premature" to TimeOut forwarded.

*pp	pointer to Pipe

OS_NO_ERR	pending of a task abborted
OS_TASK_NOT_EXIST	no pending task on this Pipe

OS_P Pipe1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_PipePendAbbort(&Pipe1); . } }

Sends one package into a Pipe. So the transmitter-buffer also dynamically allocated can be, the type declaration is OS_HUGE necessary on the other hand in order to be able to go down well away with an area over segment borders.
With OS_NO_SUSP, it immediately is come back even if the Pipe was full and becomes with OS_SUSPEND as long as waited until the package can be written down, if necessary unending.

*pp	pointer to pipe
*msg	pointer to data-paket
lenght	lenght of data-paket
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Package in Pipe sent
OS_P_FULL	Pipe fully (with OS_NO_SUSP)
OS_P_LEN_ERR	Package too long
OS_TIMEOUT	Pipe fully (after waits)

OS_P Pipe1; void OS_FAR Task1(void *data) { U08 state; U08 Message[]={"Hello World!"}; . . while(1) { . . state = OS_PipePost(&Pipe1, Message, strlen(Message), 500); . } }

Sends one package at the beginning of a Pipe. Consequently, this package first is finished reading again by the recipient (cuts in line). Since the transmitter-buffer can also be dynamically allocated, the type declaration is OS_HUGE necessary on the other hand in order to be able to go down well away with an area over segment borders.
With OS_NO_SUSP, it immediately is come back even if the Pipe was full and becomes with OS_SUSPEND as long as waited until the package can be written down, if necessary unending.

*pp	pointer to pipe
*msg	pointer to data-paket
lenght	lenght of data-paket
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Package in Pipe sent
OS_P_FULL	Pipe fully (with OS_NO_SUSP)
OS_P_LEN_ERR	Package too long
OS_TIMEOUT	Pipe fully (after waits)

OS_P Pipe1; void OS_FAR Task1(void *data) { U08 state; U08 Message[]={"Hello World !"}; . . while(1) { . . state = OS_PipeFrontPost(&Pipe1, Message, strlen(Message), OS_NO_SUSP); . } }

Abborts waiting of a sending Tasks (highest waiting prio) on a Pipe.
It is only the waiting task with the highest priority quasi "premature" to TimeOut forwarded.

*pp	pointer to Pipe

OS_NO_ERR	posting of a task abborted
OS_TASK_NOT_EXIST	no posting task on this Pipe

OS_P Pipe1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_PipePostAbbort(&Pipe1); . } }

Deletes the content of a Pipe and reactivates a waiting transmitter-process.
This function can be used to reactivate the datatransfer after a hang-on. The deleted packages get lost on that occasion.

*pp	pointer to pipe

OS_NO_ERR

Pipe-content deleted

OS_P Pipe1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . . state = OS_PipeClear(&Pipe1); . } }

Semaphores

Initialize a Semaphore. One semaphores serves the process-syncronisation. Two variations of the utilization belong semaphores to it to one.
- binary: for example the syncronisation of accesses on common recources/variables
- counting: Attendants on entering of a signal, to the control of the sequence of processes.

With a binary semaphore, a state-machine can become protected before simultaneous accesses of different processes (Read/Write), for example. So, inconsistent conditions or data are avoided. Can appear however in some cases Priority Inversion, occupied i.e. this a low Task the recource, a higher Task therefore must wait and then for example through an INT a middle Task(and its heirs) whom lower Task interrupts for an uncertain time. In such a case, it is initialized the semaphores with 1 as cnt, the access asked by means of OS_SemPend and released again by means of OS_SemPost.

With a counting semaphore, arriving is signalled by events. So, a process can wait for a signal to pause about the sequence of processes. By means of OS_SemAccept, also the number of the meanwhile entered events can be determined on that occasion. In such a case, it is initialized the semaphores with 0 as cnt, waited on the event by means of OS_SemPend or OS_SemAccept and reported the event by means of OS_SemPost.

*psem	pointer to Semaphore
cnt	start-count / max processes at the same time

OS_NO_ERR

Semaphore initialized

OS_SEM State1; void main(void) { U08 state; . . OS_Init(); . state = OS_SemInit(&State1, 1); . }

Reserve one on the protected recource semaphore and consequently the access as well as wait for an event. With OS_NO_SUSP, it immediately is come back even if was not freely the semaphores as well as no event was available and becomes with OS_SUSPEND as long as waited until the semaphores the event could be reserved as well as could happen, if necessary unending.

*psem	pointer to Semaphore
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Semaphore reserve / event was available
OS_SEM_NODATA	Semaphore occupy / no event (with OS_NO_SUSP)
OS_TIMEOUT	Semaphore occupy / no event (after waits)

OS_SEM State1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_SemPend(&State1, OS_SUSPEND); . . } }

Abborts waiting of a Tasks (highest waiting prio) on a Semaphore.
It is only the waiting task with the highest priority quasi "premature" to TimeOut forwarded.

*psem

pointer to Semaphore

OS_NO_ERR	pending of a task abborted
OS_TASK_NOT_EXIST	no pending task on this Semaphore

OS_SEM State1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_SemPendAbbort(&State1); . } }

It is used as Event-Counter with utilization of the semaphores. The Semaphore-counter is not influenced on that occasion. If the counter bigger than 0 the current counter will return. With OS_NO_SUSP, it immediately is come back even if the semaphoren-counter 0 is and becomes with OS_SUSPEND as long as waited until the event once appeared, if necessary unending.

*psem	pointer to semaphore
*cnt	pointer to variable will get the counter-value
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Event min. 1 times happened
OS_SEM_NODATA	Counter immediately 0 (with OS_NO_SUSP)
OS_TIMEOUT	Counter immediately 0 (after waits)

OS_SEM Event1; void OS_FAR Task1(void *data) { U08 state; U16 EventCnt; . . while(1) { . state = OS_SemAccept(&Event1, &EventCnt, 500); . } }

Gives a retiring semaphore and consequently the access to the protected recource again freely as well as signals an event.

*psem

pointer to semaphore

OS_NO_ERR	Semaphores released / event reported
OS_SEM_OVF	Error in the Semaphore-handling (Counter too big)

OS_SEM State1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . . state = OS_SemPost(&State1); . } }

Deletes the Counter of the semaphore. This function can be used to reset a counting-semaphore or for error-handling to restart the semaphore-handling. With application of binary semaphore to the control of accesses on a protected recource must be released the semaphore in the connection with application to the mistake-handling by OS_SemPost so much times, how simultaneously processes can access the recource.

*psem

pointer to semaphore

OS_NO_ERR

count of semaphore reset to 0

OS_SEM State1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_SemClear(&State1); . } }

Mutexes

Aims as well as initializing of a Mutex (Mutual-Exclusion). A Mutex serves the syncronisation of accesses to common recources/variables. With a Mutex, state-machines are protected from simultaneous accesses of different processes (Read/Write), for example. The second process must wait, until the first process finished his access (Read/Write). So, inconsistent conditions or data are avoided. In contrast to the utilization of semaphores, the effect of the Priority Inversion cannot kick open on that occasion here. The priority of the Mutex must be included higher, as the highest priority of the Tasks accessing it. The Mutex is written down as not current Task, so under the same priority no other Task can run.

*pmux	pointer to mutex
prio	priority of this mutex

OS_NO_ERR

Mutex written down and initialized

OS_MUX Mutex1; void main(void) { U08 state; . . OS_Init(); . state = OS_MutexCreate(&Mutex1, 10); . }

Reserve a Mutex and consequently the access on the protected recource. With OS_NO_SUSP, it immediately is come back even if the Mutex was not free and becomes with OS_SUSPEND as long as waited until the Mutex could be reserved, if necessary unending.

*pmux	pointer to mutex
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Mutex reserved
OS_MUX_NOACC	Mutex occupied (with OS_NO_SUSP)
OS_TIMEOUT	Mutex occupied (after waits)
OS_MUX_ERR	Error in Mutex-handling

OS_MUX Mutex1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . . state = OS_MutexPost(&Mutex1); . } }

Abborts waiting of a Tasks (highest waiting prio) on a Mutex.
It is only the waiting task with the highest priority quasi "premature" to TimeOut forwarded.

*pmux

pointer to Mutex

OS_NO_ERR	pending of a task abborted
OS_TASK_NOT_EXIST	no pending task on this Mutex

OS_MUX Mutex1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_MutexPendAbbort(&Mutex1); . } }

Gives a reserved Mutex free and again the access on the protected recource.

*pmux

pointer to mutex

OS_NO_ERR	Mutex released
OS_MUX_ERR	Error in Mutex-handling

OS_MUX Mutex1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . . state = OS_MutexPost(&Mutex1); . } }

Event-Groups

Initialize an Event-group.
An Eventgroup consists individually can be processed of 32 single-events, that summarized in an ULONG, as also grouped. Each Event within the group can report the appearance of an event, however any statement about it doesn't meet, how often the event appeared in the meantime.
In order to also be able to count events, you must be used semaphores as Counting-Semaphore for every individual event. (semaphore with 0 initialize, at appearance of the event "OS_SemPost" and when wait "OS_SemAccept")

*pevg

pointer to eventgroup

OS_NO_ERR

Event-group initialized

OS_EVG Events1; void main(void) { U08 state; . . OS_Init(); . state = OS_EvgInit(&Events1); . }

Report the appearance an as well as several Events of an Event-Gruppe.
The bit mask is interpreted as AND of the Events on that occasion. I.e. all Events, that are sedate in the bit mask, are reported.
Fashion is used the utilization of this function for the erasure of Events.

*pevg	pointer to eventgroup
events	bit-mask of events
mode	mode of usement "OS_OR / OS_AND"

OS_NO_ERR

Event(s) reported

OS_EVG Events1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_EvgPost(&Events1,~0x00100000, OS_AND); // clear this event state = OS_EvgPost(&Events1, 0x00000100, OS_OR); // set this event . } }

Attendants on one as well as several Events of an Event-Group.
The bit mask is interpreted modes as connection of the Events on that occasion together with him. I.e., already an Event, that is sedate in the bit mask, is enough with OS_OR for the function and with OS_AND, all Events, that are sedate in the bit mask, had to arrive. With OS_NO_SUSP, it immediately is come back even if no Event appeared and becomes with OS_SUSPEND as long as waited until the Event(s) appeared, if necessary indefinitely.

*pevg	pointer to eventgroup
events	bit-mask of events
mode	mode of usement "OS_OR / OS_AND"
timeout	kernel-ticks as waiting-time ( 1...65534 )

OS_NO_ERR	Event(s) appeared
OS_EVG_NOE	Event(s) appeared not (with OS_NO_SUSP)
OS_TIMEOUT	Event(s) appeared not (after waits)

OS_EVG Events1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_EvgPend(&Events1, 0x00100100, OS_OR, OS_SUSPEND); . } }

Abborts waiting of a task (highest waiting prio) onto a Eventgroup.
It is only the waiting task with the highest priority quasi "premature" to TimeOut forwarded.

*pevg

pointer to eventgroup

OS_NO_ERR	pending of a task abborted
OS_TASK_NOT_EXIST	no pending task on this eventgroup

OS_EVG Events1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_EvgPendAbbort(&Events1); . } }

Timer-Service

Creating / initialize a timer.
A timer can e.g. for subsequent purposes:

• timeouts within protocol layers and applications such as TCP / IP, X25, HTTP, FTP, ...
• prevent the "starvation" of tasks by defining a timeout and corresponding measures such as priority raising or other
• Periodic management of services
• soft-deadline / watchdog of services

As mode subsequent details can be made:

• OS_TMR_ENABLE - starts the Timer immediately
• OS_TMR_RONCE - Timer is of type "run-once", this means single timeout and after it is automatically disabled, but remains registered
• OS_TMR_CYCL - Timer is of type "cyclic / periodic" this means the timer will automatically restarted after each timeout
• OS_TMR_CLR - Timer is of type "run-once auto-erase," this means the timer is single timeout and is automatically deleted and must be created new for further use

It is OS_TMR_CLR the scheme goes before OS_TMR_CYCL and this before OS_TMR_RONCE.

The registered callback function should be as short as possible. For information-sharing an argument can be used.

*ptmr	pointer to timer
time	timeout of this timer (in timer-ticks)
tFct	address of timeout-callback function
tArg	argument of timeout-callback function
mode	mode of this timer (run-once / cyclic / auto-clear)

OS_NO_ERR	Timer registered and initialized
OS_TMR_NO_TIME	no valid time a parameter given (time == 0)

OS_TMR Timer1; void TCP_To_CB(void *session) { OS_QueuePost(&TCPIP_To_Q, (U08)session, OS_NO_SUSP); } U08 TCP_send(void) { U08 state; U08 session; . . state = OS_TimerCreate(&Timer1, 30, TCP_To_CB, &session, OS_TMR_ENABLE | OS_TMR_CLR); . }

Deactivate and delete a Timer.

*ptmr

pointer to timer

OS_NO_ERR	timer deleted
OS_TMR_NOT_EXIST	the timer was not registered

OS_TMR Timer1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TimerDelete(&Timer1); . . } }

Starts a deactivated, restart a run-once or restart a running Timer.

*ptmp	pointer to timer
time	new timeout (if not zero) of this timer (in timer-ticks)

OS_NO_ERR	Timer (re-)started
OS_TMR_NOT_EXIST	the timer is not registered

OS_TMR Timer1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . state = OS_TimerStart(&Timer1, 0); . . } }

Stops / deactivat a running Timer.

*ptmr

pointer to timer

OS_NO_ERR	Timer stopped
OS_TMR_NOT_EXIST	the timer is not registered

OS_TMR Timer1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . . state = OS_TimerStop(&Timer1); . } }

Returns the status of a created timer.
The following information is provided:

• OS_TMR_ENABLE - the Timer is actually running
• OS_TMR_RONCE - Timer is of type "run-once", this means single timeout and after it is automatically disabled, but remains registered
• OS_TMR_CYCL - Timer is of type "cyclic / periodic" this means the timer will automatically restarted after each timeout
• OS_TMR_CLR - Timer is of type "run-once auto-erase," this means the timer is single timeout and is automatically deleted and must be created new for further use

If in the returns status not OS_TMR_ENABLE but OS_TMR_CLR, the timer was never created or the timer was "run-once auto-erase" and the time had expired.

*ptmr

pointer to timer

status

status of the timers (see "modi" on OS_TimerCreate)

OS_TMR Timer1; void OS_FAR Task1(void *data) { U08 state; . . while(1) { . . state = OS_TimerGetState(&Timer1); if(state & OS_TMR_ENABLE) { . . } . } }

Returns the remaining time (in timer-ticks) of a running timer.
Is the returned time equal to 0, the timer was expired or was never activated by OS_TimerCreate.

*ptmr

pointer to timer

time	remaining time in timer-ticks

OS_TMR Timer1; void OS_FAR Task1(void *data) { U32 rtime; . . while(1) { . . rtime = OS_TimerGetRemain(&Timer1); . } }

System-Ticks

Places the kernel-internal Tick-Counter on handed over value.

ticks

new value of tick-counter

none

void OS_FAR Task1(void *data) { . . while(1) { . OS_TimeSet(24837); . } }

It returns the current value of the kernel-internal Tick-Counter.

none

ticks

actual value of tick-counter

void OS_FAR Task1(void *data) { U32 time; . . while(1) { . time = OS_TimeGet(); . } }

Interrupts

Register an Interrupt-Level. No contextswitch are generated by it. This function is necessary for C-Code ISRs.

none

none

void OS_FAR ISR1(void) { OS_IntEnter(); . . . OS_IntExit(); }

Unregister an Interrupt-Level. Contextswitches are generated again by it. This function is necessary for C-Code ISRs.

none

none

void OS_FAR ISR1(void) { OS_IntEnter(); . . . OS_IntExit(); }

History

If writes down an entry into the History-Table of the kernel. Additional to the two parameters still becomes the priority of the Tasks and the Tick-Counter, as time stamps, written down.

param1	first 32-bit parameter for table
param2	secound 32-bit parameter for table

OS_NO_ERR

Entry written

OS_Q Queue5; void OS_FAR Task2(void *data) { U08 state; U08 Message; . . while(1) { . Message = 0x2D; state = OS_QueueFrontPost(&Queue5, Message, 200); if(state != OS_NO_ERR) OS_HistoryPost((U32)state, 0x0205); . } }

Reads next entry from the History-Table of the kernel and deletes this on that occasion.

*param1	pointer to variable will get the first 32-bit parameter
*param2	pointer to variable will get the secound 32-bit parameter
*prio	pointer to variable will get priority of task who has this written
*time	pointer to variable will get time-stamp of this entry

OS_NO_ERR	Entry read
OS_HIS_END	no entry existing

void OS_FAR Task3(void *data) { U08 state; U32 Hpara1; U32 Hpara2; U08 Tprio; U32 stamp; . . while(1) { . state = OS_HistoryRead(&Hpara1, &Hpara2, &Tprio, &stamp); . } }