michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Change API tables to lists in the Kernel Primer.

Browse source 
The tables in the Kernel Primer are changed to lists. Making it easier
to update them. Other minor changes were done to ensure consitency.
The :c: and :cpp: markup has been fixed. When the documentation for a
call exists, then it is linked.

Change-Id: I8f389a0a0ca7c5fe904c0a1fa520e2e499f1001b
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero 2015-10-07 15:55:39 -05:00 • committed by Anas Nashif
commit c1c1ffe7f7
22 changed files with 570 additions and 734 deletions
Download patch file Download diff file Expand all files Collapse all files

92
doc/kernel/common/common_atomic.rst
View file

@ -12,7 +12,6 @@ in an uninterruptible manner. This guarantees that the desired operation
will not be interfered with due to the scheduling of a higher priority context,
even if the higher priority context manipulates the same variable.
Purpose
*******
@ -25,7 +24,6 @@ requires the manipulation of a single 32-bit data item.
a microkernel mutex, offloading the processing to a fiber, or
locking interrupts.
Usage
*****
@ -50,46 +48,58 @@ calls the routine.
...
}
APIs
****
The following atomic operation APIs are provided by :file:`atomic.h`.
The following atomic operation APIs are provided by :file:`atomic.h`:
+---------------------------------------+-------------------------------------+
| Call | Description |
+=======================================+=====================================+
| :c:func:`atomic_get()` | Reads an atomic variable. |
+---------------------------------------+-------------------------------------+
| :c:func:`atomic_set()` | Writes an atomic variable. |
+---------------------------------------+-------------------------------------+
| :c:func:`atomic_clear()` | Zeroes an atomic variable. |
+---------------------------------------+-------------------------------------+
| | :c:func:`atomic_add()` | Performs an arithmetic operation |
| | :c:func:`atomic_sub()` | on an atomic variable. |
| | :c:func:`atomic_inc()` | |
| | :c:func:`atomic_dec()` | |
+---------------------------------------+-------------------------------------+
| | :c:func:`atomic_and()` | Performs a logical operation |
| | :c:func:`atomic_or()` | on an atomic variable. |
| | :c:func:`atomic_xor()` | |
| | :c:func:`atomic_nand()` | |
+---------------------------------------+-------------------------------------+
| :c:func:`atomic_cas()` | Performs compare-and-set operation |
| | on an atomic variable. |
+---------------------------------------+-------------------------------------+
| :c:func:`atomic_set_bit()` | Sets specified bit of an atomic |
| | variable to 1. |
+---------------------------------------+-------------------------------------+
| :c:func:`atomic_clear_bit()` | Sets specified bit of an atomic |
| | variable to 0. |
+---------------------------------------+-------------------------------------+
| :c:func:`atomic_test_bit()` | Reads specified bit of an atomic |
| | variable. |
+---------------------------------------+-------------------------------------+
| :c:func:`atomic_test_and_set_bit()` | Reads specified bit of an atomic |
| | variable and sets it to 1. |
+---------------------------------------+-------------------------------------+
| :c:func:`atomic_test_and_clear_bit()` | Reads specified bit of an atomic |
| | variable and sets it to 0. |
+---------------------------------------+-------------------------------------+
:c:func:`atomic_get()`
Reads an atomic variable.
:c:func:`atomic_set()`
Writes an atomic variable.
:c:func:`atomic_clear()`
Clears an atomic variable.
:c:func:`atomic_add()`
Performs an addition operation on an atomic variable.
:c:func:`atomic_sub()`
Performs a subtraction operation on an atomic variable.
:c:func:`atomic_inc()`
Performs an increment operation on an atomic variable.
:c:func:`atomic_dec()`
Performs a decrement operation on an atomic variable.
:c:func:`atomic_and()`
Perform an "and" operation on an atomic variable.
:c:func:`atomic_or()`
Perform an "or" operation on an atomic variable.
:c:func:`atomic_xor()`
Perform a "xor" operation on an atomic variable.
:c:func:`atomic_nand()`
Perform a "nand" operation on an atomic variable.
:c:func:`atomic_cas()`
Performs compare-and-set operation on an atomic variable.
:c:func:`atomic_set_bit()`
Sets specified bit of an atomic variable to 1.
:c:func:`atomic_clear_bit()`
Sets specified bit of an atomic variable to 0.
:c:func:`atomic_test_bit()`
Reads specified bit of an atomic variable.
:c:func:`atomic_test_and_set_bit()`
Reads specified bit of an atomic variable and sets it to 1.
:c:func:`atomic_test_and_clear_bit()`
Reads specified bit of an atomic variable and sets it to 0.

37
doc/kernel/common/common_contexts.rst
View file

@ -71,37 +71,30 @@ have a custom data value.
if (sys_execution_context_type_get() != NANO_CTX_ISR) {
call_count = (uint32_t)sys_thread_custom_data_get();
if (call_count == CALL_LIMIT)
return -1;
call_count++;
sys_thread_custom_data_set((void *)call_count);
return -1;
call_count++;
sys_thread_custom_data_set((void *)call_count);
}
/* do rest of routine's processing */
...
}
APIs
****
The following kernel execution context APIs are provided by
:file:`microkernel.h` and by :file:`nanokernel.h`:
+--------------------------------------------+---------------------------------------+
| Call | Description |
+============================================+=======================================+
| :c:func:`sys_thread_self_get()` | Gets thread identifier of currently |
| | executing task or fiber. |
+--------------------------------------------+---------------------------------------+
| :c:func:`sys_execution_context_type_get()` | Gets type of currently executing |
| | context (i.e. task, fiber, or ISR). |
+--------------------------------------------+---------------------------------------+
| :c:func:`sys_thread_custom_data_set()` | Writes custom data for currently |
| | executing task or fiber. |
+--------------------------------------------+---------------------------------------+
| :c:func:`sys_thread_custom_data_get()` | Reads custom data for currently |
| | executing task or fiber. |
+--------------------------------------------+---------------------------------------+
| :c:func:`sys_thread_busy_wait()` | Performs a busy wait for the |
| | specified time period. |
+--------------------------------------------+---------------------------------------+
:c:func:`sys_thread_self_get()`
Gets thread identifier of currently executing task or fiber.
:c:func:`sys_execution_context_type_get()`
Gets type of currently executing context (i.e. task, fiber, or ISR).
:c:func:`sys_thread_custom_data_set()`
Writes custom data for currently executing task or fiber.
:c:func:`sys_thread_custom_data_get()`
Reads custom data for currently executing task or fiber.

78
doc/kernel/common/common_kernel_clocks.rst
View file

@ -29,7 +29,6 @@ to convert the time units used by the clocks into standard time units
(e.g. seconds, milliseconds, nanoseconds, etc), and to convert between
the two types of clock time units.
Purpose
*******
@ -45,7 +44,6 @@ time measurements.
means that counter rollover must be taken into account when taking
high-precision measurements over an extended period of time.
Usage
*****
@ -61,7 +59,6 @@ to zero disables all system clock and hardware clock capabilities.
to provide finer-grained timing, but also increases the amount of work
the kernel has to do to process ticks (since they occur more frequently).
Example: Measuring Time with Normal Precision
=============================================
This code uses the system clock to determine how many ticks have elapsed
@ -81,7 +78,6 @@ between two points in time.
/* compute how long the work took & update time stamp */
ticks_spent = task_tick_delta(&time_stamp);
Example: Measuring Time with High Precision
===========================================
This code uses the hardware clock to determine how many ticks have elapsed
@ -108,60 +104,46 @@ between two points in time.
nanoseconds_spent = SYS_CLOCK_HW_CYCLES_TO_NS(cycles_spent);
APIs
****
The following kernel clock APIs are provided by :file:`microkernel.h`:
+-----------------------------------+----------------------------------------+
| Call | Description |
+===================================+========================================+
| | :c:func:`task_tick_get()` | Reads system clock. |
| | :c:func:`task_tick_get_32()` | |
| | :c:func:`fiber_tick_get()` | |
| | :c:func:`fiber_tick_get_32()` | |
| | :c:func:`isr_tick_get()` | |
| | :c:func:`isr_tick_get_32()` | |
+-----------------------------------+----------------------------------------+
| | :c:func:`task_tick_delta()` | Computes elapsed time since an |
| | :c:func:`task_tick_delta_32()` | earlier system clock reading. |
+-----------------------------------+----------------------------------------+
| | :c:func:`task_cycle_get_32()` | Reads hardware clock. |
| | :c:func:`fiber_cycle_get_32()` | |
| | :c:func:`isr_cycle_get_32()` | |
+-----------------------------------+----------------------------------------+
:cpp:func:`task_tick_get()`, :cpp:func:`task_tick_get_32()`,
:c:func:`fiber_tick_get()`, :c:func:`fiber_tick_get_32()`,
:c:func:`isr_tick_get()`, :c:func:`isr_tick_get_32()`
Read the system clock.
:cpp:func:`task_tick_delta()`, :cpp:func:`task_tick_delta_32()`
Compute the elapsed time since an earlier system clock reading.
:cpp:func:`task_cycle_get_32()`, :c:func:`fiber_cycle_get_32()`,
:c:func:`isr_cycle_get_32()`
Read the hardware clock.
The following kernel clock APIs are provided by :file:`microkernel.h`
and by :file:`nanokernel.h`:
+-----------------------------------+----------------------------------------+
| Call | Description |
+===================================+========================================+
| | :c:func:`nano_tick_get()` | Reads system clock. |
| | :c:func:`nano_tick_get_32()` | |
+-----------------------------------+----------------------------------------+
| | :c:func:`nano_tick_delta()` | Computes elapsed time since an |
| | :c:func:`nano_tick_delta_32()` | earlier system clock reading. |
+-----------------------------------+----------------------------------------+
| :c:func:`nano_cycle_get_32()` | Reads hardware clock. |
+-----------------------------------+----------------------------------------+
:cpp:func:`nano_tick_get()`, :cpp:func:`nano_tick_get_32()`
Read the system clock.
:cpp:func:`nano_tick_delta()`, :cpp:func:`nano_tick_delta_32()`
Compute the elapsed time since an earlier system clock reading.
:cpp:func:`nano_cycle_get_32()`
Reads hardware clock.
The following kernel clock variables are provided by :file:`microkernel.h`
and by :file:`nanokernel.h`:
+-----------------------------------+----------------------------------------+
| Variable | Description |
+===================================+========================================+
| sys_clock_ticks_per_sec | The number of system clock ticks |
| | in a single second. |
+-----------------------------------+----------------------------------------+
| sys_clock_hw_cycles_per_sec | The number of hardware clock cycles |
| | in a single second. |
+-----------------------------------+----------------------------------------+
| sys_clock_us_per_tick | The number of microseconds in a single |
| | system clock tick. |
+-----------------------------------+----------------------------------------+
| sys_clock_hw_cycles_per_tick | The number of hardware clock cycles |
| | in a single system clock tick. |
+-----------------------------------+----------------------------------------+
:c:data:`sys_clock_ticks_per_sec`
The number of system clock ticks in a single second.
:c:data:`sys_clock_hw_cycles_per_sec`
The number of hardware clock cycles in a single second.
:c:data:`sys_clock_us_per_tick`
The number of microseconds in a single system clock tick.
:c:data:`sys_clock_hw_cycles_per_tick`
The number of hardware clock cycles in a single system clock tick.

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

