michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Clean up instructions for defining microkernel objects

Browse source 
Revise instructions to take advantage of the "public object"
and "private object" terminology now covered in the kernel
overview documentation. Also incorporates some missing information
the users need to be aware of when defining certain object types.

Change-Id: Ic0b359baf4443714c80200fdaff9cf2d253e6b99
Signed-off-by: Allan Stephens <allan.stephens@windriver.com>
This commit is contained in:
Allan Stephens 2015-08-18 16:15:10 -04:00 • committed by Anas Nashif
commit d44e380496
11 changed files with 216 additions and 159 deletions
Download patch file Download diff file Expand all files Collapse all files

14
doc/kernel/microkernel/microkernel_events.rst
View file

@ -50,12 +50,14 @@ The following parameters must be defined:
specify NULL.
Add an entry for the event in the project .MDEF file using the
following syntax:
Public Event
------------
Define the event in the application's .MDEF file using the following syntax:
.. code-block:: console
EVENT %name %handler
EVENT name handler
For example, the file :file:`projName.mdef` defines two events
as follows:
@ -67,6 +69,12 @@ as follows:
EVENT KEYPRESS validate_keypress
EVENT BUTTONPRESS NULL
A public event can be referenced from any source file that includes
the file :file:`zephyr.h`.
.. note::
Private events are not supported by the Zephyr kernel.
Example: Signaling an Event from an ISR
========================================

38
doc/kernel/microkernel/microkernel_fifos.rst
View file

@ -42,8 +42,8 @@ addresses of the destination pointer.
Usage
*****
Defining a FIFO in MDEF File
============================
Defining a FIFO
===============
The following parameters must be defined:
@ -57,12 +57,14 @@ The following parameters must be defined:
*width*
This specifies the size (in bytes) of each data item.
Add an entry for a FIFO in the project .MDEF file using the
following syntax:
Public FIFO
-----------
Define the FIFO in the application's .MDEF file using the following syntax:
.. code-block:: console
FIFO %name %depth %width
FIFO name depth width
For example, the file :file:`projName.mdef` defines a FIFO
that holds up to 10 items that are each 12 bytes long as follows:
@ -73,33 +75,31 @@ that holds up to 10 items that are each 12 bytes long as follows:
% =============================
FIFO SIGNAL_FIFO 10 12
A public FIFO can be referenced from any source file that includes
the file :file:`zephyr.h`.
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)``
can be used for this purpose.
Private FIFO
------------
For example, the following code can be used to define a global FIFO
``PRIV_FIFO``.
Define the FIFO in a source file using the following syntax:
.. code-block:: c
DEFINE_FIFO(PRIV_FIFO, depth, width);
DEFINE_FIFO(fifo_name, depth, width)
The FIFO ``PRIV_FIFO`` can be used in the same style as those FIFOs
defined in MDEF file.
For example, the following code defines a private FIFO named ``PRIV_FIFO``.
It is possible to utilize this FIFO in another source file, simply
add:
.. code-block:: c
DEFINE_FIFO(PRIV_FIFO, 10, 12);
To utilize this FIFO from a different source file use the following syntax:
.. code-block:: c
extern const kfifo_t PRIV_FIFO;
to that file. The FIFO ``PRIV_FIFO`` can be then used there.
Example: Writing to a FIFO
==========================

35
doc/kernel/microkernel/microkernel_mailboxes.rst
View file

@ -32,20 +32,22 @@ receiver tasks before passing the data.
Usage
*****
Defining a mailbox in MDEF file
===============================
Defining a Mailbox
==================
The following parameters must be defined:
*name*
This specifies a unique name for the mailbox.
Add an entry for a mailbox in the project .MDEF file using the
following syntax:
Public Mailbox
--------------
Define the mailbox in the application's .MDEF file using the following syntax:
.. code-block:: console
MAILBOX %name
MAILBOX name
For example, the file :file:`projName.mdef` defines a mailbox as follows:
@ -55,16 +57,20 @@ For example, the file :file:`projName.mdef` defines a mailbox as follows:
% ==========================
MAILBOX REQUEST_BOX
A public mailbox can be referenced from any source file that includes
the file :file:`zephyr.h`.
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)``
can be used for this purpose.
Private Mailbox
---------------
For example, the following code can be used to define a global mailbox
``PRIV_MBX``.
Define the mailbox in a source file using the following syntax:
.. code-block:: c
DEFINE_MAILBOX(name);
For example, the following code defines a private mailbox named ``PRIV_MBX``.
.. code-block:: c
@ -73,15 +79,12 @@ For example, the following code can be used to define a global mailbox
The mailbox ``PRIV_MBX`` can be used in the same style as those
defined in MDEF file.
It is possible to utilize this mailbox in another source file, simply
add:
To utilize this mailbox from a different source file use the following syntax:
.. code-block:: c
extern const kmbox_t PRIV_MBX;
to that file. The mailbox ``PRIV_MBX`` can be then used there.
Example: Sending Variable-Sized Mailbox Messages
================================================

