michaelh/zephyr
1
0
Fork 0
Code Releases Activity

Doc: Change the Microkernel Objects to the Microkernel Services section.

Browse source 
Moves the Microkernel Object documentation to a new Microkernel Services
section within the Kernel Primer. Labels, cross-references, figures,
headings and filenames were updated to reflect the new structure. 

Change-Id: Ia2a91410a94caa8a97bb8211db5afc84b5dc0974
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero 2015-08-07 13:35:41 -05:00 • committed by Anas Nashif
commit 4d8b60adca
17 changed files with 293 additions and 244 deletions
Download patch file Download diff file Expand all files Collapse all files

0
doc/object/figures/task_states.svg → doc/kernel/microkernel/figures/microkernel_tasks_states.svg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

Before After
Before After

31
doc/kernel/microkernel/microkernel.rst Normal file
View file

@ -0,0 +1,31 @@
.. _microkernel:
Microkernel Services
####################
Section Scope
*************
This section provides an overview of the most important microkernel
services, and their operation.
Each service contains a definition, a function description, and a table
of :abbr:`APIs (Application Program Interfaces)` including the context that may
call them. This section does not replace the Application Program Interface
documentation but rather complements it. The examples should provide
you with enough insight to understand the functionality but are not
meant to replace the detailed in-code documentation. Please refer to the API documentation for
further details regarding each object's functionality.
Services Documentation
*********************
.. toctree::
:maxdepth: 1
microkernel_tasks
microkernel_timers
microkernel_memory
microkernel_signaling
microkernel_data
microkernel_interrupts

13
doc/kernel/microkernel/microkernel_data.rst Normal file
View file

@ -0,0 +1,13 @@
.. _microkernel_data:
Data Passing Services
#####################
This section contains the information about all data passing services available in the microkernel.
.. toctree::
:maxdepth: 2
microkernel_fifos
microkernel_mailboxes
microkernel_pipes

24
doc/object/microkernel_events.rst → doc/kernel/microkernel/microkernel_events.rst
View file

@ -1,10 +1,10 @@
.. _events:
.. _microkernel_events:
Events
******
######
Definition
==========
**********
Event objects are microkernel synchronization objects that tasks can
signal and test. Fibers and interrupt service routines may signal
@ -16,7 +16,7 @@ available and only needs to be tested once to become clear and
unavailable.
Function
========
********
Events were designed for interrupt service routines and nanokernel
fibers that need to wake up a waiting task. The event signal can be
@ -34,10 +34,10 @@ event the call returns a fail. Use semaphores for multiple tasks to
wait on a signal from them.
Usage
=====
*****
Defining an Event
-----------------
=================
The following parameters must be defined:
@ -63,13 +63,13 @@ as follows:
.. code-block:: console
% EVENT NAME ENTRY
% =======================================
% ==========================================
EVENT KEYPRESS validate_keypress
EVENT BUTTONPRESS NULL
Example: Signalling an Event from an ISR
----------------------------------------
Example: Signaling an Event from an ISR
========================================
This code signals an event during the processing of an interrupt.
@ -83,7 +83,7 @@ This code signals an event during the processing of an interrupt.
}
Example: Consuming an Event using a Task
----------------------------------------
========================================
This code processes events of a single type using a task.
@ -106,7 +106,7 @@ This code processes events of a single type using a task.
}
Example: Filtering Event Signals using an Event Handler
-------------------------------------------------------
=======================================================
This code registers an event handler that filters out unwanted events
so that the consuming task only wakes up when needed.
@ -149,7 +149,7 @@ so that the consuming task only wakes up when needed.
APIs
====
****
The following Event APIs are provided by microkernel.h.

22
doc/object/microkernel_fifos.rst → doc/kernel/microkernel/microkernel_fifos.rst
View file