@ -48,7 +48,6 @@ allowing the same function to be shared by multiple events. An event's event
handler function is specified at compile-time, but can be changed subsequently
at run-time.
Purpose
*******
@ -58,7 +57,6 @@ detected by another task, a fiber, or an ISR.
Use an event handler to allow the microkernel server fiber to handle an event,
prior to (or instead of) letting a task handle the event.
Usage
*****
@ -83,7 +81,7 @@ The following parameters must be defined:
...
}
If no event handler is required specify :c:macro:`NULL`.
If no event handler is required specify :cpp:macro:`NULL`.
Public Event
------------
@ -110,7 +108,6 @@ the file :file:`zephyr.h`.
.. note::
Private events are not supported by the Zephyr kernel.
Example: Signaling an Event from an ISR
========================================
@ -173,7 +170,6 @@ so that the receiving task only wakes up when needed.
}
}
void keypress_task(void)
{
/* register the filtering routine */
@ -190,29 +186,28 @@ so that the receiving task only wakes up when needed.
}
}
APIs
****
The following Event APIs are provided by microkernel.h.
The following Event APIs are provided by :file:`microkernel.h`:
+------------------------------------------+----------------------------------+
| Call | Description |
+==========================================+==================================+
| :c:func:`isr_event_send()` | Signal an event from an ISR |
+------------------------------------------+----------------------------------+
| :c:func:`fiber_event_send()` | Signal an event from a fiber. |
+------------------------------------------+----------------------------------+
| :c:func:`task_event_send()` | Signal an event from a task. |
+------------------------------------------+----------------------------------+
| :c:func:`task_event_recv()` | Tests for an event signal |
| | without waiting. |
+------------------------------------------+----------------------------------+
| :c:func:`task_event_recv_wait()` | Waits for an event signal. |
+------------------------------------------+----------------------------------+
| :c:func:`task_event_recv_wait_timeout()` | Waits for an event signal |
| | for a specified time period. |
+------------------------------------------+----------------------------------+
| :c:func:`task_event_handler_set()` | Registers an event handler |
| | function for an event. |
+------------------------------------------+----------------------------------+
:cpp:func:`isr_event_send()`
Signal an event from an ISR.
:cpp:func:`fiber_event_send()`
Signal an event from a fiber.
:cpp:func:`task_event_send()`
Signal an event from a task.
:c:func:`task_event_recv()`
Tests for an event signal without waiting.
:c:func:`task_event_recv_wait()`
Waits for an event signal.
:c:func:`task_event_recv_wait_timeout()`
Waits for an event signal for a specified time period.
:cpp:func:`task_event_handler_set()`
Registers an event handler function for an event.

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

@ -38,7 +38,6 @@ Any number of tasks may wait on an empty FIFO simultaneously; when a data item
becomes available it is given to the highest priority task that has waited
the longest.
Purpose
*******
@ -61,7 +60,6 @@ anonymous manner.
The microkernel's mailbox object type *does* support non-anonymous data
transfer.
Usage
*****
@ -101,7 +99,6 @@ that holds up to 10 items that are each 12 bytes long as follows:
A public FIFO can be referenced by name from any source file that includes
the file :file:`zephyr.h`.
Private FIFO
------------
@ -123,7 +120,6 @@ To utilize this FIFO from a different source file use the following syntax:
extern const kfifo_t PRIV_FIFO;
Example: Writing to a FIFO
==========================
@ -172,39 +168,34 @@ one or more producing tasks.
}
}
APIs
****
The following APIs for a microkernel FIFO are provided by microkernel.h.
The following APIs for a microkernel FIFO are provided by
:file:`microkernel.h`:
+----------------------------------------+-----------------------------------+
| Call | Description |
+========================================+===================================+
| :c:func:`task_fifo_put()` | Write item to a FIFO, or fail and |
| | continue if it is full. |
+----------------------------------------+-----------------------------------+
| :c:func:`task_fifo_put_wait()` | Write item to a FIFO, or wait |
| | for room to write if it is full. |
+----------------------------------------+-----------------------------------+
| :c:func:`task_fifo_put_wait_timeout()` | Write item to a FIFO, or wait for |
| | a specified time period if it |
| | is full. |
+----------------------------------------+-----------------------------------+
| :c:func:`task_fifo_get()` | Read item from a FIFO, or fail |
| | and continue if it is empty. |
+----------------------------------------+-----------------------------------+
| :c:func:`task_fifo_get_wait()` | Read item from a FIFO, or wait |
| | for an item if it is empty. |
+----------------------------------------+-----------------------------------+
| :c:func:`task_fifo_get_wait_timeout()` | Read item from a FIFO, or wait |
| | for an item for a specified time |
| | period if it is empty. |
+----------------------------------------+-----------------------------------+
| :c:func:`task_fifo_purge()` | Discard all items in a FIFO and |
| | unblock any tasks waiting to read |
| | or write an item. |
+----------------------------------------+-----------------------------------+
| :c:func:`task_fifo_size_get()` | Read the number of items |
| | currently in a FIFO. |
+----------------------------------------+-----------------------------------+
:c:func:`task_fifo_put()`
Writes item to a FIFO, or fail and continue if it is full.
:c:func:`task_fifo_put_wait()`
Writes item to a FIFO, or wait for room to write if it is full.
:c:func:`task_fifo_put_wait_timeout()`
Writes item to a FIFO, or wait for a specified time period if it is full.
:c:func:`task_fifo_get()`
Reads item from a FIFO, or fail and continue if it is empty.
:c:func:`task_fifo_get_wait()`
Reads item from a FIFO, or wait for an item if it is empty.
:c:func:`task_fifo_get_wait_timeout()`
Reads item from a FIFO, or wait for an
item for a specified time period if it is empty.
:c:func:`task_fifo_purge()`
Discards all items in a FIFO and unblock any tasks
waiting to read or write an item.
:c:func:`task_fifo_size_get()`
Reads the number of items currently in a FIFO.

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