56
doc/kernel/microkernel/microkernel_memory_maps.rst
View file

@ -44,17 +44,32 @@ 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
=====================
Add an entry for one or more memory maps in the project file using the
following syntax:
The following parameters must be defined:
*name*
This specifies a unique name for the memory map.
*num_blocks*
This specifies the number of memory blocks in the memory map.
*block_size*
This specifies the size (in bytes) of each memory block.
Public Memory Map
-----------------
Define the memory map in the application's .MDEF file using the following
syntax:
.. code-block:: console
MAP %name %numBlocks %blockSize
MAP name num_blocks block_size
For example, the file :file:`projName.mdef` defines a single memory map
For example, the file :file:`projName.mdef` defines a pair of memory maps
as follows:
.. code-block:: console
@ -64,34 +79,33 @@ as follows:
MAP MYMAP 4 1024
MAP YOURMAP 6 200
A public memory map can be referenced from any source file that includes
the file :file:`zephyr.h`.
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(...)``
can be used for this purpose.
Private Memory Map
------------------
For example, the following code can be used to define a global memory
map ``PRIV_MEM_MAP``.
Define the memory map in a source file using the following syntax:
.. code-block:: c
DEFINE_MEMORY_MAP(PRIV_MEM_MAP, num_blocks, block_size);
DEFINE_MEMORY_MAP(name, num_blocks, block_size);
where the parameters are the same as memory maps defined in MDEF file.
The memory map ``PRIV_MEM_MAP`` can be used in the same style as those
defined in MDEF file.
For example, the following code defines a private memory map named
``PRIV_MEM_MAP``.
It is possible to utilize this memory map in another source file, simply
add:
.. code-block:: c
DEFINE_MEMORY_MAP(PRIV_MEM_MAP, 6, 200);
To utilize this memory map from a different source file use
the following syntax:
.. code-block:: c
extern const kmemory_map_t PRIV_MEM_MAP;
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
================================================================

21
doc/kernel/microkernel/microkernel_memory_pools.rst
View file

@ -77,26 +77,29 @@ The following parameters must be defined:
*name*
This specifies a unique name for the memory pool.
*minBlockSize*
*min_block_size*
This specifies the minimimum memory block size in bytes.
It should be a multiple of the processor's word size.
*maxBlockSize*
*max_block_size*
This specifies the maximum memory block size in bytes.
It should be a power of 4 times larger than *minBlockSize*;
therefore, maxBlockSize = minBlockSize * 4^n, where n>=0.
*numMax*
*num_max*
This specifies the number of maximum size memory blocks
available at startup.
Add an entry for memory pools in the project .MDEF file using the
following syntax:
Public Memory Pool
------------------
Define the memory pool in the application's .MDEF file using the following
syntax:
.. code-block:: console
POOL %name %minBlockSize %maxBlockSize %numMax
POOL name min_block_size max_block_size num_max
For example, the file :file:`projName.mdef` defines two memory pools
as follows:
@ -108,6 +111,12 @@ as follows:
POOL MY_POOL 32 8192 1
POOL SECOND_POOL_ID 64 1024 5
A public memory pool can be referenced from any source file that includes
the file :file:`zephyr.h`.
.. note::
Private memory pools are not supported by the Zephyr kernel.
Example: Requesting a Memory Block from a Pool with No Conditions
=================================================================

44
doc/kernel/microkernel/microkernel_mutexes.rst
View file