@ -1,10 +1,10 @@
.. _microkernel_fifos:
Microkernel FIFOs
*****************
#################
Definition
==========
**********
The FIFO is defined in :file:`include/microkernel/fifo.h` as a simple
first-in, first-out queue that handle small amounts of fixed size data.
@ -14,7 +14,7 @@ FIFO objects are suitable for asynchronously transferring small amounts
of data, such as parameters, between tasks.
Function
========
********
FIFO objects store data in a statically allocated buffer defined within
@ -40,10 +40,10 @@ the fixed number of bytes is copied from the FIFO object into the
addresses of the destination pointer.
Usage
=====
*****
Defining a FIFO in MDEF file
----------------------------
Defining a FIFO in MDEF File
============================
The following parameters must be defined:
@ -74,8 +74,8 @@ that holds up to 10 items that are each 12 bytes long as follows:
FIFO SIGNAL_FIFO 10 12
Defining FIFO inside Code
-------------------------
Defining FIFO within the Code
=============================
In addition to defining FIFOs in MDEF file, it is also possible to
define FIFOs inside code. The macro ``DEFINE_FIFO(fifo_name)``
@ -102,7 +102,7 @@ to that file. The FIFO ``PRIV_FIFO`` can be then used there.
Example: Writing to a FIFO
--------------------------
==========================
This code uses a FIFO to pass data items from a producing task to
one or more consuming tasks. If the FIFO fills up because the consumers
@ -129,7 +129,7 @@ can't keep up, throw away all existing data so newer data can be saved.
}
Example: Reading from a FIFO
----------------------------
============================
This code uses a FIFO to process data items from generated by
one or more producing tasks.
@ -151,7 +151,7 @@ one or more producing tasks.
APIs
====
****
The following APIs for a microkernel FIFO are provided by microkernel.h.

84
doc/object/microkernel_mailboxes.rst → doc/kernel/microkernel/microkernel_mailboxes.rst
View file

@ -1,16 +1,16 @@
.. _mailboxes:
.. _microkernel_mailboxes:
Mailboxes
*********
#########
Definition
==========
**********
A mailbox is defined in include :file:`/microkernel/mailbox.h`.
Mailboxes are a flexible way to pass data and for tasks to exchange messages.
Function
========
********
Each transfer within a mailbox can vary in size. The size of a data
transfer is only limited by the available memory on the platform.
@ -30,10 +30,10 @@ receive from. Then the mailbox checks the identity of the sender and
receiver tasks before passing the data.
Usage
=====
*****
Defining a mailbox in MDEF file
-------------------------------
===============================
The following parameters must be defined:
@ -52,12 +52,12 @@ For example, the file :file:`projName.mdef` defines a mailbox as follows:
.. code-block:: console
% MAILBOX NAME
% =================
% ==========================
MAILBOX REQUEST_BOX
Defining mailbox inside code
----------------------------
Defining Mailboxes within the Code
==================================
In addition to defining mailboxes in MDEF file, it is also possible to
define mailboxes inside code. The macro ``DEFINE_MAILBOX(mailbox_name)``
@ -84,7 +84,7 @@ to that file. The mailbox ``PRIV_MBX`` can be then used there.
Example: Sending Variable-Sized Mailbox Messages
------------------------------------------------
================================================
This code uses a mailbox to synchronously pass variable-sized requests
from a producing task to any consuming task that wants it. The message
@ -128,7 +128,7 @@ that each task can handle.
}
Example: Receiving Variable-Sized Mailbox Messages
--------------------------------------------------
==================================================
This code uses a mailbox to process variable-sized requests from any
producing task. The message "info" field is used to exchange information
@ -171,7 +171,7 @@ about the maximum size buffer that each task can handle.
}
Example: Sending an Empty Mailbox Message
-----------------------------------------
=========================================
This code uses a mailbox to synchronously pass 4 byte random values
to any consuming task that wants one. The message "info" field is
@ -204,7 +204,7 @@ portion of the message isn't used.
}
Example: Receiving a Mailbox Message in 2 Stages
------------------------------------------------
================================================
This code uses a mailbox to receive data from a producing task only if
it meets certain criteria, thereby eliminating unneeded data copying.
@ -243,7 +243,7 @@ The message "info" field supplied by the sender is used to classify the message.
}
Example: Sending an Asynchronous Mailbox Message
------------------------------------------------
================================================
This code uses a mailbox to send asynchronous messages using memory blocks
obtained from TXPOOL, thereby eliminating unneeded data copying when exchanging
@ -284,7 +284,7 @@ to keep up.
}
Example: Receiving an Asynchronous Mailbox Message
--------------------------------------------------
==================================================
This code uses a mailbox to receive messages sent asynchronously using a
memory block, thereby eliminating unneeded data copying when processing
@ -333,37 +333,37 @@ a large message.
APIs
====
****
The following APIs for synchronous mailbox operations are provided
by microkernel.h.
+-----------------------------------------+-----------------------------------+
| Call | Description |
+=========================================+===================================+
| :c:func:`task_mbox_put()` | Puts message in a mailbox, or |
| | fails if a receiver isn't waiting.|
+-----------------------------------------+-----------------------------------+
| :c:func:`task_mbox_put_wait()` | Puts message in a mailbox and |
| | waits until it is received. |
+-----------------------------------------+-----------------------------------+
| :c:func:`task_mbox_put_wait_timeout()` | Puts message in a mailbox and |
| | waits for a specified time period |
| | for it to be received. |
+-----------------------------------------+-----------------------------------+
| :c:func:`task_mbox_get()` | Gets message from a mailbox, or |
| | fails if no message is available. |
+-----------------------------------------+-----------------------------------+
| :c:func:`task_mbox_get_wait()` | Gets message from a mailbox, or |
| | waits until one is available. |
+-----------------------------------------+-----------------------------------+
| :c:func:`task_mbox_get_wait_timeout()` | Gets message from a mailbox, or |
| | waits for a specified time period |
| | for one to become available. |
+-----------------------------------------+-----------------------------------+
| :c:func:`task_mbox_data_get()` | Finishes receiving message that |
| | was received without its data. |
+-----------------------------------------+-----------------------------------+
+-----------------------------------------+------------------------------------+
| Call | Description |
+=========================================+====================================+
| :c:func:`task_mbox_put()` | Puts message in a mailbox, or |
| | fails if a receiver isn't waiting. |
+-----------------------------------------+------------------------------------+
| :c:func:`task_mbox_put_wait()` | Puts message in a mailbox and |
| | waits until it is received. |
+-----------------------------------------+------------------------------------+
| :c:func:`task_mbox_put_wait_timeout()` | Puts message in a mailbox and |
| | waits for a specified time period |
| | for it to be received. |
+-----------------------------------------+------------------------------------+
| :c:func:`task_mbox_get()` | Gets message from a mailbox, or |
| | fails if no message is available. |
+-----------------------------------------+------------------------------------+
| :c:func:`task_mbox_get_wait()` | Gets message from a mailbox, or |
| | waits until one is available. |
+-----------------------------------------+------------------------------------+
| :c:func:`task_mbox_get_wait_timeout()` | Gets message from a mailbox, or |
| | waits for a specified time period |
| | for one to become available. |
+-----------------------------------------+------------------------------------+
| :c:func:`task_mbox_data_get()` | Finishes receiving message that |
| | was received without its data. |
+-----------------------------------------+------------------------------------+
The following APIs for asynchronous mailbox operations using memory pool blocks
are provided by microkernel.h.

