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/01/13 01:19:34 UTC
[GitHub] aditihilbert closed pull request #725: match os_sched() doxygen with mynewt-site
aditihilbert closed pull request #725: match os_sched() doxygen with mynewt-site
URL: https://github.com/apache/mynewt-core/pull/725
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
new file mode 100644
index 000000000..d14ac6e8e
--- /dev/null
+++ b/docs/os/core_os/API.rst
@@ -0,0 +1,11 @@
+Core OS API
+-----------
+
+.. contents::
+ :local:
+ :depth: 2
+
+Scheduler
+~~~~~~~~~
+
+.. doxygenfile:: os_sched.h
diff --git a/docs/os/core_os/context_switch/context_switch.rst b/docs/os/core_os/context_switch/context_switch.rst
index e011275b0..87b255f2a 100644
--- a/docs/os/core_os/context_switch/context_switch.rst
+++ b/docs/os/core_os/context_switch/context_switch.rst
@@ -1,11 +1,9 @@
-#########
Scheduler
-#########
+=========
Scheduler's job is to maintain the list of tasks and decide which one
should be running next.
-***********
Description
***********
@@ -35,9 +33,7 @@ process is called context switch. During context switching the state of
the CPU (e.g. registers) for the currently *running* task is stored and
the new task is swapped in.
-***
API
***
-.. doxygengroup:: OSSched
- :content-only:
+* :cpp:func:`os_sched()`
diff --git a/docs/os/core_os/mynewt_os.rst b/docs/os/core_os/mynewt_os.rst
index 08327c644..328986dcb 100644
--- a/docs/os/core_os/mynewt_os.rst
+++ b/docs/os/core_os/mynewt_os.rst
@@ -18,6 +18,7 @@ Mynewt Core OS
mqueue/mqueue
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,
@@ -57,18 +58,18 @@ create on his/her own.
Core OS Features
~~~~~~~~~~~~~~~~
-- `Scheduler/context switching <context_switch/context_switch.html>`__
-- `Time <time/os_time.html>`__
-- `Tasks <task/task.html>`__
-- `Event queues/callouts <event_queue/event_queue.html>`__
-- `Semaphores <semaphore/semaphore.html>`__
-- `Mutexes <mutex/mutex.html>`__
-- `Memory pools <memory_pool/memory_pool.html>`__
-- `Heap <heap/heap.html>`__
-- `Mbufs <mbuf/mbuf.html>`__
-- `Sanity <sanity/sanity.html>`__
-- `Callouts <callout/callout.html>`__
-- `Porting OS to other platforms <porting/port_os.html>`__
+- :doc:`Scheduler/context switching <context_switch/context_switch>`
+- :doc:`Time <time/os_time>`
+- :doc:`Tasks <task/task>`
+- :doc:`Event queues/callouts <event_queue/event_queue>`
+- :doc:`Semaphores <semaphore/semaphore>`
+- :doc:`Mutexes <mutex/mutex>`
+- :doc:`Memory pools <memory_pool/memory_pool>`
+- :doc:`Heap <heap/heap>`
+- :doc:`Mbufs <mbuf/mbuf>`
+- :doc:`Sanity <sanity/sanity>`
+- :doc:`Callouts <callout/callout>`
+- :doc:`Porting OS to other platforms <porting/port_os>`
Basic OS Application Creation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -82,8 +83,7 @@ task. The main steps are:
3. In your application ``main()`` function, call the ``sysinit()``
function to initialize the system and packages, perform application
specific initialization, then wait and dispatch events from the OS
- default event queue in an infinite loop. (See `System Configuration
- and Initialization </os/modules//sysinitconfig/sysinitconfig.html>`__
+ default event queue in an infinite loop. (See :doc:`../modules/sysinitconfig/sysinitconfig`
for more details.)
Initializing application modules and tasks can get somewhat complicated
@@ -131,13 +131,12 @@ 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
-task2\_sem before task2\_sem was initialized.
+priority than task 1) had called os_sem_init() for task2_sem inside
+task2_handler(), task 1 would have called os_sem_pend() using
+task2_sem before task2_sem was initialized.
.. code:: c
-
struct os_sem task1_sem;
struct os_sem task2_sem;
@@ -237,9 +236,3 @@ task2\_sem before task2\_sem was initialized.
}
/* main never returns */
}
-
-API
-~~~~~~~~~~~~
-
-.. doxygengroup:: OSGeneral
- :content-only:
diff --git a/docs/os/os_user_guide.rst b/docs/os/os_user_guide.rst
index c19606fe0..eb1bee4a3 100644
--- a/docs/os/os_user_guide.rst
+++ b/docs/os/os_user_guide.rst
@@ -4,7 +4,7 @@ OS User Guide
.. toctree::
:hidden:
- core_os/mynewt_os
+ OS Core <core_os/mynewt_os>
core_os/porting/port_os
This guide provides comprehensive information about Mynewt OS, the
@@ -18,4 +18,4 @@ application. The guide covers all the features and services available in
the OS and contains several examples showing how they can be used.
**Send us an email on the dev@ mailing list if you have comments or
suggestions!** If you haven't joined the mailing list, you will find the
-links `here <../community.html>`__.
+links `here </community.html>`__.
diff --git a/kernel/os/include/os/os_sched.h b/kernel/os/include/os/os_sched.h
index be6b7fda2..da065aa5c 100644
--- a/kernel/os/include/os/os_sched.h
+++ b/kernel/os/include/os/os_sched.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 OSSched Scheduler
+ * @{
+ */
+
#ifndef _OS_SCHED_H
#define _OS_SCHED_H
@@ -38,7 +45,41 @@ void os_sched_ctx_sw_hook(struct os_task *);
struct os_task *os_sched_get_current_task(void);
void os_sched_set_current_task(struct os_task *);
struct os_task *os_sched_next_task(void);
+
+/**
+ * Performs context switch if needed. If next_t is set, that task will be made
+ * running. If next_t is NULL, highest priority ready to run is swapped in. This
+ * function can be called when new tasks were made ready to run or if the current
+ * task is moved to sleeping state.
+ *
+ * This function will call the architecture specific routine to swap in the new task.
+ *
+ * @param next_t Pointer to task which must run next (optional)
+ *
+ * @return n/a
+ *
+ * @note Interrupts must be disabled when calling this.
+ *
+ * @code{.c}
+ * // example
+ * os_error_t
+ * os_mutex_release(struct os_mutex *mu)
+ * {
+ * ...
+ * OS_EXIT_CRITICAL(sr);
+ *
+ * // Re-schedule if needed
+ * if (resched) {
+ * os_sched(rdy);
+ * }
+ *
+ * return OS_OK;
+ *
+ * }
+ * @endcode
+ */
void os_sched(struct os_task *);
+
void os_sched_os_timer_exp(void);
os_error_t os_sched_insert(struct os_task *);
int os_sched_sleep(struct os_task *, os_time_t nticks);
@@ -52,3 +93,8 @@ os_time_t os_sched_wakeup_ticks(os_time_t now);
#endif
#endif /* _OS_SCHED_H */
+
+/**
+ * @} OSSched
+ * @} OSKernel
+ */
diff --git a/kernel/os/src/os_sched.c b/kernel/os/src/os_sched.c
index cb0b02063..646db7aaf 100644
--- a/kernel/os/src/os_sched.c
+++ b/kernel/os/src/os_sched.c
@@ -24,13 +24,6 @@
#include <assert.h>
-/**
- * @addtogroup OSKernel
- * @{
- * @defgroup OSSched Scheduler
- * @{
- */
-
struct os_task_list g_os_run_list = TAILQ_HEAD_INITIALIZER(g_os_run_list);
struct os_task_list g_os_sleep_list = TAILQ_HEAD_INITIALIZER(g_os_sleep_list);
@@ -129,15 +122,6 @@ os_sched_set_current_task(struct os_task *t)
g_current_task = t;
}
-/**
- * os sched
- *
- * Performs a context switch. When called, it will either find the highest
- * priority task ready to run if next_t is NULL (i.e. the head of the os run
- * list) or will schedule next_t as the task to run.
- *
- * @param next_t Task to run
- */
void
os_sched(struct os_task *next_t)
{
@@ -371,8 +355,3 @@ os_sched_resort(struct os_task *t)
os_sched_insert(t);
}
}
-
-/**
- * @} OSSched
- * @} OSKernel
- */
diff --git a/kernel/os/src/os_sem.c b/kernel/os/src/os_sem.c
index 7566087a6..d41ada565 100644
--- a/kernel/os/src/os_sem.c
+++ b/kernel/os/src/os_sem.c
@@ -220,6 +220,6 @@ os_sem_pend(struct os_sem *sem, uint32_t timeout)
/**
- * @} OSSched
+ * @} OSSem
* @} OSKernel
*/
----------------------------------------------------------------
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