@ -67,15 +67,23 @@ such as a physical device.
Usage
*****
Defining a Mutex in MDEF file
=============================
Defining a Mutex
================
Add an entry for the mutex in the project file using the
following syntax:
The following parameters must be defined:
*name*
This specifies a unique name for the mutex.
Public Mutex
------------
Define the mutex in the application's .MDEF file using the following syntax:
.. code-block:: console
MUTEX %name
MUTEX name
For example, the file :file:`projName.mdef` defines a single mutex as follows:
@ -85,33 +93,31 @@ For example, the file :file:`projName.mdef` defines a single mutex as follows:
% ===============
MUTEX DEVICE_X
A public mutex can be referenced from any source file that includes
the file :file:`zephyr.h`.
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
for this purpose.
Private Mutex
-------------
For example, the following code can be used to define a global mutex
``XYZ``.
Define the mutex in a source file using the following syntax:
.. code-block:: c
DEFINE_MUTEX(name);
For example, the following code defines a private mutex named ``XYZ``.
.. code-block:: c
DEFINE_MUTEX(XYZ);
The mutex ``XYZ`` can be used in the same style as those mutexes defined
in MDEF file.
It is possible to utilize this mutex in another source file, simply add:
To utilize this mutex from a different source file use the following syntax:
.. code-block:: c
extern const kmutex_t XYZ;
to that file. The mutex ``XYZ`` can be then used there.
Example: Locking a Mutex with No Conditions
===========================================

43
doc/kernel/microkernel/microkernel_pipes.rst
View file

@ -40,8 +40,8 @@ and receiver identities.
Usage
*****
Defining a Pipes in MDEF file
=============================
Defining a Pipe
===============
The following parameters must be defined:
@ -52,14 +52,18 @@ The following parameters must be defined:
This specifies the size (in bytes) of the pipe's internal buffer.
If no internal buffer is to be used specify zero.
Add an entry for a pipe in the project .MDEF file using the
following syntax:
Public Pipe
-----------
Define the pipe in the application's .MDEF file using the following syntax:
.. code-block:: console
PIPE %name %buffer_size
PIPE name buffer_size
For example, the file :file:`projName.mdef` defines a pipe as follows:
For example, the file :file:`projName.mdef` defines a pipe with a 1 KB internal
buffer as follows:
.. code-block:: console
@ -67,34 +71,31 @@ For example, the file :file:`projName.mdef` defines a pipe as follows:
% ===============================
PIPE DATA_PIPE 1024
A public pipe can be referenced from any source file that includes
the file :file:`zephyr.h`.
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
used for this purpose.
Private Pipe
------------
For example, the following code can be used to define a global pipe
``PRIV_PIPE``.
Define the pipe in a source file using the following syntax:
.. code-block:: c
DEFINE_PIPE(PRIV_PIPE, size);
DEFINE_PIPE(name, size);
where the parameters are the same as pipes defined in MDEF file.
The pipe ``PRIV_PIPE`` can be used in the same style as those
defined in MDEF file.
For example, the following code defines a private pipe named ``PRIV_PIPE``.
It is possible to utilize this pipe in another source file, simply
add:
.. code-block:: c
DEFINE_PIPE(PRIV_PIPE, 1024);
To utilize this pipe from a different source file use the following syntax:
.. code-block:: c
extern const kpipe_t PRIV_PIPE;
to that file. The pipe ``PRIV_PIPE`` can be then used there.
Example: Writing Fixed-Size Data Items to a Pipe
================================================

41
doc/kernel/microkernel/microkernel_semaphores.rst
View file

@ -28,8 +28,8 @@ timeout, until signaled or return immediately with a failed status.
Usage
*****
Defining a Semaphore in MDEF file
=================================
Defining a Semaphore
====================
The following parameters must be defined:
@ -37,15 +37,16 @@ The following parameters must be defined:
This specifies a unique name for the semaphore.
Add an entry for a semaphore in the project .MDEF file using the
following syntax:
Public Semaphore
----------------
Define the semaphore in the application's .MDEF file using the following syntax:
.. code-block:: console
SEMA %name
SEMA name
For example, the file :file:`projName.mdef` defines two semaphores
as follows:
For example, the file :file:`projName.mdef` defines two semaphores as follows:
.. code-block:: console
@ -54,33 +55,31 @@ as follows:
SEMA INPUT_DATA
SEMA WORK_DONE
A public semaphore can be referenced from any source file that includes
the file :file:`zephyr.h`.
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)``
can be used for this purpose.
Private Semaphore
-----------------
For example, the following code can be used to define a global semaphore
``PRIV_SEM``.
Define the semaphore a source file using the following syntax:
.. code-block:: c
DEFINE_SEMAPHORE(name);
For example, the following code defines a private semaphore named ``PRIV_SEM``.
.. code-block:: c
DEFINE_SEMAPHORE(PRIV_SEM);
The semaphore ``PRIV_SEM`` can be used in the same style as those
semaphores defined in MDEF file.
It is possible to utilize this semaphore in another source file, simply
add:
To utilize this semaphore from a different source file use the following syntax:
.. code-block:: c
extern const ksem_t PRIV_SEM;
to that file. The semaphore ``PRIV_SEM`` can be then used there.
Example: Giving a Semaphore from a Task
=======================================