13
doc/kernel/microkernel/microkernel_memory.rst Normal file
View file

@ -0,0 +1,13 @@
.. _microkernel_memory:
Memory Management Services
##########################
This section contains the information about the memory management services available in the
microkernel.
.. toctree::
:maxdepth: 2
microkernel_memory_maps
microkernel_memory_pools

32
doc/object/microkernel_memory_maps.rst → doc/kernel/microkernel/microkernel_memory_maps.rst
View file

@ -1,10 +1,10 @@
.. _memory_maps:
MEMORY MAPS
***********
Memory Maps
###########
Concepts
========
********
The microkernel's memory map objects provide dynamic allocation and
release of fixed-size memory blocks.
@ -36,16 +36,16 @@ blocks. (Alternatively, a memory pool object may be used.)
Purpose
=======
*******
Use a memory map to allocate and free memory in fixed-size blocks.
Usage
=====
*****
Defining a Memory Map in MDEF file
----------------------------------
Defining a Memory Map in MDEF File
==================================
Add an entry for one or more memory maps in the project file using the
following syntax:
@ -65,8 +65,8 @@ as follows:
MAP YOURMAP 6 200
Defining Memory Map in source code
----------------------------------
Defining Memory Map in the Source Code
======================================
In addition to defining memory maps in MDEF file, it is also possible
to define memory maps inside code. The macro ``DEFINE_MEMORY_MAP(...)``
@ -94,7 +94,8 @@ to that file. The memory map ``PRIV_MEM_MAP`` can be then used there.
Example: Requesting a Memory Block from a Map with No Conditions
----------------------------------------------------------------
================================================================
This code waits indefinitely for a memory block to become
available if all the memory blocks are in use.
@ -107,7 +108,8 @@ available if all the memory blocks are in use.
Example: Requesting a Memory Block from a Map with a Conditional Time-out
-------------------------------------------------------------------------
=========================================================================
This code waits a specified amount of time for a memory block to become
available and gives a warning if the memory block does not become available
in the specified time.
@ -125,7 +127,8 @@ in the specified time.
Example: Requesting a Memory Block from a Map with a No Blocking Condition
--------------------------------------------------------------------------
==========================================================================
This code gives an immediate warning when all memory blocks are in use.
.. code-block:: c
@ -140,7 +143,8 @@ This code gives an immediate warning when all memory blocks are in use.
Example: Freeing a Memory Block back to a Map
---------------------------------------------
=============================================
This code releases a memory block back when it is no longer needed.
.. code-block:: c
@ -154,7 +158,7 @@ This code releases a memory block back when it is no longer needed.
APIs
====
****
The following Memory Map APIs are provided by :file:`microkernel.h`.