@ -60,7 +60,6 @@ For example, the file :file:`projName.mdef` defines a mailbox as follows:
A public mailbox can be referenced by name from any source file that
includes the file :file:`zephyr.h`.
Private Mailbox
---------------
@ -85,7 +84,6 @@ To utilize this mailbox from a different source file use the following syntax:
extern const kmbox_t PRIV_MBX;
Example: Sending Variable-Sized Mailbox Messages
================================================
@ -334,59 +332,49 @@ a large message.
containing the message data using RXPOOL. However, the performance benefit
of using the asynchronous approach is lost.
APIs
****
The following APIs for synchronous mailbox operations are provided
by microkernel.h.
by :file:`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. |
+-----------------------------------------+------------------------------------+
: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.
+---------------------------------------------------+-----------------------------------+
| Call | Description |
+===================================================+===================================+
| :c:func:`task_mbox_block_put()` | Puts message in a mailbox, even |
| | if a receiver isn't waiting. |
+---------------------------------------------------+-----------------------------------+
| :c:func:`task_mbox_data_block_get()` | Finishes receiving message that |
| | was received without its data, or |
| | fails if no block is available. |
+---------------------------------------------------+-----------------------------------+
| :c:func:`task_mbox_data_block_get_wait()` | Finishes receiving message that |
| | was received without its data, or |
| | waits until a block is available. |
+---------------------------------------------------+-----------------------------------+
| :c:func:`task_mbox_data_block_get_wait_timeout()` | Finishes receiving message that |
| | was received without its data, or |
| | waits for a specified time period |
| | for a block to become available. |
+---------------------------------------------------+-----------------------------------+
:c:func:`task_mbox_block_put()`
Puts message in a mailbox, even if a receiver isn't waiting.
:c:func:`task_mbox_data_block_get()`
Finishes receiving message that was received without its data, or fails if
no block is available.
:c:func:`task_mbox_data_block_get_wait()`
Finishes receiving message that was received without its data, or waits
until a block is available.
:c:func:`task_mbox_data_block_get_wait_timeout()`
Finishes receiving message that was received without its data, or waits
for a specified time period for a block to become available.

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

@ -34,13 +34,11 @@ Unlike a heap, more than one memory map can be defined, if needed. This
allows for a memory map with smaller blocks and others with larger-sized
blocks. Alternatively, a memory pool object may be used.
Purpose
*******
Use a memory map to allocate and free memory in fixed-size blocks.
Usage
*****
@ -58,7 +56,6 @@ The following parameters must be defined:
*block_size*
This specifies the size in bytes of each memory block.
Public Memory Map
-----------------
@ -82,7 +79,6 @@ as follows:
A public memory map can be referenced by name from any source file that
includes the file :file:`zephyr.h`.
Private Memory Map
------------------
@ -106,7 +102,6 @@ the following syntax:
extern const kmemory_map_t PRIV_MEM_MAP;
Example: Requesting a Memory Block from a Map with No Conditions
================================================================
@ -120,7 +115,6 @@ available if all the memory blocks are in use.
task_mem_map_alloc_wait(MYMAP, &block_ptr);
Example: Requesting a Memory Block from a Map with a Conditional Time-out
=========================================================================
@ -139,7 +133,6 @@ in the specified time.
}
Example: Requesting a Memory Block from a Map with a No Blocking Condition
==========================================================================
@ -155,7 +148,6 @@ This code gives an immediate warning when all memory blocks are in use.
display_warning(); /* and do not allocate memory block*/
}
Example: Freeing a Memory Block back to a Map
=============================================
@ -170,28 +162,23 @@ This code releases a memory block back when it is no longer needed.
task_mem_map_free(&block_ptr);
APIs
****
The following Memory Map APIs are provided by :file:`microkernel.h`.
The following Memory Map APIs are provided by :file:`microkernel.h`:
+---------------------------------------------+-----------------------------------+
| Call | Description |
+=============================================+===================================+
| :c:func:`task_mem_map_alloc()` | Requests a block from a memory |
| | map. |
+---------------------------------------------+-----------------------------------+
| :c:func:`task_mem_map_alloc_wait()` | Waits on a block of memory until |
| | it is available. |
+---------------------------------------------+-----------------------------------+
| :c:func:`task_mem_map_alloc_wait_timeout()` | Waits on a block of memory |
| | for the period of time |
| | defined by the time-out |
| | parameter. |
+---------------------------------------------+-----------------------------------+
| :c:func:`task_mem_map_free()` | Returns a block to a memory map. |
+---------------------------------------------+-----------------------------------+
| :c:func:`task_mem_map_used_get()` | Returns the number of used blocks |
| | in a memory map. |
+---------------------------------------------+-----------------------------------+
:c:func:`task_mem_map_alloc()`
Requests a block from a memory map.
:c:func:`task_mem_map_alloc_wait()`
Waits on a block of memory until it is available.
:c:func:`task_mem_map_alloc_wait_timeout()`
Waits on a block of memory for the period of time defined by the time-out
parameter.
:c:func:`task_mem_map_free()`
Returns a block to a memory map.
:cpp:func:`task_mem_map_used_get()`
Returns the number of used blocks in a memory map.

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

@ -58,7 +58,6 @@ needed. For example, different applications can utilize
different memory pools so that one application does not
allocate all of the available blocks.
Purpose
*******
Use memory pools to allocate memory in variable-size blocks.
@ -66,7 +65,6 @@ Use memory pools to allocate memory in variable-size blocks.
Use memory pool blocks when sending data to a mailbox
asynchronously.
Usage
*****
@ -91,7 +89,6 @@ The following parameters must be defined:
This specifies the number of maximum size memory blocks
available at startup.
Public Memory Pool
------------------
@ -118,7 +115,6 @@ 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
=================================================================
@ -133,7 +129,6 @@ available, then fills it with zeroes.
memset(block.pointer_to_data, 0, 80);
Example: Requesting a Memory Block from a Pool with a Conditional Time-out
==========================================================================
@ -151,7 +146,6 @@ in that time.
printf('Memory allocation timeout');
}
Example: Requesting a Memory Block from a Pool with a No Blocking Condition
===========================================================================
@ -168,7 +162,6 @@ a memory block of 80 bytes.
printf('Memory allocation timeout');
}
Example: Freeing a Memory Block Back to a Pool
==============================================
@ -182,7 +175,6 @@ This code releases a memory block back to a pool when it is no longer needed.
/* use memory block */
task_mem_pool_free(&block);
Example: Manually Defragmenting a Memory Pool
=============================================
@ -199,23 +191,20 @@ each time a memory block allocation occurs.
APIs
****
The following Memory Pools APIs are provided by microkernel.h.
The following Memory Pools APIs are provided by :file:`microkernel.h`:
+----------------------------------------------+------------------------------+
| Call | Description |
+==============================================+==============================+
| :c:func:`task_mem_pool_alloc()` | Allocates a block from |
| | a memory pool. |
+----------------------------------------------+------------------------------+
| :c:func:`task_mem_pool_alloc_wait()` | Waits for a block of memory |
| | until it is available. |
+----------------------------------------------+------------------------------+
| :c:func:`task_mem_pool_alloc_wait_timeout()` | Waits for a block of memory |
| | for the time period defined |
| | by the time-out parameter. |
+----------------------------------------------+------------------------------+
| :c:func:`task_mem_pool_free()` | Returns a block of memory |
| | to a memory pool. |
+----------------------------------------------+------------------------------+
| :c:func:`task_mem_pool_defragment()` | Defragments a memory pool. |
+----------------------------------------------+------------------------------+
:c:func:`task_mem_pool_alloc()`
Allocates a block from a memory pool.
:c:func:`task_mem_pool_alloc_wait()`
Waits for a block of memory until it is available.
:c:func:`task_mem_pool_alloc_wait_timeout()`
Waits for a block of memory for the time period defined by the time-out
parameter.
:c:func:`task_mem_pool_free()`
Returns a block of memory to a memory pool.
:c:func:`task_mem_pool_defragment()`
Defragments a memory pool.

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

@ -73,7 +73,6 @@ Purpose
Use mutexes to provide exclusive access to a resource,
such as a physical device.
Usage
*****
@ -85,7 +84,6 @@ The following parameters must be defined:
*name*
This specifies a unique name for the mutex.
Public Mutex
------------
@ -106,7 +104,6 @@ For example, the file :file:`projName.mdef` defines a single mutex as follows:
A public mutex can be referenced by name from any source file that includes
the file :file:`zephyr.h`.
Private Mutex
-------------
@ -128,7 +125,6 @@ To utilize this mutex from a different source file use the following syntax:
extern const kmutex_t XYZ;
Example: Locking a Mutex with No Conditions
===========================================
@ -142,7 +138,6 @@ mutex is in use.
lineto(200,100);
task_mutex_unlock(XYZ);
Example: Locking a Mutex with a Conditional Timeout
===================================================
@ -164,7 +159,6 @@ in the specified amount of time.
}
Example: Locking a Mutex with a No Blocking Condition
=====================================================
@ -182,33 +176,24 @@ This code gives an immediate warning when a mutex is in use.
display_warning(); /* and do not unlock mutex*/
}
APIs
****
The following Mutex APIs are provided by :file:`microkernel.h`.
The following Mutex APIs are provided by :file:`microkernel.h`:
+------------------------------------------+-----------------------------------+
| Call | Description |
+==========================================+===================================+
| :c:func:`task_mutex_lock()` | Locks a mutex, and increments |
| | the lock count. |
+------------------------------------------+-----------------------------------+
| :c:func:`task_mutex_lock_wait()` | Waits on a locked mutex until it |
| | is unlocked, then locks the mutex |
| | and increments the lock count. |
+------------------------------------------+-----------------------------------+
| :c:func:`task_mutex_lock_wait_timeout()` | Waits on a locked mutex for |
| | the period of time defined by |
| | the timeout parameter. If the |
| | mutex becomes available during |
| | that period, the function |
| | locks the mutex, and |
| | increments the lock count. |
| | If the timeout expires, it |
| | returns RC_TIME. |
+------------------------------------------+-----------------------------------+
| :c:func:`task_mutex_unlock()` | Decrements a mutex lock count, |
| | and unlocks the mutex when the |
| | count reaches zero. |
+------------------------------------------+-----------------------------------+
:c:func:`task_mutex_lock()`
Locks a mutex, and increments the lock count.
:c:func:`task_mutex_lock_wait()`
Waits on a locked mutex until it is unlocked, then locks the mutex and
increments the lock count.
:c:func:`task_mutex_lock_wait_timeout()`
Waits on a locked mutex for the period of time defined by the timeout
parameter. If the mutex becomes available during that period, the function
locks the mutex, and increments the lock count. If the timeout expires, it
returns RC_TIME.
:c:func:`task_mutex_unlock()`
Decrements a mutex lock count, and unlocks the mutex when the count
reaches zero.

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

@ -151,14 +151,12 @@ using the :option:`_ALL_N` pipe option helps to ensure that each data chunk is
transferred in a single operation. The same is true when multiple receiving
tasks are reading from the same pipe.
Purpose
*******
Use a pipe to transfer data when the receiving task needs the ability
to split or merge the data items generated by the sending task.
Usage
*****
@ -174,7 +172,6 @@ The following parameters must be defined:
This specifies the size in bytes of the pipe's ring buffer.
If no ring buffer is to be used specify zero.
Public Pipe
-----------
@ -196,7 +193,6 @@ buffer as follows:
A public pipe can be referenced by name from any source file that includes
the file :file:`zephyr.h`.
Private Pipe
------------
@ -218,7 +214,6 @@ To utilize this pipe from a different source file use the following syntax:
extern const kpipe_t PRIV_PIPE;
Example: Writing Fixed-Size Data Items to a Pipe
================================================
@ -304,35 +299,30 @@ unprocessed data bytes in the pipe.
}
}
APIs
****
The following Pipe APIs are provided by :file:`microkernel.h`.
The following Pipe APIs are provided by :file:`microkernel.h`:
+----------------------------------------+------------------------------------+
| Call | Description |
+========================================+====================================+
| :c:func:`task_pipe_put()` | Writes data to a pipe, or fails & |
| | continues if unable to write data. |
+----------------------------------------+------------------------------------+
| :c:func:`task_pipe_put_wait()` | Writes data to a pipe, or waits |
| | if unable to write data. |
+----------------------------------------+------------------------------------+
| :c:func:`task_pipe_put_wait_timeout()` | Writes data to a pipe, or waits |
| | for a specified time period if |
| | unable to write data. |
+----------------------------------------+------------------------------------+
| :c:func:`task_pipe_block_put()` | Writes data to a pipe from a |
| | memory pool block. |
+----------------------------------------+------------------------------------+
| :c:func:`task_pipe_get()` | Reads data from a pipe, or fails |
| | and continues if data isn't there. |
+----------------------------------------+------------------------------------+
| :c:func:`task_pipe_get_wait()` | Reads data from a pipe, or waits |
| | for data if data isn't there. |
+----------------------------------------+------------------------------------+
| :c:func:`task_pipe_get_wait_timeout()` | Reads data from a pipe, or waits |
| | for data for a specified time |
| | period if data isn't there. |
+----------------------------------------+------------------------------------+
:c:func:`task_pipe_put()`
Writes data to a pipe, or fails & continues if unable to write data.
:c:func:`task_pipe_put_wait()`
Writes data to a pipe, or waits if unable to write data.
:c:func:`task_pipe_put_wait_timeout()`
Writes data to a pipe, or waits for
a specified time period if unable to write data.
:c:func:`task_pipe_block_put()`
Writes data to a pipe from a memory pool block.
:c:func:`task_pipe_get()`
Reads data from a pipe, or fails and continues if data isn't there.
:c:func:`task_pipe_get_wait()`
Reads data from a pipe, or waits for data if data isn't there.
:c:func:`task_pipe_get_wait_timeout()`
Reads data from a pipe, or waits for
data for a specified time period if data isn't there.

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

@ -60,7 +60,6 @@ There is no limit on the number of semaphore groups used by a task, or
on the number of semaphores belonging to any given semaphore group. Semaphore
groups may also be shared by multiple tasks, if desired.
Purpose
*******
@ -72,7 +71,6 @@ or ISR and one or more consuming tasks.
Use a semaphore group to allow a task to signal or to monitor multiple
semaphores simultaneously.
Usage
*****
@ -84,7 +82,6 @@ The following parameters must be defined:
*name*
This specifies a unique name for the semaphore.
Public Semaphore
----------------
@ -106,7 +103,6 @@ For example, the file :file:`projName.mdef` defines two semaphores as follows:
A public semaphore can be referenced by name from any source file that
includes the file :file:`zephyr.h`.
Private Semaphore
-----------------
@ -128,7 +124,6 @@ To utilize this semaphore from a different source file use the following syntax:
extern const ksem_t PRIV_SEM;
Example: Giving a Semaphore from a Task
=======================================
@ -243,51 +238,49 @@ the semaphores used by four other tasks in a single operation.
...
}
APIs
****
The following APIs for an individual semaphore are provided by microkernel.h.
The following APIs for an individual semaphore are provided by
:file:`microkernel.h`:
+----------------------------------------+------------------------------------+
| Call | Description |
+========================================+====================================+
| :cpp:func:`isr_sem_give()` | Signal a semaphore from an ISR. |
+----------------------------------------+------------------------------------+
| :cpp:func:`fiber_sem_give()` | Signal a semaphore from a fiber. |
+----------------------------------------+------------------------------------+
| :cpp:func:`task_sem_give()` | Signal a semaphore from a task. |
+----------------------------------------+------------------------------------+
| :c:func:`task_sem_take()` | Test a semaphore without waiting. |
+----------------------------------------+------------------------------------+
| :c:func:`task_sem_take_wait()` | Wait on a semaphore. |
+----------------------------------------+------------------------------------+
| :c:func:`task_sem_take_wait_timeout()` | Wait on a semaphore for a |
| | specified time period. |
+----------------------------------------+------------------------------------+
| :cpp:func:`task_sem_reset()` | Sets the semaphore count to zero. |
+----------------------------------------+------------------------------------+
| :cpp:func:`task_sem_count_get()` | Read signal count for a semaphore. |
+----------------------------------------+------------------------------------+
:cpp:func:`isr_sem_give()`
Signals a semaphore from an ISR.
:cpp:func:`fiber_sem_give()`
Signals a semaphore from a fiber.
:cpp:func:`task_sem_give()`
Signals a semaphore from a task.
:c:func:`task_sem_take()`
Tests a semaphore without waiting.
:c:func:`task_sem_take_wait()`
Waits on a semaphore.
:c:func:`task_sem_take_wait_timeout()`
Waits on a semaphore for a specified time period.
:cpp:func:`task_sem_reset()`
Sets the semaphore count to zero.
:cpp:func:`task_sem_count_get()`
Reads signal count for a semaphore.
The following APIs for semaphore groups are provided by microkernel.h.
+----------------------------------------------+------------------------------+
| Call | Description |
+==============================================+==============================+
| :cpp:func:`task_sem_group_give()` | Signal a set of semaphores. |
+----------------------------------------------+------------------------------+
| :cpp:func:`task_sem_group_take()` | Test a set of semaphores |
| | without waiting. |
+----------------------------------------------+------------------------------+
| :c:func:`task_sem_group_take_wait()` | Wait on a set of semaphores. |
+----------------------------------------------+------------------------------+
| :c:func:`task_sem_group_take_wait_timeout()` | Wait on a set of semaphores |
| | for a specified time period. |
+----------------------------------------------+------------------------------+
| :cpp:func:`task_sem_group_reset()` | Sets the semaphore count to |
| | to zero for a set of |
| | semaphores. |
+----------------------------------------------+------------------------------+
:cpp:func:`task_sem_group_give()`
Signals a set of semaphores.
:c:func:`task_sem_group_take()`
Tests a set of semaphores without waiting.
:c:func:`task_sem_group_take_wait()`
Waits on a set of semaphores.
:c:func:`task_sem_group_take_wait_timeout()`
Waits on a set of semaphores for a specified time period.
:cpp:func:`task_sem_group_reset()`
Sets the semaphore count to to zero for a set of semaphores.

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

@ -40,7 +40,6 @@ When a task no longer needs a task IRQ it should free the task IRQ.
This disables the interrupt associated with the task IRQ
and makes the task IRQ available for re-allocation.
Purpose
*******
@ -64,7 +63,6 @@ The default value of zero for this option disables task IRQs.
as a group using a configuration option, rather than as individual
public objects in an MDEF or private objects in a source file.
Example: Allocating a Task IRQ
==============================
@ -83,7 +81,6 @@ so they can be processed using the task IRQ.
printf("Task IRQ allocation failed!");
}
Example: Servicing Interrupts using a Task IRQ
==============================================
@ -102,7 +99,6 @@ acknowledge the interrupt, and take the necessary steps to service it.
/* Device interrupt is now unmasked */
/* Do post-acknowledgement device processing (if any) */
The steps required to service a device are device-specific.
In some cases all processing may need to be completed
before the interrupt is acknowledged,
@ -110,7 +106,6 @@ while in other cases no processing at all should be done
until the interrupt is acknowledged.
Some devices may require processing both before and after acknowledgement.
Example: Freeing a Task IRQ
===========================
@ -123,30 +118,25 @@ Interrupts from that device are no longer enabled.
task_irq_free(FOO_DEVICE);
APIs
****
The following task IRQ APIs are provided by :file:`microkernel.h`:
+----------------------------------------+-----------------------------------+
| Call | Description |
+========================================+===================================+
| :cpp:func:`task_irq_alloc()` | Binds a task IRQ to a device |
| | and enables interrupts. |
+----------------------------------------+-----------------------------------+
| :cpp:func:`task_irq_ack()` | Acknowledges an interrupt and |
| | re-enables the interrupt. |
+----------------------------------------+-----------------------------------+
| :cpp:func:`task_irq_free()` | Unbinds a task IRQ from a device |
| | and disables interrupts. |
+----------------------------------------+-----------------------------------+
| :c:func:`task_irq_test()` | Tests to determine if an |
| | interrupt has occurred. |
+----------------------------------------+-----------------------------------+
| :c:func:`task_irq_test_wait()` | Waits for an interrupt to occur. |
+----------------------------------------+-----------------------------------+
| :c:func:`task_irq_test_wait_timeout()` | Waits for an interrupt to occur |
| | within a specified time period. |
+----------------------------------------+-----------------------------------+
:cpp:func:`task_irq_alloc()`
Binds a task IRQ to a device and enables interrupts.
:cpp:func:`task_irq_ack()`
Acknowledges an interrupt and re-enables the interrupt.
:cpp:func:`task_irq_free()`
Unbinds a task IRQ from a device and disables interrupts.
:c:func:`task_irq_test()`
Tests to determine if an interrupt has occurred.
:c:func:`task_irq_test_wait()`
Waits for an interrupt to occur.
:c:func:`task_irq_test_wait_timeout()`
Waits for an interrupt to occur within a specified time period.

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

@ -66,7 +66,6 @@ co-ordindate with another task to invoke such APIs indirectly.
The kernel does not currently make any claims regarding an application's
ability to restart a terminated task.
Task Scheduling
===============
@ -224,7 +223,6 @@ task groups can be defined by the application.
context information during context switches. (Tasks in this group are
implicitly members of the :c:macro:`FPU` task group too.)
Usage
*****
@ -290,7 +288,6 @@ of six tasks as follows:
A public task can be referenced by name from any source file that includes
the file :file:`zephyr.h`.
Private Task
------------
@ -317,7 +314,6 @@ To utilize this task from a different source file use the following syntax:
extern const ktask_t PRIV_TASK;
Defining a Task Group
=====================
@ -353,7 +349,6 @@ includes the file :file:`zephyr.h`.
.. note::
Private task groups are not supported by the Zephyr kernel.
Example: Starting a Task from Another Task
==========================================
@ -373,7 +368,6 @@ This code shows how the currently executing task can start another task.
...
}
Example: Suspending and Resuming a Set of Tasks
===============================================
@ -392,13 +386,15 @@ the execution of all tasks belonging to the designated task groups.
/* suspend non-essential tasks when overheating is detected */
if (now_overheated && !was_overheated) {
task_group_suspend(VIDEO_TASKS | AUDIO_TASKS);
task_group_suspend(VIDEO_TASKS
AUDIO_TASKS);
was_overheated = 1;
}
/* resume non-essential tasks when overheating abates */
if (!now_overheated && was_overheated) {
task_group_resume(VIDEO_TASKS | AUDIO_TASKS);
task_group_resume(VIDEO_TASKS
AUDIO_TASKS);
was_overheated = 0;
}
@ -460,78 +456,79 @@ APIs
****
The following APIs affecting the currently executing task
are provided by :file:`microkernel.h`.
are provided by :file:`microkernel.h`:
+-------------------------------------+-----------------------------------------+
| Call | Description |
+=====================================+=========================================+
| :cpp:func:`task_id_get()` | Gets the task's ID. |
+-------------------------------------+-----------------------------------------+
| :c:func:`isr_task_id_get()` | Gets the task's ID from an ISR. |
+-------------------------------------+-----------------------------------------+
| :cpp:func:`task_priority_get()` | Gets the task's priority. |
+-------------------------------------+-----------------------------------------+
| :c:func:`isr_task_priority_get()` | Gets the task's priority from an ISR. |
+-------------------------------------+-----------------------------------------+
| :cpp: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. |
+-------------------------------------+-----------------------------------------+
| :cpp:func:`task_abort_handler_set()`| Installs the task's abort handler. |
+-------------------------------------+-----------------------------------------+
| :cpp:func:`task_yield()` | Yields CPU to equal-priority tasks. |
+-------------------------------------+-----------------------------------------+
| :cpp:func:`task_sleep()` | Yields CPU for a specified time period. |
+-------------------------------------+-----------------------------------------+
| :c:func:`task_offload_to_fiber()` | Instructs the microkernel server fiber |
| | to execute a function. |
+-------------------------------------+-----------------------------------------+
:cpp:func:`task_id_get()`
Gets the task's ID.
:c:func:`isr_task_id_get()`
Gets the task's ID from an ISR.
:cpp:func:`task_priority_get()`
Gets the task's priority.
:c:func:`isr_task_priority_get()`
Gets the task's priority from an ISR.
:cpp: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.
:cpp:func:`task_abort_handler_set()`
Installs the task's abort handler.
:cpp:func:`task_yield()`
Yields CPU to equal-priority tasks.
:cpp:func:`task_sleep()`
Yields CPU for a specified time period.
:cpp:func:`task_offload_to_fiber()`
Instructs the microkernel server fiber to execute a function.
The following APIs affecting a specified task
are provided by :file:`microkernel.h`.
are provided by :file:`microkernel.h`:
+-------------------------------------------+----------------------------------+
| Call | Description |
+===========================================+==================================+
| :cpp:func:`task_priority_set()` | Sets a task's priority. |
+-------------------------------------------+----------------------------------+
| :c:func:`task_entry_set()` | Sets a task's entry point. |
+-------------------------------------------+----------------------------------+
| :c:func:`task_start()` | Starts execution of a task. |
+-------------------------------------------+----------------------------------+
| :c:func:`task_suspend()` | Suspends execution of a task. |
+-------------------------------------------+----------------------------------+
| :c:func:`task_resume()` | Resumes execution of a task. |
+-------------------------------------------+----------------------------------+
| :c:func:`task_abort()` | Aborts execution of a task. |
+-------------------------------------------+----------------------------------+
| :cpp:func:`task_group_join()` | Adds a task to the specified |
| | task group(s). |
+-------------------------------------------+----------------------------------+
| :cpp:func:`task_group_leave()` | Removes a task from the |
| | specified task group(s). |
+-------------------------------------------+----------------------------------+
:cpp:func:`task_priority_set()`
Sets a task's priority.
:cpp:func:`task_entry_set()`
Sets a task's entry point.
:c:func:`task_start()`
Starts execution of a task.
:c:func:`task_suspend()`
Suspends execution of a task.
:c:func:`task_resume()`
Resumes execution of a task.
:c:func:`task_abort()`
Aborts execution of a task.
:cpp:func:`task_group_join()`
Adds a task to the specified task group(s).
:cpp:func:`task_group_leave()`
Removes a task from the specified task group(s).
The following APIs affecting multiple tasks
are provided by :file:`microkernel.h`.
are provided by :file:`microkernel.h`:
+-------------------------------------------+---------------------------------+
| Call | Description |
+===========================================+=================================+
| :cpp:func:`sys_scheduler_time_slice_set()`| Sets the time slice period used |
| | in round-robin task scheduling. |
+-------------------------------------------+---------------------------------+
| :c:func:`task_group_start()` | Starts execution of all tasks |
| | in the specified task groups. |
+-------------------------------------------+---------------------------------+
| :c:func:`task_group_suspend()` | Suspends execution of all tasks |
| | in the specified task groups. |
+-------------------------------------------+---------------------------------+
| :c:func:`task_group_resume()` | Resumes execution of all tasks |
| | in the specified task groups. |
+-------------------------------------------+---------------------------------+
| :c:func:`task_group_abort()` | Aborts execution of all tasks |
| | in the specified task groups. |
+-------------------------------------------+---------------------------------+
:cpp:func:`sys_scheduler_time_slice_set()`
Sets the time slice period used in round-robin task scheduling.
:c:func:`task_group_start()`
Starts execution of all tasks in the specified task groups.
:c:func:`task_group_suspend()`
Suspends execution of all tasks in the specified task groups.
:c:func:`task_group_resume()`
Resumes execution of all tasks in the specified task groups.
:c:func:`task_group_abort()`
Aborts execution of all tasks in the specified task groups.

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

@ -55,7 +55,6 @@ then starting it afresh.
When a task no longer needs a timer it should free the timer.
This makes the timer available for reallocation.
Purpose
*******
@ -65,14 +64,13 @@ other work.
.. note::
If a task has no other work to perform while waiting for time to pass
it can simply call :c:func:`task_sleep()`.
it can simply call :cpp:func:`task_sleep()`.
.. note::
The microkernel provides additional APIs that allow a task to monitor
the system clock, as well as the higher precision hardware clock,
without using a microkernel timer.
Usage
*****
@ -92,7 +90,6 @@ the sum of the following quantities:
as a group using a configuration option, rather than as individual
public objects in an MDEF or private objects in a source file.
Example: Allocating a Microkernel Timer
=======================================
@ -104,7 +101,6 @@ This code allocates an unused timer.
timer_id = task_timer_alloc();
Example: Starting a One Shot Microkernel Timer
==============================================
This code uses a timer to limit the amount of time a task
@ -130,7 +126,6 @@ a period of zero, it stops automatically once it expires.
/* process the new data */
...
Example: Starting a Periodic Microkernel Timer
==============================================
This code is similar to the previous example, except that the timer
@ -158,7 +153,6 @@ reactivate the timer.
...
}
Example: Cancelling a Microkernel Timer
=======================================
This code illustrates how an active timer can be stopped prematurely.
@ -184,7 +178,6 @@ This code illustrates how an active timer can be stopped prematurely.
printf("Warning: Input took too long to arrive!");
}
Example: Freeing a Microkernel Timer
====================================
This code allows a task to relinquish a previously allocated timer
@ -195,23 +188,22 @@ so it can be used by other tasks.
task_timer_free(timer_id);
APIs
****
The following microkernel timer APIs are provided by :file:`microkernel.h`:
+----------------------------------------+-----------------------------------+
| Call | Description |
+========================================+===================================+
| :cpp:func:`task_timer_alloc()` | Allocates an unused timer. |
+----------------------------------------+-----------------------------------+
| :cpp:func:`task_timer_start()` | Starts a timer. |
+----------------------------------------+-----------------------------------+
| :cpp:func:`task_timer_restart()` | Restarts a timer. |
+----------------------------------------+-----------------------------------+
| :cpp:func:`task_timer_stop()` | Cancels a timer. |
+----------------------------------------+-----------------------------------+
| :cpp:func:`task_timer_free()` | Marks timer as unused. |
+----------------------------------------+-----------------------------------+
:cpp:func:`task_timer_alloc()`
Allocates an unused timer.
:cpp:func:`task_timer_start()`
Starts a timer.
:cpp:func:`task_timer_restart()`
Restarts a timer.
:cpp:func:`task_timer_stop()`
Cancels a timer.
:cpp:func:`task_timer_free()`
Marks timer as unused.

60
doc/kernel/nanokernel/nanokernel_fibers.rst
View file

@ -53,7 +53,7 @@ be reused.
A fiber may also terminate non-gracefully by *aborting*. The kernel
automatically aborts a fiber when it generates a fatal error condition,
such as dereferencing a null pointer. A fiber can also explicitly abort itself
using :c:func:`fiber_abort()`. As with graceful fiber termination, the kernel
using :cpp:func:`fiber_abort()`. As with graceful fiber termination, the kernel
does not attempt to reclaim system resources owned by the fiber.
.. note::
@ -124,7 +124,7 @@ by the nanokernel until one of the following occurs:
* The fiber terminates itself by returning from its entry point function.
* The fiber aborts itself by performing an operation that causes a fatal error,
or by calling :c:func:`fiber_abort()`.
or by calling :cpp:func:`fiber_abort()`.
Once the current task becomes the current context it remains scheduled for
execution by the nanokernel until is supplanted by a fiber.
@ -145,14 +145,14 @@ to time to permit other fibers to execute.
A fiber can relinquish the CPU in two ways:
* Calling :c:func:`fiber_yield()` places the fiber back in the nanokernel
* Calling :cpp:func:`fiber_yield()` places the fiber back in the nanokernel
scheduler's list of executable fibers and then invokes the scheduler.
All executable fibers whose priority is higher or equal to that of the
yielding fiber are then allowed to execute before the yielding fiber is
rescheduled. If no such executable fibers exist, the scheduler immediately
reschedules the yielding fiber without context switching.
* Calling :c:func:`fiber_sleep()` blocks the execution of the fiber for
* Calling :cpp:func:`fiber_sleep()` blocks the execution of the fiber for
a specified time period. Executable fibers of all priorities are then
allowed to execute, although there is no guarantee that fibers whose
priority is lower than that of the sleeping task will actually be scheduled
@ -172,16 +172,15 @@ options is spawned using an options value of 0.
The fiber options listed below are pre-defined by the kernel.
:c:macro:`USE_FP`
:c:macro:`USE_FP`
Instructs the kernel to save the fiber's x87 FPU and MMX floating point
context information during context switches.
:c:macro:`USE_SSE`
:c:macro:`USE_SSE`
Instructs the kernel to save the fiber's SSE floating point context
information during context switches. (A fiber using this option
implicitly uses the :c:macro:`USE_FP` option too.)
Usage
*****
@ -227,7 +226,6 @@ The following properties must be defined when spawning a fiber:
*options*
This specifies the fiber's options.
Example: Spawning a Fiber from a Task
=====================================
@ -280,32 +278,28 @@ APIs
The following APIs affecting the currently executing fiber are provided
by :file:`microkernel.h` and by :file:`nanokernel.h`:
+-----------------------------------+-----------------------------------------+
| Call | Description |
+-----------------------------------+-----------------------------------------+
| :cpp:func:`fiber_yield()` | Yields CPU to higher priority and |
| | equal priority fibers. |
+-----------------------------------+-----------------------------------------+
| :cpp:func:`fiber_sleep()` | Yields CPU for a specified time period. |
+-----------------------------------+-----------------------------------------+
| :cpp:func:`fiber_abort()` | Terminates fiber execution. |
+-----------------------------------+-----------------------------------------+
:cpp:func:`fiber_yield()`
Yields CPU to higher priority and equal priority fibers.
:cpp:func:`fiber_sleep()`
Yields CPU for a specified time period.
:cpp:func:`fiber_abort()`
Terminates fiber execution.
The following APIs affecting a specified fiber are provided
by :file:`microkernel.h` and by :file:`nanokernel.h`:
+------------------------------------------------+----------------------------+
| Call | Description |
+------------------------------------------------+----------------------------+
| | :c:func:`task_fiber_start()` | Spawns a new fiber. |
| | :c:func:`fiber_fiber_start()` | |
| | :c:func:`fiber_start()` | |
+------------------------------------------------+----------------------------+
| | :c:func:`task_fiber_delayed_start()` | Spawns a new fiber after |
| | :c:func:`fiber_fiber_delayed_start()` | a specified time period |
| | :c:func:`fiber_delayed_start()` | |
+------------------------------------------------+----------------------------+
| | :c:func:`task_fiber_delayed_start_cancel()` | Cancels spawning of a |
| | :c:func:`fiber_fiber_delayed_start_cancel()` | new fiber, if not already |
| | :c:func:`fiber_delayed_start_cancel()` | started. |
+------------------------------------------------+----------------------------+
:c:func:`task_fiber_start()`, :cpp:func:`fiber_fiber_start()`,
:cpp:func:`fiber_start()`
Spawn a new fiber.
:c:func:`task_fiber_delayed_start()`,
:cpp:func:`fiber_fiber_delayed_start()`,
:cpp:func:`fiber_delayed_start()`
Spawn a new fiber after a specified time period.
:c:func:`task_fiber_delayed_start_cancel()`,
:cpp:func:`fiber_fiber_delayed_start_cancel()`,
:cpp:func:`fiber_delayed_start_cancel()`
Cancel spawning of a new fiber, if not already started.

65
doc/kernel/nanokernel/nanokernel_fifos.rst
View file

@ -18,19 +18,19 @@ the first 32 bits of each item for use as a pointer to the next data item
in the FIFO's linked list. Consequently, a data item that holds N bytes
of application data requires N+4 bytes of memory.
Any number of nanokernel FIFOs can be defined. Each FIFO is a distinct variable
of type :c:type:`struct nano_fifo`, and is referenced using a pointer to that
variable. A FIFO must be initialized before it can be used to send or receive
data items.
Any number of nanokernel FIFOs can be defined. Each FIFO is a distinct
variable of type :cpp:type:`struct nano_fifo`, and is referenced using a
pointer to that variable. A FIFO must be initialized before it can be used to
send or receive data items.
Items can be added to a nanokernel FIFO in a non-blocking manner by any
context type (i.e. ISR, fiber, or task).
Items can be removed from a nanokernel FIFO in a non-blocking manner by any
context type; if the FIFO is empty the :c:macro:`NULL` return code indicates
that no item was removed. Items can also be removed from a nanokernel FIFO
in a blocking manner by a fiber or task; if the FIFO is empty the thread
waits for an item to be added.
context type; if the FIFO is empty the :c:macro:`NULL` return code
indicates that no item was removed. Items can also be removed from a
nanokernel FIFO in a blocking manner by a fiber or task; if the FIFO is empty
the thread waits for an item to be added.
Any number of threads may wait on an empty nanokernel FIFO simultaneously.
When a data item becomes available it is given to the fiber that has waited
@ -49,14 +49,12 @@ longest, or to a waiting task if no fiber is waiting.
priority tasks. However, the order in which equal priority tasks are given
data items is unpredictible.
Purpose
*******
Use a nanokernel FIFO to asynchronously transfer data items of arbitrary size
in a "first in, first out" manner.
Usage
*****
@ -71,7 +69,6 @@ This code establishes an empty nanokernel FIFO.
nano_fifo_init(&signal_fifo);
Example: Writing to a Nanokernel FIFO from a Fiber
==================================================
@ -102,7 +99,6 @@ This code uses a nanokernel FIFO to send data to one or more consumer fibers.
}
}
Example: Reading from a Nanokernel FIFO
=======================================
@ -130,28 +126,25 @@ of data items to multiple consumer fibers, if desired.
APIs
****
The following APIs for a nanokernel FIFO are provided by :file:`nanokernel.h.`
The following APIs for a nanokernel FIFO are provided by :file:`nanokernel.h`:
+------------------------------------------------+------------------------------------+
| Call | Description |
+================================================+====================================+
| :c:func:`nano_fifo_init()` | Initializes a FIFO. |
+------------------------------------------------+------------------------------------+
| | :c:func:`nano_task_fifo_put()` | Adds item to a FIFO. |
| | :c:func:`nano_fiber_fifo_put()` | |
| | :c:func:`nano_isr_fifo_put()` | |
| | :c:func:`nano_fifo_put()` | |
+------------------------------------------------+------------------------------------+
| | :c:func:`nano_task_fifo_get()` | Removes item from a FIFO, or fails |
| | :c:func:`nano_fiber_fifo_get()` | and continues if it is empty. |
| | :c:func:`nano_isr_fifo_get()` | |
| | :c:func:`nano_fifo_get()` | |
+------------------------------------------------+------------------------------------+
| | :c:func:`nano_task_fifo_get_wait()` | Removes item from a FIFO, or waits |
| | :c:func:`nano_fiber_fifo_get_wait()` | for an item if it is empty. |
| | :c:func:`nano_fifo_get_wait()` | |
+------------------------------------------------+------------------------------------+
| | :c:func:`nano_task_fifo_get_wait_timeout()` | Removes item from a FIFO, or waits |
| | :c:func:`nano_fiber_fifo_get_wait_timeout()` | for an item for a specified time |
| | :c:func:`nano_fifo_get_wait_timeout()` | period if it is empty. |
+------------------------------------------------+------------------------------------+
:cpp:func:`nano_fifo_init()`
Initializes a FIFO.
:cpp:func:`nano_task_fifo_put()`, :cpp:func:`nano_fiber_fifo_put()`,
:cpp:func:`nano_isr_fifo_put()`, :cpp:func:`nano_fifo_put()`
Add an item to a FIFO.
:cpp:func:`nano_task_fifo_get()`, :cpp:func:`nano_fiber_fifo_get()`,
:cpp:func:`nano_isr_fifo_get()`, :cpp:func:`nano_fifo_get()`
Remove an item from a FIFO, or fails and continues if it is empty.
:cpp:func:`nano_task_fifo_get_wait()`, :cpp:func:`nano_fiber_fifo_get_wait()`,
:cpp:func:`nano_fifo_get_wait()`
Remove an item from a FIFO, or waits for an item if it is empty.
:cpp:func:`nano_task_fifo_get_wait_timeout()`,
:cpp:func:`nano_fiber_fifo_get_wait_timeout()`,
:cpp:func:`nano_fifo_get_wait_timeout()`
Remove an item from a FIFO, or waits for an item for a specified time
period if it is empty.

51
doc/kernel/nanokernel/nanokernel_interrupts.rst
View file

@ -71,7 +71,6 @@ Use one of the following procedures to install an ISR:
* `Installing a Static ISR`_
* `Installing a Dynamic ISR`_
Installing a Static ISR
=======================
@ -119,7 +118,6 @@ For x86 platforms only, you must also create an interrupt stub as follows:
ioapic_mkstub my_dev my_isr
Installing a Dynamic ISR
========================
@ -140,7 +138,6 @@ Prerequisites
* (x86 only) Set the :option:`NUM_DYNAMIC_STUBS` configuration option
to specify the maximum number of dynamic ISRs allowed in the project.
Example
-------
@ -166,7 +163,6 @@ This is an example of a dynamic interrupt for x86:
...
}
Working with Interrupts
***********************
@ -175,7 +171,6 @@ Use the following:
* `Offloading ISR Work`_
* `IDT Security`_
Offloading ISR Work
===================
@ -231,7 +226,6 @@ Additional intermediate context switches may be required
to execute any currently executing fiber or any higher-priority tasks
that are scheduled to run.
IDT Security
============
@ -245,38 +239,33 @@ therefore *not* protected. This is true even for systems using
reside in read-only memory (such as flash memory or ROM).
APIs
****
This table lists interrupt-related Application Program Interfaces.
These are the interrupt-related Application Program Interfaces.
+-------------------------+-------------------------------------------------+
| Call | Description |
+=========================+=================================================+
| :c:func:`irq_connect()` | Registers a dynamic ISR with the IDT and |
| | interrupt controller. |
+-------------------------+-------------------------------------------------+
| :c:func:`irq_enable()` | Enables interrupts from a specific IRQ. |
+-------------------------+-------------------------------------------------+
| :c:func:`irq_disable()` | Disables interrupts from a specific IRQ. |
+-------------------------+-------------------------------------------------+
| :c:func:`irq_lock()` | Locks out interrupts from all sources. |
+-------------------------+-------------------------------------------------+
| :c:func:`irq_unlock()` | Removes lock on interrupts from all sources. |
+-------------------------+-------------------------------------------------+
:c:func:`irq_connect()`
Registers a dynamic ISR with the IDT and interrupt controller.
:c:func:`irq_enable()`
Enables interrupts from a specific IRQ.
:c:func:`irq_disable()`
Disables interrupts from a specific IRQ.
:c:func:`irq_lock()`
Locks out interrupts from all sources.
:c:func:`irq_unlock()`
Removes lock on interrupts from all sources.
Macros
******
This table lists the macros used to install a static ISR.
These are the macros used to install a static ISR.
+----------------------------------+-----------------------------------------+
| Call | Description |
+==================================+=========================================+
| :c:macro:`IRQ_CONNECT_STATIC( )` | Registers a static ISR with the IDT. |
+----------------------------------+-----------------------------------------+
| :c:macro:`IRQ_CONFIG( )` | Registers a static ISR with the |
| | interrupt controller. |
+----------------------------------+-----------------------------------------+
:c:macro:`IRQ_CONNECT_STATIC( )`
Registers a static ISR with the IDT.
:c:macro:`IRQ_CONFIG( )`
Registers a static ISR with the interrupt controller.

60
doc/kernel/nanokernel/nanokernel_lifos.rst
View file

@ -18,19 +18,19 @@ the first 32 bits of each item for use as a pointer to the next data item
in the LIFO's linked list. Consequently, a data item that holds N bytes
of application data requires N+4 bytes of memory.
Any number of nanokernel LIFOs can be defined. Each LIFO is a distinct variable
of type :c:type:`struct nano_lifo`, and is referenced using a pointer to that
variable. A LIFO must be initialized before it can be used to send or receive
data items.
Any number of nanokernel LIFOs can be defined. Each LIFO is a distinct
variable of type :cpp:type:`struct nano_lifo`, and is referenced using a
pointer to that variable. A LIFO must be initialized before it can be used to
send or receive data items.
Items can be added to a nanokernel LIFO in a non-blocking manner by any
context type (i.e. ISR, fiber, or task).
Items can be removed from a nanokernel LIFO in a non-blocking manner by any
context type; if the LIFO is empty the :c:macro:`NULL` return code indicates
that no item was removed. Items can also be removed from a nanokernel LIFO
in a blocking manner by a fiber or task; if the LIFO is empty the thread
waits for an item to be added.
context type; if the LIFO is empty the :c:macro:`NULL` return code
indicates that no item was removed. Items can also be removed from a
nanokernel LIFO in a blocking manner by a fiber or task; if the LIFO is empty
the thread waits for an item to be added.
Any number of threads may wait on an empty nanokernel LIFO simultaneously.
When a data item becomes available it is given to the fiber that has waited
@ -47,8 +47,7 @@ longest, or to a waiting task if no fiber is waiting.
If multiple tasks in a microkernel application wait on the same nanokernel
LIFO, higher priority tasks are given data items in preference to lower
priority tasks. However, the order in which equal priority tasks are given
data items is unpredictible.
data items is unpredictable.
Purpose
*******
@ -56,7 +55,6 @@ Purpose
Use a nanokernel LIFO to asynchronously transfer data items of arbitrary size
in a "last in, first out" manner.
Usage
*****
@ -126,25 +124,23 @@ which are then processed in some manner.
APIs
****
The following APIs for a nanokernel LIFO are provided by :file:`nanokernel.h.`
The following APIs for a nanokernel LIFO are provided by :file:`nanokernel.h`:
+------------------------------------------------+------------------------------------+
| Call | Description |
+================================================+====================================+
| :c:func:`nano_lifo_init()` | Initializes a LIFO. |
+------------------------------------------------+------------------------------------+
| | :c:func:`nano_task_lifo_put()` | Adds item to a LIFO. |
| | :c:func:`nano_fiber_lifo_put()` | |
| | :c:func:`nano_isr_lifo_put()` | |
+------------------------------------------------+------------------------------------+
| | :c:func:`nano_task_lifo_get()` | Removes item from a LIFO, or fails |
| | :c:func:`nano_fiber_lifo_get()` | and continues if it is empty. |
| | :c:func:`nano_isr_lifo_get()` | |
+------------------------------------------------+------------------------------------+
| | :c:func:`nano_task_lifo_get_wait()` | Removes item from a LIFO, or waits |
| | :c:func:`nano_fiber_lifo_get_wait()` | for an item if it is empty. |
+------------------------------------------------+------------------------------------+
| | :c:func:`nano_task_lifo_get_wait_timeout()` | Removes item from a LIFO, or waits |
| | :c:func:`nano_fiber_lifo_get_wait_timeout()` | for an item for a specified time |
| | | period if it is empty. |
+------------------------------------------------+------------------------------------+
:cpp:func:`nano_lifo_init()`
Initializes a LIFO.
:cpp:func:`nano_task_lifo_put()`, :cpp:func:`nano_fiber_lifo_put()`,
:cpp:func:`nano_isr_lifo_put()`
Add an item to a LIFO.
:cpp:func:`nano_task_lifo_get()`, :cpp:func:`nano_fiber_lifo_get()`,
:cpp:func:`nano_isr_lifo_get()`
Remove an item from a LIFO, or fails and continues if it is empty.
:cpp:func:`nano_task_lifo_get_wait()`, :cpp:func:`nano_fiber_lifo_get_wait()`
Remove an item from a LIFO, or waits for an item if it is empty.
:cpp:func:`nano_task_lifo_get_wait_timeout()`,
:cpp:func:`nano_fiber_lifo_get_wait_timeout()`
Remove an item from a LIFO, or waits for an item for a specified time
period if it is empty.

36
doc/kernel/nanokernel/nanokernel_ring_buffers.rst
View file

@ -57,7 +57,6 @@ these will always be slower due to use of modulo operations:
#define MY_RING_BUF_SIZE 93
SYS_RING_BUF_DECLARE_SIZE(my_ring_buf, MY_RING_BUF_SIZE);
Alternatively, a ring buffer may be initialized manually. Whether the buffer
will use modulo or mask operations will be detected automatically:
@ -120,24 +119,23 @@ Example: Retrieving data
APIs
****
The following APIs for ring buffers are provided by :file:`ring_buffer.h`.
The following APIs for ring buffers are provided by :file:`ring_buffer.h`:
+------------------------------------------------+------------------------------------+
| Call | Description |
+================================================+====================================+
| :c:func:`sys_ring_buf_init()` | Initialize a ring buffer. |
+------------------------------------------------+------------------------------------+
| :c:func:`SYS_RING_BUF_DECLARE_POW2()` | Declare and init a file-scope |
| :c:func:`SYS_RING_BUF_DECLARE_SIZE()` | ring buffer. |
+------------------------------------------------+------------------------------------+
| :c:func:`sys_ring_buf_get_space()` | Return the amount of free buffer |
| | storage space in 32-bit dwords |
+------------------------------------------------+------------------------------------+
| :c:func:`sys_ring_buf_is_empty()` | Indicate whether a buffer is empty |
+------------------------------------------------+------------------------------------+
| :c:func:`sys_ring_buf_put()` | Enqueue an item |
+------------------------------------------------+------------------------------------+
| :c:func:`sys_ring_buf_get()` | De-queue an item |
+------------------------------------------------+------------------------------------+
:c:func:`sys_ring_buf_init()`
Initializes a ring buffer.
:c:func:`SYS_RING_BUF_DECLARE_POW2()`,
:c:func:`SYS_RING_BUF_DECLARE_SIZE()`
Declare and init a file-scope ring buffer.
:c:func:`sys_ring_buf_get_space()`
Returns the amount of free buffer storage space in 32-bit dwords.
:c:func:`sys_ring_buf_is_empty()`
Indicates whether a buffer is empty.
:c:func:`sys_ring_buf_put()`
Enqueues an item.
:c:func:`sys_ring_buf_get()`
De-queues an item.

41
doc/kernel/nanokernel/nanokernel_stacks.rst
View file

@ -14,7 +14,7 @@ Each stack uses an array of 32-bit words to hold its data values. The array
may be of any size, but must be aligned on a 4-byte boundary.
Any number of nanokernel stacks can be defined. Each stack is a distinct
variable of type :c:type:`struct nano_stack`, and is referenced using a pointer
variable of type :cpp:type:`struct nano_stack`, and is referenced using a pointer
to that variable. A stack must be initialized to use its array before it
can be used to send or receive data values.
@ -51,8 +51,7 @@ waiting fiber, or to a waiting task if no fiber is waiting.
If multiple tasks in a microkernel application wait on the same nanokernel
stack, higher priority tasks are given data values in preference to lower
priority tasks. However, the order in which equal priority tasks are given
data values is unpredictible.
data values is unpredictable.
Purpose
*******
@ -60,7 +59,6 @@ Purpose
Use a nanokernel stack to store and retrieve 32-bit data values in a "last in,
first out" manner, when the maximum number of stored items is known.
Usage
*****
@ -82,7 +80,6 @@ up to 10 items.
nano_stack_init(&alarm_stack, stack_area);
Example: Writing to a Nanokernel Stack
======================================
@ -101,7 +98,6 @@ indication to a processing fiber.
...
}
Example: Reading from a Nanokernel Stack
========================================
@ -125,26 +121,23 @@ in which alarms are processed isn't significant.
}
}
APIs
****
The following APIs for a nanokernel stack are provided by :file:`nanokernel.h.`
The following APIs for a nanokernel stack are provided by
:file:`nanokernel.h`:
+-----------------------------------------+-----------------------------------+
| Call | Description |
+=========================================+===================================+
| :c:func:`nano_stack_init()` | Initializes a stack. |
+-----------------------------------------+-----------------------------------+
| | :c:func:`nano_task_stack_push()` | Adds item to a stack. |
| | :c:func:`nano_fiber_stack_push()` | |
| | :c:func:`nano_isr_stack_push()` | |
+-----------------------------------------+-----------------------------------+
| | :c:func:`nano_task_stack_pop()` | Removes item from a stack, |
| | :c:func:`nano_fiber_stack_pop()` | or fails and continues |
| | :c:func:`nano_isr_stack_pop()` | if it is empty. |
+-----------------------------------------+-----------------------------------+
| | :c:func:`nano_task_stack_pop_wait()` | Removes item from a stack, or |
| | :c:func:`nano_fiber_stack_pop_wait()` | waits for an item if it is empty. |
+-----------------------------------------+-----------------------------------+
:cpp:func:`nano_stack_init()`
Initializes a stack.
:cpp:func:`nano_task_stack_push()`, :cpp:func:`nano_fiber_stack_push()`,
:cpp:func:`nano_isr_stack_push()`
Add an item to a stack.
:cpp:func:`nano_task_stack_pop()`, :cpp:func:`nano_fiber_stack_pop()`,
:cpp:func:`nano_isr_stack_pop()`
Remove an item from a stack, or fails and continues if it is empty.
:cpp:func:`nano_task_stack_pop_wait()`,
:cpp:func:`nano_fiber_stack_pop_wait()`
Remove an item from a stack, or waits for an item if it is empty.

49
doc/kernel/nanokernel/nanokernel_synchronization.rst
View file

@ -18,7 +18,7 @@ The nanokernel's semaphore object type is an implementation of a traditional
counting semaphore. It is mainly intended for use by fibers.
Any number of nanokernel semaphores can be defined. Each semaphore is a
distinct variable of type :c:type:`struct nano_sem`, and is referenced
distinct variable of type :cpp:type:`struct nano_sem`, and is referenced
using a pointer to that variable. A semaphore must be initialized before
it can be used.
@ -50,8 +50,7 @@ that has waited longest, or to a waiting task if no fiber is waiting.
If multiple tasks in a microkernel application wait on the same nanokernel
semaphore, higher priority tasks are given the semaphore in preference to
lower priority tasks. However, the order in which equal priority tasks
are given the semaphore is unpredictible.
are given the semaphore is unpredictable.
Purpose
=======
@ -62,7 +61,6 @@ fibers.
Use a nanokernel semaphore to synchronize processing between a producing task,
fiber, or ISR and one or more consuming fibers.
Usage
=====
@ -114,31 +112,28 @@ and gives warning if it is not obtained in that time.
...
}
APIs
====
The following APIs for a nanokernel semaphore are provided
by :file:`nanokernel.h.`
by :file:`nanokernel.h`:
+------------------------------------------------+----------------------------+
| Call | Description |
+================================================+============================+
| :c:func:`nano_sem_init()` | Initializes a semaphore. |
+------------------------------------------------+----------------------------+
| | :c:func:`nano_task_sem_give()` | Signals a sempahore. |
| | :c:func:`nano_fiber_sem_give()` | |
| | :c:func:`nano_isr_sem_give()` | |
| | :c:func:`nano_sem_give()` | |
+------------------------------------------------+----------------------------+
| | :c:func:`nano_task_sem_take()` | Tests a semaphore. |
| | :c:func:`nano_fiber_sem_take()` | |
| | :c:func:`nano_isr_sem_take()` | |
+------------------------------------------------+----------------------------+
| | :c:func:`nano_task_sem_take_wait()` | Waits on a semaphore. |
| | :c:func:`nano_fiber_sem_take_wait()` | |
| | :c:func:`nano_sem_task_wait()` | |
+------------------------------------------------+----------------------------+
| | :c:func:`nano_task_sem_take_wait_timeout()` | Waits on a semaphore for a |
| | :c:func:`nano_fiber_sem_take_wait_timeout()` | specified time period. |
+------------------------------------------------+----------------------------+
:cpp:func:`nano_sem_init()`
Initializes a semaphore.
:cpp:func:`nano_task_sem_give()`, :cpp:func:`nano_fiber_sem_give()`,
:cpp:func:`nano_isr_sem_give()`, :cpp:func:`nano_sem_give()`
Signal a sempahore.
:cpp:func:`nano_task_sem_take()`, :cpp:func:`nano_fiber_sem_take()`,
:cpp:func:`nano_isr_sem_take()`
Test a semaphore.
:cpp:func:`nano_task_sem_take_wait()`,
:cpp:func:`nano_fiber_sem_take_wait()`,
:cpp:func:`nano_sem_task_wait()`
Wait on a semaphore.
:cpp:func:`nano_task_sem_take_wait_timeout()`,
:cpp:func:`nano_fiber_sem_take_wait_timeout()`
Wait on a semaphore for a specified time period.

38
doc/kernel/nanokernel/nanokernel_timers.rst
View file

@ -23,7 +23,7 @@ Any remaining bytes of this area can be used to hold data that is helpful
to the thread that uses the timer.
Any number of nanokernel timers can be defined. Each timer is a distinct
variable of type :c:type:`struct nano_timer`, and is referenced using a pointer
variable of type :cpp:type:`struct nano_timer`, and is referenced using a pointer
to that variable. A timer must be initialized with its user data structure
before it can be used.
@ -78,8 +78,8 @@ other work.
.. note::
If a fiber or task has no other work to perform while waiting
for time to pass it can simply call :c:func:`fiber_sleep()`
or :c:func:`task_sleep()`, respectively.
for time to pass it can simply call :cpp:func:`fiber_sleep()`
or :cpp:func:`task_sleep()`, respectively.
.. note::
The kernel provides additional APIs that allow a fiber or task to monitor
@ -153,23 +153,19 @@ APIs
****
The following APIs for a nanokernel timer are provided
by :file:`nanokernel.h.`
by :file:`nanokernel.h`:
+------------------------------------------------+----------------------------+
| Call | Description |
+================================================+============================+
| :c:func:`nano_timer_init()` | Initializes a timer. |
+------------------------------------------------+----------------------------+
| | :c:func:`nano_task_timer_start()` | Starts a timer. |
| | :c:func:`nano_fiber_timer_start()` | |
+------------------------------------------------+----------------------------+
| | :c:func:`nano_task_timer_test()` | Tests a timer |
| | :c:func:`nano_fiber_timer_test()` | to see if it has expired. |
+------------------------------------------------+----------------------------+
| | :c:func:`nano_task_timer_wait()` | Waits on a timer |
| | :c:func:`nano_fiber_timer_wait()` | until it expires. |
+------------------------------------------------+----------------------------+
| | :c:func:`nano_task_timer_stop()` | Forces timer expiration, |
| | :c:func:`nano_fiber_timer_stop()` | if not already expired. |
+------------------------------------------------+----------------------------+
:cpp:func:`nano_timer_init()`
Initializes a timer.
:cpp:func:`nano_task_timer_start()`, :cpp:func:`nano_fiber_timer_start()`
Start a timer.
:cpp:func:`nano_task_timer_test()`, :cpp:func:`nano_fiber_timer_test()`
Test a timer to see if it has expired.
:cpp:func:`nano_task_timer_wait()`, :cpp:func:`nano_fiber_timer_wait()`
Wait on a timer until it expires.
:cpp:func:`nano_task_timer_stop()`, :cpp:func:`nano_fiber_timer_stop()`
Force timer expiration, if not already expired.