You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by GitBox <gi...@apache.org> on 2018/03/03 00:20:27 UTC
[GitHub] aditihilbert closed pull request #858: HAL & OS documentation update
aditihilbert closed pull request #858: HAL & OS documentation update
URL: https://github.com/apache/mynewt-core/pull/858
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/os/core_os/API.rst b/docs/os/core_os/API.rst
deleted file mode 100644
index 3a5a05f30..000000000
--- a/docs/os/core_os/API.rst
+++ /dev/null
@@ -1,33 +0,0 @@
-Core OS API
------------
-
-.. contents::
- :local:
- :depth: 2
-
-
-Core
-~~~~
-
-.. doxygenfile:: os.h
-
-
-Scheduler
-~~~~~~~~~
-
-.. doxygenfile:: os_sched.h
-
-CPU Time
-~~~~~~~~
-
-.. doxygenfile:: os_cputime.h
-
-OS Time
-~~~~~~~~
-
-.. doxygenfile:: os_time.h
-
-Task
-~~~~
-
-.. doxygenfile:: os_task.h
diff --git a/docs/os/core_os/callout/callout.rst b/docs/os/core_os/callout/callout.rst
index ad8f51d29..c52dc371a 100644
--- a/docs/os/core_os/callout/callout.rst
+++ b/docs/os/core_os/callout/callout.rst
@@ -1,7 +1,7 @@
Callout
=======
-Callouts are MyNewt OS timers.
+Callouts are Apache Mynewt OS timers.
Description
~~~~~~~~~~~
@@ -10,73 +10,33 @@ Callout is a way of setting up an OS timer. When the timer fires, it is
delivered as an event to task's event queue.
User would initialize their callout structure using
-*os\_callout\_init()*, or *os\_callout\_func\_init()* and then arm it
-with *os\_callout\_reset()*.
+:c:func:`os_callout_init()`, or :c:func:`os_callout_func_init()` and
+then arm it with :c:func:`os_callout_reset()`.
If user wants to cancel the timer before it expires, they can either use
-*os\_callout\_reset()* to arm it for later expiry, or stop it altogether
-by calling *os\_callout\_stop()*.
+:c:func:`os_callout_reset()` to arm it for later expiry, or stop it altogether
+by calling :c:func:`os_callout_stop()`.
There are 2 different options for data structure to use. First is
-*struct os\_callout*, which is a bare-bones version. You would
-initialize this with *os\_callout\_init()*.
+:c:type:`struct os_callout`, which is a bare-bones version. You would
+initialize this with :c:func:`os_callout_init()`.
-Second option is *struct os\_callout\_func*. This you can use if you
+Second option is :c:type:`struct os_callout_func`. This you can use if you
expect to have multiple different types of timers in your task, running
concurrently. The structure contains a function pointer, and you would
call that function from your task's event processing loop.
Time unit when arming the timer is OS ticks. This rate of this ticker
depends on the platform this is running on. You should use OS define
-*OS\_TICKS\_PER\_SEC* to convert wallclock time to OS ticks.
+``OS_TICKS_PER_SEC`` to convert wallclock time to OS ticks.
Callout timer fires out just once. For periodic timer type of operation
you need to rearm it once it fires.
-Data structures
-~~~~~~~~~~~~~~~
-
-::
-
- struct os_callout {
- struct os_event c_ev;
- struct os_eventq *c_evq;
- uint32_t c_ticks;
- TAILQ_ENTRY(os_callout) c_next;
- };
-
-+------------+------------------------------------------------------------+
-| Element | Description |
-+============+============================================================+
-| c\_ev | Event structure of this callout |
-+------------+------------------------------------------------------------+
-| c\_evq | Event queue where this callout is placed on timer expiry |
-+------------+------------------------------------------------------------+
-| c\_ticks | OS tick amount when timer fires |
-+------------+------------------------------------------------------------+
-| c\_next | Linkage to other unexpired callouts |
-+------------+------------------------------------------------------------+
-
-::
-
- struct os_callout_func {
- struct os_callout cf_c;
- os_callout_func_t cf_func;
- void *cf_arg;
- };
-
-+------------+---------------------------------------------------------------------+
-| Element | Description |
-+============+=====================================================================+
-| cf\_c | struct os\_callout. See above |
-+------------+---------------------------------------------------------------------+
-| cf\_func | Function pointer which should be called by event queue processing |
-+------------+---------------------------------------------------------------------+
-| cf\_arg | Generic void \* argument to that function |
-+------------+---------------------------------------------------------------------+
API
-----------------
.. doxygengroup:: OSCallouts
:content-only:
+ :members:
diff --git a/docs/os/core_os/context_switch/context_switch.rst b/docs/os/core_os/context_switch/context_switch.rst
index f3ff7430c..3c8c5dcbc 100644
--- a/docs/os/core_os/context_switch/context_switch.rst
+++ b/docs/os/core_os/context_switch/context_switch.rst
@@ -5,7 +5,7 @@ Scheduler's job is to maintain the list of tasks and decide which one
should be running next.
Description
-***********
+-------------
Task states can be *running*, *ready to run* or *sleeping*.
@@ -20,7 +20,7 @@ someone else to wake it up.
Scheduler algorithm is simple: from among the tasks which are ready to
run, pick the the one with highest priority (lowest numeric value in
-task's t\_prio field), and make its state *running*.
+task's :c:member:`t_prio` field), and make its state *running*.
Tasks which are either *running* or *ready to run* are kept in linked
list ``g_os_run_list``. This list is ordered by priority.
@@ -34,17 +34,8 @@ the CPU (e.g. registers) for the currently *running* task is stored and
the new task is swapped in.
API
-***
-
-* :c:func:`os_sched()`
-* :c:func:`os_arch_ctx_sw()`
-* :c:func:`os_sched_ctx_sw_hook()`
-* :c:func:`os_sched_get_current_task()`
-* :c:func:`os_sched_insert()`
-* :c:func:`os_sched_next_task()`
-* :c:func:`os_sched_os_timer_exp()`
-* :c:func:`os_sched_remove()`
-* :c:func:`os_sched_resort()`
-* :c:func:`os_sched_set_current_task()`
-* :c:func:`os_sched_sleep()`
-* :c:func:`os_sched_wakeup()`
+----
+
+.. doxygengroup:: OSSched
+ :content-only:
+ :members:
diff --git a/docs/os/core_os/cputime/os_cputime.rst b/docs/os/core_os/cputime/os_cputime.rst
index 1304b0189..cf0c2e000 100644
--- a/docs/os/core_os/cputime/os_cputime.rst
+++ b/docs/os/core_os/cputime/os_cputime.rst
@@ -8,38 +8,15 @@ Description
-----------
The ``cputime`` API provides high resolution time and timer support. The
-module must be initialized, using the ``os_cputime_init()`` function,
+module must be initialized, using the :c:func:`os_cputime_init()` function,
with the clock frequency to use. The module uses the ``hal_timer`` API,
defined in hal/hal_timer.h, to access the hardware timers. It uses the
hardware timer number specified by the ``OS_CPUTIME_TIMER_NUM`` system
configuration setting.
-Data Structures
----------------
-
-The module uses the following data structures:
-
-- ``uint32_t`` to represent ``cputime``. Only the lower 32 bits of a 64
- timer are used.
-- ``struct hal_timer`` to represent a cputime timer.
-
API
-----------------
-* :c:func:`os_cputime_delay_nsecs()`
-* :c:func:`os_cputime_delay_ticks()`
-* :c:func:`os_cputime_delay_usecs()`
-* :c:func:`os_cputime_get32()`
-* :c:func:`os_cputime_init()`
-* :c:func:`os_cputime_nsecs_to_ticks()`
-* :c:func:`os_cputime_ticks_to_nsecs()`
-* :c:func:`os_cputime_ticks_to_usecs()`
-* :c:func:`os_cputime_timer_init()`
-* :c:func:`os_cputime_timer_relative()`
-* :c:func:`os_cputime_timer_start()`
-* :c:func:`os_cputime_timer_stop()`
-* :c:func:`os_cputime_usecs_to_ticks()`
-* :c:macro:`CPUTIME_LT`
-* :c:macro:`CPUTIME_GT`
-* :c:macro:`CPUTIME_LEQ`
-* :c:macro:`CPUTIME_GEQ`
+.. doxygengroup:: OSCPUTime
+ :content-only:
+ :members:
diff --git a/docs/os/core_os/event_queue/event_queue.rst b/docs/os/core_os/event_queue/event_queue.rst
index b8f2f7606..8c2aabcf7 100644
--- a/docs/os/core_os/event_queue/event_queue.rst
+++ b/docs/os/core_os/event_queue/event_queue.rst
@@ -4,9 +4,8 @@ Event Queues
An event queue allows a task to serialize incoming events and simplify
event processing. Events are stored in a queue and a task removes and
processes an event from the queue. An event is processed in the context
-of this task. Events may be generated by `OS
-callouts <../callout/callout.html>`__, interrupt handlers, and other
-tasks.
+of this task. Events may be generated by OS callouts, interrupt handlers,
+and other tasks.
Description
---------------
@@ -30,83 +29,36 @@ real-time timing requirements should use Mynewt's default event queue
for its events. The callback function for an event from the Mynewt
default event queue is executed in the context of the application main
task. A package can, optionally, export a function that allows an
-application to specify the event queue for the package to use. (See the
-example in the ``os_eventq_designate()`` function description on how to
-write such a function.) The application task handler that manages the
-event queue simply pulls events from the event queue and executes the
-event's callback function in its context.
+application to specify the event queue for the package to use. The
+application task handler that manages the event queue simply pulls events
+from the event queue and executes the event's callback function in its context.
A common way that Mynewt applications or packages process events from an
event queue is to have a task that executes in an infinite loop and
-calls the ``os_eventq_get()`` function to dequeue and return the event
+calls the :c:func:`os_eventq_get()` function to dequeue and return the event
from the head of the event queue. The task then calls the event callback
-function to process the event. The ``os_eventq_get()`` function puts the
+function to process the event. The :c:func:`os_eventq_get()` function puts the
task in to the ``sleeping`` state when there are no events on the queue.
-(See `Scheduler <../context_switch/context_switch.html>`__ for more
+(See :doc:`../context_switch/context_switch` for more
information on task execution states.) Other tasks (or interrupts) call
-the ``os_eventq_put()`` function to add an event to the queue. The
-``os_eventq_put()`` function determines whether a task is blocked
+the :c:func:`os_eventq_put()` function to add an event to the queue. The
+:c:func:`os_eventq_put()` function determines whether a task is blocked
waiting for an event on the queue and puts the task into the
``ready-to-run`` state.
-A task can use the ``os_eventq_run()`` wrapper function that calls the
-``os_eventq_get()`` function to dequeue an event from the queue and then
+A task can use the :c:func:`os_eventq_run()` wrapper function that calls the
+:c:func:`os_eventq_get()` function to dequeue an event from the queue and then
calls the event callback function to process the event.
-
Note:
- Only one task should consume or block waiting for events from an
event queue.
-- The `os\_callout <../callout/callout.html>`__ subsystem uses events for
- timer expiration notification.
-
-Data structures
----------------
-
-The ``os_event`` structure defines an event and has the following
-fields:
-
-.. code:: c
-
- struct os_event {
- uint8_t ev_queued;
- os_event_fn *ev_cb;
- void *ev_arg;
- STAILQ_ENTRY(os_event) ev_next;
- };
-
-+-----------------+--------------------------------------------------------------------------------------------+
-| Element | Description |
-+=================+============================================================================================+
-| ``ev_queued`` | Internal field that indicates whether this event is currently linked to an event queue |
-+-----------------+--------------------------------------------------------------------------------------------+
-| ``ev_cb`` | Pointer to the callback function to call to process this event |
-+-----------------+--------------------------------------------------------------------------------------------+
-| ``ev_arg`` | Pointer to an optional opaque data that the callback function uses to process this event |
-+-----------------+--------------------------------------------------------------------------------------------+
-| ``ev_next`` | Linkage attaching this event to an event queue |
-+-----------------+--------------------------------------------------------------------------------------------+
-
-An event callback function has the following function prototype:
-
-.. code:: c
+- The OS callout subsystem uses events for timer expiration notification.
- typedef void os_event_fn(struct os_event *ev);
+Example
+-------
-A pointer to the ``os_event`` structure for the event is passed as an
-argument to the callback function.
-
-Notes: If the memory for the ``os_event`` structure is dynamically
-allocated:
-
-- You must not free the memory for an event that is currently on an
- event queue.
-- You must free the memory in the callback function after it completes
- processing the event.
-
-You must set the callback function for an event when you initialize the
-event. For example, here is an example of a statically-initialized event
-in the NimBLE host:
+Here is an example of using an event from the BLE host:
.. code:: c
@@ -117,29 +69,10 @@ in the NimBLE host:
.ev_cb = ble_hs_event_tx_notify,
};
-The ``os_eventq`` structure defines an event queue and has the following fields:
-
-.. code:: c
-
- struct os_eventq {
- struct os_task *evq_task;
- STAILQ_HEAD(, os_event) evq_list;
- };
-
-+----------------+------------------------------------------------------------------------------------------------------------------------------------+
-| Element | Description |
-+================+====================================================================================================================================+
-| ``evq_task`` | Pointer to the task, if any, that is waiting (in the ``sleeping`` state) for the ``os_eventq_get()`` function to return an event |
-+----------------+------------------------------------------------------------------------------------------------------------------------------------+
-| ``evq_list`` | Head of the list of events in this queue |
-+----------------+------------------------------------------------------------------------------------------------------------------------------------+
-
-
-You must call the ``os_eventq_init()`` function to initialize an event
-queue before you can add events to the queue.
-
+
API
----
.. doxygengroup:: OSEvent
+ :members:
:content-only:
diff --git a/docs/os/core_os/heap/heap.rst b/docs/os/core_os/heap/heap.rst
index c4e30b2ab..9915da0b9 100644
--- a/docs/os/core_os/heap/heap.rst
+++ b/docs/os/core_os/heap/heap.rst
@@ -8,18 +8,13 @@ Description
This provides malloc()/free() functionality with locking. The shared
resource heap needs to be protected from concurrent access when OS has
-been started. *os\_malloc()* function grabs a mutex before calling
-*malloc()*.
+been started. :c:func:`os_malloc()` function grabs a mutex before calling
+``malloc()``.
-Data structures
------------------
-
-N/A
API
----
-See the API for OS level function calls.
-
-- `Mynewt Core OS <../mynewt_os.html>`__
-
+.. doxygengroup:: OSMalloc
+ :content-only:
+ :members:
diff --git a/docs/os/core_os/mbuf/mbuf.rst b/docs/os/core_os/mbuf/mbuf.rst
index e5df9f573..b1e775075 100644
--- a/docs/os/core_os/mbuf/mbuf.rst
+++ b/docs/os/core_os/mbuf/mbuf.rst
@@ -40,7 +40,7 @@ various layers of the networking stack. Any mbufs that are part of the
packet (i.e. in the mbuf chain but not the first one) are "normal" (i.e.
non-packet header) mbufs. A normal mbuf does not have any packet header
or user packet header structures in them; they only contain the basic
-mbuf header (``struct os_mbuf``). Figure 1 illustrates these two types
+mbuf header (:c:type:`struct os_mbuf`). Figure 1 illustrates these two types
of mbufs. Note that the numbers/text in parentheses denote the size of
the structures/elements (in bytes) and that MBLEN is the memory block
length of the memory pool used by the mbuf pool.
@@ -55,35 +55,35 @@ Normal mbuf
Now let's take a deeper dive into the mbuf structure. Figure 2
illustrates a normal mbuf and breaks out the various fields in the
-``os_mbuf`` structure.
+c:type:`os_mbuf` structure.
-- The *om\_data* field is a pointer to where the data starts inside the
+- The :c:member:`om_data` field is a pointer to where the data starts inside the
data buffer. Typically, mbufs that are allocated from the mbuf pool
- (discussed later) have their om\_data pointer set to the start of the
+ (discussed later) have their :c:member:`om_data` pointer set to the start of the
data buffer but there are cases where this may not be desirable
(added a protocol header to a packet, for example).
-- The *om\_flags* field is a set of flags used internally by the mbuf
+- The :c:member:`om_flags` field is a set of flags used internally by the mbuf
library. Currently, no flags have been defined.
-- The *om\_pkthdr\_len* field is the total length of all packet headers
+- The :c:member:`om_pkthdr_len` field is the total length of all packet headers
in the mbuf. For normal mbufs this is set to 0 as there is no packet
or user packet headers. For packet header mbufs, this would be set to
the length of the packet header structure (16) plus the size of the
user packet header (if any). Note that it is this field which
differentiates packet header mbufs from normal mbufs (i.e. if
- *om\_pkthdr\_len* is zero, this is a normal mbuf; otherwise it is a
+ :c:member:`om_pkthdr_len` is zero, this is a normal mbuf; otherwise it is a
packet header mbuf).
-- The *om\_len* field contains the amount of user data in the data
+- The :c:member:`om_len` field contains the amount of user data in the data
buffer. When initially allocated, this field is 0 as there is no user
data in the mbuf.
-- The *omp\_pool* field is a pointer to the pool from which this mbuf
+- The :c:member:`omp_pool` field is a pointer to the pool from which this mbuf
has been allocated. This is used internally by the mbuf library.
-- The *omp\_next* field is a linked list element which is used to chain
+- The :c:member:`omp_next` field is a linked list element which is used to chain
mbufs.
-Figure 2 also shows a normal mbuf with actual values in the ``os_mbuf``
+Figure 2 also shows a normal mbuf with actual values in the :c:type:`os_mbuf`
structure. This mbuf starts at address 0x1000 and is 256 bytes in total
length. In this example, the user has copied 33 bytes into the data
-buffer starting at address 0x1010 (this is where om\_data points). Note
+buffer starting at address 0x1010 (this is where :c:member:`om_data` points). Note
that the packet header length in this mbuf is 0 as it is not a packet
header mbuf.
@@ -95,7 +95,7 @@ header mbuf.
Figure 3 illustrates the packet header mbuf along with some chained
mbufs (i.e a "packet"). In this example, the user header structure is
defined to be 8 bytes. Note that in figure 3 we show a number of
-different mbufs with varying *om\_data* pointers and lengths since we
+different mbufs with varying :c:member:`om_data` pointers and lengths since we
want to show various examples of valid mbufs. For all the mbufs (both
packet header and normal ones) the total length of the memory block is
128 bytes.
@@ -172,18 +172,54 @@ block size required, denoted by the macro *MBUF\_MEMBLOCK\_OVERHEAD*.
assert(rc == 0);
}
+Msys
+-----
+
+Msys stands for "system mbufs" and is a set of API built on top of the
+mbuf code. The basic idea behind msys is the following. The developer
+can create different size mbuf pools and register them with msys. The
+application then allocates mbufs using the msys API (as opposed to the
+mbuf API). The msys code will choose the mbuf pool with the smallest
+mbufs that can accommodate the requested size.
+
+Let us walk through an example where the user registers three mbuf pools
+with msys: one with 32 byte mbufs, one with 256 and one with 2048. If
+the user requests an mbuf with 10 bytes, the 32-byte mbuf pool is used.
+If the request is for 33 bytes the 256 byte mbuf pool is used. If an
+mbuf data size is requested that is larger than any of the pools (say,
+4000 bytes) the largest pool is used. While this behaviour may not be
+optimal in all cases that is the currently implemented behaviour. All
+this means is that the user is not guaranteed that a single mbuf can
+hold the requested data.
+
+The msys code will not allocate an mbuf from a larger pool if the chosen
+mbuf pool is empty. Similarly, the msys code will not chain together a
+number of smaller mbufs to accommodate the requested size. While this
+behaviour may change in future implementations the current code will
+simply return NULL. Using the above example, say the user requests 250
+bytes. The msys code chooses the appropriate pool (i.e. the 256 byte
+mbuf pool) and attempts to allocate an mbuf from that pool. If that pool
+is empty, NULL is returned even though the 32 and 2048 byte pools are
+not empty.
+
+Note that no added descriptions on how to use the msys API are presented
+here (other than in the API descriptions themselves) as the msys API is
+used in exactly the same manner as the mbuf API. The only difference is
+that mbuf pools are added to msys by calling ``os_msys_register().``
+
+
Using mbufs
--------------
The following examples illustrate typical mbuf usage. There are two
-basic mbuf allocation API: ``os_mbuf_get()`` and
-``os_mbuf_get_pkthdr()``. The first API obtains a normal mbuf whereas
+basic mbuf allocation API: c:func:`os_mbuf_get()` and
+:c:func:`os_mbuf_get_pkthdr()`. The first API obtains a normal mbuf whereas
the latter obtains a packet header mbuf. Typically, application
-developers use ``os_mbuf_get_pkthdr()`` and rarely, if ever, need to
-call ``os_mbuf_get()`` as the rest of the mbuf API (e.g.
-``os_mbuf_append()``, ``os_mbuf_copyinto()``, etc.) typically deal with
-allocating and chaining mbufs. It is recommended to use the provided API
-to copy data into/out of mbuf chains and/or manipulate mbufs.
+developers use :c:func:`os_mbuf_get_pkthdr()` and rarely, if ever, need to
+call :c:func:`os_mbuf_get()` as the rest of the mbuf API (e.g.
+:c:func:`os_mbuf_append()`, :c:func:`os_mbuf_copyinto()`, etc.) typically
+deal with allocating and chaining mbufs. It is recommended to use the
+provided API to copy data into/out of mbuf chains and/or manipulate mbufs.
In ``example1``, the developer creates a packet and then sends the
packet to a networking interface. The code sample also provides an
@@ -293,180 +329,91 @@ definitions used in the first example.
os_mbuf_free_chain(om);
}
-Data Structures
------------------
-.. code:: c
+Mqueue
+-------
- struct os_mbuf_pool {
- uint16_t omp_databuf_len;
- uint16_t omp_mbuf_count;
- struct os_mempool *omp_pool;
- STAILQ_ENTRY(os_mbuf_pool) omp_next;
- };
-
-+--------------+----------------+
-| **Element** | **Description* |
-| | * |
-+==============+================+
-| omp\_databuf | The length, in |
-| \_len | bytes, of the |
-| | "data buffer" |
-| | of the mbuf. |
-| | The data |
-| | buffer of the |
-| | mbuf is |
-| | everything |
-| | except the |
-| | os\_mbuf |
-| | structure |
-| | (which is |
-| | present in all |
-| | types of |
-| | mbufs) |
-+--------------+----------------+
-| omp\_mbuf\_c | Total number |
-| ount | of mbufs in |
-| | the pool when |
-| | allocated. |
-| | This is NOT |
-| | the number of |
-| | free mbufs in |
-| | the pool! |
-+--------------+----------------+
-| omp\_pool | The memory |
-| | pool from |
-| | which the |
-| | mbufs are |
-| | allocated |
-+--------------+----------------+
-| omp\_next | This is a |
-| | linked list |
-| | pointer which |
-| | chains memory |
-| | pools. It is |
-| | used by the |
-| | system memory |
-| | pool library |
-+--------------+----------------+
+The mqueue construct allows a task to wake up when it receives data.
+Typically, this data is in the form of packets received over a network.
+A common networking stack operation is to put a packet on a queue and
+post an event to the task monitoring that queue. When the task handles
+the event, it processes each packet on the packet queue.
-.. code:: c
+Using Mqueue
+--------------
+
+The following code sample demonstrates how to use an mqueue. In this
+example:
- struct os_mbuf_pkthdr {
- uint16_t omp_len;
- uint16_t omp_flags;
- STAILQ_ENTRY(os_mbuf_pkthdr) omp_next;
- };
-
-+--------------+----------------+
-| **Element** | **Description* |
-| | * |
-+==============+================+
-| omp\_len | Length, in |
-| | bytes, of the |
-| | "packet". This |
-| | is the sum of |
-| | the user data |
-| | in all the |
-| | mbufs chained |
-| | to the packet |
-| | header mbuf |
-| | (including the |
-| | packet header |
-| | mbuf) |
-+--------------+----------------+
-| omp\_flags | Packet header |
-| | flags. |
-+--------------+----------------+
-| omp\_next | Linked list |
-| | pointer to |
-| | chain |
-| | "packets". |
-| | This can be |
-| | used to add |
-| | mbuf chains to |
-| | a queue or |
-| | linked list |
-| | and is there |
-| | for |
-| | convenience. |
-+--------------+----------------+
+- packets are put on a receive queue
+- a task processes each packet on the queue (increments a receive
+ counter)
+
+Not shown in the code example is a call ``my_task_rx_data_func``.
+Presumably, some other code will call this API.
.. code:: c
- struct os_mbuf {
- uint8_t *om_data;
- uint8_t om_flags;
- uint8_t om_pkthdr_len;
- uint16_t om_len;
- struct os_mbuf_pool *om_omp;
- SLIST_ENTRY(os_mbuf) om_next;
- uint8_t om_databuf[0];
- };
-
-+--------------+----------------+
-| **Element** | **Description* |
-| | * |
-+==============+================+
-| om\_data | Pointer to |
-| | start of user |
-| | data in mbuf |
-| | data buffer |
-+--------------+----------------+
-| om\_flags | mbuf flags |
-| | field. |
-| | Currently all |
-| | flags unused. |
-+--------------+----------------+
-| om\_pkthdr\_ | The total |
-| len | length of all |
-| | packet headers |
-| | in the mbuf |
-| | (mbuf packet |
-| | header plus |
-| | user packet |
-| | header), in |
-| | bytes |
-+--------------+----------------+
-| om\_len | The length of |
-| | the user data |
-| | contained in |
-| | this mbuf, in |
-| | bytes |
-+--------------+----------------+
-| om\_omp | Memory pool |
-| | pointer. This |
-| | is the mbuf |
-| | pool from |
-| | which this |
-| | mbuf was |
-| | allocated. |
-+--------------+----------------+
-| om\_next | Pointer to |
-| | next mbuf in |
-| | packet chain |
-+--------------+----------------+
-| om\_databuf | mbuf data |
-| | buffer |
-| | (accessor to |
-| | start of mbuf |
-| | data buffer). |
-| | Note that the |
-| | mbuf data |
-| | buffer refers |
-| | to the start |
-| | of either the |
-| | user data in |
-| | normal mbufs |
-| | or the start |
-| | of the os mbuf |
-| | packet header |
-| | for packet |
-| | header mbufs |
-+--------------+----------------+
+ uint32_t pkts_rxd;
+ struct os_mqueue rxpkt_q;
+ struct os_eventq my_task_evq;
+
+ /**
+ * Removes each packet from the receive queue and processes it.
+ */
+ void
+ process_rx_data_queue(void)
+ {
+ struct os_mbuf *om;
+
+ while ((om = os_mqueue_get(&rxpkt_q)) != NULL) {
+ ++pkts_rxd;
+ os_mbuf_free_chain(om);
+ }
+ }
+
+ /**
+ * Called when a packet is received.
+ */
+ int
+ my_task_rx_data_func(struct os_mbuf *om)
+ {
+ int rc;
+
+ /* Enqueue the received packet and wake up the listening task. */
+ rc = os_mqueue_put(&rxpkt_q, &my_task_evq, om);
+ if (rc != 0) {
+ return -1;
+ }
+
+ return 0;
+ }
+
+ void
+ my_task_handler(void *arg)
+ {
+ struct os_event *ev;
+ struct os_callout_func *cf;
+ int rc;
+
+ /* Initialize eventq */
+ os_eventq_init(&my_task_evq);
+
+ /* Initialize mqueue */
+ os_mqueue_init(&rxpkt_q, NULL);
+
+ /* Process each event posted to our eventq. When there are no events to
+ * process, sleep until one arrives.
+ */
+ while (1) {
+ os_eventq_run(&my_task_evq);
+ }
+ }
+
API
-----------------
.. doxygengroup:: OSMbuf
:content-only:
+ :members:
diff --git a/docs/os/core_os/memory_pool/memory_pool.rst b/docs/os/core_os/memory_pool/memory_pool.rst
index 43f20b183..8fbc14940 100644
--- a/docs/os/core_os/memory_pool/memory_pool.rst
+++ b/docs/os/core_os/memory_pool/memory_pool.rst
@@ -26,7 +26,7 @@ variable) or dynamically allocated (i.e. from the heap). When
determining the amount of memory required for the memory pool, simply
multiplying the number of blocks by the size of each block is not
sufficient as the OS may have alignment requirements. The alignment size
-definition is named ``OS_ALIGNMENT`` and can be found in os\_arch.h as
+definition is named :c:macro:`OS_ALIGNMENT` and can be found in os\_arch.h as
it is architecture specific. The memory block alignment is usually for
efficiency but may be due to other reasons. Generally, blocks are
aligned on 32-bit boundaries. Note that memory blocks must also be of
@@ -34,16 +34,16 @@ sufficient size to hold a list pointer as this is needed to chain memory
blocks on the free list.
In order to simplify this for the user two macros have been provided:
-``OS_MEMPOOL_BYTES(n, blksize)`` and ``OS_MEMPOOL_SIZE(n, blksize)``.
+c:macro:`OS_MEMPOOL_BYTES(n, blksize)` and :c:macro:`OS_MEMPOOL_SIZE(n, blksize)`.
The first macro returns the number of bytes needed for the memory pool
-while the second returns the number of ``os_membuf_t`` elements required
-by the memory pool. The ``os_membuf_t`` type is used to guarantee that
+while the second returns the number of :c:type:`os_membuf_t`` elements required
+by the memory pool. The :c:type:`os_membuf_t` type is used to guarantee that
the memory buffer used by the memory pool is aligned on the correct
boundary.
Here are some examples. Note that if a custom malloc implementation is
used it must guarantee that the memory buffer used by the pool is
-allocated on the correct boundary (i.e. OS\_ALIGNMENT).
+allocated on the correct boundary (i.e. :c:macro:`OS_ALIGNMENT`).
.. code:: c
@@ -56,7 +56,7 @@ allocated on the correct boundary (i.e. OS\_ALIGNMENT).
Now that the memory pool has been defined as well as the memory
required for the memory blocks which make up the pool the user needs to
-initialize the memory pool by calling ``os_mempool_init``.
+initialize the memory pool by calling :c:func:`os_mempool_init``.
.. code:: c
@@ -64,94 +64,15 @@ initialize the memory pool by calling ``os_mempool_init``.
"MyPool");
Once the memory pool has been initialized the developer can allocate
-memory blocks from the pool by calling ``os_memblock_get``. When the
+memory blocks from the pool by calling :c:func:`os_memblock_get`. When the
memory block is no longer needed the memory can be freed by calling
-``os_memblock_put``.
-
-Data structures
-----------------
-
-.. code:: c
-
- struct os_mempool {
- int mp_block_size;
- int mp_num_blocks;
- int mp_num_free;
- int mp_min_free;
- uint32_t mp_membuf_addr;
- STAILQ_ENTRY(os_mempool) mp_list;
- SLIST_HEAD(,os_memblock);
- char *name;
- };
-
- struct os_mempool_info {
- int omi_block_size;
- int omi_num_blocks;
- int omi_num_free;
- int omi_min_free;
- char omi_name[OS_MEMPOOL_INFO_NAME_LEN];
- };
-
-+--------------+----------------+
-| **Element** | **Description* |
-| | * |
-+==============+================+
-| mp\_block\_s | Size of the |
-| ize | memory blocks, |
-| | in bytes. This |
-| | is not the |
-| | actual number |
-| | of bytes used |
-| | by each block; |
-| | it is the |
-| | requested size |
-| | of each block. |
-| | The actual |
-| | memory block |
-| | size will be |
-| | aligned to |
-| | OS\_ALIGNMENT |
-| | bytes |
-+--------------+----------------+
-| mp\_num\_blo | Number of |
-| cks | memory blocks |
-| | in the pool |
-+--------------+----------------+
-| mp\_num\_fre | Number of free |
-| e | blocks left |
-+--------------+----------------+
-| mp\_min\_fre | Lowest number |
-| e | of free blocks |
-| | seen |
-+--------------+----------------+
-| mp\_membuf\_ | The address of |
-| addr | the memory |
-| | block. This is |
-| | used to check |
-| | that a valid |
-| | memory block |
-| | is being |
-| | freed. |
-+--------------+----------------+
-| mp\_list | List pointer |
-| | to chain |
-| | memory pools |
-| | so they can be |
-| | displayed by |
-| | newt tools |
-+--------------+----------------+
-| SLIST\_HEAD( | List pointer |
-| ,os\_membloc | to chain free |
-| k) | memory blocks |
-+--------------+----------------+
-| name | Name for the |
-| | memory block |
-+--------------+----------------+
+:c:func:`os_memblock_put`.
API
-----
.. doxygengroup:: OSMempool
:content-only:
+ :members:
diff --git a/docs/os/core_os/mqueue/mqueue.rst b/docs/os/core_os/mqueue/mqueue.rst
deleted file mode 100644
index b7c13b858..000000000
--- a/docs/os/core_os/mqueue/mqueue.rst
+++ /dev/null
@@ -1,95 +0,0 @@
-Mqueue
-======
-
-The mqueue construct allows a task to wake up when it receives data.
-Typically, this data is in the form of packets received over a network.
-A common networking stack operation is to put a packet on a queue and
-post an event to the task monitoring that queue. When the task handles
-the event, it processes each packet on the packet queue.
-
-Using Mqueue
---------------
-
-The following code sample demonstrates how to use an mqueue. In this
-example:
-
-- packets are put on a receive queue
-- a task processes each packet on the queue (increments a receive
- counter)
-
-Not shown in the code example is a call ``my_task_rx_data_func``.
-Presumably, some other code will call this API.
-
-.. code:: c
-
- uint32_t pkts_rxd;
- struct os_mqueue rxpkt_q;
- struct os_eventq my_task_evq;
-
- /**
- * Removes each packet from the receive queue and processes it.
- */
- void
- process_rx_data_queue(void)
- {
- struct os_mbuf *om;
-
- while ((om = os_mqueue_get(&rxpkt_q)) != NULL) {
- ++pkts_rxd;
- os_mbuf_free_chain(om);
- }
- }
-
- /**
- * Called when a packet is received.
- */
- int
- my_task_rx_data_func(struct os_mbuf *om)
- {
- int rc;
-
- /* Enqueue the received packet and wake up the listening task. */
- rc = os_mqueue_put(&rxpkt_q, &my_task_evq, om);
- if (rc != 0) {
- return -1;
- }
-
- return 0;
- }
-
- void
- my_task_handler(void *arg)
- {
- struct os_event *ev;
- struct os_callout_func *cf;
- int rc;
-
- /* Initialize eventq */
- os_eventq_init(&my_task_evq);
-
- /* Initialize mqueue */
- os_mqueue_init(&rxpkt_q, NULL);
-
- /* Process each event posted to our eventq. When there are no events to
- * process, sleep until one arrives.
- */
- while (1) {
- os_eventq_run(&my_task_evq);
- }
- }
-
-Data Structures
-----------------
-
-.. code:: c
-
- struct os_mqueue {
- STAILQ_HEAD(, os_mbuf_pkthdr) mq_head;
- struct os_event mq_ev;
- };
-
-API
------------------
-
-.. doxygengroup:: OSMqueue
- :content-only:
diff --git a/docs/os/core_os/msys/msys.rst b/docs/os/core_os/msys/msys.rst
deleted file mode 100644
index 8f8420b39..000000000
--- a/docs/os/core_os/msys/msys.rst
+++ /dev/null
@@ -1,40 +0,0 @@
-Msys
-====
-
-Msys stands for "system mbufs" and is a set of API built on top of the
-mbuf code. The basic idea behind msys is the following. The developer
-can create different size mbuf pools and register them with msys. The
-application then allocates mbufs using the msys API (as opposed to the
-mbuf API). The msys code will choose the mbuf pool with the smallest
-mbufs that can accommodate the requested size.
-
-Let us walk through an example where the user registers three mbuf pools
-with msys: one with 32 byte mbufs, one with 256 and one with 2048. If
-the user requests an mbuf with 10 bytes, the 32-byte mbuf pool is used.
-If the request is for 33 bytes the 256 byte mbuf pool is used. If an
-mbuf data size is requested that is larger than any of the pools (say,
-4000 bytes) the largest pool is used. While this behaviour may not be
-optimal in all cases that is the currently implemented behaviour. All
-this means is that the user is not guaranteed that a single mbuf can
-hold the requested data.
-
-The msys code will not allocate an mbuf from a larger pool if the chosen
-mbuf pool is empty. Similarly, the msys code will not chain together a
-number of smaller mbufs to accommodate the requested size. While this
-behaviour may change in future implementations the current code will
-simply return NULL. Using the above example, say the user requests 250
-bytes. The msys code chooses the appropriate pool (i.e. the 256 byte
-mbuf pool) and attempts to allocate an mbuf from that pool. If that pool
-is empty, NULL is returned even though the 32 and 2048 byte pools are
-not empty.
-
-Note that no added descriptions on how to use the msys API are presented
-here (other than in the API descriptions themselves) as the msys API is
-used in exactly the same manner as the mbuf API. The only difference is
-that mbuf pools are added to msys by calling ``os_msys_register().``
-
-API
------------------
-
-.. doxygengroup:: OSMsys
- :content-only:
diff --git a/docs/os/core_os/mutex/mutex.rst b/docs/os/core_os/mutex/mutex.rst
index 4d56acd46..b4f9d05f3 100644
--- a/docs/os/core_os/mutex/mutex.rst
+++ b/docs/os/core_os/mutex/mutex.rst
@@ -18,15 +18,15 @@ tasks start running in order to avoid a task possibly using the mutex
before it is initialized.
When a task wants exclusive access to a shared resource it needs to
-obtain the mutex by calling *os\_mutex\_pend*. If the mutex is currently
+obtain the mutex by calling :c:func:`os_mutex_pend`. If the mutex is currently
owned by a different task (a lower priority task), the requesting task
will be put to sleep and the owners priority will be elevated to the
priority of the requesting task. Note that multiple tasks can request
ownership and the current owner is elevated to the highest priority of
any task waitin on the mutex. When the task is done using the shared
-resource, it needs to release the mutex by called *os\_mutex\_release*.
+resource, it needs to release the mutex by called :c:func:`os_mutex_release`.
There needs to be one release per call to pend. Note that nested calls
-to *os\_mutex\_pend* are allowed but there needs to be one release per
+to :c:func:`os_mutex_pend` are allowed but there needs to be one release per
pend.
The following example will illustrate how priority inheritance works. In
@@ -46,52 +46,9 @@ Note that when multiple tasks are waiting on a mutex owned by another
task, once the mutex is released the highest priority task waiting on
the mutex is run.
-Data structures
-----------------
-
-.. code:: c
-
- struct os_mutex
- {
- SLIST_HEAD(, os_task) mu_head;
- uint8_t _pad;
- uint8_t mu_prio;
- uint16_t mu_level;
- struct os_task *mu_owner;
- };
-
-+--------------+----------------+
-| Element | Description |
-+==============+================+
-| mu\_head | Queue head for |
-| | list of tasks |
-| | waiting on |
-| | mutex |
-+--------------+----------------+
-| \_pad | Padding |
-+--------------+----------------+
-| mu\_prio | Default |
-| | priority of |
-| | owner of |
-| | mutex. Used to |
-| | reset priority |
-| | of task when |
-| | mutex released |
-+--------------+----------------+
-| mu\_level | Call nesting |
-| | level (for |
-| | nested calls) |
-+--------------+----------------+
-| mu\_owner | Pointer to |
-| | task structure |
-| | which owns |
-| | mutex |
-+--------------+----------------+
-
API
----
.. doxygengroup:: OSMutex
:content-only:
-
-
+ :members:
diff --git a/docs/os/core_os/mynewt_os.rst b/docs/os/core_os/mynewt_os.rst
index 328986dcb..93387239e 100644
--- a/docs/os/core_os/mynewt_os.rst
+++ b/docs/os/core_os/mynewt_os.rst
@@ -1,24 +1,21 @@
-Mynewt Core OS
-==============
+Apache Mynewt Operating System Kernel
+======================================
.. toctree::
:hidden:
context_switch/context_switch
- cputime/os_cputime
- time/os_time
task/task
- event_queue/event_queue
- semaphore/semaphore
mutex/mutex
- memory_pool/memory_pool
+ semaphore/semaphore
+ event_queue/event_queue
+ callout/callout
heap/heap
+ memory_pool/memory_pool
mbuf/mbuf
- msys/msys
- mqueue/mqueue
+ cputime/os_cputime
+ time/os_time
sanity/sanity
- callout/callout
- API <API>
The Mynewt Core OS is a multitasking, preemptive real-time operating
system combining a scheduler with typical RTOS features such as mutexes,
@@ -123,7 +120,7 @@ initialization" function, and dispatches events from the default event
queue. The application task initialization function is responsible for
initializing all the data objects that each task exposes to the other
tasks. The tasks themselves are also initialized at this time (by
-calling ``os_task_init()``).
+calling :c:func:`os_task_init()`).
In the example, each task works in a ping-pong like fashion: task 1
wakes up, adds a token to semaphore 1 and then waits for a token from
@@ -131,8 +128,8 @@ semaphore 2. Task 2 waits for a token on semaphore 1 and once it gets
it, adds a token to semaphore 2. Notice that the semaphores are
initialized by the application specific task initialization functions
and not inside the task handler functions. If task 2 (being lower in
-priority than task 1) had called os_sem_init() for task2_sem inside
-task2_handler(), task 1 would have called os_sem_pend() using
+priority than task 1) had called :c:func:`os_sem_init()` for task2_sem inside
+task2_handler(), task 1 would have called :c:func:`os_sem_pend()` using
task2_sem before task2_sem was initialized.
.. code:: c
diff --git a/docs/os/core_os/os_init.rst b/docs/os/core_os/os_init.rst
deleted file mode 100644
index 628e3f871..000000000
--- a/docs/os/core_os/os_init.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-os\_init
---------
-
-.. code-block:: console
-
- void os_init(void)
-
-Initializes the OS. Must be called before the OS is started (i.e.
-os\_start() is called).
-
-Arguments
-^^^^^^^^^
-
-None
-
-Returned values
-^^^^^^^^^^^^^^^
-
-None
-
-Notes
-^^^^^
-
-The call to os\_init performs architecture and bsp initializations and
-initializes the idle task.
-
-This function does not start the OS, the OS time tick interrupt, or the
-scheduler.
diff --git a/docs/os/core_os/os_start.rst b/docs/os/core_os/os_start.rst
deleted file mode 100644
index fd2fa2691..000000000
--- a/docs/os/core_os/os_start.rst
+++ /dev/null
@@ -1,27 +0,0 @@
-os\_start
----------
-
-.. code-block:: console
-
- void os_start(void)
-
-Starts the OS by initializing and enabling the OS time tick and starting
-the scheduler.
-
-This function does not return.
-
-Arguments
-^^^^^^^^^
-
-None
-
-Returned values
-^^^^^^^^^^^^^^^
-
-None (does not return).
-
-Notes
-^^^^^
-
-Once os\_start has been called, context is switched to the highest
-priority task that was initialized prior to calling os\_start.
diff --git a/docs/os/core_os/os_started.rst b/docs/os/core_os/os_started.rst
deleted file mode 100644
index 486a3d86e..000000000
--- a/docs/os/core_os/os_started.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-os\_started
------------
-
-.. code-block:: console
-
- int os_started(void)
-
-Returns 'true' (1) if the os has been started; 0 otherwise.
-
-Arguments
-^^^^^^^^^
-
-None
-
-Returned values
-^^^^^^^^^^^^^^^
-
-Integer value with 0 meaning the OS has not been started and 1
-indicating the OS has been started (i.e. os\_start() has been called).
diff --git a/docs/os/core_os/sanity/sanity.rst b/docs/os/core_os/sanity/sanity.rst
index 8e4216935..5211c58a9 100644
--- a/docs/os/core_os/sanity/sanity.rst
+++ b/docs/os/core_os/sanity/sanity.rst
@@ -32,13 +32,13 @@ Description
Sanity Task
-----------
-Mynewt OS uses the OS Idle task to check sanity. The ``SANITY_INTERVAL``
+Mynewt OS uses the OS Idle task to check sanity. The :c:macro:`SANITY_INTERVAL`
syscfg setting specifies the interval in seconds to perform the sanity
checks.
By default, every operating system task provides the frequency it will
check in with the sanity task, with the ``sanity_itvl`` parameter in the
-``os_task_init()`` function:
+c:func:`os_task_init()` function:
.. code:: c
@@ -46,7 +46,7 @@ check in with the sanity task, with the ``sanity_itvl`` parameter in the
void *arg, uint8_t prio, os_time_t sanity_itvl, os_stack_t *bottom,
uint16_t stack_size);
-``sanity_itvl`` is the time in OS time ticks that the task being created
+c:var:`sanity_itvl` is the time in OS time ticks that the task being created
must register in with the sanity task.
Checking in with Sanity Task
@@ -54,7 +54,7 @@ Checking in with Sanity Task
The task must then register in with the sanity task every
``sanity_itvl`` seconds. In order to do that, the task should call the
-``os_sanity_task_checkin`` function, which will reset the sanity check
+:c:func:`os_sanity_task_checkin` function, which will reset the sanity check
associated with this task. Here is an example of a task that uses a
callout to checkin with the sanity task every 50 seconds:
@@ -105,8 +105,8 @@ Registering a Custom Sanity Check
If a particular task wants to further hook into the sanity framework to
perform other checks during the sanity task's operation, it can do so by
-registering a ``struct os_sanity_check`` using the
-``os_sanity_check_register`` function.
+registering a :c:type:`struct os_sanity_check` using the
+:c:func:`os_sanity_check_register()` function.
.. code:: c
@@ -149,8 +149,8 @@ registering a ``struct os_sanity_check`` using the
In the above example, every time the custom sanity check
``mymodule_perform_sanity_check`` returns successfully (0), the sanity
-check is reset. In the ``OS_SANITY_CHECK_SETFUNC`` macro, the sanity
-checkin interval is specified as 50 \* SANITY\_TASK\_INTERVAL (which is
+check is reset. In the c:macro:`OS_SANITY_CHECK_SETFUNC` macro, the sanity
+checkin interval is specified as 50 \* :c:macro:`SANITY_TASK_INTERVAL` (which is
the interval at which the sanity task runs.) This means that the
``mymodule_perform_sanity_check()`` function needs to fail 50 times
consecutively before the sanity task will crash the system.
@@ -160,73 +160,9 @@ temporarily be exhausted, it's a good idea to have the sanity check fail
multiple consecutive times before crashing the system. This will avoid
crashing for temporary failures.
-Data structures
----------------
-
-OS Sanity Check
-----------------
-
-.. code:: c
-
- struct os_sanity_check {
- os_time_t sc_checkin_last;
- os_time_t sc_checkin_itvl;
- os_sanity_check_func_t sc_func;
- void *sc_arg;
-
- SLIST_ENTRY(os_sanity_check) sc_next;
- };
-
-+--------------+----------------+
-| **Element** | **Description* |
-| | * |
-+==============+================+
-| ``sc_checkin | The last time |
-| _last`` | this sanity |
-| | check checked |
-| | in with the |
-| | sanity task, |
-| | in OS time |
-| | ticks. |
-+--------------+----------------+
-| ``sc_checkin | How frequently |
-| _itvl`` | the sanity |
-| | check is |
-| | supposed to |
-| | check in with |
-| | the sanity |
-| | task, in OS |
-| | time ticks. |
-+--------------+----------------+
-| ``sc_func`` | If not |
-| | ``NULL``, call |
-| | this function |
-| | when running |
-| | the sanity |
-| | task. If the |
-| | function |
-| | returns 0, |
-| | reset the |
-| | sanity check. |
-+--------------+----------------+
-| ``sc_arg`` | Argument to |
-| | pass to |
-| | ``sc_func`` |
-| | when calling |
-| | it. |
-+--------------+----------------+
-| ``sc_next`` | Sanity checks |
-| | are chained in |
-| | the sanity |
-| | task when |
-| | ``os_sanity_ch |
-| | eck_register() |
-| | `` |
-| | is called. |
-+--------------+----------------+
-
API
-----------------
.. doxygengroup:: OSSanity
:content-only:
+ :members:
diff --git a/docs/os/core_os/semaphore/semaphore.rst b/docs/os/core_os/semaphore/semaphore.rst
index 8c8b4a24d..04fbff62b 100644
--- a/docs/os/core_os/semaphore/semaphore.rst
+++ b/docs/os/core_os/semaphore/semaphore.rst
@@ -19,9 +19,9 @@ semaphore, the initial number of tokens can be set as well.
When used for exclusive access to a shared resource the semaphore only
needs a single token. In this case, a single task "creates" the
-semaphore by calling *os\_sem\_init* with a value of one (1) for the
+semaphore by calling :c:func:`os_sem_init()` with a value of one (1) for the
token. When a task desires exclusive access to the shared resource it
-requests the semaphore by calling *os\_sem\_pend*. If there is a token
+requests the semaphore by calling :c:func:`os_sem_pend()`. If there is a token
the requesting task will acquire the semaphore and continue operation.
If no tokens are available the task will be put to sleep until there is
a token. A common "problem" with using a semaphore for exclusive access
@@ -45,48 +45,27 @@ of this would be the following. A task creates a semaphore and
initializes it with no tokens. The task then waits on the semaphore, and
since there are no tokens, the task is put to sleep. When other tasks
want to wake up the sleeping task they simply add a token by calling
-*os\_sem\_release*. This will cause the sleeping task to wake up
+:c:func:`os_sem_release()`. This will cause the sleeping task to wake up
(instantly if no other higher priority tasks want to run).
The other common use of a counting semaphore is in what is commonly
called a "producer/consumer" relationship. The producer adds tokens (by
-calling *os\_sem\_release*) and the consumer consumes them by calling
-*os\_sem\_pend*. In this relationship, the producer has work for the
+calling :c:func:`os_sem_release()`) and the consumer consumes them by calling
+:c:func:`os_sem_pend()`. In this relationship, the producer has work for the
consumer to do. Each token added to the semaphore will cause the
consumer to do whatever work is required. A simple example could be the
following: every time a button is pressed there is some work to do (ring
a bell). Each button press causes the producer to add a token. Each
token consumed rings the bell. There will exactly the same number of
bell rings as there are button presses. In other words, each call to
-*os\_sem\_pend* subtracts exactly one token and each call to
-*os\_sem\_release* adds exactly one token.
-
-Data structures
-----------------
-
-.. code:: c
-
- struct os_sem
- {
- SLIST_HEAD(, os_task) sem_head; /* chain of waiting tasks */
- uint16_t _pad;
- uint16_t sem_tokens; /* # of tokens */
- };
-
-+---------------+-----------------------------------------------------+
-| Element | Description |
-+===============+=====================================================+
-| sem\_head | Queue head for list of tasks waiting on semaphore |
-+---------------+-----------------------------------------------------+
-| \_pad | Padding for alignment |
-+---------------+-----------------------------------------------------+
-| sem\_tokens | Current number of tokens |
-+---------------+-----------------------------------------------------+
+:c:func:`os_sem_pend()` subtracts exactly one token and each call to
+:c:func:`os_sem_release()` adds exactly one token.
API
----
.. doxygengroup:: OSSem
:content-only:
+ :members:
diff --git a/docs/os/core_os/task/task.rst b/docs/os/core_os/task/task.rst
index 2a3498444..01cf85a06 100644
--- a/docs/os/core_os/task/task.rst
+++ b/docs/os/core_os/task/task.rst
@@ -37,7 +37,7 @@ stack size can be a bit tricky; generally developers should not declare
large local variables on the stack so that task stacks can be of limited
size. However, all applications are different and the developer must
choose the stack size accordingly. NOTE: be careful when declaring your
-stack! The stack is in units of ``os_stack_t`` sized elements (generally
+stack! The stack is in units of :c:type:`os_stack_t` sized elements (generally
32-bits). Looking at the example given below and assuming ``os_stack_t``
is defined to be a 32-bit unsigned value, "my_task_stack" will use 256
bytes.
@@ -107,3 +107,11 @@ task. This task simply toggles an LED at a one second interval.
}
/* main never returns */
}
+
+
+API
+----
+
+.. doxygengroup:: OSTask
+ :content-only:
+ :members:
diff --git a/docs/os/core_os/time/os_time.rst b/docs/os/core_os/time/os_time.rst
index 8a4e24907..831d41c27 100644
--- a/docs/os/core_os/time/os_time.rst
+++ b/docs/os/core_os/time/os_time.rst
@@ -68,7 +68,7 @@ Functions
Function Description
=============================== ====================
:c:func:`os_time_advance()` Increments the OS time tick for the system.
-:c:func:`os_time_delay()` Put the current task to sleep for the given number of ticks.
+:c:func:`os_time_delay()` Put the current task to sleep for the given number of ticks.
:c:func:`os_time_get()` Get the current value of OS time.
:c:func:`os_time_ms_to_ticks()` Converts milliseconds to os ticks.
:c:func:`os_get_uptime_usec()` Gets the time duration since boot.
@@ -117,3 +117,11 @@ the OS time epoch is 49.7 days.
If two times are more than 1/2 the OS time epoch apart, any time
comparison will be incorrect. Ensure at design time that comparisons
will not occur between times that are more than half the OS time epoch.
+
+
+API
+-----
+
+.. doxygengroup:: OSTime
+ :content-only:
+ :members:
diff --git a/docs/os/modules/hal/hal.rst b/docs/os/modules/hal/hal.rst
index a1cb41940..201b7d51d 100644
--- a/docs/os/modules/hal/hal.rst
+++ b/docs/os/modules/hal/hal.rst
@@ -1,6 +1,19 @@
Hardware Abstraction Layer
==========================
+.. toctree::
+ :hidden:
+
+ hal_timer/hal_timer
+ hal_gpio/hal_gpio
+ hal_uart/hal_uart
+ hal_spi/hal_spi
+ hal_i2c/hal_i2c
+ hal_flash/hal_flash
+ hal_system/hal_system
+ hal_watchdog/hal_watchdog
+ hal_bsp/hal_bsp
+
Description
~~~~~~~~~~~
diff --git a/docs/os/modules/hal/hal_api.rst b/docs/os/modules/hal/hal_api.rst
deleted file mode 100644
index 1214f6e0e..000000000
--- a/docs/os/modules/hal/hal_api.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-HAL Interfaces
-==============
-
-The HAL supports separate interfaces for many peripherals. A brief
-description of the interfaces are shown below.
-
-+-----------------+-------------------------+---------------------+
-| **Hal Name** | \*\* Interface File | **Description ** |
-| | \*\* | |
-+=================+=========================+=====================+
-| `bsp <hal_bsp/h | `hal\_bsp.h <https://gi | An hardware |
-| al_bsp.html>`__ | thub.com/apache/incubat | independent |
-| | or-mynewt-core/blob/dev | interface to |
-| | elop/hw/hal/include/hal | identify and access |
-| | /hal_bsp.h>`__ | underlying BSP. |
-+-----------------+-------------------------+---------------------+
-| `flash api for | `hal\_flash.h <https:// | A blocking |
-| apps to | github.com/apache/incub | interface to access |
-| use <hal_flash/ | ator-mynewt-core/blob/d | flash memory. |
-| hal_flash.html>`_ | evelop/hw/hal/include/h | |
-| _ | al/hal_flash.h>`__ | |
-+-----------------+-------------------------+---------------------+
-| `flash api for | `flash\_map.h <https:// | An interface to |
-| drivers to | github.com/apache/incub | query information |
-| implement <hal_ | ator-mynewt-core/blob/d | about the flash map |
-| flash/hal_flash | evelop/hw/hal/include/h | (regions and |
-| _int.html>`__ | al/hal_flash_int.h>`__ | sectors) |
-+-----------------+-------------------------+---------------------+
-| `gpio <hal_gpio | `hal\_gpio.h <https://g | An interface for |
-| /hal_gpio.html>`_ | ithub.com/apache/incuba | manipulating |
-| _ | tor-mynewt-core/blob/de | General Purpose |
-| | velop/hw/hal/include/ha | Inputs and Outputs. |
-| | l/hal_gpio.h>`__ | |
-+-----------------+-------------------------+---------------------+
-| `i2c <hal_i2c/h | `hal\_i2c.h <https://gi | An interface for |
-| al_i2c.html>`__ | thub.com/apache/incubat | controlling |
-| | or-mynewt-core/blob/dev | Inter-Integrated-Ci |
-| | elop/hw/hal/include/hal | rcuit |
-| | /hal_i2c.h>`__ | (i2c) devices. |
-+-----------------+-------------------------+---------------------+
-| `OS | `hal\_os\_tick.h <https | An interface to set |
-| tick <hal_os_ti | ://github.com/apache/in | up interrupt timers |
-| ck/hal_os_tick. | cubator-mynewt-core/blo | or halt CPU in |
-| md>`__ | b/develop/hw/hal/includ | terms of OS ticks. |
-| | e/hal/hal_os_tick.h>`__ | |
-+-----------------+-------------------------+---------------------+
-| `spi <hal_spi/h | `hal\_spi.h <https://gi | An interface for |
-| al_spi.html>`__ | thub.com/apache/incubat | controlling Serial |
-| | or-mynewt-core/blob/dev | Peripheral |
-| | elop/hw/hal/include/hal | Interface (SPI) |
-| | /hal_spi.h>`__ | devices. |
-+-----------------+-------------------------+---------------------+
-| `system <hal_sy | `hal\_system.h <https:/ | An interface for |
-| stem/hal_sys.md | /github.com/apache/incu | starting and |
-| >`__ | bator-mynewt-core/blob/ | resetting the |
-| | develop/hw/hal/include/ | system. |
-| | hal/hal_system.h>`__ | |
-+-----------------+-------------------------+---------------------+
-| `timer <hal_tim | `hal\_cputime.h <https: | An interface for |
-| er/hal_timer.md | //github.com/apache/inc | configuring and |
-| >`__ | ubator-mynewt-core/tree | running HW timers |
-| | /develop/hw/hal/include | |
-| | /hal/hal_timer.h>`__ | |
-+-----------------+-------------------------+---------------------+
-| `uart <hal_uart | `hal\_uart.h <https://g | An interface for |
-| /hal_uart.html>`_ | ithub.com/apache/incuba | communicating via |
-| _ | tor-mynewt-core/blob/de | asynchronous serial |
-| | velop/hw/hal/include/ha | interface. |
-| | l/hal_uart.h>`__ | |
-+-----------------+-------------------------+---------------------+
-| `watchdog <hal_ | `hal\_watchdog.h <https | An interface for |
-| watchdog/hal_wa | ://github.com/apache/in | enabling internal |
-| tchdog.html>`__ | cubator-mynewt-core/blo | hardware watchdogs. |
-| | b/develop/hw/hal/includ | |
-| | e/hal/hal_watchdog.h>`_ | |
-| | _ | |
-+-----------------+-------------------------+---------------------+
diff --git a/docs/os/modules/hal/hal_bsp/hal_bsp.rst b/docs/os/modules/hal/hal_bsp/hal_bsp.rst
index ae9872bf2..16d573d34 100644
--- a/docs/os/modules/hal/hal_bsp/hal_bsp.rst
+++ b/docs/os/modules/hal/hal_bsp/hal_bsp.rst
@@ -1,4 +1,4 @@
-hal\_bsp
+BSP
========
This is the hardware independent BSP (Board Support Package) Interface
@@ -10,12 +10,9 @@ Description
Contains the basic operations to initialize, specify memory to include
in coredump, configure interrupt priority etc.
-Definition
+API
~~~~~~~~~~
-`hal\_bsp.h <https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_bsp.h>`__
-
-Examples
-~~~~~~~~
-
---------------
+.. doxygengroup:: HALBsp
+ :content-only:
+ :members:
diff --git a/docs/os/modules/hal/hal_flash/hal_flash.rst b/docs/os/modules/hal/hal_flash/hal_flash.rst
index 0ca447472..c9b24c44d 100644
--- a/docs/os/modules/hal/hal_flash/hal_flash.rst
+++ b/docs/os/modules/hal/hal_flash/hal_flash.rst
@@ -1,4 +1,4 @@
-hal\_flash
+Flash
==========
The hardware independent interface to flash memory that is used by
@@ -10,10 +10,9 @@ Description
The API offers basic initialization, read, write, erase, sector erase,
and other operations.
-Definition
+API
~~~~~~~~~~
-`hal\_flash.h <https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_flash.h>`__
-
-Examples
-~~~~~~~~
+.. doxygengroup:: HALFlash
+ :content-only:
+ :members:
diff --git a/docs/os/modules/hal/hal_gpio/hal_gpio.rst b/docs/os/modules/hal/hal_gpio/hal_gpio.rst
index b3d000906..22050c2bd 100644
--- a/docs/os/modules/hal/hal_gpio/hal_gpio.rst
+++ b/docs/os/modules/hal/hal_gpio/hal_gpio.rst
@@ -1,4 +1,4 @@
-hal\_gpio
+GPIO
=========
This is the hardware independent GPIO (General Purpose Input Output)
@@ -54,21 +54,11 @@ Said another way, in this specific system we get
SYSTEM_LED --> hal_gpio virtual pin 37 --> port C pin 5 on the stm34F4xx
-Definition
+API
~~~~~~~~~~
-`hal\_gpio.h <https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_gpio.h>`__
+.. doxygengroup:: HALGpio
+ :content-only:
+ :members:
-Examples
-~~~~~~~~
-Blinky
-^^^^^^
-
-Blinky uses the hal\_gpio to blink the system LED. The blinky source
-code is available in the `blinky
-repo <https://github.com/apache/incubator-mynewt-blinky/blob/master/apps/blinky/src/main.c>`__.
-Examine how ``blinky_task_handler`` initializes and toggles the GPIO to
-control the LED.
-
---------------
diff --git a/docs/os/modules/hal/hal_i2c/hal_i2c.rst b/docs/os/modules/hal/hal_i2c/hal_i2c.rst
index 2635195ef..d6c2e1b39 100644
--- a/docs/os/modules/hal/hal_i2c/hal_i2c.rst
+++ b/docs/os/modules/hal/hal_i2c/hal_i2c.rst
@@ -1,4 +1,4 @@
-hal\_i2c
+I2C
========
The hardware independent interface to I2C Devices.
@@ -16,11 +16,6 @@ I2C is often though of as a 2-wire protocol because it uses two wires
For a detailed description of I2C, see the `I?C wikipedia
page <https://en.wikipedia.org/wiki/I?C>`__
-Definition
-~~~~~~~~~~
-
-`hal\_i2c.h <https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_i2c.h>`__
-
HAL\_I2C Theory Of Operation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -94,3 +89,11 @@ In the HAL\_I2C API you would communicate with this device with address
``0b1000110``, which is hex 0x46 or decimal 70. The I?C drive would add
the R/W bit and transmit it as hex 0x8C (binary 10001100) or 0x8D
(binary 10001101) depending whether it was a read or write command.
+
+
+API
+~~~~~~~~~~
+
+.. doxygengroup:: HALI2c
+ :content-only:
+ :members:
diff --git a/docs/os/modules/hal/hal_os_tick/hal_os_tick.rst b/docs/os/modules/hal/hal_os_tick/hal_os_tick.rst
index 343b9b88e..14c8e0c96 100644
--- a/docs/os/modules/hal/hal_os_tick/hal_os_tick.rst
+++ b/docs/os/modules/hal/hal_os_tick/hal_os_tick.rst
@@ -1,4 +1,4 @@
-hal\_os\_tick
+OS Tick
=============
The hardware independent interface to set up interrupt timers or halt
@@ -24,15 +24,11 @@ You can halt CPU for up to ``n`` ticks:
The function implementations are in the mcu-specific directories such as
``hw/mcu/nordic/nrf51xxx/src/hal_os_tick.c``.
-Definition
+API
~~~~~~~~~~
-`hal\_os\_tick.h <https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_os_tick.h>`__
+.. doxygengroup:: HALOsTick
+ :content-only:
+ :members:
-Examples
-~~~~~~~~
-An example of the API being used by the OS kernel for the Cortex M0
-architecture to initialize and start the system clock timer can be seen
-in
-`kernel/os/src/arch/cortex\_m0/os\_arch\_arm.c <https://github.com/apache/incubator-mynewt-core/blob/master/kernel/os/src/arch/cortex_m0/os_arch_arm.c>`__.
diff --git a/docs/os/modules/hal/hal_spi/hal_spi.rst b/docs/os/modules/hal/hal_spi/hal_spi.rst
index f17bd6b0c..8837134f0 100644
--- a/docs/os/modules/hal/hal_spi/hal_spi.rst
+++ b/docs/os/modules/hal/hal_spi/hal_spi.rst
@@ -1,4 +1,4 @@
-hal\_spi
+SPI
========
SPI (Serial Peripheral Interface) is a synchronous 4-wire serial
@@ -14,12 +14,8 @@ The Mynewt HAL interface supports the SPI master functionality with both
blocking and non-blocking interface. SPI slave functionality is
supported in non-blocking mode.
-Definition
-~~~~~~~~~~
-
-`hal\_spi.h <https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_spi.h>`__
-HAL\_SPI Theory Of Operation
+Theory Of Operation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
SPI is called a 4-wire interface because of the 4 signals, MISO, MOSI,
@@ -63,3 +59,12 @@ The SPI settings consist of the following:
The Mynewt SPI HAL does not include built-in SS (Slave Select)
signaling. It's up to the hal\_spi user to control their own SS pins.
Typically applications will do this with GPIO.
+
+API
+~~~~~~~~~~
+
+.. doxygengroup:: HALSpi
+ :content-only:
+ :members:
+
+
diff --git a/docs/os/modules/hal/hal_system/hal_sys.rst b/docs/os/modules/hal/hal_system/hal_sys.rst
index d0f7d2ad0..d16303bfa 100644
--- a/docs/os/modules/hal/hal_system/hal_sys.rst
+++ b/docs/os/modules/hal/hal_system/hal_sys.rst
@@ -1,4 +1,4 @@
-hal\_system
+System
===========
A hardware independent interface for starting and resetting the system.
@@ -13,10 +13,10 @@ implemented in the MCU specific directories e.g. ``hal_reset_cause.c``,
``/hw/mcu/nordic/nrf52xxx/src/`` directory for Nordic nRF52 series of
chips.
-Definition
+API
~~~~~~~~~~
-`hal\_system.h <https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_system.h>`__
+.. doxygengroup:: HALSystem
+ :content-only:
+ :members:
-Examples
-~~~~~~~~
diff --git a/docs/os/modules/hal/hal_timer/hal_timer.rst b/docs/os/modules/hal/hal_timer/hal_timer.rst
index a3b7a0fb9..4fc166785 100644
--- a/docs/os/modules/hal/hal_timer/hal_timer.rst
+++ b/docs/os/modules/hal/hal_timer/hal_timer.rst
@@ -1,4 +1,4 @@
-hal\_timer
+Timer
==========
The hardware independent timer structure and API to configure,
@@ -27,10 +27,9 @@ structure; the hal timer API should be used.
TAILQ_ENTRY(hal_timer) link; /* Queue linked list structure */
};
-Definition
-~~~~~~~~~~
-
-`hal\_timer.h <https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_timer.h>`__
-
-Examples
+API
~~~~~~~~
+
+.. doxygengroup:: HALTimer
+ :content-only:
+ :members:
diff --git a/docs/os/modules/hal/hal_uart/hal_uart.rst b/docs/os/modules/hal/hal_uart/hal_uart.rst
index 1f490d8a7..3ebcd02c8 100644
--- a/docs/os/modules/hal/hal_uart/hal_uart.rst
+++ b/docs/os/modules/hal/hal_uart/hal_uart.rst
@@ -1,4 +1,4 @@
-hal\_uart
+UART
=========
The hardware independent UART interface for Mynewt.
@@ -11,11 +11,6 @@ Contains the basic operations to send and receive data over a UART
to apply settings such as speed, parity etc. to the UART. The UART port
should be closed before any reconfiguring.
-Definition
-~~~~~~~~~~
-
-`hal\_uart.h <https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_uart.h>`__
-
Examples
~~~~~~~~
@@ -34,3 +29,12 @@ mode where the UART has to block until character has been sent.
}
hal_uart_blocking_tx(MY_UART, '\n');
}
+
+API
+~~~~
+
+.. doxygengroup:: HALUart
+ :content-only:
+ :members:
+
+
diff --git a/docs/os/modules/hal/hal_watchdog/hal_watchdog.rst b/docs/os/modules/hal/hal_watchdog/hal_watchdog.rst
index d96359c75..241c90c75 100644
--- a/docs/os/modules/hal/hal_watchdog/hal_watchdog.rst
+++ b/docs/os/modules/hal/hal_watchdog/hal_watchdog.rst
@@ -1,4 +1,4 @@
-hal\_watchdog
+Watchdog
=============
The hardware independent interface to enable internal hardware
@@ -18,15 +18,9 @@ Watchdog needs to be then started with a call to
``hal_watchdog_enable()``. Watchdog should be tickled periodically with
a frequency smaller than 'expire\_secs' using ``hal_watchdog_tickle()``.
-Definition
-~~~~~~~~~~
-
-`hal\_watchdog <https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_watchdog.h>`__
-
-Examples
+API
~~~~~~~~
-The OS initializes and starts a watchdog timer and tickles it
-periodically to check that the OS is running properly. This can be seen
-in
-`/kernel/os/src/os.c <https://github.com/apache/incubator-mynewt-core/blob/master/kernel/os/src/os.c>`__.
+.. doxygengroup:: HALWatchdog
+ :content-only:
+ :members:
diff --git a/docs/os/os_user_guide.rst b/docs/os/os_user_guide.rst
index 57556fe51..66e3c9066 100644
--- a/docs/os/os_user_guide.rst
+++ b/docs/os/os_user_guide.rst
@@ -4,10 +4,11 @@ OS User Guide
.. toctree::
:hidden:
- OS Core <core_os/mynewt_os>
- core_os/porting/port_os
- modules/console/console
- modules/sysinitconfig/sysinitconfig
+ Kernel <core_os/mynewt_os>
+ Hardware Abstraction <modules/hal/hal>
+ Porting Guide <core_os/porting/port_os>
+ System Configuration <modules/sysinitconfig/sysinitconfig>
+ Console <modules/console/console>
This guide provides comprehensive information about Mynewt OS, the
real-time operating system for embedded systems. It is intended both for
diff --git a/hw/hal/include/hal/hal_bsp.h b/hw/hal/include/hal/hal_bsp.h
index 8b52f271b..0e3269d68 100644
--- a/hw/hal/include/hal/hal_bsp.h
+++ b/hw/hal/include/hal/hal_bsp.h
@@ -17,6 +17,14 @@
* under the License.
*/
+
+/**
+ * @addtogroup HAL
+ * @{
+ * @defgroup HALBsp HAL BSP
+ * @{
+ */
+
#ifndef __HAL_BSP_H_
#define __HAL_BSP_H_
@@ -26,12 +34,12 @@ extern "C" {
#include <inttypes.h>
-/*
+/**
* Initializes BSP; registers flash_map with the system.
*/
void hal_bsp_init(void);
-/*
+/**
* Return pointer to flash device structure, given BSP specific
* flash id.
*/
@@ -43,33 +51,67 @@ const struct hal_flash *hal_bsp_flash_dev(uint8_t flash_id);
*/
void *_sbrk(int incr);
-/*
- * Report which memory areas should be included inside a coredump.
- */
struct hal_bsp_mem_dump {
void *hbmd_start;
uint32_t hbmd_size;
};
+/**
+ * Report which memory areas should be included inside a coredump.
+ */
const struct hal_bsp_mem_dump *hal_bsp_core_dump(int *area_cnt);
-/*
+#define HAL_BSP_MAX_ID_LEN 32
+/**
* Get unique HW identifier/serial number for platform.
* Returns the number of bytes filled in.
+ *
+ * @param id Pointer to the ID to fill out
+ * @param max_len Maximum length to fill into the ID
+ *
+ * @return 0 on success, non-zero error code on failure
*/
-#define HAL_BSP_MAX_ID_LEN 32
int hal_bsp_hw_id(uint8_t *id, int max_len);
+/** Full System On */
#define HAL_BSP_POWER_ON (1)
+/** Wait for Interrupt: CPU off */
#define HAL_BSP_POWER_WFI (2)
+/** System sleep mode, processor off, some peripherals off too */
#define HAL_BSP_POWER_SLEEP (3)
+/**
+ * Deep sleep: possible loss of RAM retention, system wakes up in
+ * undefined state.
+ */
#define HAL_BSP_POWER_DEEP_SLEEP (4)
+/**
+ * System powering off
+ */
#define HAL_BSP_POWER_OFF (5)
+/**
+ * Per-user power state, base number for user to define custom power states.
+ */
#define HAL_BSP_POWER_PERUSER (128)
+/**
+ * Move the system into the specified power state
+ *
+ * @param state The power state to move the system into, this is one of
+ * * HAL_BSP_POWER_ON: Full system on
+ * * HAL_BSP_POWER_WFI: Processor off, wait for interrupt.
+ * * HAL_BSP_POWER_SLEEP: Put the system to sleep
+ * * HAL_BSP_POWER_DEEP_SLEEP: Put the system into deep sleep.
+ * * HAL_BSP_POWER_OFF: Turn off the system.
+ * * HAL_BSP_POWER_PERUSER: From this value on, allow user
+ * defined power states.
+ *
+ * @return 0 on success, non-zero if system cannot move into this power state.
+ */
int hal_bsp_power_state(int state);
-/* Returns priority of given interrupt number */
+/**
+ * Returns priority of given interrupt number
+ */
uint32_t hal_bsp_get_nvic_priority(int irq_num, uint32_t pri);
#ifdef __cplusplus
@@ -77,3 +119,9 @@ uint32_t hal_bsp_get_nvic_priority(int irq_num, uint32_t pri);
#endif
#endif
+
+
+/**
+ * @} HALBsp
+ * @} HAL
+ */
diff --git a/hw/hal/include/hal/hal_flash.h b/hw/hal/include/hal/hal_flash.h
index 11f5f1df4..ccef6e272 100644
--- a/hw/hal/include/hal/hal_flash.h
+++ b/hw/hal/include/hal/hal_flash.h
@@ -17,6 +17,13 @@
* under the License.
*/
+/**
+ * @addtogroup HAL
+ * @{
+ * @defgroup HALFlash HAL Flash
+ * @{
+ */
+
#ifndef H_HAL_FLASH_
#define H_HAL_FLASH_
@@ -41,3 +48,8 @@ int hal_flash_init(void);
#endif
#endif /* H_HAL_FLASH_ */
+
+/**
+ * @} HALFlash
+ * @} HAL
+ */
diff --git a/hw/hal/include/hal/hal_gpio.h b/hw/hal/include/hal/hal_gpio.h
index d83aca2f4..0555c1769 100644
--- a/hw/hal/include/hal/hal_gpio.h
+++ b/hw/hal/include/hal/hal_gpio.h
@@ -17,6 +17,14 @@
* under the License.
*/
+
+/**
+ * @addtogroup HAL
+ * @{
+ * @defgroup HALGpio HAL GPIO
+ * @{
+ */
+
#ifndef H_HAL_GPIO_
#define H_HAL_GPIO_
@@ -24,13 +32,16 @@
extern "C" {
#endif
-/*
+/**
* The "mode" of the gpio. The gpio is either an input, output, or it is
* "not connected" (the pin specified is not functioning as a gpio)
*/
enum hal_gpio_mode_e {
+ /** Not connected */
HAL_GPIO_MODE_NC = -1,
+ /** Input */
HAL_GPIO_MODE_IN = 0,
+ /** Output */
HAL_GPIO_MODE_OUT = 1
};
typedef enum hal_gpio_mode_e hal_gpio_mode_t;
@@ -39,9 +50,12 @@ typedef enum hal_gpio_mode_e hal_gpio_mode_t;
* The "pull" of the gpio. This is either an input or an output.
*/
enum hal_gpio_pull {
- HAL_GPIO_PULL_NONE = 0, /* pull-up/down not enabled */
- HAL_GPIO_PULL_UP = 1, /* pull-up enabled */
- HAL_GPIO_PULL_DOWN = 2 /* pull-down enabled */
+ /** Pull-up/down not enabled */
+ HAL_GPIO_PULL_NONE = 0,
+ /** Pull-up enabled */
+ HAL_GPIO_PULL_UP = 1,
+ /** Pull-down enabled */
+ HAL_GPIO_PULL_DOWN = 2
};
typedef enum hal_gpio_pull hal_gpio_pull_t;
@@ -50,11 +64,16 @@ typedef enum hal_gpio_pull hal_gpio_pull_t;
*/
enum hal_gpio_irq_trigger {
HAL_GPIO_TRIG_NONE = 0,
- HAL_GPIO_TRIG_RISING = 1, /* IRQ occurs on rising edge */
- HAL_GPIO_TRIG_FALLING = 2, /* IRQ occurs on falling edge */
- HAL_GPIO_TRIG_BOTH = 3, /* IRQ occurs on either edge */
- HAL_GPIO_TRIG_LOW = 4, /* IRQ occurs when line is low */
- HAL_GPIO_TRIG_HIGH = 5 /* IRQ occurs when line is high */
+ /** IRQ occurs on rising edge */
+ HAL_GPIO_TRIG_RISING = 1,
+ /** IRQ occurs on falling edge */
+ HAL_GPIO_TRIG_FALLING = 2,
+ /** IRQ occurs on either edge */
+ HAL_GPIO_TRIG_BOTH = 3,
+ /** IRQ occurs when line is low */
+ HAL_GPIO_TRIG_LOW = 4,
+ /** IRQ occurs when line is high */
+ HAL_GPIO_TRIG_HIGH = 5
};
typedef enum hal_gpio_irq_trigger hal_gpio_irq_trig_t;
@@ -62,8 +81,6 @@ typedef enum hal_gpio_irq_trigger hal_gpio_irq_trig_t;
typedef void (*hal_gpio_irq_handler_t)(void *arg);
/**
- * gpio init in
- *
* Initializes the specified pin as an input
*
* @param pin Pin number to set as input
@@ -74,8 +91,6 @@ typedef void (*hal_gpio_irq_handler_t)(void *arg);
int hal_gpio_init_in(int pin, hal_gpio_pull_t pull);
/**
- * gpio init out
- *
* Initialize the specified pin as an output, setting the pin to the specified
* value.
*
@@ -87,8 +102,6 @@ int hal_gpio_init_in(int pin, hal_gpio_pull_t pull);
int hal_gpio_init_out(int pin, int val);
/**
- * gpio write
- *
* Write a value (either high or low) to the specified pin.
*
* @param pin Pin to set
@@ -97,11 +110,8 @@ int hal_gpio_init_out(int pin, int val);
void hal_gpio_write(int pin, int val);
/**
- * gpio read
- *
* Reads the specified pin.
*
- *
* @param pin Pin number to read
*
* @return int 0: low, 1: high
@@ -109,8 +119,6 @@ void hal_gpio_write(int pin, int val);
int hal_gpio_read(int pin);
/**
- * gpio toggle
- *
* Toggles the specified pin
*
* @param pin Pin number to toggle
@@ -119,10 +127,39 @@ int hal_gpio_read(int pin);
*/
int hal_gpio_toggle(int pin);
+/**
+ * Initialize a given pin to trigger a GPIO IRQ callback.
+ *
+ * @param pin The pin to trigger GPIO interrupt on
+ * @param handler The handler function to call
+ * @param arg The argument to provide to the IRQ handler
+ * @param trig The trigger mode (e.g. rising, falling)
+ * @param pull The mode of the pin (e.g. pullup, pulldown)
+ *
+ * @return 0 on success, non-zero error code on failure.
+ */
int hal_gpio_irq_init(int pin, hal_gpio_irq_handler_t handler, void *arg,
hal_gpio_irq_trig_t trig, hal_gpio_pull_t pull);
+
+/**
+ * Release a pin from being configured to trigger IRQ on state change.
+ *
+ * @param pin The pin to release
+ */
void hal_gpio_irq_release(int pin);
+
+/**
+ * Enable IRQs on the passed pin
+ *
+ * @param pin The pin to enable IRQs on
+ */
void hal_gpio_irq_enable(int pin);
+
+/**
+ * Disable IRQs on the passed pin
+ *
+ * @param pin The pin to disable IRQs on
+ */
void hal_gpio_irq_disable(int pin);
@@ -131,3 +168,8 @@ void hal_gpio_irq_disable(int pin);
#endif
#endif /* H_HAL_GPIO_ */
+
+/**
+ * @} HALGpio
+ * @} HAL
+ */
diff --git a/hw/hal/include/hal/hal_i2c.h b/hw/hal/include/hal/hal_i2c.h
index ecbf7221a..22f8f8e1e 100644
--- a/hw/hal/include/hal/hal_i2c.h
+++ b/hw/hal/include/hal/hal_i2c.h
@@ -17,6 +17,14 @@
* under the License.
*/
+
+/**
+ * @addtogroup HAL
+ * @{
+ * @defgroup HALI2c HAL I2c
+ * @{
+ */
+
#ifndef H_HAL_I2C_
#define H_HAL_I2C_
@@ -35,11 +43,11 @@ extern "C" {
* Typical usage of this API is as follows:
*
* Initialize an i2c device with:
- * hal_i2c_init()
+ * :c:func:`hal_i2c_init()`
*
* When you wish to perform an i2c transaction, you call one or both of:
- * hal_i2c_master_write();
- * hal_i2c_master_read();
+ * :c:func:`hal_i2c_master_write()`;
+ * :c:func:`hal_i2c_master_read()`;
*
* These functions will issue a START condition, followed by the device's
* 7-bit I2C address, and then send or receive the payload based on the data
@@ -50,25 +58,30 @@ extern "C" {
*
* For example, in an I2C memory access you might write a register address and
* then read data back via:
- * hal_i2c_write(); -- write to a specific register on the device
- * hal_i2c_read(); --- read back data, setting 'last_op' to '1'
+ * :c:func:`hal_i2c_write()`; -- write to a specific register on the device
+ * :c:func:`hal_i2c_read()`; --- read back data, setting 'last_op' to '1'
*/
/**
- * when sending a packet, use this structure to pass the arguments.
+ * When sending a packet, use this structure to pass the arguments.
*/
struct hal_i2c_master_data {
- uint8_t address; /* destination address */
- /* An I2C address has 7 bits. In the protocol these
- * 7 bits are combined with a 1 bit R/W bit to specify read
- * or write operation in an 8-bit address field sent to
- * the remote device. This API accepts the 7-bit
- * address as its argument in the 7 LSBs of the
- * address field above. For example if I2C was
- * writing a 0x81 in its protocol, you would pass
- * only the top 7-bits to this function as 0x40 */
- uint16_t len; /* number of buffer bytes to transmit or receive */
- uint8_t *buffer; /* buffer space to hold the transmit or receive */
+ /**
+ * Destination address
+ * An I2C address has 7 bits. In the protocol these
+ * 7 bits are combined with a 1 bit R/W bit to specify read
+ * or write operation in an 8-bit address field sent to
+ * the remote device. This API accepts the 7-bit
+ * address as its argument in the 7 LSBs of the
+ * address field above. For example if I2C was
+ * writing a 0x81 in its protocol, you would pass
+ * only the top 7-bits to this function as 0x40
+ */
+ uint8_t address
+ /** Number of buffer bytes to transmit or receive */;
+ uint16_t len;
+ /** Buffer space to hold the transmit or receive */
+ uint8_t *buffer;
};
/**
@@ -137,3 +150,9 @@ int hal_i2c_master_probe(uint8_t i2c_num, uint8_t address,
#endif
#endif /* H_HAL_I2C_ */
+
+
+/**
+ * @} HALI2c
+ * @} HAL
+ */
diff --git a/hw/hal/include/hal/hal_os_tick.h b/hw/hal/include/hal/hal_os_tick.h
index d67e217cd..e981bacb5 100644
--- a/hw/hal/include/hal/hal_os_tick.h
+++ b/hw/hal/include/hal/hal_os_tick.h
@@ -16,6 +16,14 @@
* specific language governing permissions and limitations
* under the License.
*/
+
+/**
+ * @addtogroup HAL
+ * @{
+ * @defgroup HALOsTick HAL OS Tick
+ * @{
+ */
+
#ifndef H_HAL_OS_TICK_
#define H_HAL_OS_TICK_
@@ -25,14 +33,19 @@ extern "C" {
#include <os/os_time.h>
-/*
+/**
* Set up the periodic timer to interrupt at a frequency of 'os_ticks_per_sec'.
* 'prio' is the cpu-specific priority of the periodic timer interrupt.
+ *
+ * @param os_ticks_per_sec Frequency of the OS tick timer
+ * @param prio Priority of the OS tick timer
*/
void os_tick_init(uint32_t os_ticks_per_sec, int prio);
-/*
+/**
* Halt CPU for up to 'n' ticks.
+ *
+ * @param n The number of ticks to halt the CPU for
*/
void os_tick_idle(os_time_t n);
@@ -42,3 +55,8 @@ void os_tick_idle(os_time_t n);
#endif
#endif /* H_HAL_OS_TICK_ */
+
+/**
+ * @} HALOsTick
+ * @} HAL
+ */
diff --git a/hw/hal/include/hal/hal_spi.h b/hw/hal/include/hal/hal_spi.h
index d987e3d0d..092cbf706 100644
--- a/hw/hal/include/hal/hal_spi.h
+++ b/hw/hal/include/hal/hal_spi.h
@@ -16,6 +16,14 @@
* specific language governing permissions and limitations
* under the License.
*/
+
+/**
+ * @addtogroup HAL
+ * @{
+ * @defgroup HALSpi HAL SPI
+ * @{
+ */
+
#ifndef H_HAL_SPI_
#define H_HAL_SPI_
@@ -25,22 +33,28 @@ extern "C" {
#include <inttypes.h>
-/* SPI type */
+/* SPI Type of Master */
#define HAL_SPI_TYPE_MASTER (0)
+/* SPI Type of Slave */
#define HAL_SPI_TYPE_SLAVE (1)
-/* SPI modes */
+/** SPI mode 0 */
#define HAL_SPI_MODE0 (0)
+/** SPI mode 1 */
#define HAL_SPI_MODE1 (1)
+/** SPI mode 2 */
#define HAL_SPI_MODE2 (2)
+/** SPI mode 3 */
#define HAL_SPI_MODE3 (3)
-/* SPI data order */
+/** SPI data order, most significant bit first */
#define HAL_SPI_MSB_FIRST (0)
+/** SPI data order, least significant bit first */
#define HAL_SPI_LSB_FIRST (1)
-/* SPI word size */
+/** SPI word size 8 bit */
#define HAL_SPI_WORD_SIZE_8BIT (0)
+/** SPI word size 9 bit */
#define HAL_SPI_WORD_SIZE_9BIT (1)
/* Prototype for tx/rx callback */
@@ -51,10 +65,14 @@ typedef void (*hal_spi_txrx_cb)(void *arg, int len);
* can be changed on the fly from the hal
*/
struct hal_spi_settings {
+ /** Data mode of SPI driver, defined by HAL_SPI_MODEn */
uint8_t data_mode;
+ /** Data order, either HAL_SPI_MSB_FIRST or HAL_SPI_LSB_FIRST */
uint8_t data_order;
+ /** The word size of the SPI transaction, either 8-bit or 9-bit */
uint8_t word_size;
- uint32_t baudrate; /* baudrate in kHz */
+ /** Baudrate in kHz */
+ uint32_t baudrate;
};
/**
@@ -216,7 +234,16 @@ int hal_spi_slave_set_def_tx_val(int spi_num, uint16_t val);
*/
int hal_spi_abort(int spi_num);
-/** Utility functions; defined once for all MCUs. */
+/**
+ * Extracts CPOL and CPHA values from a data-mode constant.
+ * Utility function, defined once for every MCU.
+ *
+ * @param data_mode The HAL_SPI_MODE value to convert.
+ * @param out_cpol The CPOL gets written here on success.
+ * @param out_cpha The CPHA gets written here on success.
+ *
+ * @return 0 on success; nonzero on invalid input.
+ */
int hal_spi_data_mode_breakout(uint8_t data_mode,
int *out_cpol, int *out_cpha);
@@ -226,3 +253,8 @@ int hal_spi_data_mode_breakout(uint8_t data_mode,
#endif
#endif /* H_HAL_SPI_ */
+
+/**
+ * @} HALSpi
+ * @} HAL
+ */
diff --git a/hw/hal/include/hal/hal_system.h b/hw/hal/include/hal/hal_system.h
index 4470b3d20..d2b3fffc5 100644
--- a/hw/hal/include/hal/hal_system.h
+++ b/hw/hal/include/hal/hal_system.h
@@ -17,6 +17,14 @@
* under the License.
*/
+
+/**
+ * @addtogroup HAL
+ * @{
+ * @defgroup HALSystem HAL System
+ * @{
+ */
+
#ifndef H_HAL_SYSTEM_
#define H_HAL_SYSTEM_
@@ -24,40 +32,54 @@
extern "C" {
#endif
-/*
+/**
* System reset.
*/
void hal_system_reset(void) __attribute((noreturn));
-/*
+/**
* Called by bootloader to start loaded program.
*/
void hal_system_start(void *img_start) __attribute((noreturn));
-/*
+/**
* Called by split app loader to start the app program.
*/
void hal_system_restart(void *img_start) __attribute((noreturn));
-/*
+/**
* Returns non-zero if there is a HW debugger attached.
*/
int hal_debugger_connected(void);
-/*
+/**
* Reboot reason
*/
enum hal_reset_reason {
- HAL_RESET_POR = 1, /* power on reset */
- HAL_RESET_PIN = 2, /* caused by reset pin */
- HAL_RESET_WATCHDOG = 3, /* watchdog */
- HAL_RESET_SOFT = 4, /* system_reset() or equiv */
- HAL_RESET_BROWNOUT = 5, /* low supply voltage */
- HAL_RESET_REQUESTED = 6, /* restart due to user request */
+ /** Power on Reset */
+ HAL_RESET_POR = 1,
+ /** Caused by Reset Pin */
+ HAL_RESET_PIN = 2,
+ /** Caused by Watchdog */
+ HAL_RESET_WATCHDOG = 3,
+ /** Soft reset, either system reset or crash */
+ HAL_RESET_SOFT = 4,
+ /** Low supply voltage */
+ HAL_RESET_BROWNOUT = 5,
+ /** Restart due to user request */
+ HAL_RESET_REQUESTED = 6,
};
+
+/**
+ * Return the reboot reason
+ *
+ * @return A reboot reason
+ */
enum hal_reset_reason hal_reset_cause(void);
-/* Starts clocks needed by system */
+/**
+ * Starts clocks needed by system
+ */
void hal_system_clock_start(void);
#ifdef __cplusplus
@@ -65,3 +87,8 @@ void hal_system_clock_start(void);
#endif
#endif /* H_HAL_SYSTEM_ */
+
+/**
+ * @} HALSystem
+ * @} HAL
+ */
diff --git a/hw/hal/include/hal/hal_timer.h b/hw/hal/include/hal/hal_timer.h
index 19371308a..1d1d9ba57 100644
--- a/hw/hal/include/hal/hal_timer.h
+++ b/hw/hal/include/hal/hal_timer.h
@@ -17,6 +17,14 @@
* under the License.
*/
+
+/**
+ * @addtogroup HAL
+ * @{
+ * @defgroup HALTimer HAL Timer
+ * @{
+ */
+
#ifndef H_HAL_TIMER_
#define H_HAL_TIMER_
@@ -31,75 +39,139 @@ extern "C" {
#include "os/queue.h"
-/* HAL timer struct */
+/* HAL timer callback */
typedef void (*hal_timer_cb)(void *arg);
/**
* The HAL timer structure. The user can declare as many of these structures
* as desired. They are enqueued on a particular HW timer queue when the user
- * calls the hal_timer_start or hal_timer_start_at API. The user must have
- * called hal_timer_set_cb before starting a timer.
+ * calls the :c:func:`hal_timer_start()` or :c:func:`hal_timer_start_at()` API.
+ * The user must have called :c:func:`hal_timer_set_cb()` before starting a
+ * timer.
*
* NOTE: the user should not have to modify/examine the contents of this
* structure; the hal timer API should be used.
*/
-struct hal_timer
-{
- void *bsp_timer; /* Internal platform specific pointer */
- hal_timer_cb cb_func; /* Callback function */
- void *cb_arg; /* Callback argument */
- uint32_t expiry; /* Tick at which timer should expire */
+struct hal_timer {
+ /** Internal platform specific pointer */
+ void *bsp_timer;
+ /** Callback function */
+ hal_timer_cb cb_func;
+ /** Callback argument */
+ void *cb_arg;
+ /** Tick at which timer should expire */
+ uint32_t expiry;
TAILQ_ENTRY(hal_timer) link; /* Queue linked list structure */
};
-/* Initialize a HW timer. */
+/**
+ * Initialize a HW timer.
+ *
+ * @param timer_num The number of the HW timer to initialize
+ * @param cfg Hardware specific timer configuration. This is
+ * passed from BSP directly to the MCU specific driver.
+ */
int hal_timer_init(int timer_num, void *cfg);
-/* Un-initialize a HW timer. */
+/**
+ * Un-initialize a HW timer.
+ *
+ * @param timer_num The number of the HW timer to un-initialize
+ */
int hal_timer_deinit(int timer_num);
-/*
+/**
* Config a HW timer at the given frequency and start it. If the exact
* frequency is not obtainable the closest obtainable frequency is set.
+ *
+ * @param timer_num The number of the HW timer to configure
+ * @param freq_hz The frequency in Hz to configure the timer at
+ *
+ * @return 0 on success, non-zero error code on failure
*/
int hal_timer_config(int timer_num, uint32_t freq_hz);
-/*
+/**
* Returns the resolution of the HW timer. NOTE: the frequency may not be
* obtainable so the caller can use this to determine the resolution.
* Returns resolution in nanoseconds. A return value of 0 indicates an invalid
* timer was used.
+ *
+ * @param timer_num The number of the HW timer to get resolution for
+ *
+ * @return The resolution of the timer
*/
uint32_t hal_timer_get_resolution(int timer_num);
-/* Returns the HW timer current tick value */
+/**
+ * Returns the HW timer current tick value
+ *
+ * @param timer_num The HW timer to read the tick value from
+ *
+ * @return The current tick value
+ */
uint32_t hal_timer_read(int timer_num);
-/* Perform a blocking delay for a number of ticks. */
+/**
+ * Perform a blocking delay for a number of ticks.
+ *
+ * @param timer_num The timer number to use for the blocking delay
+ * @param ticks The number of ticks to delay for
+ *
+ * @return 0 on success, non-zero error code on failure
+ */
int hal_timer_delay(int timer_num, uint32_t ticks);
-/*
+/**
* Set the timer structure prior to use. Should not be called if the timer
* is running. Must be called at least once prior to using timer.
+ *
+ * @param timer_num The number of the HW timer to configure the callback on
+ * @param tmr The timer structure to use for this timer
+ * @param cb_func The timer callback to call when the timer fires
+ * @param arg An opaque argument to provide the timer callback
+ *
+ * @return 0 on success, non-zero error code on failure.
*/
int hal_timer_set_cb(int timer_num, struct hal_timer *tmr, hal_timer_cb cb_func,
void *arg);
-/* Start a timer that will expire in 'ticks' ticks. Ticks cannot be 0 */
-int hal_timer_start(struct hal_timer *, uint32_t ticks);
+/**
+ * Start a timer that will expire in 'ticks' ticks. Ticks cannot be 0
+ *
+ * @param tmr The timer to start
+ * @param ticks The number of ticks to expire the timer in
+ *
+ * @return 0 on success, non-zero error code on failure.
+ */
+int hal_timer_start(struct hal_timer *tmr, uint32_t ticks);
-/*
+/**
* Start a timer that will expire when the timer reaches 'tick'. If tick
* has already passed the timer callback will be called "immediately" (at
* interrupt context).
+ *
+ * @param tmr The timer to start
+ * @param tick The absolute tick value to fire the timer at
+ *
+ * @return 0 on success, non-zero error code on failure.
*/
-int hal_timer_start_at(struct hal_timer *, uint32_t tick);
+int hal_timer_start_at(struct hal_timer *tmr, uint32_t tick);
-/* Stop a currently running timer; associated callback will NOT be called */
-int hal_timer_stop(struct hal_timer *);
+/**
+ * Stop a currently running timer; associated callback will NOT be called
+ *
+ * @param tmr The timer to stop
+ */
+int hal_timer_stop(struct hal_timer *tmr);
#ifdef __cplusplus
}
#endif
#endif /* H_HAL_TIMER_ */
+
+/**
+ * @} HALTimer
+ * @} HAL
+ */
diff --git a/hw/hal/include/hal/hal_uart.h b/hw/hal/include/hal/hal_uart.h
index bfbcbd96d..6c5282e8b 100644
--- a/hw/hal/include/hal/hal_uart.h
+++ b/hw/hal/include/hal/hal_uart.h
@@ -17,6 +17,14 @@
* under the License.
*/
+
+/**
+ * @addtogroup HAL
+ * @{
+ * @defgroup HALUart HAL UART
+ * @{
+ */
+
#ifndef H_HAL_UART_H_
#define H_HAL_UART_H_
@@ -27,14 +35,14 @@ extern "C" {
#include <inttypes.h>
-/*
+/**
* Function prototype for UART driver to ask for more data to send.
* Returns -1 if no more data is available for TX.
* Driver must call this with interrupts disabled.
*/
typedef int (*hal_uart_tx_char)(void *arg);
-/*
+/**
* Function prototype for UART driver to report that transmission is
* complete. This should be called when transmission of last byte is
* finished.
@@ -42,7 +50,7 @@ typedef int (*hal_uart_tx_char)(void *arg);
*/
typedef void (*hal_uart_tx_done)(void *arg);
-/*
+/**
* Function prototype for UART driver to report incoming byte of data.
* Returns -1 if data was dropped.
* Driver must call this with interrupts disabled.
@@ -50,8 +58,6 @@ typedef void (*hal_uart_tx_done)(void *arg);
typedef int (*hal_uart_rx_char)(void *arg, uint8_t byte);
/**
- * hal uart init cbs
- *
* Initializes given uart. Mapping of logical UART number to physical
* UART/GPIO pins is in BSP.
*/
@@ -59,14 +65,19 @@ int hal_uart_init_cbs(int uart, hal_uart_tx_char tx_func,
hal_uart_tx_done tx_done, hal_uart_rx_char rx_func, void *arg);
enum hal_uart_parity {
- HAL_UART_PARITY_NONE = 0, /* no parity */
- HAL_UART_PARITY_ODD = 1, /* odd parity bit */
- HAL_UART_PARITY_EVEN = 2 /* even parity bit */
+ /** No Parity */
+ HAL_UART_PARITY_NONE = 0,
+ /** Odd parity */
+ HAL_UART_PARITY_ODD = 1,
+ /** Even parity */
+ HAL_UART_PARITY_EVEN = 2
};
enum hal_uart_flow_ctl {
- HAL_UART_FLOW_CTL_NONE = 0, /* no flow control */
- HAL_UART_FLOW_CTL_RTS_CTS = 1 /* RTS/CTS */
+ /** No Flow Control */
+ HAL_UART_FLOW_CTL_NONE = 0,
+ /** RTS/CTS */
+ HAL_UART_FLOW_CTL_RTS_CTS = 1
};
/**
@@ -75,46 +86,58 @@ enum hal_uart_flow_ctl {
* @param uart The uart number to configure
* @param cfg Hardware specific uart configuration. This is passed from BSP
* directly to the MCU specific driver.
+ *
+ * @return 0 on success, non-zero error code on failure
*/
int hal_uart_init(int uart, void *cfg);
/**
- * hal uart config
- *
* Applies given configuration to UART.
+ *
+ * @param uart The UART number to configure
+ * @param speed The baudrate in bps to configure
+ * @param databits The number of databits to send per byte
+ * @param stopbits The number of stop bits to send
+ * @param parity The UART parity
+ * @param flow_ctl Flow control settings on the UART
+ *
+ * @return 0 on success, non-zero error code on failure
*/
int hal_uart_config(int uart, int32_t speed, uint8_t databits, uint8_t stopbits,
enum hal_uart_parity parity, enum hal_uart_flow_ctl flow_ctl);
-/*
+/**
* Close UART port. Can call hal_uart_config() with different settings after
* calling this.
+ *
+ * @param uart The UART number to close
*/
-int hal_uart_close(int port);
+int hal_uart_close(int uart);
/**
- * hal uart start tx
- *
* More data queued for transmission. UART driver will start asking for that
* data.
+ *
+ * @param uart The UART number to start TX on
*/
void hal_uart_start_tx(int uart);
/**
- * hal uart start rx
- *
* Upper layers have consumed some data, and are now ready to receive more.
* This is meaningful after uart_rx_char callback has returned -1 telling
* that no more data can be accepted.
+ *
+ * @param uart The UART number to begin RX on
*/
void hal_uart_start_rx(int uart);
/**
- * hal uart blocking tx
- *
* This is type of write where UART has to block until character has been sent.
* Used when printing diag output from system crash.
* Must be called with interrupts disabled.
+ *
+ * @param uart The UART number to TX on
+ * @param byte The byte to TX on the UART
*/
void hal_uart_blocking_tx(int uart, uint8_t byte);
@@ -124,3 +147,9 @@ void hal_uart_blocking_tx(int uart, uint8_t byte);
#endif /* H_HAL_UART_H_ */
+
+
+/**
+ * @} HALUart
+ * @} HAL
+ */
diff --git a/hw/hal/include/hal/hal_watchdog.h b/hw/hal/include/hal/hal_watchdog.h
index 540269aae..8c946f1b6 100644
--- a/hw/hal/include/hal/hal_watchdog.h
+++ b/hw/hal/include/hal/hal_watchdog.h
@@ -17,6 +17,14 @@
* under the License.
*/
+
+/**
+ * @addtogroup HAL
+ * @{
+ * @defgroup HALWatchdog HAL Watchdog
+ * @{
+ */
+
#ifndef _HAL_WATCHDOG_H_
#define _HAL_WATCHDOG_H_
@@ -25,11 +33,11 @@
extern "C" {
#endif
-/*
+/**
* Set a recurring watchdog timer to fire no sooner than in 'expire_secs'
* seconds. Watchdog should be tickled periodically with a frequency
* smaller than 'expire_secs'. Watchdog needs to be then started with
- * a call to hal_watchdog_enable().
+ * a call to :c:func:`hal_watchdog_enable()`.
*
* @param expire_msecs Watchdog timer expiration time in msecs
*
@@ -38,13 +46,14 @@ extern "C" {
*/
int hal_watchdog_init(uint32_t expire_msecs);
-/*
+/**
* Starts the watchdog.
*/
void hal_watchdog_enable(void);
-/*
- * Tickles the watchdog. Needs to be done before 'expire_secs' fires.
+/**
+ * Tickles the watchdog. This needs to be done periodically, before
+ * the value configured in :c:func:`hal_watchdog_init()` expires.
*/
void hal_watchdog_tickle(void);
@@ -53,3 +62,8 @@ void hal_watchdog_tickle(void);
#endif
#endif /* _HAL_WATCHDOG_H_ */
+
+/**
+ * @} HALWatchdog
+ * @} HAL
+ */
diff --git a/hw/hal/src/hal_common.c b/hw/hal/src/hal_common.c
index e13358517..826f2f15e 100644
--- a/hw/hal/src/hal_common.c
+++ b/hw/hal/src/hal_common.c
@@ -28,15 +28,7 @@ _exit(int status)
hal_system_reset();
}
-/**
- * Extracts CPOL and CPHA values from a data-mode constant.
- *
- * @param data_mode The HAL_SPI_MODE value to convert.
- * @param out_cpol The CPOL gets written here on success.
- * @param out_cpha The CPHA gets written here on success.
- *
- * @return 0 on success; nonzero on invalid input.
- */
+
int
hal_spi_data_mode_breakout(uint8_t data_mode, int *out_cpol, int *out_cpha)
{
diff --git a/kernel/os/include/os/os.h b/kernel/os/include/os/os.h
index 80eaf8217..3bbfb1035 100644
--- a/kernel/os/include/os/os.h
+++ b/kernel/os/include/os/os.h
@@ -49,6 +49,9 @@ extern "C" {
#define CTASSERT(x) typedef int __ctasssert ## __LINE__[(x) ? 1 : -1]
+/**
+ * @cond INTERNAL_HIDDEN
+ */
/**
* Whether or not the operating system has been started. Set to
* 1 right before first task is run.
@@ -57,24 +60,52 @@ extern int g_os_started;
int os_info_init(void);
+/* XXX: Not sure if this should go here; I want to differentiate API that
+ * should be called by application developers as those that should not. */
+void os_init_idle_task(void);
+/**
+ * @endcond
+ */
+
/**
- * Returns 1 if the OS has been started, 0 if it has not yet been
- * been started.
+ * Check whether or not the OS has been started.
+ *
+ * @return 1 if the OS has been started and 0 if it has not yet been started.
*/
int os_started(void);
+/**
+ * Definition used for functions that take timeouts to specify
+ * waiting indefinitely.
+ */
#define OS_WAIT_FOREVER (-1)
+/**
+ * Priority of the IDLE task. Always the lowest priority task in teh system.
+ */
#define OS_IDLE_PRIO (0xff)
+
+/**
+ * Main task priority, defined by sysconfig.
+ */
#define OS_MAIN_TASK_PRIO MYNEWT_VAL(OS_MAIN_TASK_PRIO)
+/**
+ * Main task stack size, defined by sysconfig.
+ */
#define OS_MAIN_STACK_SIZE MYNEWT_VAL(OS_MAIN_STACK_SIZE)
+/**
+ * Initialize the OS, including memory areas and housekeeping functions.
+ * This calls into the architecture specific OS initialization.
+ *
+ * @param fn The system "main" function to start the main task with.
+ */
void os_init(int (*fn)(int argc, char **argv));
-void os_start(void);
-/* XXX: Not sure if this should go here; I want to differentiate API that
- * should be called by application developers as those that should not. */
-void os_init_idle_task(void);
+/**
+ * Start the OS and begin processing.
+ */
+void os_start(void);
#include "os/endian.h"
#include "os/os_arch.h"
diff --git a/kernel/os/include/os/os_callout.h b/kernel/os/include/os/os_callout.h
index 254d7a4ee..858bdffea 100644
--- a/kernel/os/include/os/os_callout.h
+++ b/kernel/os/include/os/os_callout.h
@@ -16,11 +16,17 @@
* specific language governing permissions and limitations
* under the License.
*/
-
-
#ifndef _OS_CALLOUT_H
#define _OS_CALLOUT_H
+/**
+ * @addtogroup OSKernel
+ * @{
+ * @defgroup OSCallouts Event Timers (Callouts)
+ * @{
+ */
+
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -29,34 +35,116 @@ extern "C" {
#include "os/os_eventq.h"
+/**
+ * Structure containing the definition of a callout, initialized
+ * by os_callout_init() and passed to callout functions.
+ */
struct os_callout {
+ /** Event to post when the callout expires. */
struct os_event c_ev;
+ /** Pointer to the event queue to post the event to */
struct os_eventq *c_evq;
+ /** Number of ticks in the future to expire the callout */
uint32_t c_ticks;
+
+
TAILQ_ENTRY(os_callout) c_next;
};
+/**
+ * @cond INTERNAL_HIDDEN
+ */
+
TAILQ_HEAD(os_callout_list, os_callout);
+/**
+ * @endcond
+ */
+
+/**
+ * Initialize a callout.
+ *
+ * Callouts are used to schedule events in the future onto a task's event
+ * queue. Callout timers are scheduled using the os_callout_reset()
+ * function. When the timer expires, an event is posted to the event
+ * queue specified in os_callout_init(). The event argument given here
+ * is posted in the ev_arg field of that event.
+ *
+ * @param c The callout to initialize
+ * @param evq The event queue to post an OS_EVENT_T_TIMER event to
+ * @param timo_func The function to call on this callout for the host task
+ * used to provide multiple timer events to a task
+ * (this can be NULL.)
+ * @param ev_arg The argument to provide to the event when posting the
+ * timer.
+ */
void os_callout_init(struct os_callout *cf, struct os_eventq *evq,
os_event_fn *ev_cb, void *ev_arg);
+
+
+/**
+ * Stop the callout from firing off, any pending events will be cleared.
+ *
+ * @param c The callout to stop
+ */
void os_callout_stop(struct os_callout *);
+
+
+/**
+ * Reset the callout to fire off in 'ticks' ticks.
+ *
+ * @param c The callout to reset
+ * @param ticks The number of ticks to wait before posting an event
+ *
+ * @return 0 on success, non-zero on failure
+ */
int os_callout_reset(struct os_callout *, int32_t);
-void os_callout_tick(void);
-os_time_t os_callout_wakeup_ticks(os_time_t now);
-os_time_t os_callout_remaining_ticks(struct os_callout *c, os_time_t now);
+/*
+ * Returns the number of ticks which remains to callout..
+ *
+ * @param c The callout to check
+ * @param now The current time in OS ticks
+ *
+ * @return Number of ticks to first pending callout
+ */
+os_time_t os_callout_remaining_ticks(struct os_callout *, os_time_t);
+
+
+/**
+ * Returned whether or not the callout has been posted to it's
+ * event queue.
+ *
+ * @param c The callout to check
+ *
+ * @return 1 if queued, 0 if not queued.
+ */
static inline int
os_callout_queued(struct os_callout *c)
{
return c->c_next.tqe_prev != NULL;
}
+/**
+ * @cond INTERNAL_HIDDEN
+ */
+
+void os_callout_tick(void);
+os_time_t os_callout_wakeup_ticks(os_time_t now);
+
+/**
+ * @endcond
+ */
+
#ifdef __cplusplus
}
#endif
#endif /* _OS_CALLOUT_H */
+/**
+ * @} Callout Timers
+ * @} OS Kernel
+ */
diff --git a/kernel/os/include/os/os_cputime.h b/kernel/os/include/os/os_cputime.h
index b8c723fa3..8b57f8a00 100644
--- a/kernel/os/include/os/os_cputime.h
+++ b/kernel/os/include/os/os_cputime.h
@@ -94,8 +94,6 @@ extern struct os_cputime_data g_os_cputime;
#define CPUTIME_LEQ(__t1, __t2) ((int32_t) ((__t1) - (__t2)) <= 0)
/**
- * os cputime init
- *
* Initialize the cputime module. This must be called after os_init is called
* and before any other timer API are used. This should be called only once
* and should be called before the hardware timer is used.
@@ -107,8 +105,6 @@ extern struct os_cputime_data g_os_cputime;
int os_cputime_init(uint32_t clock_freq);
/**
- * os cputime get32
- *
* Returns the low 32 bits of cputime.
*
* @return uint32_t The lower 32 bits of cputime
@@ -117,9 +113,8 @@ uint32_t os_cputime_get32(void);
#if !defined(OS_CPUTIME_FREQ_PWR2)
/**
- * os cputime nsecs to ticks
- *
* Converts the given number of nanoseconds into cputime ticks.
+ * Not defined if OS_CPUTIME_FREQ_PWR2 is defined.
*
* @param usecs The number of nanoseconds to convert to ticks
*
@@ -128,9 +123,8 @@ uint32_t os_cputime_get32(void);
uint32_t os_cputime_nsecs_to_ticks(uint32_t nsecs);
/**
- * os cputime ticks to nsecs
- *
* Convert the given number of ticks into nanoseconds.
+ * Not defined if OS_CPUTIME_FREQ_PWR2 is defined.
*
* @param ticks The number of ticks to convert to nanoseconds.
*
@@ -139,9 +133,9 @@ uint32_t os_cputime_nsecs_to_ticks(uint32_t nsecs);
uint32_t os_cputime_ticks_to_nsecs(uint32_t ticks);
/**
- * os cputime delay nsecs
- *
* Wait until 'nsecs' nanoseconds has elapsed. This is a blocking delay.
+ * Not defined if OS_CPUTIME_FREQ_PWR2 is defined.
+ *
*
* @param nsecs The number of nanoseconds to wait.
*/
@@ -152,9 +146,8 @@ void os_cputime_delay_nsecs(uint32_t nsecs);
#define os_cputime_usecs_to_ticks(x) (x)
#define os_cputime_ticks_to_usecs(x) (x)
#else
+
/**
- * os cputime usecs to ticks
- *
* Converts the given number of microseconds into cputime ticks.
*
* @param usecs The number of microseconds to convert to ticks
@@ -164,8 +157,6 @@ void os_cputime_delay_nsecs(uint32_t nsecs);
uint32_t os_cputime_usecs_to_ticks(uint32_t usecs);
/**
- * os cputime ticks to usecs
- *
* Convert the given number of ticks into microseconds.
*
* @param ticks The number of ticks to convert to microseconds.
@@ -176,8 +167,6 @@ uint32_t os_cputime_ticks_to_usecs(uint32_t ticks);
#endif
/**
- * os cputime delay ticks
- *
* Wait until the number of ticks has elapsed. This is a blocking delay.
*
* @param ticks The number of ticks to wait.
@@ -185,8 +174,6 @@ uint32_t os_cputime_ticks_to_usecs(uint32_t ticks);
void os_cputime_delay_ticks(uint32_t ticks);
/**
- * os cputime delay usecs
- *
* Wait until 'usecs' microseconds has elapsed. This is a blocking delay.
*
* @param usecs The number of usecs to wait.
@@ -194,17 +181,16 @@ void os_cputime_delay_ticks(uint32_t ticks);
void os_cputime_delay_usecs(uint32_t usecs);
/**
- * os cputime timer init
+ * Initialize a CPU timer, using the given HAL timer.
*
* @param timer The timer to initialize. Cannot be NULL.
* @param fp The timer callback function. Cannot be NULL.
* @param arg Pointer to data object to pass to timer.
*/
-void os_cputime_timer_init(struct hal_timer *timer, hal_timer_cb fp, void *arg);
+void os_cputime_timer_init(struct hal_timer *timer, hal_timer_cb fp,
+ void *arg);
/**
- * os cputime timer start
- *
* Start a cputimer that will expire at 'cputime'. If cputime has already
* passed, the timer callback will still be called (at interrupt context).
*
@@ -220,8 +206,6 @@ void os_cputime_timer_init(struct hal_timer *timer, hal_timer_cb fp, void *arg);
int os_cputime_timer_start(struct hal_timer *timer, uint32_t cputime);
/**
- * os cputimer timer relative
- *
* Sets a cpu timer that will expire 'usecs' microseconds from the current
* cputime.
*
@@ -236,8 +220,6 @@ int os_cputime_timer_start(struct hal_timer *timer, uint32_t cputime);
int os_cputime_timer_relative(struct hal_timer *timer, uint32_t usecs);
/**
- * os cputime timer stop
- *
* Stops a cputimer from running. The timer is removed from the timer queue
* and interrupts are disabled if no timers are left on the queue. Can be
* called even if timer is not running.
diff --git a/kernel/os/include/os/os_dev.h b/kernel/os/include/os/os_dev.h
index ed65a0873..b8c8647e9 100644
--- a/kernel/os/include/os/os_dev.h
+++ b/kernel/os/include/os/os_dev.h
@@ -20,6 +20,13 @@
#ifndef _OS_DEV_H
#define _OS_DEV_H
+/**
+ * @addtogroup OSKernel
+ * @{
+ * @defgroup OSDevice Device Framework
+ * @{
+ */
+
#include <os/os.h>
#include "os/queue.h"
@@ -35,35 +42,77 @@ struct os_dev;
* by the Mynewt kernel.
*
*/
+/* Primary is initialized during OS init, after the initialization
+ * of OS memory and architecture specific functions, but before the
+ * OS gets started.
+ */
#define OS_DEV_INIT_PRIMARY (1)
+/** Secondary is initialized directly after primary. */
#define OS_DEV_INIT_SECONDARY (2)
+/** Initialize device in the main task, after the kernel has started. */
#define OS_DEV_INIT_KERNEL (3)
+/**
+ * This device initializing is critical, fail device init if it does
+ * not successfully initialize.
+ */
#define OS_DEV_INIT_F_CRITICAL (1 << 0)
-
#define OS_DEV_INIT_PRIO_DEFAULT (0xff)
-/**
- * Device status, so functions can ensure device is called in a
- * consistent state.
- */
+/** Device is initialized, and ready to be accessed. */
#define OS_DEV_F_STATUS_READY (1 << 0)
+/** Device is open */
#define OS_DEV_F_STATUS_OPEN (1 << 1)
+/** Device is in suspended state. */
#define OS_DEV_F_STATUS_SUSPENDED (1 << 2)
+/**
+ * It is critical to the system operation that this device successfully
+ * initialized. Fail device init if it does not.
+ */
#define OS_DEV_F_INIT_CRITICAL (1 << 3)
+/**
+ * Initialize a device.
+ *
+ * @param dev The device to initialize.
+ * @param arg User defined argument to pass to the device initalization
+ *
+ * @return 0 on success, non-zero error code on failure.
+ */
typedef int (*os_dev_init_func_t)(struct os_dev *, void *);
+
typedef int (*os_dev_open_func_t)(struct os_dev *, uint32_t,
void *);
typedef int (*os_dev_suspend_func_t)(struct os_dev *, os_time_t, int);
typedef int (*os_dev_resume_func_t)(struct os_dev *);
typedef int (*os_dev_close_func_t)(struct os_dev *);
+/**
+ * Device handlers, implementers of device drivers should fill these
+ * out to control device operation.
+ */
struct os_dev_handlers {
+ /**
+ * Device open handler, called when the user opens the device.
+ * Any locking of the device should be done within the open handler.
+ */
os_dev_open_func_t od_open;
+ /**
+ * Suspend handler, called when the device is being suspended.
+ * Up to the implementer to save device state before power down,
+ * so that the device can be cleanly resumed -- or error out and
+ * delay suspension.
+ */
os_dev_suspend_func_t od_suspend;
+ /**
+ * Resume handler, restores device state after a suspend operation.
+ */
os_dev_resume_func_t od_resume;
+ /**
+ * Close handler, releases the device, including any locks that
+ * may have been taken by open().
+ */
os_dev_close_func_t od_close;
};
@@ -71,13 +120,24 @@ struct os_dev_handlers {
* Device structure.
*/
struct os_dev {
+ /** Device handlers. Implementation of base device functions. */
struct os_dev_handlers od_handlers;
+ /** Device initialization function. */
os_dev_init_func_t od_init;
+ /** Argument to pass to device initialization function. */
void *od_init_arg;
+ /** Stage during which to initialize this device. */
uint8_t od_stage;
+ /** Priority within a given stage to initialize a device. */
uint8_t od_priority;
+ /**
+ * Number of references to a device being open before marking
+ * the device closed.
+ */
uint8_t od_open_ref;
+ /** Device flags. */
uint8_t od_flags;
+ /** Device name */
char *od_name;
STAILQ_ENTRY(os_dev) od_next;
};
@@ -86,6 +146,17 @@ struct os_dev {
(__dev)->od_handlers.od_open = (__open); \
(__dev)->od_handlers.od_close = (__close);
+
+/**
+ * Suspend the operation of the device.
+ *
+ * @param dev The device to suspend.
+ * @param suspend_t When the device should be suspended.
+ * @param force Whether not the suspend operation can be overridden by the
+ * device handler.
+ *
+ * @return 0 on success, non-zero error code on failure.
+ */
static inline int
os_dev_suspend(struct os_dev *dev, os_time_t suspend_t, uint8_t force)
{
@@ -96,6 +167,14 @@ os_dev_suspend(struct os_dev *dev, os_time_t suspend_t, uint8_t force)
}
}
+
+/**
+ * Resume the device operation.
+ *
+ * @param dev The device to resume
+ *
+ * @return 0 on success, non-zero error code on failure.
+ */
static inline int
os_dev_resume(struct os_dev *dev)
{
@@ -106,14 +185,89 @@ os_dev_resume(struct os_dev *dev)
}
}
+/**
+ * Create a new device in the kernel.
+ *
+ * @param dev The device to create.
+ * @param name The name of the device to create.
+ * @param stage The stage to initialize that device to.
+ * @param priority The priority of initializing that device
+ * @param od_init The initialization function to call for this
+ * device.
+ * @param arg The argument to provide this device initialization
+ * function.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
int os_dev_create(struct os_dev *dev, char *name, uint8_t stage,
uint8_t priority, os_dev_init_func_t od_init, void *arg);
+
+/**
+ * Lookup a device by name.
+ *
+ * WARNING: This should be called before any locking on the device is done, or
+ * the device list itself is modified in any context. There is no locking.
+ *
+ * @param name The name of the device to look up.
+ *
+ * @return A pointer to the device corresponding to name, or NULL if not found.
+ */
struct os_dev *os_dev_lookup(char *name);
-int os_dev_initialize_all(uint8_t stage);
+
+/**
+ * Initialize all devices for a given state.
+ *
+ * @param stage The stage to initialize.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
+int os_dev_initialize_all(uint8_t);
+
+
+/**
+ * Suspend all devices.
+ *
+ * @param suspend_t The number of ticks to suspend this device for
+ * @param force Whether or not to force suspending the device
+ *
+ * @return 0 on success, or a non-zero error code if one of the devices
+ * returned it.
+ */
int os_dev_suspend_all(os_time_t, uint8_t);
+
+/**
+ * Resume all the devices that were suspended.
+ *
+ * @return 0 on success, -1 if any of the devices have failed to resume.
+ */
int os_dev_resume_all(void);
+
+/**
+ * Open a device.
+ *
+ * @param dev The device to open
+ * @param timo The timeout to open the device, if not specified.
+ * @param arg The argument to the device open() call.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
struct os_dev *os_dev_open(char *devname, uint32_t timo, void *arg);
+
+/**
+ * Close a device.
+ *
+ * @param dev The device to close
+ *
+ * @return 0 on success, non-zero on failure.
+ */
int os_dev_close(struct os_dev *dev);
+
+
+/**
+ * Clears the device list. This function does not close any devices or free
+ * any resources; its purpose is to allow a full system reset between unit
+ * tests.
+ */
void os_dev_reset(void);
#ifdef __cplusplus
@@ -121,3 +275,9 @@ void os_dev_reset(void);
#endif
#endif /* _OS_DEV_H */
+
+
+/**
+ * @} OSDevice
+ * @} OSKernel
+ */
diff --git a/kernel/os/include/os/os_eventq.h b/kernel/os/include/os/os_eventq.h
index b0c3abdb2..2445fd6f3 100644
--- a/kernel/os/include/os/os_eventq.h
+++ b/kernel/os/include/os/os_eventq.h
@@ -17,6 +17,14 @@
* under the License.
*/
+
+/**
+ * @addtogroup OSKernel
+ * @{
+ * @defgroup OSEvent Event Queues
+ * @{
+ */
+
#ifndef _OS_EVENTQ_H
#define _OS_EVENTQ_H
@@ -31,38 +39,140 @@ extern "C" {
struct os_event;
typedef void os_event_fn(struct os_event *ev);
+/**
+ * Structure representing an OS event. OS events get placed onto the
+ * event queues and are consumed by tasks.
+ */
struct os_event {
+ /** Whether this OS event is queued on an event queue. */
uint8_t ev_queued;
+ /**
+ * Callback to call when the event is taken off of an event queue.
+ * APIs, except for os_eventq_run(), assume this callback will be called by
+ * the user.
+ */
os_event_fn *ev_cb;
+ /** Argument to pass to the event queue callback. */
void *ev_arg;
+
+
STAILQ_ENTRY(os_event) ev_next;
};
+/** Return whether or not the given event is queued. */
#define OS_EVENT_QUEUED(__ev) ((__ev)->ev_queued)
struct os_eventq {
- struct os_task *evq_owner; /* owner task */
- struct os_task *evq_task; /* sleeper; must be either NULL, or the owner */
+ /** Pointer to task that "owns" this event queue. */
+ struct os_task *evq_owner;
+ /**
+ * Pointer to the task that is sleeping on this event queue, either NULL,
+ * or the owner task.
+ */
+ struct os_task *evq_task;
+
+
STAILQ_HEAD(, os_event) evq_list;
};
+
+/**
+ * Initialize the event queue
+ *
+ * @param evq The event queue to initialize
+ */
void os_eventq_init(struct os_eventq *);
+
+/**
+ * Check whether the event queue is initialized.
+ *
+ * @param evq The event queue to check
+ */
int os_eventq_inited(const struct os_eventq *evq);
+
+/**
+ * Put an event on the event queue.
+ *
+ * @param evq The event queue to put an event on
+ * @param ev The event to put on the queue
+ */
void os_eventq_put(struct os_eventq *, struct os_event *);
+
+/**
+ * Poll an event from the event queue and return it immediately.
+ * If no event is available, don't block, just return NULL.
+ *
+ * @return Event from the queue, or NULL if none available.
+ */
struct os_event *os_eventq_get_no_wait(struct os_eventq *evq);
+
+/**
+ * Pull a single item from an event queue. This function blocks until there
+ * is an item on the event queue to read.
+ *
+ * @param evq The event queue to pull an event from
+ *
+ * @return The event from the queue
+ */
struct os_event *os_eventq_get(struct os_eventq *);
+
+/**
+ * Pull a single item off the event queue and call it's event
+ * callback.
+ *
+ * @param evq The event queue to pull the item off.
+ */
void os_eventq_run(struct os_eventq *evq);
+
+
+/**
+ * Poll the list of event queues specified by the evq parameter
+ * (size nevqs), and return the "first" event available on any of
+ * the queues. Event queues are searched in the order that they
+ * are passed in the array.
+ *
+ * @param evq Array of event queues
+ * @param nevqs Number of event queues in evq
+ * @param timo Timeout, forever if OS_WAIT_FOREVER is passed to poll.
+ *
+ * @return An event, or NULL if no events available
+ */
struct os_event *os_eventq_poll(struct os_eventq **, int, os_time_t);
+
+/**
+ * Remove an event from the queue.
+ *
+ * @param evq The event queue to remove the event from
+ * @param ev The event to remove from the queue
+ */
void os_eventq_remove(struct os_eventq *, struct os_event *);
+
+/**
+ * Retrieves the default event queue processed by OS main task.
+ *
+ * @return The default event queue.
+ */
struct os_eventq *os_eventq_dflt_get(void);
-/* [DEPRECATED] */
+/**
+ * @cond INTERNAL_HIDDEN
+ * [DEPRECATED]
+ */
void os_eventq_designate(struct os_eventq **dst, struct os_eventq *val,
struct os_event *start_ev);
+/**
+ * @endcond
+ */
+
#ifdef __cplusplus
}
#endif
#endif /* _OS_EVENTQ_H */
+
+/**
+ * @} OSEvent
+ * @} OSKernel
+ */
diff --git a/kernel/os/include/os/os_heap.h b/kernel/os/include/os/os_heap.h
index 4413568e4..3ce6f2e22 100644
--- a/kernel/os/include/os/os_heap.h
+++ b/kernel/os/include/os/os_heap.h
@@ -6,7 +6,7 @@
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
@@ -17,6 +17,15 @@
* under the License.
*/
+
+/**
+ * @addtogroup OSKernel
+ * @{
+ * @defgroup OSGeneral
+ * @{
+ */
+
+
#ifndef H_OS_HEAP_
#define H_OS_HEAP_
@@ -26,8 +35,39 @@
extern "C" {
#endif
+
+/**
+ * Operating system level malloc(). This ensures that a safe malloc occurs
+ * within the context of the OS. Depending on platform, the OS may rely on
+ * libc's malloc() implementation, which is not guaranteed to be thread-safe.
+ * This malloc() will always be thread-safe.
+ *
+ * @param size The number of bytes to allocate
+ *
+ * @return A pointer to the memory region allocated.
+ */
void *os_malloc(size_t size);
+
+
+/**
+ * Operating system level free(). See description of os_malloc() for reasoning.
+ *
+ * Free's memory allocated by malloc.
+ *
+ * @param mem The memory to free.
+ */
void os_free(void *mem);
+
+/**
+ * Operating system level realloc(). See description of os_malloc() for reasoning.
+ *
+ * Reallocates the memory at ptr, to be size contiguouos bytes.
+ *
+ * @param ptr A pointer to the memory to allocate
+ * @param size The number of contiguouos bytes to allocate at that location
+ *
+ * @return A pointer to memory of size, or NULL on failure to allocate
+ */
void *os_realloc(void *ptr, size_t size);
#ifdef __cplusplus
@@ -36,3 +76,8 @@ void *os_realloc(void *ptr, size_t size);
#endif
+
+/**
+ * @} OSGeneral
+ * @} OS Kernel
+ */
diff --git a/kernel/os/include/os/os_mbuf.h b/kernel/os/include/os/os_mbuf.h
index bfb500310..f264d5687 100644
--- a/kernel/os/include/os/os_mbuf.h
+++ b/kernel/os/include/os/os_mbuf.h
@@ -17,6 +17,15 @@
* under the License.
*/
+
+/**
+ * @addtogroup OSKernel
+ * @{
+ * @defgroup OSMbuf Chained Memory Buffers
+ * @{
+ */
+
+
#ifndef _OS_MBUF_H
#define _OS_MBUF_H
@@ -45,9 +54,6 @@ struct os_mbuf_pool {
*/
struct os_mempool *omp_pool;
- /**
- * Link to the next mbuf pool for system memory pools.
- */
STAILQ_ENTRY(os_mbuf_pool) omp_next;
};
@@ -64,9 +70,7 @@ struct os_mbuf_pkthdr {
* Flags
*/
uint16_t omp_flags;
- /**
- * Next packet in the mbuf chain.
- */
+
STAILQ_ENTRY(os_mbuf_pkthdr) omp_next;
};
@@ -96,9 +100,6 @@ struct os_mbuf {
*/
struct os_mbuf_pool *om_omp;
- /**
- * Pointer to next entry in the chained memory buffer
- */
SLIST_ENTRY(os_mbuf) om_next;
/**
@@ -107,8 +108,12 @@ struct os_mbuf {
uint8_t om_databuf[0];
};
+/**
+ * Structure representing a queue of mbufs.
+ */
struct os_mqueue {
STAILQ_HEAD(, os_mbuf_pkthdr) mq_head;
+ /** Event to post when new buffers are available on the queue. */
struct os_event mq_ev;
};
@@ -127,11 +132,11 @@ struct os_mqueue {
#define OS_MBUF_IS_PKTHDR(__om) \
((__om)->om_pkthdr_len >= sizeof (struct os_mbuf_pkthdr))
-/* Get a packet header pointer given an mbuf pointer */
+/** Get a packet header pointer given an mbuf pointer */
#define OS_MBUF_PKTHDR(__om) ((struct os_mbuf_pkthdr *) \
((uint8_t *)&(__om)->om_data + sizeof(struct os_mbuf)))
-/* Given a mbuf packet header pointer, return a pointer to the mbuf */
+/** Given a mbuf packet header pointer, return a pointer to the mbuf */
#define OS_MBUF_PKTHDR_TO_MBUF(__hdr) \
(struct os_mbuf *)((uint8_t *)(__hdr) - sizeof(struct os_mbuf))
@@ -141,7 +146,7 @@ struct os_mqueue {
*/
#define OS_MBUF_PKTLEN(__om) (OS_MBUF_PKTHDR(__om)->omp_len)
-/*
+/**
* Access the data of a mbuf, and cast it to type
*
* @param __om The mbuf to access, and cast
@@ -167,6 +172,9 @@ struct os_mqueue {
#define OS_MBUF_USRHDR_LEN(om) \
((om)->om_pkthdr_len - sizeof (struct os_mbuf_pkthdr))
+
+/** @cond INTERNAL_HIDDEN */
+
/*
* Called by OS_MBUF_LEADINGSPACE() macro
*/
@@ -187,6 +195,8 @@ _os_mbuf_leadingspace(struct os_mbuf *om)
return (leadingspace);
}
+/** @endcond */
+
/**
* Returns the leading space (space at the beginning) of the mbuf.
* Works on both packet header, and regular mbufs, as it accounts
@@ -199,6 +209,9 @@ _os_mbuf_leadingspace(struct os_mbuf *om)
*/
#define OS_MBUF_LEADINGSPACE(__om) _os_mbuf_leadingspace(__om)
+
+/** @cond INTERNAL_HIDDEN */
+
/* Called by OS_MBUF_TRAILINGSPACE() macro. */
static inline uint16_t
_os_mbuf_trailingspace(struct os_mbuf *om)
@@ -211,6 +224,8 @@ _os_mbuf_trailingspace(struct os_mbuf *om)
(om->om_data + om->om_len);
}
+/** @endcond */
+
/**
* Returns the trailing space (space at the end) of the mbuf.
* Works on both packet header and regular mbufs.
@@ -222,80 +237,392 @@ _os_mbuf_trailingspace(struct os_mbuf *om)
*/
#define OS_MBUF_TRAILINGSPACE(__om) _os_mbuf_trailingspace(__om)
-/* Mbuf queue functions */
-/* Initialize a mbuf queue */
+/**
+ * Initializes an mqueue. An mqueue is a queue of mbufs that ties to a
+ * particular task's event queue. Mqueues form a helper API around a common
+ * paradigm: wait on an event queue until at least one packet is available,
+ * then process a queue of packets.
+ *
+ * When mbufs are available on the queue, an event OS_EVENT_T_MQUEUE_DATA
+ * will be posted to the task's mbuf queue.
+ *
+ * @param mq The mqueue to initialize
+ * @param ev_cb The callback to associate with the mqeueue
+ * event. Typically, this callback pulls each
+ * packet off the mqueue and processes them.
+ * @param arg The argument to associate with the mqueue event.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
int os_mqueue_init(struct os_mqueue *mq, os_event_fn *ev_cb, void *arg);
-/* Get an element from a mbuf queue */
+/**
+ * Remove and return a single mbuf from the mbuf queue. Does not block.
+ *
+ * @param mq The mbuf queue to pull an element off of.
+ *
+ * @return The next mbuf in the queue, or NULL if queue has no mbufs.
+ */
struct os_mbuf *os_mqueue_get(struct os_mqueue *);
-/* Put an element in a mbuf queue */
+/**
+ * Adds a packet (i.e. packet header mbuf) to an mqueue. The event associated
+ * with the mqueue gets posted to the specified eventq.
+ *
+ * @param mq The mbuf queue to append the mbuf to.
+ * @param evq The event queue to post an event to.
+ * @param m The mbuf to append to the mbuf queue.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
int os_mqueue_put(struct os_mqueue *, struct os_eventq *, struct os_mbuf *);
-/* Register an mbuf pool with the system pool registry */
+/**
+ * MSYS is a system level mbuf registry. Allows the system to share
+ * packet buffers amongst the various networking stacks that can be running
+ * simultaeneously.
+ *
+ * Mbuf pools are created in the system initialization code, and then when
+ * a mbuf is allocated out of msys, it will try and find the best fit based
+ * upon estimated mbuf size.
+ *
+ * os_msys_register() registers a mbuf pool with MSYS, and allows MSYS to
+ * allocate mbufs out of it.
+ *
+ * @param new_pool The pool to register with MSYS
+ *
+ * @return 0 on success, non-zero on failure
+ */
int os_msys_register(struct os_mbuf_pool *);
-/* Return a mbuf from the system pool, given an indicative mbuf size */
+/**
+ * Allocate a mbuf from msys. Based upon the data size requested,
+ * os_msys_get() will choose the mbuf pool that has the best fit.
+ *
+ * @param dsize The estimated size of the data being stored in the mbuf
+ * @param leadingspace The amount of leadingspace to allocate in the mbuf
+ *
+ * @return A freshly allocated mbuf on success, NULL on failure.
+ */
struct os_mbuf *os_msys_get(uint16_t dsize, uint16_t leadingspace);
-/* De-registers all mbuf pools from msys. */
+/**
+ * De-registers all mbuf pools from msys.
+ */
void os_msys_reset(void);
-/* Return a packet header mbuf from the system pool */
+/**
+ * Allocate a packet header structure from the MSYS pool. See
+ * os_msys_register() for a description of MSYS.
+ *
+ * @param dsize The estimated size of the data being stored in the mbuf
+ * @param user_hdr_len The length to allocate for the packet header structure
+ *
+ * @return A freshly allocated mbuf on success, NULL on failure.
+ */
struct os_mbuf *os_msys_get_pkthdr(uint16_t dsize, uint16_t user_hdr_len);
+/**
+ * Count the number of blocks in all the mbuf pools that are allocated.
+ *
+ * @return total number of blocks allocated in Msys
+ */
int os_msys_count(void);
+
+/**
+ * Return the number of free blocks in Msys
+ *
+ * @return Number of free blocks available in Msys
+ */
int os_msys_num_free(void);
-/* Initialize a mbuf pool */
+/**
+ * Initialize a pool of mbufs.
+ *
+ * @param omp The mbuf pool to initialize
+ * @param mp The memory pool that will hold this mbuf pool
+ * @param buf_len The length of the buffer itself.
+ * @param nbufs The number of buffers in the pool
+ *
+ * @return 0 on success, error code on failure.
+ */
int os_mbuf_pool_init(struct os_mbuf_pool *, struct os_mempool *mp,
uint16_t, uint16_t);
-/* Allocate a new mbuf out of the os_mbuf_pool */
+/**
+ * Get an mbuf from the mbuf pool. The mbuf is allocated, and initialized
+ * prior to being returned.
+ *
+ * @param omp The mbuf pool to return the packet from
+ * @param leadingspace The amount of leadingspace to put before the data
+ * section by default.
+ *
+ * @return An initialized mbuf on success, and NULL on failure.
+ */
struct os_mbuf *os_mbuf_get(struct os_mbuf_pool *omp, uint16_t);
-/* Allocate a new packet header mbuf out of the os_mbuf_pool */
+/**
+ * Allocate a new packet header mbuf out of the os_mbuf_pool.
+ *
+ * @param omp The mbuf pool to allocate out of
+ * @param user_pkthdr_len The packet header length to reserve for the caller.
+ *
+ * @return A freshly allocated mbuf on success, NULL on failure.
+ */
struct os_mbuf *os_mbuf_get_pkthdr(struct os_mbuf_pool *omp,
uint8_t pkthdr_len);
-/* Duplicate a mbuf from the pool */
+/**
+ * Duplicate a chain of mbufs. Return the start of the duplicated chain.
+ *
+ * @param omp The mbuf pool to duplicate out of
+ * @param om The mbuf chain to duplicate
+ *
+ * @return A pointer to the new chain of mbufs
+ */
struct os_mbuf *os_mbuf_dup(struct os_mbuf *m);
+/**
+ * Locates the specified absolute offset within an mbuf chain. The offset
+ * can be one past than the total length of the chain, but no greater.
+ *
+ * @param om The start of the mbuf chain to seek within.
+ * @param off The absolute address to find.
+ * @param out_off On success, this points to the relative offset
+ * within the returned mbuf.
+ *
+ * @return The mbuf containing the specified offset on
+ * success.
+ * NULL if the specified offset is out of bounds.
+ */
struct os_mbuf *os_mbuf_off(const struct os_mbuf *om, int off,
uint16_t *out_off);
-/* Copy data from an mbuf to a flat buffer. */
+
+/*
+ * Copy data from an mbuf chain starting "off" bytes from the beginning,
+ * continuing for "len" bytes, into the indicated buffer.
+ *
+ * @param m The mbuf chain to copy from
+ * @param off The offset into the mbuf chain to begin copying from
+ * @param len The length of the data to copy
+ * @param dst The destination buffer to copy into
+ *
+ * @return 0 on success;
+ * -1 if the mbuf does not contain enough data.
+ */
int os_mbuf_copydata(const struct os_mbuf *m, int off, int len, void *dst);
-/* Append data onto a mbuf */
+/**
+ * Append data onto a mbuf
+ *
+ * @param om The mbuf to append the data onto
+ * @param data The data to append onto the mbuf
+ * @param len The length of the data to append
+ *
+ * @return 0 on success, and an error code on failure
+ */
int os_mbuf_append(struct os_mbuf *m, const void *, uint16_t);
+/**
+ * Reads data from one mbuf and appends it to another. On error, the specified
+ * data range may be partially appended. Neither mbuf is required to contain
+ * an mbuf packet header.
+ *
+ * @param dst The mbuf to append to.
+ * @param src The mbuf to copy data from.
+ * @param src_off The absolute offset within the source mbuf
+ * chain to read from.
+ * @param len The number of bytes to append.
+ *
+ * @return 0 on success;
+ * OS_EINVAL if the specified range extends beyond
+ * the end of the source mbuf chain.
+ */
int os_mbuf_appendfrom(struct os_mbuf *dst, const struct os_mbuf *src,
uint16_t src_off, uint16_t len);
-/* Free a mbuf */
+/**
+ * Release a mbuf back to the pool
+ *
+ * @param omp The Mbuf pool to release back to
+ * @param om The Mbuf to release back to the pool
+ *
+ * @return 0 on success, -1 on failure
+ */
int os_mbuf_free(struct os_mbuf *mb);
-/* Free a mbuf chain */
+/**
+ * Free a chain of mbufs
+ *
+ * @param omp The mbuf pool to free the chain of mbufs into
+ * @param om The starting mbuf of the chain to free back into the pool
+ *
+ * @return 0 on success, -1 on failure
+ */
int os_mbuf_free_chain(struct os_mbuf *om);
+/**
+ * Adjust the length of a mbuf, trimming either from the head or the tail
+ * of the mbuf.
+ *
+ * @param mp The mbuf chain to adjust
+ * @param req_len The length to trim from the mbuf. If positive, trims
+ * from the head of the mbuf, if negative, trims from the
+ * tail of the mbuf.
+ */
void os_mbuf_adj(struct os_mbuf *mp, int req_len);
+
+
+/**
+ * Performs a memory compare of the specified region of an mbuf chain against a
+ * flat buffer.
+ *
+ * @param om The start of the mbuf chain to compare.
+ * @param off The offset within the mbuf chain to start the
+ * comparison.
+ * @param data The flat buffer to compare.
+ * @param len The length of the flat buffer.
+ *
+ * @return 0 if both memory regions are identical;
+ * A memcmp return code if there is a mismatch;
+ * INT_MAX if the mbuf is too short.
+ */
int os_mbuf_cmpf(const struct os_mbuf *om, int off, const void *data, int len);
+
+/**
+ * Compares the contents of two mbuf chains. The ranges of the two chains to
+ * be compared are specified via the two offset parameters and the len
+ * parameter. Neither mbuf chain is required to contain a packet header.
+ *
+ * @param om1 The first mbuf chain to compare.
+ * @param offset1 The absolute offset within om1 at which to
+ * start the comparison.
+ * @param om2 The second mbuf chain to compare.
+ * @param offset2 The absolute offset within om2 at which to
+ * start the comparison.
+ * @param len The number of bytes to compare.
+ *
+ * @return 0 if both mbuf segments are identical;
+ * A memcmp() return code if the segment contents
+ * differ;
+ * INT_MAX if a specified range extends beyond the
+ * end of its corresponding mbuf chain.
+ */
int os_mbuf_cmpm(const struct os_mbuf *om1, uint16_t offset1,
const struct os_mbuf *om2, uint16_t offset2,
uint16_t len);
+/**
+ * Increases the length of an mbuf chain by adding data to the front. If there
+ * is insufficient room in the leading mbuf, additional mbufs are allocated and
+ * prepended as necessary. If this function fails to allocate an mbuf, the
+ * entire chain is freed.
+ *
+ * The specified mbuf chain does not need to contain a packet header.
+ *
+ * @param omp The mbuf pool to allocate from.
+ * @param om The head of the mbuf chain.
+ * @param len The number of bytes to prepend.
+ *
+ * @return The new head of the chain on success;
+ * NULL on failure.
+ */
struct os_mbuf *os_mbuf_prepend(struct os_mbuf *om, int len);
+
+/**
+ * Prepends a chunk of empty data to the specified mbuf chain and ensures the
+ * chunk is contiguous. If either operation fails, the specified mbuf chain is
+ * freed and NULL is returned.
+ *
+ * @param om The mbuf chain to prepend to.
+ * @param len The number of bytes to prepend and pullup.
+ *
+ * @return The modified mbuf on success;
+ * NULL on failure (and the mbuf chain is freed).
+ */
struct os_mbuf *os_mbuf_prepend_pullup(struct os_mbuf *om, uint16_t len);
+
+/**
+ * Copies the contents of a flat buffer into an mbuf chain, starting at the
+ * specified destination offset. If the mbuf is too small for the source data,
+ * it is extended as necessary. If the destination mbuf contains a packet
+ * header, the header length is updated.
+ *
+ * @param omp The mbuf pool to allocate from.
+ * @param om The mbuf chain to copy into.
+ * @param off The offset within the chain to copy to.
+ * @param src The source buffer to copy from.
+ * @param len The number of bytes to copy.
+ *
+ * @return 0 on success; nonzero on failure.
+ */
int os_mbuf_copyinto(struct os_mbuf *om, int off, const void *src, int len);
+
+/**
+ * Attaches a second mbuf chain onto the end of the first. If the first chain
+ * contains a packet header, the header's length is updated. If the second
+ * chain has a packet header, its header is cleared.
+ *
+ * @param first The mbuf chain being attached to.
+ * @param second The mbuf chain that gets attached.
+ */
void os_mbuf_concat(struct os_mbuf *first, struct os_mbuf *second);
+
+
+/**
+ * Increases the length of an mbuf chain by the specified amount. If there is
+ * not sufficient room in the last buffer, a new buffer is allocated and
+ * appended to the chain. It is an error to request more data than can fit in
+ * a single buffer.
+ *
+ * @param omp
+ * @param om The head of the chain to extend.
+ * @param len The number of bytes to extend by.
+ *
+ * @return A pointer to the new data on success;
+ * NULL on failure.
+ */
void *os_mbuf_extend(struct os_mbuf *om, uint16_t len);
+
+/**
+ * Rearrange a mbuf chain so that len bytes are contiguous,
+ * and in the data area of an mbuf (so that OS_MBUF_DATA() will
+ * work on a structure of size len.) Returns the resulting
+ * mbuf chain on success, free's it and returns NULL on failure.
+ *
+ * If there is room, it will add up to "max_protohdr - len"
+ * extra bytes to the contiguous region, in an attempt to avoid being
+ * called next time.
+ *
+ * @param omp The mbuf pool to take the mbufs out of
+ * @param om The mbuf chain to make contiguous
+ * @param len The number of bytes in the chain to make contiguous
+ *
+ * @return The contiguous mbuf chain on success, NULL on failure.
+ */
struct os_mbuf *os_mbuf_pullup(struct os_mbuf *om, uint16_t len);
+
+
+/**
+ * Removes and frees empty mbufs from the front of a chain. If the chain
+ * contains a packet header, it is preserved.
+ *
+ * @param om The mbuf chain to trim.
+ *
+ * @return The head of the trimmed mbuf chain.
+ */
struct os_mbuf *os_mbuf_trim_front(struct os_mbuf *om);
#ifdef __cplusplus
}
#endif
-#endif /* _OS_MBUF_H */
+#endif /* _OS_MBUF_H */
+
+
+/**
+ * @} OSMbuf
+ * @} OSKernel
+ */
diff --git a/kernel/os/include/os/os_mempool.h b/kernel/os/include/os/os_mempool.h
index 2de871d3e..2416ac944 100644
--- a/kernel/os/include/os/os_mempool.h
+++ b/kernel/os/include/os/os_mempool.h
@@ -17,6 +17,14 @@
* under the License.
*/
+/**
+ * @addtogroup OSKernel
+ * @{
+ * @defgroup OSMempool Memory Pools
+ * @{
+ */
+
+
#ifndef _OS_MEMPOOL_H_
#define _OS_MEMPOOL_H_
@@ -27,7 +35,7 @@
extern "C" {
#endif
-/*
+/**
* A memory block structure. This simply contains a pointer to the free list
* chain and is only used when the block is on the free list. When the block
* has been removed from the free list the entire memory block is usable by the
@@ -42,17 +50,26 @@ struct os_memblock {
/* XXX: Change how I coded the SLIST_HEAD here. It should be named:
SLIST_HEAD(,os_memblock) mp_head; */
-/* Memory pool */
+/**
+ * Memory pool
+ */
struct os_mempool {
- uint32_t mp_block_size; /* Size of the memory blocks, in bytes. */
- uint16_t mp_num_blocks; /* The number of memory blocks. */
- uint16_t mp_num_free; /* The number of free blocks left */
- uint16_t mp_min_free; /* The lowest number of free blocks seen */
- uint8_t mp_flags; /* Bitmap of OS_MEMPOOL_F_[...] values. */
- uint32_t mp_membuf_addr; /* Address of memory buffer used by pool */
+ /** Size of the memory blocks, in bytes. */
+ uint32_t mp_block_size;
+ /** The number of memory blocks. */
+ uint16_t mp_num_blocks;
+ /** The number of free blocks left */
+ uint16_t mp_num_free;
+ /** The lowest number of free blocks seen */
+ uint16_t mp_min_free;
+ /** Bitmap of OS_MEMPOOL_F_[...] values. */
+ uint8_t mp_flags;
+ /** Address of memory buffer used by pool */
+ uint32_t mp_membuf_addr;
STAILQ_ENTRY(os_mempool) mp_list;
- SLIST_HEAD(,os_memblock); /* Pointer to list of free blocks */
- char *name; /* Name for memory block */
+ SLIST_HEAD(,os_memblock);
+ /** Name for memory block */
+ char *name;
};
/**
@@ -94,14 +111,33 @@ struct os_mempool_ext {
#define OS_MEMPOOL_INFO_NAME_LEN (32)
+/**
+ * Information describing a memory pool, used to return OS information
+ * to the management layer.
+ */
struct os_mempool_info {
+ /** Size of the memory blocks in the pool */
int omi_block_size;
+ /** Number of memory blocks in the pool */
int omi_num_blocks;
+ /** Number of free memory blocks */
int omi_num_free;
+ /** Minimum number of free memory blocks ever */
int omi_min_free;
+ /** Name of the memory pool */
char omi_name[OS_MEMPOOL_INFO_NAME_LEN];
};
+/**
+ * Get information about the next system memory pool.
+ *
+ * @param mempool The current memory pool, or NULL if starting iteration.
+ * @param info A pointer to the structure to return memory pool information
+ * into.
+ *
+ * @return The next memory pool in the list to get information about, or NULL
+ * when at the last memory pool.
+ */
struct os_mempool *os_mempool_info_get_next(struct os_mempool *,
struct os_mempool_info *);
@@ -122,24 +158,88 @@ typedef uint64_t os_membuf_t;
#define OS_MEMPOOL_BYTES(n,blksize) \
(sizeof (os_membuf_t) * OS_MEMPOOL_SIZE((n), (blksize)))
-/* Initialize a memory pool */
+/**
+ * Initialize a memory pool.
+ *
+ * @param mp Pointer to a pointer to a mempool
+ * @param blocks The number of blocks in the pool
+ * @param blocks_size The size of the block, in bytes.
+ * @param membuf Pointer to memory to contain blocks.
+ * @param name Name of the pool.
+ *
+ * @return os_error_t
+ */
os_error_t os_mempool_init(struct os_mempool *mp, uint16_t blocks,
uint32_t block_size, void *membuf, char *name);
+
+/**
+ * Initializes an extended memory pool. Extended attributes (e.g., callbacks)
+ * are not specified when this function is called; they are assigned manually
+ * after initialization.
+ *
+ * @param mpe The extended memory pool to initialize.
+ * @param blocks The number of blocks in the pool.
+ * @param block_size The size of each block, in bytes.
+ * @param membuf Pointer to memory to contain blocks.
+ * @param name Name of the pool.
+ *
+ * @return os_error_t
+ */
os_error_t os_mempool_ext_init(struct os_mempool_ext *mpe, uint16_t blocks,
uint32_t block_size, void *membuf, char *name);
-/* Performs an integrity check of the specified mempool. */
+/**
+ * Performs an integrity check of the specified mempool. This function
+ * attempts to detect memory corruption in the specified memory pool.
+ *
+ * @param mp The mempool to check.
+ *
+ * @return true if the memory pool passes the integrity
+ * check;
+ * false if the memory pool is corrupt.
+ */
bool os_mempool_is_sane(const struct os_mempool *mp);
-/* Checks if a memory block was allocated from the specified mempool. */
+/**
+ * Checks if a memory block was allocated from the specified mempool.
+ *
+ * @param mp The mempool to check as parent.
+ * @param block_addr The memory block to check as child.
+ *
+ * @return 0 if the block does not belong to the mempool;
+ * 1 if the block does belong to the mempool.
+ */
int os_memblock_from(const struct os_mempool *mp, const void *block_addr);
-/* Get a memory block from the pool */
+/**
+ * Get a memory block from a memory pool
+ *
+ * @param mp Pointer to the memory pool
+ *
+ * @return void* Pointer to block if available; NULL otherwise
+ */
void *os_memblock_get(struct os_mempool *mp);
+/**
+ * Puts the memory block back into the pool, ignoring the put callback, if any.
+ * This function should only be called from a put callback to free a block
+ * without causing infinite recursion.
+ *
+ * @param mp Pointer to memory pool
+ * @param block_addr Pointer to memory block
+ *
+ * @return os_error_t
+ */
os_error_t os_memblock_put_from_cb(struct os_mempool *mp, void *block_addr);
-/* Put the memory block back into the pool */
+/**
+ * Puts the memory block back into the pool
+ *
+ * @param mp Pointer to memory pool
+ * @param block_addr Pointer to memory block
+ *
+ * @return os_error_t
+ */
os_error_t os_memblock_put(struct os_mempool *mp, void *block_addr);
#ifdef __cplusplus
@@ -147,3 +247,9 @@ os_error_t os_memblock_put(struct os_mempool *mp, void *block_addr);
#endif
#endif /* _OS_MEMPOOL_H_ */
+
+
+/**
+ * @} OSMempool
+ * @} OSKernel
+ */
diff --git a/kernel/os/include/os/os_mutex.h b/kernel/os/include/os/os_mutex.h
index 2964edb88..14f58161d 100644
--- a/kernel/os/include/os/os_mutex.h
+++ b/kernel/os/include/os/os_mutex.h
@@ -6,7 +6,7 @@
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
@@ -17,6 +17,13 @@
* under the License.
*/
+/**
+ * @addtogroup OSKernel
+ * @{
+ * @defgroup OSMutex Mutexes
+ * @{
+ */
+
#ifndef _OS_MUTEX_H_
#define _OS_MUTEX_H_
@@ -27,16 +34,21 @@
extern "C" {
#endif
-struct os_mutex
-{
- SLIST_HEAD(, os_task) mu_head; /* chain of waiting tasks */
+/**
+ * OS mutex structure
+ */
+struct os_mutex {
+ SLIST_HEAD(, os_task) mu_head;
uint8_t _pad;
- uint8_t mu_prio; /* owner's default priority*/
- uint16_t mu_level; /* call nesting level */
- struct os_task *mu_owner; /* owners task */
+ /** Mutex owner's default priority */
+ uint8_t mu_prio;
+ /** Mutex call nesting level */
+ uint16_t mu_level;
+ /** Task that owns the mutex */
+ struct os_task *mu_owner;
};
-/*
+/*
XXX: NOTES
-> Should we add a magic number or flag to the mutex structure so
that we know that this is a mutex? We can use it for double checking
@@ -48,16 +60,46 @@ struct os_mutex
*/
/* XXX: api to create
-os_mutex_inspect();
-*/
+os_mutex_inspect();
+*/
-/* Initialize a mutex */
+/**
+ * Create a mutex and initialize it.
+ *
+ * @param mu Pointer to mutex
+ *
+ * @return os_error_t
+ * OS_INVALID_PARM Mutex passed in was NULL.
+ * OS_OK no error.
+ */
os_error_t os_mutex_init(struct os_mutex *mu);
-/* Release a mutex */
+/**
+ * Release a mutex.
+ *
+ * @param mu Pointer to the mutex to be released
+ *
+ * @return os_error_t
+ * OS_INVALID_PARM Mutex passed in was NULL.
+ * OS_BAD_MUTEX Mutex was not granted to current task (not owner).
+ * OS_OK No error
+ */
os_error_t os_mutex_release(struct os_mutex *mu);
-/* Pend (wait) for a mutex */
+/**
+ * Pend (wait) for a mutex.
+ *
+ * @param mu Pointer to mutex.
+ * @param timeout Timeout, in os ticks. A timeout of 0 means do
+ * not wait if not available. A timeout of
+ * 0xFFFFFFFF means wait forever.
+ *
+ *
+ * @return os_error_t
+ * OS_INVALID_PARM Mutex passed in was NULL.
+ * OS_TIMEOUT Mutex was owned by another task and timeout=0
+ * OS_OK no error.
+ */
os_error_t os_mutex_pend(struct os_mutex *mu, uint32_t timeout);
#ifdef __cplusplus
diff --git a/kernel/os/include/os/os_sanity.h b/kernel/os/include/os/os_sanity.h
index e74f2f9f9..1dd248564 100644
--- a/kernel/os/include/os/os_sanity.h
+++ b/kernel/os/include/os/os_sanity.h
@@ -17,6 +17,14 @@
* under the License.
*/
+
+/**
+ * @addtogroup OSKernel
+ * @{
+ * @defgroup OSSanity Sanity
+ * @{
+ */
+
#ifndef _OS_SANITY_H
#define _OS_SANITY_H
@@ -33,9 +41,13 @@ struct os_sanity_check;
typedef int (*os_sanity_check_func_t)(struct os_sanity_check *, void *);
struct os_sanity_check {
+ /** Time this check last ran successfully. */
os_time_t sc_checkin_last;
+ /** Interval this task should check in at */
os_time_t sc_checkin_itvl;
+ /** Sanity check to run */
os_sanity_check_func_t sc_func;
+ /** Argument to pass to sanity check */
void *sc_arg;
SLIST_ENTRY(os_sanity_check) sc_next;
@@ -47,14 +59,48 @@ struct os_sanity_check {
(__sc)->sc_arg = (__arg); \
(__sc)->sc_checkin_itvl = (__itvl) * OS_TICKS_PER_SEC;
+/** @cond INTERNAL_HIDDEN */
int os_sanity_init(void);
void os_sanity_run(void);
+/** @endcond */
struct os_task;
+
+/**
+ * Provide a "task checkin" for the sanity task.
+ *
+ * @param t The task to check in
+ *
+ * @return 0 on success, error code on failure
+ */
int os_sanity_task_checkin(struct os_task *);
+/**
+ * Initialize a sanity check
+ *
+ * @param sc The sanity check to initialize
+ *
+ * @return 0 on success, error code on failure.
+ */
int os_sanity_check_init(struct os_sanity_check *);
+
+/**
+ * Register a sanity check
+ *
+ * @param sc The sanity check to register
+ *
+ * @return 0 on success, error code on failure
+ */
int os_sanity_check_register(struct os_sanity_check *);
+
+/**
+ * Reset the os sanity check, so that it doesn't trip up the
+ * sanity timer.
+ *
+ * @param sc The sanity check to reset
+ *
+ * @return 0 on success, error code on failure
+ */
int os_sanity_check_reset(struct os_sanity_check *);
#ifdef __cplusplus
@@ -62,3 +108,9 @@ int os_sanity_check_reset(struct os_sanity_check *);
#endif
#endif /* _OS_SANITY_H */
+
+
+/**
+ * @} OSSanity
+ * @} OSKernel
+ */
diff --git a/kernel/os/include/os/os_sched.h b/kernel/os/include/os/os_sched.h
index da065aa5c..43823a19b 100644
--- a/kernel/os/include/os/os_sched.h
+++ b/kernel/os/include/os/os_sched.h
@@ -33,6 +33,8 @@
extern "C" {
#endif
+
+/** @cond INTERNAL_HIDDEN */
struct os_task;
TAILQ_HEAD(os_task_list, os_task);
@@ -42,7 +44,17 @@ extern struct os_task_list g_os_run_list;
extern struct os_task_list g_os_sleep_list;
void os_sched_ctx_sw_hook(struct os_task *);
+
+/** @endcond */
+
+/**
+ * Returns the currently running task. Note that this task may or may not be
+ * the highest priority task ready to run.
+ *
+ * @return The currently running task.
+ */
struct os_task *os_sched_get_current_task(void);
+/** @cond INTERNAL_HIDDEN */
void os_sched_set_current_task(struct os_task *);
struct os_task *os_sched_next_task(void);
@@ -88,6 +100,8 @@ int os_sched_remove(struct os_task *);
void os_sched_resort(struct os_task *);
os_time_t os_sched_wakeup_ticks(os_time_t now);
+/** @endcond */
+
#ifdef __cplusplus
}
#endif
diff --git a/kernel/os/include/os/os_sem.h b/kernel/os/include/os/os_sem.h
index d5451ab3d..6460731a0 100644
--- a/kernel/os/include/os/os_sem.h
+++ b/kernel/os/include/os/os_sem.h
@@ -6,7 +6,7 @@
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
@@ -17,6 +17,13 @@
* under the License.
*/
+/**
+ * @addtogroup OSKernel
+ * @{
+ * @defgroup OSSem Semaphores
+ * @{
+ */
+
#ifndef _OS_SEM_H_
#define _OS_SEM_H_
@@ -26,14 +33,17 @@
extern "C" {
#endif
-struct os_sem
-{
- SLIST_HEAD(, os_task) sem_head; /* chain of waiting tasks */
+/**
+ * Structure representing an OS semaphore.
+ */
+struct os_sem {
+ SLIST_HEAD(, os_task) sem_head;
uint16_t _pad;
- uint16_t sem_tokens; /* # of tokens */
+ /** Number of tokens */
+ uint16_t sem_tokens;
};
-/*
+/*
XXX: NOTES
-> Should we add a magic number or flag to the semaphore structure so
that we know that this is a semaphore? We can use it for double checking
@@ -42,18 +52,52 @@ struct os_sem
acquired the semaphore? File/line where it was released?
-> Should we add a name to the semaphore?
-> Should we add a "os_sem_inspect() api, like ucos?
-*/
+*/
-/* Create a semaphore */
+/**
+ * Initialize a semaphore
+ *
+ * @param sem Pointer to semaphore
+ * tokens: # of tokens the semaphore should contain initially.
+ *
+ * @return os_error_t
+ * OS_INVALID_PARM Semaphore passed in was NULL.
+ * OS_OK no error.
+ */
os_error_t os_sem_init(struct os_sem *sem, uint16_t tokens);
-/* Release a semaphore */
+/**
+ * Release a semaphore.
+ *
+ * @param sem Pointer to the semaphore to be released
+ *
+ * @return os_error_t
+ * OS_INVALID_PARM Semaphore passed in was NULL.
+ * OS_OK No error
+ */
os_error_t os_sem_release(struct os_sem *sem);
-/* Pend (wait) for a semaphore */
+/**
+ * os sem pend
+ *
+ * Pend (wait) for a semaphore.
+ *
+ * @param mu Pointer to semaphore.
+ * @param timeout Timeout, in os ticks. A timeout of 0 means do
+ * not wait if not available. A timeout of
+ * 0xFFFFFFFF means wait forever.
+ *
+ *
+ * @return os_error_t
+ * OS_INVALID_PARM Semaphore passed in was NULL.
+ * OS_TIMEOUT Semaphore was owned by another task and timeout=0
+ * OS_OK no error.
+ */
os_error_t os_sem_pend(struct os_sem *sem, uint32_t timeout);
-/* Get current semaphore's count */
+/**
+ * Get current semaphore's count
+ */
static inline uint16_t os_sem_get_count(struct os_sem *sem)
{
return sem->sem_tokens;
@@ -64,3 +108,9 @@ static inline uint16_t os_sem_get_count(struct os_sem *sem)
#endif
#endif /* _OS_SEM_H_ */
+
+
+/**
+ * @} OSSem
+ * @} OSKernel
+ */
diff --git a/kernel/os/include/os/os_task.h b/kernel/os/include/os/os_task.h
index a9e420f5e..da517ef05 100644
--- a/kernel/os/include/os/os_task.h
+++ b/kernel/os/include/os/os_task.h
@@ -17,6 +17,14 @@
* under the License.
*/
+
+/**
+ * @addtogroup OSKernel
+ * @{
+ * @defgroup OSTask Tasks
+ * @{
+ */
+
#ifndef _OS_TASK_H
#define _OS_TASK_H
@@ -28,8 +36,9 @@
extern "C" {
#endif
-/* The highest and lowest task priorities */
+/** Highest priority task */
#define OS_TASK_PRI_HIGHEST (0)
+/** Lowest priority task */
#define OS_TASK_PRI_LOWEST (0xff)
/*
@@ -42,82 +51,176 @@ struct os_task_obj {
SLIST_HEAD(, os_task) obj_head; /* chain of waiting tasks */
};
-/* Task states */
+/** Task states */
typedef enum os_task_state {
+ /** Task is ready to run */
OS_TASK_READY = 1,
+ /** Task is sleeping */
OS_TASK_SLEEP = 2,
} os_task_state_t;
/* Task flags */
#define OS_TASK_FLAG_NO_TIMEOUT (0x01U)
+/** Task waiting on a semaphore */
#define OS_TASK_FLAG_SEM_WAIT (0x02U)
+/** Task waiting on a mutex */
#define OS_TASK_FLAG_MUTEX_WAIT (0x04U)
+/** Task waiting on a event queue */
#define OS_TASK_FLAG_EVQ_WAIT (0x08U)
typedef void (*os_task_func_t)(void *);
#define OS_TASK_MAX_NAME_LEN (32)
+/**
+ * Structure containing information about a running task
+ */
struct os_task {
+ /** Current stack pointer for this task */
os_stack_t *t_stackptr;
+ /** Pointer to top of this task's stack */
os_stack_t *t_stacktop;
-
+ /** Size of this task's stack */
uint16_t t_stacksize;
+ /** Task ID */
uint8_t t_taskid;
+ /** Task Priority */
uint8_t t_prio;
-
+ /* Task state, either READY or SLEEP */
uint8_t t_state;
+ /** Task flags, bitmask */
uint8_t t_flags;
uint8_t t_lockcnt;
uint8_t t_pad;
+ /** Task name */
const char *t_name;
+ /** Task function that executes */
os_task_func_t t_func;
+ /** Argument to pass to task function when called */
void *t_arg;
+ /** Current object task is waiting on, either a semaphore or mutex */
void *t_obj;
+ /** Default sanity check for this task */
struct os_sanity_check t_sanity_check;
+ /** Next scheduled wakeup if this task is sleeping */
os_time_t t_next_wakeup;
+ /** Total task run time */
os_time_t t_run_time;
+ /**
+ * Total number of times this task has been context switched during
+ * execution.
+ */
uint32_t t_ctx_sw_cnt;
- /* Global list of all tasks, irrespective of run or sleep lists */
STAILQ_ENTRY(os_task) t_os_task_list;
-
- /* Used to chain task to either the run or sleep list */
TAILQ_ENTRY(os_task) t_os_list;
-
- /* Used to chain task to an object such as a semaphore or mutex */
SLIST_ENTRY(os_task) t_obj_list;
};
+/** @cond INTERNAL_HIDDEN */
STAILQ_HEAD(os_task_stailq, os_task);
extern struct os_task_stailq g_os_task_list;
+/** @endcond */
+/**
+ * Initialize a task.
+ *
+ * This function initializes the task structure pointed to by t,
+ * clearing and setting it's stack pointer, provides sane defaults
+ * and sets the task as ready to run, and inserts it into the operating
+ * system scheduler.
+ *
+ * @param t The task to initialize
+ * @param name The name of the task to initialize
+ * @param func The task function to call
+ * @param arg The argument to pass to this task function
+ * @param prio The priority at which to run this task
+ * @param sanity_itvl The time at which this task should check in with the
+ * sanity task. OS_WAIT_FOREVER means never check in
+ * here.
+ * @param stack_bottom A pointer to the bottom of a task's stack
+ * @param stack_size The overall size of the task's stack.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
int os_task_init(struct os_task *, const char *, os_task_func_t, void *,
uint8_t, os_time_t, os_stack_t *, uint16_t);
+/**
+ * Removes specified task
+ * XXX
+ * NOTE: This interface is currently experimental and not ready for common use
+ */
int os_task_remove(struct os_task *t);
+/**
+ * Return the number of tasks initialized.
+ *
+ * @return number of tasks initialized
+ */
uint8_t os_task_count(void);
+/**
+ * Information about an individual task, returned for management APIs.
+ */
struct os_task_info {
+ /** Task priority */
uint8_t oti_prio;
+ /** Task identifier */
uint8_t oti_taskid;
+ /** Task state, either READY or SLEEP */
uint8_t oti_state;
+ /** Task stack usage */
uint16_t oti_stkusage;
+ /** Task stack size */
uint16_t oti_stksize;
+ /** Task context switch count */
uint32_t oti_cswcnt;
+ /** Task runtime */
uint32_t oti_runtime;
+ /** Last time this task checked in with sanity */
os_time_t oti_last_checkin;
+ /** Next time this task is scheduled to check-in with sanity */
os_time_t oti_next_checkin;
-
+ /** Name of this task */
char oti_name[OS_TASK_MAX_NAME_LEN];
};
+/**
+ * Iterate through tasks, and return the following information about them:
+ *
+ * - Priority
+ * - Task ID
+ * - State (READY, SLEEP)
+ * - Total Stack Usage
+ * - Stack Size
+ * - Context Switch Count
+ * - Runtime
+ * - Last & Next Sanity checkin
+ * - Task Name
+ *
+ * To get the first task in the list, call os_task_info_get_next() with a
+ * NULL pointer in the prev argument, and os_task_info_get_next() will
+ * return a pointer to the task structure, and fill out the os_task_info
+ * structure pointed to by oti.
+ *
+ * To get the next task in the list, provide the task structure returned
+ * by the previous call to os_task_info_get_next(), and os_task_info_get_next()
+ * will fill out the task structure pointed to by oti again, and return
+ * the next task in the list.
+ *
+ * @param prev The previous task returned by os_task_info_get_next(), or NULL
+ * to begin iteration.
+ * @param oti The OS task info structure to fill out.
+ *
+ * @return A pointer to the OS task that has been read, or NULL when finished
+ * iterating through all tasks.
+ */
struct os_task *os_task_info_get_next(const struct os_task *,
struct os_task_info *);
@@ -126,3 +229,9 @@ struct os_task *os_task_info_get_next(const struct os_task *,
#endif
#endif /* _OS_TASK_H */
+
+
+/**
+ * @} OSTask
+ * @} OSKernel
+ */
diff --git a/kernel/os/include/os/os_time.h b/kernel/os/include/os/os_time.h
index 2fa07e93a..25f076b40 100644
--- a/kernel/os/include/os/os_time.h
+++ b/kernel/os/include/os/os_time.h
@@ -6,7 +6,7 @@
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
@@ -49,6 +49,14 @@
* $FreeBSD$
*/
+
+/**
+ * @addtogroup OSKernel
+ * @{
+ * @defgroup OSTime Time
+ * @{
+ */
+
#ifndef _OS_TIME_H
#define _OS_TIME_H
@@ -66,28 +74,60 @@ extern "C" {
typedef uint32_t os_time_t;
typedef int32_t os_stime_t;
#define OS_TIME_MAX UINT32_MAX
-
+
/* Used to wait forever for events and mutexs */
#define OS_TIMEOUT_NEVER (UINT32_MAX)
+
+/**
+ * Get the current OS time in ticks
+ *
+ * @return OS time in ticks
+ */
os_time_t os_time_get(void);
+
+/**
+ * Move OS time forward ticks.
+ *
+ * @param ticks The number of ticks to move time forward.
+ */
void os_time_advance(int ticks);
+
+/**
+ * Puts the current task to sleep for the specified number of os ticks. There
+ * is no delay if ticks is <= 0.
+ *
+ * @param osticks Number of ticks to delay (<= 0 means no delay).
+ */
void os_time_delay(int32_t osticks);
#define OS_TIME_TICK_LT(__t1, __t2) ((os_stime_t) ((__t1) - (__t2)) < 0)
#define OS_TIME_TICK_GT(__t1, __t2) ((os_stime_t) ((__t1) - (__t2)) > 0)
#define OS_TIME_TICK_GEQ(__t1, __t2) ((os_stime_t) ((__t1) - (__t2)) >= 0)
+/**
+ * Structure representing time since Jan 1 1970 with microsecond
+ * granularity
+ */
struct os_timeval {
- int64_t tv_sec; /* seconds since Jan 1 1970 */
- int32_t tv_usec; /* microseconds within the second */
+ /* Seconds */
+ int64_t tv_sec;
+ /* Microseconds within the second */
+ int32_t tv_usec;
};
+/** Structure representing a timezone offset */
struct os_timezone {
- int16_t tz_minuteswest; /* with respect to GMT */
- int16_t tz_dsttime; /* daylight savings time correction (if any) */
+ /** Minutes west of GMT */
+ int16_t tz_minuteswest;
+ /** Daylight savings time correction (if any) */
+ int16_t tz_dsttime;
};
+/**
+ * Add first two timeval arguments and place results in third timeval
+ * argument.
+ */
#define os_timeradd(tvp, uvp, vvp) \
do { \
(vvp)->tv_sec = (tvp)->tv_sec + (uvp)->tv_sec; \
@@ -98,6 +138,11 @@ struct os_timezone {
} \
} while (0)
+
+/**
+ * Subtract first two timeval arguments and place results in third timeval
+ * argument.
+ */
#define os_timersub(tvp, uvp, vvp) \
do { \
(vvp)->tv_sec = (tvp)->tv_sec - (uvp)->tv_sec; \
@@ -108,9 +153,46 @@ struct os_timezone {
} \
} while (0)
+
+/**
+ * Set the time of day. This does not modify os time, but rather just modifies
+ * the offset by which we are tracking real time against os time.
+ *
+ * @param utctime A timeval representing the UTC time we are setting
+ * @param tz The time-zone to apply against the utctime being set.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
int os_settimeofday(struct os_timeval *utctime, struct os_timezone *tz);
+
+/**
+ * Get the current time of day. Returns the time of day in UTC
+ * into the tv argument, and returns the timezone (if set) into
+ * tz.
+ *
+ * @param tv The structure to put the UTC time of day into
+ * @param tz The structure to put the timezone information into
+ *
+ * @return 0 on success, non-zero on failure
+ */
int os_gettimeofday(struct os_timeval *utctime, struct os_timezone *tz);
+
+/**
+ * Get time since boot in microseconds.
+ *
+ * @return time since boot in microseconds
+ */
int64_t os_get_uptime_usec(void);
+
+/**
+ * Converts milliseconds to OS ticks.
+ *
+ * @param ms The milliseconds input.
+ * @param out_ticks The OS ticks output.
+ *
+ * @return 0 on success; OS_EINVAL if the result is too
+ * large to fit in a uint32_t.
+ */
int os_time_ms_to_ticks(uint32_t ms, uint32_t *out_ticks);
#ifdef __cplusplus
@@ -118,3 +200,9 @@ int os_time_ms_to_ticks(uint32_t ms, uint32_t *out_ticks);
#endif
#endif /* _OS_TIME_H */
+
+
+/**
+ * @} OSKernel
+ * @} OSTime
+ */
diff --git a/kernel/os/src/os.c b/kernel/os/src/os.c
index a6389c05b..438694f80 100644
--- a/kernel/os/src/os.c
+++ b/kernel/os/src/os.c
@@ -166,10 +166,6 @@ os_init_idle_task(void)
assert(rc == 0);
}
-/**
- * Initialize the operating system, calls into the architecture specific
- * support to initialize the operating system.
- */
void
os_init(int (*main_fn)(int argc, char **arg))
{
@@ -201,10 +197,6 @@ os_init(int (*main_fn)(int argc, char **arg))
assert(err == OS_OK);
}
-/**
- * Start the operating system, calls into the architecture specific support
- * to start the operating system.
- */
void
os_start(void)
{
diff --git a/kernel/os/src/os_callout.c b/kernel/os/src/os_callout.c
index 560fa516b..61d7c89e5 100644
--- a/kernel/os/src/os_callout.c
+++ b/kernel/os/src/os_callout.c
@@ -23,31 +23,8 @@
#include "os/os.h"
#include "os_priv.h"
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSCallouts Event Timers (Callouts)
- * @{
- */
struct os_callout_list g_callout_list;
-/**
- * Initialize a callout.
- *
- * Callouts are used to schedule events in the future onto a task's event
- * queue. Callout timers are scheduled using the os_callout_reset()
- * function. When the timer expires, an event is posted to the event
- * queue specified in os_callout_init(). The event argument given here
- * is posted in the ev_arg field of that event.
- *
- * @param c The callout to initialize
- * @param evq The event queue to post an OS_EVENT_T_TIMER event to
- * @param timo_func The function to call on this callout for the host task
- * used to provide multiple timer events to a task
- * (this can be NULL.)
- * @param ev_arg The argument to provide to the event when posting the
- * timer.
- */
void os_callout_init(struct os_callout *c, struct os_eventq *evq,
os_event_fn *ev_cb, void *ev_arg)
{
@@ -57,11 +34,6 @@ void os_callout_init(struct os_callout *c, struct os_eventq *evq,
c->c_evq = evq;
}
-/**
- * Stop the callout from firing off, any pending events will be cleared.
- *
- * @param c The callout to stop
- */
void
os_callout_stop(struct os_callout *c)
{
@@ -81,14 +53,6 @@ os_callout_stop(struct os_callout *c)
OS_EXIT_CRITICAL(sr);
}
-/**
- * Reset the callout to fire off in 'ticks' ticks.
- *
- * @param c The callout to reset
- * @param ticks The number of ticks to wait before posting an event
- *
- * @return 0 on success, non-zero on failure
- */
int
os_callout_reset(struct os_callout *c, int32_t ticks)
{
@@ -131,6 +95,7 @@ os_callout_reset(struct os_callout *c, int32_t ticks)
return (rc);
}
+
/**
* This function is called by the OS in the time tick. It searches the list
* of callouts, and sees if any of them are ready to run. If they are ready
@@ -201,15 +166,9 @@ os_callout_wakeup_ticks(os_time_t now)
return (rt);
}
-/*
- * Returns the number of ticks which remains to callout..
- *
- * @param c callout
- * @param now The time now
- *
- * @return Number of ticks to first pending callout
- */
-os_time_t os_callout_remaining_ticks(struct os_callout *c, os_time_t now)
+
+os_time_t
+os_callout_remaining_ticks(struct os_callout *c, os_time_t now)
{
os_time_t rt;
@@ -224,7 +183,3 @@ os_time_t os_callout_remaining_ticks(struct os_callout *c, os_time_t now)
return rt;
}
-/**
- * @} Callout Timers
- * @} OS Kernel
- */
diff --git a/kernel/os/src/os_cputime.c b/kernel/os/src/os_cputime.c
index 19b0b8241..6713ad5d1 100644
--- a/kernel/os/src/os_cputime.c
+++ b/kernel/os/src/os_cputime.c
@@ -23,28 +23,10 @@
#include "os/os.h"
#include "os/os_cputime.h"
-/**
- * @addtogroup OSKernel Operating System Kernel
- * @{
- * @defgroup OSCPUTime High Resolution Timers
- * @{
- */
-
#if defined(OS_CPUTIME_FREQ_HIGH)
struct os_cputime_data g_os_cputime;
#endif
-/**
- * os cputime init
- *
- * Initialize the cputime module. This must be called after os_init is called
- * and before any other timer API are used. This should be called only once
- * and should be called before the hardware timer is used.
- *
- * @param clock_freq The desired cputime frequency, in hertz (Hz).
- *
- * @return int 0 on success; -1 on error.
- */
int
os_cputime_init(uint32_t clock_freq)
{
@@ -59,8 +41,6 @@ os_cputime_init(uint32_t clock_freq)
}
/**
- * os cputime delay ticks
- *
* Wait until the number of ticks has elapsed. This is a blocking delay.
*
* @param ticks The number of ticks to wait.
@@ -77,13 +57,6 @@ os_cputime_delay_ticks(uint32_t ticks)
}
#if !defined(OS_CPUTIME_FREQ_PWR2)
-/**
- * os cputime delay nsecs
- *
- * Wait until 'nsecs' nanoseconds has elapsed. This is a blocking delay.
- *
- * @param nsecs The number of nanoseconds to wait.
- */
void
os_cputime_delay_nsecs(uint32_t nsecs)
{
@@ -94,13 +67,6 @@ os_cputime_delay_nsecs(uint32_t nsecs)
}
#endif
-/**
- * os cputime delay usecs
- *
- * Wait until 'usecs' microseconds has elapsed. This is a blocking delay.
- *
- * @param usecs The number of usecs to wait.
- */
void
os_cputime_delay_usecs(uint32_t usecs)
{
@@ -110,13 +76,6 @@ os_cputime_delay_usecs(uint32_t usecs)
os_cputime_delay_ticks(ticks);
}
-/**
- * os cputime timer init
- *
- * @param timer The timer to initialize. Cannot be NULL.
- * @param fp The timer callback function. Cannot be NULL.
- * @param arg Pointer to data object to pass to timer.
- */
void
os_cputime_timer_init(struct hal_timer *timer, hal_timer_cb fp, void *arg)
{
@@ -126,21 +85,6 @@ os_cputime_timer_init(struct hal_timer *timer, hal_timer_cb fp, void *arg)
hal_timer_set_cb(MYNEWT_VAL(OS_CPUTIME_TIMER_NUM), timer, fp, arg);
}
-/**
- * os cputime timer start
- *
- * Start a cputimer that will expire at 'cputime'. If cputime has already
- * passed, the timer callback will still be called (at interrupt context).
- *
- * NOTE: This must be called when the timer is stopped.
- *
- * @param timer Pointer to timer to start. Cannot be NULL.
- * @param cputime The cputime at which the timer should expire.
- *
- * @return int 0 on success; EINVAL if timer already started or timer struct
- * invalid
- *
- */
int
os_cputime_timer_start(struct hal_timer *timer, uint32_t cputime)
{
@@ -150,20 +94,6 @@ os_cputime_timer_start(struct hal_timer *timer, uint32_t cputime)
return rc;
}
-/**
- * os cputimer timer relative
- *
- * Sets a cpu timer that will expire 'usecs' microseconds from the current
- * cputime.
- *
- * NOTE: This must be called when the timer is stopped.
- *
- * @param timer Pointer to timer. Cannot be NULL.
- * @param usecs The number of usecs from now at which the timer will expire.
- *
- * @return int 0 on success; EINVAL if timer already started or timer struct
- * invalid
- */
int
os_cputime_timer_relative(struct hal_timer *timer, uint32_t usecs)
{
@@ -178,28 +108,12 @@ os_cputime_timer_relative(struct hal_timer *timer, uint32_t usecs)
return rc;
}
-/**
- * os cputime timer stop
- *
- * Stops a cputimer from running. The timer is removed from the timer queue
- * and interrupts are disabled if no timers are left on the queue. Can be
- * called even if timer is not running.
- *
- * @param timer Pointer to cputimer to stop. Cannot be NULL.
- */
void
os_cputime_timer_stop(struct hal_timer *timer)
{
hal_timer_stop(timer);
}
-/**
- * os cputime get32
- *
- * Returns current value of cputime.
- *
- * @return uint32_t cputime
- */
uint32_t
os_cputime_get32(void)
{
@@ -209,7 +123,3 @@ os_cputime_get32(void)
return cpu_time;
}
-/**
- * @} OSCPUTime
- * @} OSKernel
- */
diff --git a/kernel/os/src/os_dev.c b/kernel/os/src/os_dev.c
index 07b1c5450..96708ab62 100644
--- a/kernel/os/src/os_dev.c
+++ b/kernel/os/src/os_dev.c
@@ -23,12 +23,6 @@
#include <string.h>
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSDevice Device Framework
- * @{
- */
static STAILQ_HEAD(, os_dev) g_os_dev_list;
@@ -117,21 +111,6 @@ os_dev_initialize(struct os_dev *dev)
return rc;
}
-
-/**
- * Create a new device in the kernel.
- *
- * @param dev The device to create.
- * @param name The name of the device to create.
- * @param stage The stage to initialize that device to.
- * @param priority The priority of initializing that device
- * @param od_init The initialization function to call for this
- * device.
- * @param arg The argument to provide this device initialization
- * function.
- *
- * @return 0 on success, non-zero on failure.
- */
int
os_dev_create(struct os_dev *dev, char *name, uint8_t stage,
uint8_t priority, os_dev_init_func_t od_init, void *arg)
@@ -155,13 +134,6 @@ os_dev_create(struct os_dev *dev, char *name, uint8_t stage,
return (rc);
}
-/**
- * Initialize all devices for a given state.
- *
- * @param stage The stage to initialize.
- *
- * @return 0 on success, non-zero on failure.
- */
int
os_dev_initialize_all(uint8_t stage)
{
@@ -180,16 +152,6 @@ os_dev_initialize_all(uint8_t stage)
return (rc);
}
-/**
- * Suspend all devices.
- *
- * @param dev The device to suspend
- * @param suspend_t The number of ticks to suspend this device for
- * @param force Whether or not to force suspending the device
- *
- * @return 0 on success, or a non-zero error code if one of the devices
- * returned it.
- */
int
os_dev_suspend_all(os_time_t suspend_t, uint8_t force)
{
@@ -208,11 +170,6 @@ os_dev_suspend_all(os_time_t suspend_t, uint8_t force)
return (suspend_failure);
}
-/**
- * Resume all the devices that were suspended.
- *
- * @return 0 on success, -1 if any of the devices have failed to resume.
- */
int
os_dev_resume_all(void)
{
@@ -231,16 +188,6 @@ os_dev_resume_all(void)
return (rc);
}
-/**
- * Lookup a device by name.
- *
- * WARNING: This should be called before any locking on the device is done, or
- * the device list itself is modified in any context. There is no locking.
- *
- * @param name The name of the device to look up.
- *
- * @return A pointer to the device corresponding to name, or NULL if not found.
- */
struct os_dev *
os_dev_lookup(char *name)
{
@@ -255,15 +202,6 @@ os_dev_lookup(char *name)
return (dev);
}
-/**
- * Open a device.
- *
- * @param dev The device to open
- * @param timo The timeout to open the device, if not specified.
- * @param arg The argument to the device open() call.
- *
- * @return 0 on success, non-zero on failure.
- */
struct os_dev *
os_dev_open(char *devname, uint32_t timo, void *arg)
{
@@ -298,13 +236,6 @@ os_dev_open(char *devname, uint32_t timo, void *arg)
return (NULL);
}
-/**
- * Close a device.
- *
- * @param dev The device to close
- *
- * @return 0 on success, non-zero on failure.
- */
int
os_dev_close(struct os_dev *dev)
{
@@ -329,18 +260,9 @@ os_dev_close(struct os_dev *dev)
return (rc);
}
-/**
- * Clears the device list. This function does not close any devices or free
- * any resources; its purpose is to allow a full system reset between unit
- * tests.
- */
void
os_dev_reset(void)
{
STAILQ_INIT(&g_os_dev_list);
}
-/**
- * @} OSDevice
- * @} OSKernel
- */
diff --git a/kernel/os/src/os_eventq.c b/kernel/os/src/os_eventq.c
index b09c81f22..3308eea13 100644
--- a/kernel/os/src/os_eventq.c
+++ b/kernel/os/src/os_eventq.c
@@ -23,20 +23,8 @@
#include "os/os.h"
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSEvent Event Queues
- * @{
- */
-
static struct os_eventq os_eventq_main;
-/**
- * Initialize the event queue
- *
- * @param evq The event queue to initialize
- */
void
os_eventq_init(struct os_eventq *evq)
{
@@ -50,12 +38,6 @@ os_eventq_inited(const struct os_eventq *evq)
return evq->evq_list.stqh_last != NULL;
}
-/**
- * Put an event on the event queue.
- *
- * @param evq The event queue to put an event on
- * @param ev The event to put on the queue
- */
void
os_eventq_put(struct os_eventq *evq, struct os_event *ev)
{
@@ -114,14 +96,6 @@ os_eventq_get_no_wait(struct os_eventq *evq)
return ev;
}
-/**
- * Pull a single item from an event queue. This function blocks until there
- * is an item on the event queue to read.
- *
- * @param evq The event queue to pull an event from
- *
- * @return The event from the queue
- */
struct os_event *
os_eventq_get(struct os_eventq *evq)
{
@@ -201,18 +175,6 @@ os_eventq_poll_0timo(struct os_eventq **evq, int nevqs)
return ev;
}
-/**
- * Poll the list of event queues specified by the evq parameter
- * (size nevqs), and return the "first" event available on any of
- * the queues. Event queues are searched in the order that they
- * are passed in the array.
- *
- * @param evq Array of event queues
- * @param nevqs Number of event queues in evq
- * @param timo Timeout, forever if OS_WAIT_FOREVER is passed to poll.
- *
- * @return An event, or NULL if no events available
- */
struct os_event *
os_eventq_poll(struct os_eventq **evq, int nevqs, os_time_t timo)
{
@@ -279,12 +241,6 @@ os_eventq_poll(struct os_eventq **evq, int nevqs, os_time_t timo)
return (ev);
}
-/**
- * Remove an event from the queue.
- *
- * @param evq The event queue to remove the event from
- * @param ev The event to remove from the queue
- */
void
os_eventq_remove(struct os_eventq *evq, struct os_event *ev)
{
@@ -298,11 +254,6 @@ os_eventq_remove(struct os_eventq *evq, struct os_event *ev)
OS_EXIT_CRITICAL(sr);
}
-/**
- * Retrieves the default event queue processed by OS main task.
- *
- * @return The default event queue.
- */
struct os_eventq *
os_eventq_dflt_get(void)
{
@@ -348,7 +299,3 @@ os_eventq_designate(struct os_eventq **cur_evq,
}
}
-/**
- * @} OSEvent
- * @} OSKernel
- */
diff --git a/kernel/os/src/os_heap.c b/kernel/os/src/os_heap.c
index 0d94325a1..d62c34b3c 100644
--- a/kernel/os/src/os_heap.c
+++ b/kernel/os/src/os_heap.c
@@ -22,13 +22,6 @@
#include "os/os_mutex.h"
#include "os/os_heap.h"
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSGeneral
- * @{
- */
-
#if MYNEWT_VAL(OS_SCHEDULING)
static struct os_mutex os_malloc_mutex;
#endif
@@ -59,16 +52,6 @@ os_malloc_unlock(void)
#endif
}
-/**
- * Operating system level malloc(). This ensures that a safe malloc occurs
- * within the context of the OS. Depending on platform, the OS may rely on
- * libc's malloc() implementation, which is not guaranteed to be thread-safe.
- * This malloc() will always be thread-safe.
- *
- * @param size The number of bytes to allocate
- *
- * @return A pointer to the memory region allocated.
- */
void *
os_malloc(size_t size)
{
@@ -81,13 +64,6 @@ os_malloc(size_t size)
return ptr;
}
-/**
- * Operating system level free(). See description of os_malloc() for reasoning.
- *
- * Free's memory allocated by malloc.
- *
- * @param mem The memory to free.
- */
void
os_free(void *mem)
{
@@ -96,16 +72,6 @@ os_free(void *mem)
os_malloc_unlock();
}
-/**
- * Operating system level realloc(). See description of os_malloc() for reasoning.
- *
- * Reallocates the memory at ptr, to be size contiguouos bytes.
- *
- * @param ptr A pointer to the memory to allocate
- * @param size The number of contiguouos bytes to allocate at that location
- *
- * @return A pointer to memory of size, or NULL on failure to allocate
- */
void *
os_realloc(void *ptr, size_t size)
{
@@ -118,7 +84,3 @@ os_realloc(void *ptr, size_t size)
return new_ptr;
}
-/**
- * @} OSGeneral
- * @} OS Kernel
- */
diff --git a/kernel/os/src/os_mbuf.c b/kernel/os/src/os_mbuf.c
index 0a1cb968b..bb04062c4 100644
--- a/kernel/os/src/os_mbuf.c
+++ b/kernel/os/src/os_mbuf.c
@@ -49,23 +49,7 @@
STAILQ_HEAD(, os_mbuf_pool) g_msys_pool_list =
STAILQ_HEAD_INITIALIZER(g_msys_pool_list);
-/**
- * Initializes an mqueue. An mqueue is a queue of mbufs that ties to a
- * particular task's event queue. Mqueues form a helper API around a common
- * paradigm: wait on an event queue until at least one packet is available,
- * then process a queue of packets.
- *
- * When mbufs are available on the queue, an event OS_EVENT_T_MQUEUE_DATA
- * will be posted to the task's mbuf queue.
- *
- * @param mq The mqueue to initialize
- * @param ev_cb The callback to associate with the mqeueue
- * event. Typically, this callback pulls each
- * packet off the mqueue and processes them.
- * @param arg The argument to associate with the mqueue event.
- *
- * @return 0 on success, non-zero on failure.
- */
+
int
os_mqueue_init(struct os_mqueue *mq, os_event_fn *ev_cb, void *arg)
{
@@ -81,13 +65,6 @@ os_mqueue_init(struct os_mqueue *mq, os_event_fn *ev_cb, void *arg)
return (0);
}
-/**
- * Remove and return a single mbuf from the mbuf queue. Does not block.
- *
- * @param mq The mbuf queue to pull an element off of.
- *
- * @return The next mbuf in the queue, or NULL if queue has no mbufs.
- */
struct os_mbuf *
os_mqueue_get(struct os_mqueue *mq)
{
@@ -111,16 +88,6 @@ os_mqueue_get(struct os_mqueue *mq)
return (m);
}
-/**
- * Adds a packet (i.e. packet header mbuf) to an mqueue. The event associated
- * with the mqueue gets posted to the specified eventq.
- *
- * @param mq The mbuf queue to append the mbuf to.
- * @param evq The event queue to post an event to.
- * @param m The mbuf to append to the mbuf queue.
- *
- * @return 0 on success, non-zero on failure.
- */
int
os_mqueue_put(struct os_mqueue *mq, struct os_eventq *evq, struct os_mbuf *m)
{
@@ -150,35 +117,6 @@ os_mqueue_put(struct os_mqueue *mq, struct os_eventq *evq, struct os_mbuf *m)
return (rc);
}
-/**
- * @} OSMqueue
- * @} OSKernel
- */
-
-
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSMsys System level mbuf
- * @{
- */
-
-/**
- * MSYS is a system level mbuf registry. Allows the system to share
- * packet buffers amongst the various networking stacks that can be running
- * simultaeneously.
- *
- * Mbuf pools are created in the system initialization code, and then when
- * a mbuf is allocated out of msys, it will try and find the best fit based
- * upon estimated mbuf size.
- *
- * os_msys_register() registers a mbuf pool with MSYS, and allows MSYS to
- * allocate mbufs out of it.
- *
- * @param new_pool The pool to register with MSYS
- *
- * @return 0 on success, non-zero on failure
- */
int
os_msys_register(struct os_mbuf_pool *new_pool)
{
@@ -200,9 +138,6 @@ os_msys_register(struct os_mbuf_pool *new_pool)
return (0);
}
-/**
- * De-registers all mbuf pools from msys.
- */
void
os_msys_reset(void)
{
@@ -228,16 +163,7 @@ _os_msys_find_pool(uint16_t dsize)
return (pool);
}
-/**
- * Allocate a mbuf from msys. Based upon the data size requested,
- * os_msys_get() will choose the mbuf pool that has the best fit.
- *
- * @param dsize The estimated size of the data being stored in the mbuf
- * @param leadingspace The amount of leadingspace to allocate in the mbuf
- *
- * @return A freshly allocated mbuf on success, NULL on failure.
- *
- */
+
struct os_mbuf *
os_msys_get(uint16_t dsize, uint16_t leadingspace)
{
@@ -255,15 +181,6 @@ os_msys_get(uint16_t dsize, uint16_t leadingspace)
return (NULL);
}
-/**
- * Allocate a packet header structure from the MSYS pool. See
- * os_msys_register() for a description of MSYS.
- *
- * @param dsize The estimated size of the data being stored in the mbuf
- * @param user_hdr_len The length to allocate for the packet header structure
- *
- * @return A freshly allocated mbuf on success, NULL on failure.
- */
struct os_mbuf *
os_msys_get_pkthdr(uint16_t dsize, uint16_t user_hdr_len)
{
@@ -311,30 +228,7 @@ os_msys_num_free(void)
return total;
}
-/**
- * @} OSMsys
- * @} OSKernel
- */
-
-
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSMbuf Chained Memory Buffers
- * @{
- */
-
-/**
- * Initialize a pool of mbufs.
- *
- * @param omp The mbuf pool to initialize
- * @param mp The memory pool that will hold this mbuf pool
- * @param buf_len The length of the buffer itself.
- * @param nbufs The number of buffers in the pool
- *
- * @return 0 on success, error code on failure.
- */
int
os_mbuf_pool_init(struct os_mbuf_pool *omp, struct os_mempool *mp,
uint16_t buf_len, uint16_t nbufs)
@@ -345,16 +239,6 @@ os_mbuf_pool_init(struct os_mbuf_pool *omp, struct os_mempool *mp,
return (0);
}
-/**
- * Get an mbuf from the mbuf pool. The mbuf is allocated, and initialized
- * prior to being returned.
- *
- * @param omp The mbuf pool to return the packet from
- * @param leadingspace The amount of leadingspace to put before the data
- * section by default.
- *
- * @return An initialized mbuf on success, and NULL on failure.
- */
struct os_mbuf *
os_mbuf_get(struct os_mbuf_pool *omp, uint16_t leadingspace)
{
@@ -381,14 +265,6 @@ os_mbuf_get(struct os_mbuf_pool *omp, uint16_t leadingspace)
return (NULL);
}
-/**
- * Allocate a new packet header mbuf out of the os_mbuf_pool.
- *
- * @param omp The mbuf pool to allocate out of
- * @param user_pkthdr_len The packet header length to reserve for the caller.
- *
- * @return A freshly allocated mbuf on success, NULL on failure.
- */
struct os_mbuf *
os_mbuf_get_pkthdr(struct os_mbuf_pool *omp, uint8_t user_pkthdr_len)
{
@@ -416,14 +292,6 @@ os_mbuf_get_pkthdr(struct os_mbuf_pool *omp, uint8_t user_pkthdr_len)
return om;
}
-/**
- * Release a mbuf back to the pool
- *
- * @param omp The Mbuf pool to release back to
- * @param om The Mbuf to release back to the pool
- *
- * @return 0 on success, -1 on failure
- */
int
os_mbuf_free(struct os_mbuf *om)
{
@@ -441,14 +309,6 @@ os_mbuf_free(struct os_mbuf *om)
return (rc);
}
-/**
- * Free a chain of mbufs
- *
- * @param omp The mbuf pool to free the chain of mbufs into
- * @param om The starting mbuf of the chain to free back into the pool
- *
- * @return 0 on success, -1 on failure
- */
int
os_mbuf_free_chain(struct os_mbuf *om)
{
@@ -489,15 +349,6 @@ _os_mbuf_copypkthdr(struct os_mbuf *new_buf, struct os_mbuf *old_buf)
new_buf->om_data = new_buf->om_databuf + old_buf->om_pkthdr_len;
}
-/**
- * Append data onto a mbuf
- *
- * @param om The mbuf to append the data onto
- * @param data The data to append onto the mbuf
- * @param len The length of the data to append
- *
- * @return 0 on success, and an error code on failure
- */
int
os_mbuf_append(struct os_mbuf *om, const void *data, uint16_t len)
{
@@ -572,21 +423,6 @@ os_mbuf_append(struct os_mbuf *om, const void *data, uint16_t len)
return (rc);
}
-/**
- * Reads data from one mbuf and appends it to another. On error, the specified
- * data range may be partially appended. Neither mbuf is required to contain
- * an mbuf packet header.
- *
- * @param dst The mbuf to append to.
- * @param src The mbuf to copy data from.
- * @param src_off The absolute offset within the source mbuf
- * chain to read from.
- * @param len The number of bytes to append.
- *
- * @return 0 on success;
- * OS_EINVAL if the specified range extends beyond
- * the end of the source mbuf chain.
- */
int
os_mbuf_appendfrom(struct os_mbuf *dst, const struct os_mbuf *src,
uint16_t src_off, uint16_t len)
@@ -616,14 +452,6 @@ os_mbuf_appendfrom(struct os_mbuf *dst, const struct os_mbuf *src,
return 0;
}
-/**
- * Duplicate a chain of mbufs. Return the start of the duplicated chain.
- *
- * @param omp The mbuf pool to duplicate out of
- * @param om The mbuf chain to duplicate
- *
- * @return A pointer to the new chain of mbufs
- */
struct os_mbuf *
os_mbuf_dup(struct os_mbuf *om)
{
@@ -668,19 +496,6 @@ os_mbuf_dup(struct os_mbuf *om)
return (NULL);
}
-/**
- * Locates the specified absolute offset within an mbuf chain. The offset
- * can be one past than the total length of the chain, but no greater.
- *
- * @param om The start of the mbuf chain to seek within.
- * @param off The absolute address to find.
- * @param out_off On success, this points to the relative offset
- * within the returned mbuf.
- *
- * @return The mbuf containing the specified offset on
- * success.
- * NULL if the specified offset is out of bounds.
- */
struct os_mbuf *
os_mbuf_off(const struct os_mbuf *om, int off, uint16_t *out_off)
{
@@ -709,18 +524,6 @@ os_mbuf_off(const struct os_mbuf *om, int off, uint16_t *out_off)
}
}
-/*
- * Copy data from an mbuf chain starting "off" bytes from the beginning,
- * continuing for "len" bytes, into the indicated buffer.
- *
- * @param m The mbuf chain to copy from
- * @param off The offset into the mbuf chain to begin copying from
- * @param len The length of the data to copy
- * @param dst The destination buffer to copy into
- *
- * @return 0 on success;
- * -1 if the mbuf does not contain enough data.
- */
int
os_mbuf_copydata(const struct os_mbuf *m, int off, int len, void *dst)
{
@@ -755,15 +558,6 @@ os_mbuf_copydata(const struct os_mbuf *m, int off, int len, void *dst)
return (len > 0 ? -1 : 0);
}
-/**
- * Adjust the length of a mbuf, trimming either from the head or the tail
- * of the mbuf.
- *
- * @param mp The mbuf chain to adjust
- * @param req_len The length to trim from the mbuf. If positive, trims
- * from the head of the mbuf, if negative, trims from the
- * tail of the mbuf.
- */
void
os_mbuf_adj(struct os_mbuf *mp, int req_len)
{
@@ -837,20 +631,6 @@ os_mbuf_adj(struct os_mbuf *mp, int req_len)
}
}
-/**
- * Performs a memory compare of the specified region of an mbuf chain against a
- * flat buffer.
- *
- * @param om The start of the mbuf chain to compare.
- * @param off The offset within the mbuf chain to start the
- * comparison.
- * @param data The flat buffer to compare.
- * @param len The length of the flat buffer.
- *
- * @return 0 if both memory regions are identical;
- * A memcmp return code if there is a mismatch;
- * INT_MAX if the mbuf is too short.
- */
int
os_mbuf_cmpf(const struct os_mbuf *om, int off, const void *data, int len)
{
@@ -892,25 +672,6 @@ os_mbuf_cmpf(const struct os_mbuf *om, int off, const void *data, int len)
}
}
-/**
- * Compares the contents of two mbuf chains. The ranges of the two chains to
- * be compared are specified via the two offset parameters and the len
- * parameter. Neither mbuf chain is required to contain a packet header.
- *
- * @param om1 The first mbuf chain to compare.
- * @param offset1 The absolute offset within om1 at which to
- * start the comparison.
- * @param om2 The second mbuf chain to compare.
- * @param offset2 The absolute offset within om2 at which to
- * start the comparison.
- * @param len The number of bytes to compare.
- *
- * @return 0 if both mbuf segments are identical;
- * A memcmp() return code if the segment contents
- * differ;
- * INT_MAX if a specified range extends beyond the
- * end of its corresponding mbuf chain.
- */
int
os_mbuf_cmpm(const struct os_mbuf *om1, uint16_t offset1,
const struct os_mbuf *om2, uint16_t offset2,
@@ -967,21 +728,6 @@ os_mbuf_cmpm(const struct os_mbuf *om1, uint16_t offset1,
}
}
-/**
- * Increases the length of an mbuf chain by adding data to the front. If there
- * is insufficient room in the leading mbuf, additional mbufs are allocated and
- * prepended as necessary. If this function fails to allocate an mbuf, the
- * entire chain is freed.
- *
- * The specified mbuf chain does not need to contain a packet header.
- *
- * @param omp The mbuf pool to allocate from.
- * @param om The head of the mbuf chain.
- * @param len The number of bytes to prepend.
- *
- * @return The new head of the chain on success;
- * NULL on failure.
- */
struct os_mbuf *
os_mbuf_prepend(struct os_mbuf *om, int len)
{
@@ -1035,17 +781,6 @@ os_mbuf_prepend(struct os_mbuf *om, int len)
return om;
}
-/**
- * Prepends a chunk of empty data to the specified mbuf chain and ensures the
- * chunk is contiguous. If either operation fails, the specified mbuf chain is
- * freed and NULL is returned.
- *
- * @param om The mbuf chain to prepend to.
- * @param len The number of bytes to prepend and pullup.
- *
- * @return The modified mbuf on success;
- * NULL on failure (and the mbuf chain is freed).
- */
struct os_mbuf *
os_mbuf_prepend_pullup(struct os_mbuf *om, uint16_t len)
{
@@ -1062,20 +797,6 @@ os_mbuf_prepend_pullup(struct os_mbuf *om, uint16_t len)
return om;
}
-/**
- * Copies the contents of a flat buffer into an mbuf chain, starting at the
- * specified destination offset. If the mbuf is too small for the source data,
- * it is extended as necessary. If the destination mbuf contains a packet
- * header, the header length is updated.
- *
- * @param omp The mbuf pool to allocate from.
- * @param om The mbuf chain to copy into.
- * @param off The offset within the chain to copy to.
- * @param src The source buffer to copy from.
- * @param len The number of bytes to copy.
- *
- * @return 0 on success; nonzero on failure.
- */
int
os_mbuf_copyinto(struct os_mbuf *om, int off, const void *src, int len)
{
@@ -1133,14 +854,6 @@ os_mbuf_copyinto(struct os_mbuf *om, int off, const void *src, int len)
return 0;
}
-/**
- * Attaches a second mbuf chain onto the end of the first. If the first chain
- * contains a packet header, the header's length is updated. If the second
- * chain has a packet header, its header is cleared.
- *
- * @param first The mbuf chain being attached to.
- * @param second The mbuf chain that gets attached.
- */
void
os_mbuf_concat(struct os_mbuf *first, struct os_mbuf *second)
{
@@ -1177,19 +890,6 @@ os_mbuf_concat(struct os_mbuf *first, struct os_mbuf *second)
second->om_pkthdr_len = 0;
}
-/**
- * Increases the length of an mbuf chain by the specified amount. If there is
- * not sufficient room in the last buffer, a new buffer is allocated and
- * appended to the chain. It is an error to request more data than can fit in
- * a single buffer.
- *
- * @param omp
- * @param om The head of the chain to extend.
- * @param len The number of bytes to extend by.
- *
- * @return A pointer to the new data on success;
- * NULL on failure.
- */
void *
os_mbuf_extend(struct os_mbuf *om, uint16_t len)
{
@@ -1227,22 +927,7 @@ os_mbuf_extend(struct os_mbuf *om, uint16_t len)
return data;
}
-/**
- * Rearrange a mbuf chain so that len bytes are contiguous,
- * and in the data area of an mbuf (so that OS_MBUF_DATA() will
- * work on a structure of size len.) Returns the resulting
- * mbuf chain on success, free's it and returns NULL on failure.
- *
- * If there is room, it will add up to "max_protohdr - len"
- * extra bytes to the contiguous region, in an attempt to avoid being
- * called next time.
- *
- * @param omp The mbuf pool to take the mbufs out of
- * @param om The mbuf chain to make contiguous
- * @param len The number of bytes in the chain to make contiguous
- *
- * @return The contiguous mbuf chain on success, NULL on failure.
- */
+
struct os_mbuf *
os_mbuf_pullup(struct os_mbuf *om, uint16_t len)
{
@@ -1308,14 +993,6 @@ os_mbuf_pullup(struct os_mbuf *om, uint16_t len)
return (NULL);
}
-/**
- * Removes and frees empty mbufs from the front of a chain. If the chain
- * contains a packet header, it is preserved.
- *
- * @param om The mbuf chain to trim.
- *
- * @return The head of the trimmed mbuf chain.
- */
struct os_mbuf *
os_mbuf_trim_front(struct os_mbuf *om)
{
@@ -1361,7 +1038,3 @@ os_mbuf_trim_front(struct os_mbuf *om)
return om;
}
-/**
- * @} OSMbuf
- * @} OSKernel
- */
diff --git a/kernel/os/src/os_mempool.c b/kernel/os/src/os_mempool.c
index 07aaf9a99..d83697d3b 100644
--- a/kernel/os/src/os_mempool.c
+++ b/kernel/os/src/os_mempool.c
@@ -23,13 +23,6 @@
#include <assert.h>
#include <stdbool.h>
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSMempool Memory Pools
- * @{
- */
-
#define OS_MEM_TRUE_BLOCK_SIZE(bsize) OS_ALIGN(bsize, OS_ALIGNMENT)
#define OS_MEMPOOL_TRUE_BLOCK_SIZE(mp) OS_MEM_TRUE_BLOCK_SIZE(mp->mp_block_size)
@@ -68,19 +61,6 @@ os_mempool_poison_check(void *start, int sz)
#define os_mempool_poison_check(start, sz)
#endif
-/**
- * os mempool init
- *
- * Initialize a memory pool.
- *
- * @param mp Pointer to a pointer to a mempool
- * @param blocks The number of blocks in the pool
- * @param blocks_size The size of the block, in bytes.
- * @param membuf Pointer to memory to contain blocks.
- * @param name Name of the pool.
- *
- * @return os_error_t
- */
os_error_t
os_mempool_init(struct os_mempool *mp, uint16_t blocks, uint32_t block_size,
void *membuf, char *name)
@@ -138,19 +118,6 @@ os_mempool_init(struct os_mempool *mp, uint16_t blocks, uint32_t block_size,
return OS_OK;
}
-/**
- * Initializes an extended memory pool. Extended attributes (e.g., callbacks)
- * are not specified when this function is called; they are assigned manually
- * after initialization.
- *
- * @param mpe The extended memory pool to initialize.
- * @param blocks The number of blocks in the pool.
- * @param block_size The size of each block, in bytes.
- * @param membuf Pointer to memory to contain blocks.
- * @param name Name of the pool.
- *
- * @return os_error_t
- */
os_error_t
os_mempool_ext_init(struct os_mempool_ext *mpe, uint16_t blocks,
uint32_t block_size, void *membuf, char *name)
@@ -169,16 +136,6 @@ os_mempool_ext_init(struct os_mempool_ext *mpe, uint16_t blocks,
return 0;
}
-/**
- * Performs an integrity check of the specified mempool. This function
- * attempts to detect memory corruption in the specified memory pool.
- *
- * @param mp The mempool to check.
- *
- * @return true if the memory pool passes the integrity
- * check;
- * false if the memory pool is corrupt.
- */
bool
os_mempool_is_sane(const struct os_mempool *mp)
{
@@ -195,15 +152,6 @@ os_mempool_is_sane(const struct os_mempool *mp)
return true;
}
-/**
- * Checks if a memory block was allocated from the specified mempool.
- *
- * @param mp The mempool to check as parent.
- * @param block_addr The memory block to check as child.
- *
- * @return 0 if the block does not belong to the mempool;
- * 1 if the block does belong to the mempool.
- */
int
os_memblock_from(const struct os_mempool *mp, const void *block_addr)
{
@@ -231,15 +179,6 @@ os_memblock_from(const struct os_mempool *mp, const void *block_addr)
return 1;
}
-/**
- * os memblock get
- *
- * Get a memory block from a memory pool
- *
- * @param mp Pointer to the memory pool
- *
- * @return void* Pointer to block if available; NULL otherwise
- */
void *
os_memblock_get(struct os_mempool *mp)
{
@@ -272,18 +211,6 @@ os_memblock_get(struct os_mempool *mp)
return (void *)block;
}
-/**
- * os memblock put from cb
- *
- * Puts the memory block back into the pool, ignoring the put callback, if any.
- * This function should only be called from a put callback to free a block
- * without causing infinite recursion.
- *
- * @param mp Pointer to memory pool
- * @param block_addr Pointer to memory block
- *
- * @return os_error_t
- */
os_error_t
os_memblock_put_from_cb(struct os_mempool *mp, void *block_addr)
{
@@ -308,16 +235,6 @@ os_memblock_put_from_cb(struct os_mempool *mp, void *block_addr)
return OS_OK;
}
-/**
- * os memblock put
- *
- * Puts the memory block back into the pool
- *
- * @param mp Pointer to memory pool
- * @param block_addr Pointer to memory block
- *
- * @return os_error_t
- */
os_error_t
os_memblock_put(struct os_mempool *mp, void *block_addr)
{
@@ -384,7 +301,3 @@ os_mempool_info_get_next(struct os_mempool *mp, struct os_mempool_info *omi)
}
-/**
- * @} OSMempool
- * @} OSKernel
- */
diff --git a/kernel/os/src/os_mutex.c b/kernel/os/src/os_mutex.c
index 117045f97..b35807683 100644
--- a/kernel/os/src/os_mutex.c
+++ b/kernel/os/src/os_mutex.c
@@ -21,25 +21,6 @@
#include "os/os_trace_api.h"
#include <assert.h>
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSMutex Mutexes
- * @{
- */
-
-
-/**
- * os mutex create
- *
- * Create a mutex and initialize it.
- *
- * @param mu Pointer to mutex
- *
- * @return os_error_t
- * OS_INVALID_PARM Mutex passed in was NULL.
- * OS_OK no error.
- */
os_error_t
os_mutex_init(struct os_mutex *mu)
{
@@ -58,18 +39,6 @@ os_mutex_init(struct os_mutex *mu)
return OS_OK;
}
-/**
- * os mutex release
- *
- * Release a mutex.
- *
- * @param mu Pointer to the mutex to be released
- *
- * @return os_error_t
- * OS_INVALID_PARM Mutex passed in was NULL.
- * OS_BAD_MUTEX Mutex was not granted to current task (not owner).
- * OS_OK No error
- */
os_error_t
os_mutex_release(struct os_mutex *mu)
{
@@ -145,22 +114,6 @@ os_mutex_release(struct os_mutex *mu)
return OS_OK;
}
-/**
- * os mutex pend
- *
- * Pend (wait) for a mutex.
- *
- * @param mu Pointer to mutex.
- * @param timeout Timeout, in os ticks. A timeout of 0 means do
- * not wait if not available. A timeout of
- * 0xFFFFFFFF means wait forever.
- *
- *
- * @return os_error_t
- * OS_INVALID_PARM Mutex passed in was NULL.
- * OS_TIMEOUT Mutex was owned by another task and timeout=0
- * OS_OK no error.
- */
os_error_t
os_mutex_pend(struct os_mutex *mu, uint32_t timeout)
{
@@ -255,8 +208,3 @@ os_mutex_pend(struct os_mutex *mu, uint32_t timeout)
return rc;
}
-
-/**
- * @} OSMutex
- * @} OSKernel
- */
diff --git a/kernel/os/src/os_sanity.c b/kernel/os/src/os_sanity.c
index 5b967119a..d696d1ee5 100644
--- a/kernel/os/src/os_sanity.c
+++ b/kernel/os/src/os_sanity.c
@@ -22,25 +22,11 @@
#include "os/os.h"
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSSanity Sanity
- * @{
- */
-
SLIST_HEAD(, os_sanity_check) g_os_sanity_check_list =
SLIST_HEAD_INITIALIZER(os_sanity_check_list);
struct os_mutex g_os_sanity_check_mu;
-/**
- * Initialize a sanity check
- *
- * @param sc The sanity check to initialize
- *
- * @return 0 on success, error code on failure.
- */
int
os_sanity_check_init(struct os_sanity_check *sc)
{
@@ -97,13 +83,6 @@ os_sanity_check_list_unlock(void)
return (rc);
}
-/**
- * Provide a "task checkin" for the sanity task.
- *
- * @param t The task to check in
- *
- * @return 0 on success, error code on failure
- */
int
os_sanity_task_checkin(struct os_task *t)
{
@@ -124,13 +103,6 @@ os_sanity_task_checkin(struct os_task *t)
}
-/**
- * Register a sanity check
- *
- * @param sc The sanity check to register
- *
- * @return 0 on success, error code on failure
- */
int
os_sanity_check_register(struct os_sanity_check *sc)
{
@@ -154,14 +126,6 @@ os_sanity_check_register(struct os_sanity_check *sc)
}
-/**
- * Reset the os sanity check, so that it doesn't trip up the
- * sanity timer.
- *
- * @param sc The sanity check to reset
- *
- * @return 0 on success, error code on failure
- */
int
os_sanity_check_reset(struct os_sanity_check *sc)
{
@@ -224,11 +188,6 @@ os_sanity_run(void)
}
}
-/**
- * Initialize the sanity task and mutex.
- *
- * @return 0 on success, error code on failure
- */
int
os_sanity_init(void)
{
@@ -244,7 +203,3 @@ os_sanity_init(void)
return (rc);
}
-/**
- * @} OSSanity
- * @} OSKernel
- */
diff --git a/kernel/os/src/os_sched.c b/kernel/os/src/os_sched.c
index 646db7aaf..682a55de6 100644
--- a/kernel/os/src/os_sched.c
+++ b/kernel/os/src/os_sched.c
@@ -92,15 +92,6 @@ os_sched_ctx_sw_hook(struct os_task *next_t)
g_os_last_ctx_sw_time = g_os_time;
}
-/**
- * os sched get current task
- *
- * Returns the currently running task. Note that this task may or may not be
- * the highest priority task ready to run.
- *
- *
- * @return struct os_task*
- */
struct os_task *
os_sched_get_current_task(void)
{
diff --git a/kernel/os/src/os_sem.c b/kernel/os/src/os_sem.c
index d41ada565..767c9f20c 100644
--- a/kernel/os/src/os_sem.c
+++ b/kernel/os/src/os_sem.c
@@ -20,32 +20,12 @@
#include "os/os.h"
#include <assert.h>
-
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSSem Semaphores
- * @{
- */
-
/* XXX:
* 1) Should I check to see if we are within an ISR for some of these?
* 2) Would I do anything different for os_sem_release() if we were in an
* ISR when this was called?
*/
-/**
- * os sem initialize
- *
- * Initialize a semaphore
- *
- * @param sem Pointer to semaphore
- * tokens: # of tokens the semaphore should contain initially.
- *
- * @return os_error_t
- * OS_INVALID_PARM Semaphore passed in was NULL.
- * OS_OK no error.
- */
os_error_t
os_sem_init(struct os_sem *sem, uint16_t tokens)
{
@@ -59,17 +39,6 @@ os_sem_init(struct os_sem *sem, uint16_t tokens)
return OS_OK;
}
-/**
- * os sem release
- *
- * Release a semaphore.
- *
- * @param sem Pointer to the semaphore to be released
- *
- * @return os_error_t
- * OS_INVALID_PARM Semaphore passed in was NULL.
- * OS_OK No error
- */
os_error_t
os_sem_release(struct os_sem *sem)
{
@@ -120,22 +89,6 @@ os_sem_release(struct os_sem *sem)
return OS_OK;
}
-/**
- * os sem pend
- *
- * Pend (wait) for a semaphore.
- *
- * @param mu Pointer to semaphore.
- * @param timeout Timeout, in os ticks. A timeout of 0 means do
- * not wait if not available. A timeout of
- * 0xFFFFFFFF means wait forever.
- *
- *
- * @return os_error_t
- * OS_INVALID_PARM Semaphore passed in was NULL.
- * OS_TIMEOUT Semaphore was owned by another task and timeout=0
- * OS_OK no error.
- */
os_error_t
os_sem_pend(struct os_sem *sem, uint32_t timeout)
{
@@ -219,7 +172,3 @@ os_sem_pend(struct os_sem *sem, uint32_t timeout)
}
-/**
- * @} OSSem
- * @} OSKernel
- */
diff --git a/kernel/os/src/os_task.c b/kernel/os/src/os_task.c
index 10fceec4b..9cc5e9ec5 100644
--- a/kernel/os/src/os_task.c
+++ b/kernel/os/src/os_task.c
@@ -25,12 +25,6 @@
#include <assert.h>
#include <string.h>
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSTask Tasks
- * @{
- */
uint8_t g_task_id;
@@ -60,38 +54,12 @@ os_task_next_id(void)
return (rc);
}
-/**
- * Return the number of tasks initialized.
- *
- * @return number of tasks initialized
- */
uint8_t
os_task_count(void)
{
return (g_task_id);
}
-/**
- * Initialize a task.
- *
- * This function initializes the task structure pointed to by t,
- * clearing and setting it's stack pointer, provides sane defaults
- * and sets the task as ready to run, and inserts it into the operating
- * system scheduler.
- *
- * @param t The task to initialize
- * @param name The name of the task to initialize
- * @param func The task function to call
- * @param arg The argument to pass to this task function
- * @param prio The priority at which to run this task
- * @param sanity_itvl The time at which this task should check in with the
- * sanity task. OS_WAIT_FOREVER means never check in
- * here.
- * @param stack_bottom A pointer to the bottom of a task's stack
- * @param stack_size The overall size of the task's stack.
- *
- * @return 0 on success, non-zero on failure.
- */
int
os_task_init(struct os_task *t, const char *name, os_task_func_t func,
void *arg, uint8_t prio, os_time_t sanity_itvl,
@@ -154,11 +122,6 @@ os_task_init(struct os_task *t, const char *name, os_task_func_t func,
return (rc);
}
-/*
- * Removes specified task
- * XXX
- * NOTE: This interface is currently experimental and not ready for common use
- */
int
os_task_remove(struct os_task *t)
{
@@ -203,36 +166,7 @@ os_task_remove(struct os_task *t)
return rc;
}
-/**
- * Iterate through tasks, and return the following information about them:
- *
- * - Priority
- * - Task ID
- * - State (ACTIVE, SLEEP)
- * - Total Stack Usage
- * - Stack Size
- * - Context Switch Count
- * - Runtime
- * - Last & Next Sanity checkin
- * - Task Name
- *
- * To get the first task in the list, call os_task_info_get_next() with a
- * NULL pointer in the prev argument, and os_task_info_get_next() will
- * return a pointer to the task structure, and fill out the os_task_info
- * structure pointed to by oti.
- *
- * To get the next task in the list, provide the task structure returned
- * by the previous call to os_task_info_get_next(), and os_task_info_get_next()
- * will fill out the task structure pointed to by oti again, and return
- * the next task in the list.
- *
- * @param prev The previous task returned by os_task_info_get_next(), or NULL
- * to begin iteration.
- * @param oti The OS task info structure to fill out.
- *
- * @return A pointer to the OS task that has been read, or NULL when finished
- * iterating through all tasks.
- */
+
struct os_task *
os_task_info_get_next(const struct os_task *prev, struct os_task_info *oti)
{
@@ -278,7 +212,3 @@ os_task_info_get_next(const struct os_task *prev, struct os_task_info *oti)
return (next);
}
-/**
- * @} OSTask
- * @} OSKernel
- */
diff --git a/kernel/os/src/os_time.c b/kernel/os/src/os_time.c
index 3f6816de3..6a809b82b 100644
--- a/kernel/os/src/os_time.c
+++ b/kernel/os/src/os_time.c
@@ -23,12 +23,6 @@
#include "os/os.h"
#include "os/queue.h"
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSTime Time
- * @{
- */
CTASSERT(sizeof(os_time_t) == 4);
@@ -57,11 +51,6 @@ os_deltatime(os_time_t delta, const struct os_timeval *base,
os_timeradd(base, &tvdelta, result);
}
-/**
- * Get the current OS time in ticks
- *
- * @return OS time in ticks
- */
os_time_t
os_time_get(void)
{
@@ -94,11 +83,6 @@ os_time_tick(int ticks)
OS_EXIT_CRITICAL(sr);
}
-/**
- * Move OS time forward ticks.
- *
- * @param ticks The number of ticks to move time forward.
- */
void
os_time_advance(int ticks)
{
@@ -123,12 +107,6 @@ os_time_advance(int ticks)
}
#endif
-/**
- * Puts the current task to sleep for the specified number of os ticks. There
- * is no delay if ticks is <= 0.
- *
- * @param osticks Number of ticks to delay (<= 0 means no delay).
- */
void
os_time_delay(int32_t osticks)
{
@@ -142,15 +120,6 @@ os_time_delay(int32_t osticks)
}
}
-/**
- * Set the time of day. This does not modify os time, but rather just modifies
- * the offset by which we are tracking real time against os time.
- *
- * @param utctime A timeval representing the UTC time we are setting
- * @param tz The time-zone to apply against the utctime being set.
- *
- * @return 0 on success, non-zero on failure.
- */
int
os_settimeofday(struct os_timeval *utctime, struct os_timezone *tz)
{
@@ -176,16 +145,6 @@ os_settimeofday(struct os_timeval *utctime, struct os_timezone *tz)
return (0);
}
-/**
- * Get the current time of day. Returns the time of day in UTC
- * into the tv argument, and returns the timezone (if set) into
- * tz.
- *
- * @param tv The structure to put the UTC time of day into
- * @param tz The structure to put the timezone information into
- *
- * @return 0 on success, non-zero on failure
- */
int
os_gettimeofday(struct os_timeval *tv, struct os_timezone *tz)
{
@@ -206,11 +165,6 @@ os_gettimeofday(struct os_timeval *tv, struct os_timezone *tz)
return (0);
}
-/**
- * Get time since boot in microseconds.
- *
- * @return time since boot in microseconds
- */
int64_t
os_get_uptime_usec(void)
{
@@ -231,15 +185,6 @@ os_get_uptime_usec(void)
return(tv.tv_sec * 1000000 + tv.tv_usec);
}
-/**
- * Converts milliseconds to OS ticks.
- *
- * @param ms The milliseconds input.
- * @param out_ticks The OS ticks output.
- *
- * @return 0 on success; OS_EINVAL if the result is too
- * large to fit in a uint32_t.
- */
int
os_time_ms_to_ticks(uint32_t ms, uint32_t *out_ticks)
{
@@ -262,7 +207,3 @@ os_time_ms_to_ticks(uint32_t ms, uint32_t *out_ticks)
return 0;
}
-/**
- * @} OSKernel
- * @} OSTime
- */
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services