28
doc/object/microkernel_memory_pools.rst → doc/kernel/microkernel/microkernel_memory_pools.rst
View file

@ -1,10 +1,10 @@
.. _memory_pools:
MEMORY POOLS
************
Memory Pools
############
Concepts
========
********
The microkernel's memory pool objects provide dynamic allocation and
release of variable-size memory blocks.
@ -59,7 +59,7 @@ allocate all of the available blocks.
Purpose
=======
*******
Use memory pools to allocate memory in variable-size blocks.
Use memory pool blocks when sending data to a mailbox
@ -67,10 +67,10 @@ asynchronously.
Usage
=====
*****
Defining a Memory Pool
----------------------
======================
The following parameters must be defined:
@ -110,7 +110,7 @@ as follows:
Example: Requesting a Memory Block from a Pool with No Conditions
-----------------------------------------------------------------
=================================================================
This code waits indefinitely for an 80 byte memory block to become
available, then fills it with zeroes.
@ -125,7 +125,8 @@ available, then fills it with zeroes.
Example: Requesting a Memory Block from a Pool with a Conditional Time-out
--------------------------------------------------------------------------
==========================================================================
This code waits up to 5 ticks for an 80 byte memory block to become
available and gives a warning if a suitable memory block is not obtained
in that time.
@ -142,7 +143,8 @@ in that time.
Example: Requesting a Memory Block from a Pool with a No Blocking Condition
---------------------------------------------------------------------------
===========================================================================
This code gives an immediate warning when it can not satisfy the request for
a memory block of 80 bytes.
@ -158,7 +160,8 @@ a memory block of 80 bytes.
Example: Freeing a Memory Block Back to a Pool
----------------------------------------------
==============================================
This code releases a memory block back to a pool when it is no longer needed.
.. code-block:: c
@ -171,7 +174,8 @@ This code releases a memory block back to a pool when it is no longer needed.
Example: Manually Defragmenting a Memory Pool
---------------------------------------------
=============================================
This code instructs the memory pool to concatenate any unused memory blocks
that can be merged. Doing a full defragmentation of the entire memory pool
before allocating a number of memory blocks may be more efficient
@ -183,7 +187,7 @@ each time a memory block allocation occurs.
task_mem_pool_defragment(MYPOOL);
APIs
====
****
The following Memory Pools APIs are provided by microkernel.h.

57
doc/object/microkernel_mutexes.rst → doc/kernel/microkernel/microkernel_mutexes.rst
View file