6
doc/kernel/microkernel/microkernel_task_irqs.rst
View file

@ -60,9 +60,9 @@ to specify the number of task IRQs allowed in the project.
The default value of zero for this option disables task IRQs.
.. note::
Task-level IRQs are microkernel objects, but are *not* configured in a
project MDEF file.
Unlike most other microkernel object types, task-level IRQs are defined
as a group using a configuration option, rather than as individual
public objects in an .MDEF file or private objects in a source file.
Example: Allocating a Task IRQ

72
doc/kernel/microkernel/microkernel_tasks.rst
View file

@ -191,11 +191,11 @@ 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.
Defining a Task
***************
Usage
*****
Inside MDEF files
=================
Defining a Task
===============
The following parameters must be defined:
@ -225,17 +225,20 @@ The following parameters must be defined:
This specifies the size of the task's stack, in bytes.
*groups*
This specifies the task groups the task belongs to. It consists
of a comma-separated list of task group names enclosed in square
brackets, with no embedded spaces. If a task does not belong
to any groups an empty list must be specified; i.e. :literal:`[]`.
This specifies the task groups the task belongs to.
Add an entry for a task in the project .MDEF file using the
following syntax:
Public Task
-----------
Define the task in the application's .MDEF file using the following syntax:
.. code-block:: console
TASK %name %priority %entry_point %stack_size %groups
TASK name priority entry_point stack_size groups
The task groups are specified using a comma-separated list of task group names
enclosed in square brackets, with no embedded spaces. If the task does not
belong to any task group specify an empty list; i.e. :literal:`[]`.
For example, the file :file:`projName.mdef` defines a system comprised
of six tasks as follows:
@ -251,51 +254,57 @@ of six tasks as follows:
TASK SPEAKER1_TASK 10 speaker_1_main 1024 [AUDIO_TASKS]
TASK SPEAKER2_TASK 10 speaker_2_main 1024 [AUDIO_TASKS]
A public task can be referenced from any source file that includes
the file :file:`zephyr.h`.
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
used for this purpose.
Private Task
------------
For example, the following code can be used to define a global task
``PRIV_TASK``.
Define the task in a source file using the following syntax:
.. code-block:: c
DEFINE_TASK(PRIV_TASK, priority, entry, stack_size, groups);
where the parameters are the same as tasks defined in MDEF file.
The task ``PRIV_TASK`` can be used in the same style as those
defined in MDEF file.
The task groups are specified using a list of task group names separated by
:literal:`|`; i.e. the logical OR operator. If the task does not belong to any
task group specify NULL.
It is possible to utilize this task in another source file, simply
add:
For example, the following code can be used to define a private task named
``PRIV_TASK``.
.. code-block:: c
DEFINE_TASK(PRIV_TASK, 10, priv_task_main, 800, EXE);
To utilize this task from a different source file use the following syntax:
.. code-block:: c
extern const ktask_t PRIV_TASK;
to that file. The task ``PRIV_TASK`` can be then used there.
Defining a Task Group
*************************
=====================
The following parameters must be defined:
*name*
This specifies a unique name for the task group.
Add an entry for a task in the project .MDEF file using the
following syntax:
Public Task Group
-----------------
Define the task group in the application's .MDEF file using the following
syntax:
.. code-block:: console
TASKGROUP %name
TASKGROUP name
For example, the file :file:`projName.mdef` defines three new
task groups as follows:
For example, the file :file:`projName.mdef` defines three new task groups
as follows:
.. code-block:: console
@ -305,6 +314,9 @@ task groups as follows:
TASKGROUP AUDIO_TASKS
TASKGROUP KEYPAD_TASKS
.. note::
Private task groups are not supported by the Zephyr kernel.
Example: Starting a Task from a Different Task
==============================================

5
doc/kernel/microkernel/microkernel_timers.rst
View file

@ -87,6 +87,11 @@ the sum of the following quantities:
* The number of microkernel timers.
* The number of tasks.
.. note::
Unlike most other microkernel object types, microkernel timers are defined
as a group using a configuration option, rather than as individual
public objects in an .MDEF file or private objects in a source file.
Example: Allocating a Microkernel Timer
=======================================