@ -1,10 +1,10 @@
.. _mutexes:
.. _microkernel_mutexes:
MUTEXES
*******
Mutexes
#######
Concepts
========
********
The microkernel's mutex objects provide reentrant mutex
capabilities with priority inheritance.
@ -59,16 +59,16 @@ completely.
Purpose
=======
*******
Use mutexes to provide exclusive access to a resource,
such as a physical device.
Usage
=====
*****
Defining a Mutex in MDEF file
-----------------------------
=============================
Add an entry for the mutex in the project file using the
following syntax:
@ -87,7 +87,7 @@ For example, the file :file:`projName.mdef` defines a single mutex as follows:
Defining a Mutex inside Code
----------------------------
============================
In addition to defining mutexes in MDEF file, it is also possible to define
mutexes inside code. The macro ``DEFINE_MUTEX(mutex_name)`` can be used
@ -114,58 +114,61 @@ to that file. The mutex ``XYZ`` can be then used there.
Example: Locking a Mutex with No Conditions
-------------------------------------------
===========================================
This code waits indefinitely for the mutex to become available if the
mutex is in use.
.. code-block:: c
task_mutex_lock_wait(XYZ);
moveto(100,100);
lineto(200,100);
task_mutex_unlock(XYZ);
task_mutex_lock_wait(XYZ);
moveto(100,100);
lineto(200,100);
task_mutex_unlock(XYZ);
Example: Locking a Mutex with a Conditional Timeout
---------------------------------------------------
===================================================
This code waits for a mutex to become available for a specified
time, and gives a warning if the mutex does not become available
in the specified amount of time.
.. code-block:: c
if (task_mutex_lock_wait_timeout(XYZ, 100) == RC_OK)
if (task_mutex_lock_wait_timeout(XYZ, 100) == RC_OK)
{
moveto(100,100);
lineto(200,100);
task_mutex_unlock(XYZ);
moveto(100,100);
lineto(200,100);
task_mutex_unlock(XYZ);
}
else
else
{
printf("Cannot lock XYZ display\n");
printf("Cannot lock XYZ display\n");
}
Example: Locking a Mutex with a No Blocking Condition
-----------------------------------------------------
=====================================================
This code gives an immediate warning when a mutex is in use.
.. code-block:: c
if (task_mutex_lock(XYZ) == RC_OK);
if (task_mutex_lock(XYZ) == RC_OK);
{
do_something();
task_mutex_unlock(XYZ); /* and unlock mutex*/
do_something();
task_mutex_unlock(XYZ); /* and unlock mutex*/
}
else
else
{
display_warning(); /* and do not unlock mutex*/
display_warning(); /* and do not unlock mutex*/
}
APIs
====
****
The following Mutex APIs are provided by :file:`microkernel.h`.

26
doc/object/microkernel_pipes.rst → doc/kernel/microkernel/microkernel_pipes.rst
View file

@ -1,10 +1,10 @@
.. _pipes:
.. _microkernel_pipes:
Pipes
*****
#####
Definition
==========
**********
Microkernel pipes are defined in :file:`kernel/microkernel/k_pipe.c`.
Pipes allow any task to put any amount of data in or out. Pipes are
@ -15,7 +15,7 @@ un-buffered operation is also possible. The main difference between
FIFO objects and pipes is that pipes handle variable-sized data.
Function
========
********
Pipes accept and send variable-sized data, and can be configured to work
with or without a buffer. Buffered pipes are time-ordered. The incoming
@ -38,10 +38,10 @@ receiver. Alternatively, mailboxes can be used to specify the sender
and receiver identities.
Usage
=====
*****
Defining a pipe in MDEF file
----------------------------
Defining a Pipes in MDEF file
=============================
The following parameters must be defined:
@ -68,8 +68,8 @@ For example, the file :file:`projName.mdef` defines a pipe as follows:
PIPE DATA_PIPE 1024
Defining pipes in source code
-----------------------------
Defining Pipes within the Code
========================================
In addition to defining pipes in MDEF file, it is also possible to
define pipes inside code. The macro ``DEFINE_PIPE(...)`` can be
@ -97,7 +97,7 @@ to that file. The pipe ``PRIV_PIPE`` can be then used there.
Example: Writing Fixed-Size Data Items to a Pipe
------------------------------------------------
================================================
This code uses a pipe to send a series of fixed-size data items
to a consuming task.
@ -121,7 +121,7 @@ to a consuming task.
}
Example: Reading Fixed-Size Data Items from a Pipe
--------------------------------------------------
==================================================
This code uses a pipe to receive a series of fixed-size data items
from a producing task. To improve performance, the consuming task
@ -150,7 +150,7 @@ rather than reading them individually.
}
Example: Reading a Stream of Data Bytes from a Pipe
---------------------------------------------------
===================================================
This code uses a pipe to process a stream of data bytes from a
producing task. The pipe is read in a non-blocking manner to allow
@ -183,7 +183,7 @@ unprocessed data bytes in the pipe.
APIs
====
****
The following Pipe APIs are provided by :file:`microkernel.h`.

26
doc/object/microkernel_semaphores.rst → doc/kernel/microkernel/microkernel_semaphores.rst
View file

@ -1,10 +1,10 @@
.. _microkernel_semaphores:
Semaphores
**********
##########
Definition
==========
**********
The microkernel semaphore is defined in
:file:`kernel/microkernel/k_semaphore.c` and are an implementation of
@ -12,7 +12,7 @@ traditional counting semaphores. Semaphores are used to synchronize
application task activities.
Function
========
********
Semaphores are initialized by the system. At start the semaphore is
un-signaled and no task is waiting for it. Any task in the system can
@ -26,10 +26,10 @@ signaled. If not signaled, tasks can either wait, with or without a
timeout, until signaled or return immediately with a failed status.
Usage
=====
*****
Defining a Semaphore in MDEF file
---------------------------------
=================================
The following parameters must be defined:
@ -55,8 +55,8 @@ as follows:
SEMA WORK_DONE
Defining Semaphore inside Code
------------------------------
Defining Semaphore Inside Code
==============================
In addition to defining semaphores in MDEF file, it is also possible to
define semaphores inside code. The macro ``DEFINE_SEMAPHORE(sem_name)``
@ -83,7 +83,7 @@ to that file. The semaphore ``PRIV_SEM`` can be then used there.
Example: Giving a Semaphore from a Task
---------------------------------------
=======================================
This code uses a semaphore to indicate that a unit of data
is available for processing by a consumer task.
@ -102,7 +102,7 @@ is available for processing by a consumer task.
}
Example: Giving a Semaphore from an ISR
---------------------------------------
=======================================
This code uses a semaphore to indicate that a unit of data
is available for processing by a consumer task.
@ -131,7 +131,7 @@ is available for processing by a consumer task.
}
Example: Taking a Semaphore with a Conditional Time-out
-------------------------------------------------------
=======================================================
This code waits up to 500 ticks for a semaphore to be given,
and gives a warning if it is not obtained in that time.
@ -152,7 +152,7 @@ and gives a warning if it is not obtained in that time.
}
Example: Monitoring Multiple Semaphores at Once
-----------------------------------------------
===============================================
This code waits on two semaphores simultaneously, and then takes
action depending on which one was given.
@ -178,7 +178,7 @@ action depending on which one was given.
}
Example: Giving Multiple Semaphores at Once
-------------------------------------------
===========================================
This code uses a semaphore group to allow a controlling task to signal
the semaphores used by four other tasks in a single operation.
@ -196,7 +196,7 @@ the semaphores used by four other tasks in a single operation.
APIs
====
****
The following APIs for an individual semaphore are provided by microkernel.h.

13
doc/kernel/microkernel/microkernel_signaling.rst Normal file
View file

@ -0,0 +1,13 @@
.. _microkernel_signaling:
Signaling Services
##################
This section contains the information about all signaling services available in the microkernel.
.. toctree::
:maxdepth: 2
microkernel_semaphores
microkernel_events
microkernel_mutexes

30
doc/object/microkernel_task_IRQs.rst → doc/kernel/microkernel/microkernel_task_irqs.rst
View file

@ -1,10 +1,10 @@
.. _task_IRQs:
.. _microkernel_task_irqs:
TASK IRQs
*********
Task IRQs
#########
Concepts
========
********
The microkernel's task IRQ objects allow interrupts to be serviced
by tasks, rather than interrupt service routines (ISRs).
@ -42,17 +42,17 @@ and makes the task IRQ available for re-allocation.
Purpose
=======
*******
Use a task IRQ when the work required to process an interrupt
cannot be done in an ISR, either because it takes a long time
or it requires the processing routine to block.
Usage
=====
*****
Configuring Task IRQs
---------------------
=====================
Set the :option:`MAX_NUM_TASK_IRQS` configuration option
to specify the number of task IRQs allowed in the project.
@ -66,7 +66,7 @@ project MDEF file.
Example: Allocating a Task IRQ
------------------------------
==============================
This code associates a task IRQ with interrupts generated by a device.
Interrupts from that device are then enabled
@ -85,14 +85,15 @@ so they can be processed using the task IRQ.
Example: Servicing Interrupts using a Task IRQ
----------------------------------------------
==============================================
This code allows a task to wait for an interrupt from a device,
acknowledge the interrupt, and take the necessary steps to service it.
.. code-block:: c
task_irq_test_wait(FOO_DEVICE);
/* Device interrupt is now masked */
/* Do pre-acknowledgement device processing (if any) */
@ -110,8 +111,9 @@ until the interrupt is acknowledged.
Some devices may require processing both before and after acknowledgement.
Example: Freeing a Task IRQ
---------------------------
Example: Freeing a Task IRQ
===========================
This code allows a task to disassociate a task IRQ
from interrupts generated by its associated device.
Interrupts from that device are no longer enabled.
@ -122,8 +124,8 @@ Interrupts from that device are no longer enabled.
Task IRQ APIs
=============
APIs
****
The following task IRQ APIs are provided by :file:`microkernel.h`:

104
doc/object/tasks.rst → doc/kernel/microkernel/microkernel_tasks.rst
View file

@ -1,5 +1,7 @@
Tasks
#####
.. _tasks:
Task Services
#############
Properties of Tasks
*******************
@ -15,7 +17,6 @@ Task Groups
TBD (how they are used; maximum of 32 groups; mention pre-defined task groups)
Task Behavior
*************
@ -52,7 +53,7 @@ possible transitions. The most usual transitions are green,
bidirectional transitions are blue and uncommon transitions are marked
orange.
.. figure:: figures/task_states.svg
.. figure:: figures/microkernel_tasks_states.svg
:scale: 75 %
:alt: Possible Task States
@ -84,12 +85,12 @@ a runnable state immediately after the kernel boots up.
Tasks Starting Other Tasks
^^^^^^^^^^^^^^^^^^^^^^^^^^
--------------------------
.. todo:: Add details on how to start a task from within another task.
Task Scheduling
---------------
Tasks Scheduling Model
**********************
Once started, a task is scheduled for execution by the microkernel until
one of the following occurs:
@ -104,12 +105,12 @@ one of the following occurs:
* The task becomes non-runnable.
Task Completion
^^^^^^^^^^^^^^^
===============
.. todo:: Add details on how tasks complete.
Task Priorities
^^^^^^^^^^^^^^^
===============
The kernel offers a configurable number of task priority levels. The
number ranges from 0 to :literal:`NUM_TASK_PRIORITIES-1`. The lowest
@ -136,7 +137,7 @@ principle of preemption.
Suspended Tasks
^^^^^^^^^^^^^^^
===============
Tasks can suspend other tasks, or themselves, using
:c:func:`task_suspend()`. The task stays suspended until
@ -161,8 +162,8 @@ execution when :c:func:`task_abort()` is called, and run the abort
handler function immediately.
Time-Slicing
------------
Task Time-Slicing
=================
Time-slicing, enabled through the :c:func:`sys_scheduler_time_slice_set()`
function, can share a processor between multiple tasks with the same
@ -183,25 +184,18 @@ If no other task of the same priority is runnable, the task that called
:c:func:`task_yield()` sorts the tasks in FIFO order.
Task Context Switches
^^^^^^^^^^^^^^^^^^^^^
=====================
When a task swap occurs, the kernel saves the context of the task
that is swapped out and restores the context of the task that is
swapped in.
Usage
=====
Defining a task
---------------
Defining a Task
***************
Inside MDEF files
^^^^^^^^^^^^^^^^^
=================
The following parameters must be defined:
@ -259,7 +253,7 @@ of six tasks as follows:
Inside Source Code
^^^^^^^^^^^^^^^^^^
==================
In addition to defining tasks in MDEF file, it is also possible to
define tasks inside code. The macro ``DEFINE_TASK(...)`` can be
@ -285,8 +279,8 @@ add:
to that file. The task ``PRIV_TASK`` can be then used there.
Defining a new task group
-------------------------
Defining a Task Group
*************************
The following parameters must be defined:
@ -313,7 +307,7 @@ task groups as follows:
Example: Starting a Task from a Different Task
----------------------------------------------
==============================================
This code shows how the currently executing task can start another task.
@ -333,7 +327,7 @@ This code shows how the currently executing task can start another task.
Example: Suspending and Resuming a Set of Tasks
-----------------------------------------------
===============================================
This code shows how the currently executing task can temporarily suspend
the execution of all tasks belonging to the designated task groups.
@ -365,43 +359,41 @@ the execution of all tasks belonging to the designated task groups.
}
}
APIs
====
****
The following APIs affecting the currently executing task
are provided by :file:`microkernel.h`.
+-------------------------------------+----------------------------------------+
| Call | Description |
+-------------------------------------+----------------------------------------+
| :c:func:`task_id_get()` | Gets the task's ID. |
+-------------------------------------+----------------------------------------+
| :c:func:`isr_task_id_get()` | Gets the task's ID from an ISR. |
+-------------------------------------+----------------------------------------+
| :c:func:`task_priority_get()` | Gets the task's priority. |
+-------------------------------------+----------------------------------------+
| :c:func:`isr_task_priority_get()` | Gets the task's priority from an ISR. |
+-------------------------------------+----------------------------------------+
| :c:func:`task_group_mask_get()` | Gets the task's group memberships. |
+-------------------------------------+----------------------------------------+
| :c:func:`isr_task_group_mask_get()` | Gets the task's group memberships from |
| | an ISR. |
+-------------------------------------+----------------------------------------+
| :c:func:`task_yield()` | Yields CPU to equal-priority tasks. |
+-------------------------------------+----------------------------------------+
| :c:func:`task_sleep()` | Yields CPU for a specified time period.|
+-------------------------------------+----------------------------------------+
| :c:func:`task_abort_handler_set()` | Installs the task's abort handler. |
+-------------------------------------+----------------------------------------+
+-------------------------------------+-----------------------------------------+
| Call | Description |
+=====================================+=========================================+
| :c:func:`task_id_get()` | Gets the task's ID. |
+-------------------------------------+-----------------------------------------+
| :c:func:`isr_task_id_get()` | Gets the task's ID from an ISR. |
+-------------------------------------+-----------------------------------------+
| :c:func:`task_priority_get()` | Gets the task's priority. |
+-------------------------------------+-----------------------------------------+
| :c:func:`isr_task_priority_get()` | Gets the task's priority from an ISR. |
+-------------------------------------+-----------------------------------------+
| :c:func:`task_group_mask_get()` | Gets the task's group memberships. |
+-------------------------------------+-----------------------------------------+
| :c:func:`isr_task_group_mask_get()` | Gets the task's group memberships from |
| | an ISR. |
+-------------------------------------+-----------------------------------------+
| :c:func:`task_yield()` | Yields CPU to equal-priority tasks. |
+-------------------------------------+-----------------------------------------+
| :c:func:`task_sleep()` | Yields CPU for a specified time period. |
+-------------------------------------+-----------------------------------------+
| :c:func:`task_abort_handler_set()` | Installs the task's abort handler. |
+-------------------------------------+-----------------------------------------+
The following APIs affecting a specified task
are provided by :file:`microkernel.h`.
+-------------------------------------------+----------------------------------+
| Call | Description |
+-------------------------------------------+----------------------------------+
+===========================================+==================================+
| :c:func:`task_priority_set()` | Sets a task's priority. |
+-------------------------------------------+----------------------------------+
| :c:func:`task_entry_set()` | Sets a task's entry point. |
@ -426,7 +418,7 @@ are provided by :file:`microkernel.h`.
+-------------------------------------------+---------------------------------+
| Call | Description |
+-------------------------------------------+---------------------------------+
+===========================================+=================================+
| :c:func:`sys_scheduler_time_slice_set()` | Sets the time slice period used |
| | in round-robin task scheduling. |
+-------------------------------------------+---------------------------------+
@ -441,4 +433,4 @@ are provided by :file:`microkernel.h`.
+-------------------------------------------+---------------------------------+
| :c:func:`task_group_abort()` | Aborts execution of all tasks |
| | in the specified task groups. |
+-------------------------------------------+---------------------------------+
+-------------------------------------------+---------------------------------+

4
doc/kernel/microkernel/microkernel_timers.rst Normal file
View file

@ -0,0 +1,4 @@
.. _microkernel_timers:
Timer Services
##############

30
doc/object/microkernel.rst
View file

@ -1,30 +0,0 @@
.. _microkernel_objects:
Microkernel Objects
###################
Section Scope
*************
This section provides an overview of the most important microkernel
objects, and their operation.
Each object contains a definition, a function description, and a table
of Application Program Interfaces (API) including the context that may
call them. Please refer to the API documentation for further details
regarding each object's functionality.
Objects Documentation
*********************
.. toctree::
:maxdepth: 3
microkernel_events
microkernel_fifos
microkernel_mailboxes
microkernel_memory_maps
microkernel_memory_pools
microkernel_mutexes
microkernel_pipes
microkernel_semaphores