183 lines
6.9 KiB
ReStructuredText
183 lines
6.9 KiB
ReStructuredText
==========================
|
|
Task Scheduling Interfaces
|
|
==========================
|
|
|
|
By default, NuttX performs strict priority scheduling: Tasks of higher
|
|
priority have exclusive access to the CPU until they become blocked. At
|
|
that time, the CPU is available to tasks of lower priority. Tasks of
|
|
equal priority are scheduled FIFO.
|
|
|
|
Optionally, a NuttX task or thread can be configured with round-robin or
|
|
*sporadic* scheduler. The round-robin is similar to priority scheduling
|
|
*except* that tasks with equal priority and share CPU time via
|
|
*time-slicing*. The time-slice interval is a constant determined by the
|
|
configuration setting ``CONFIG_RR_INTERVAL`` to a positive, non-zero
|
|
value. Sporadic scheduling scheduling is more complex, varying the
|
|
priority of a thread over a *replenishment* period. Support for sporadic
|
|
scheduling is enabled by the configuration option
|
|
``CONFIG_SCHED_SPORADIC``.
|
|
|
|
The OS interfaces described in the following paragraphs provide a POSIX-
|
|
compliant interface to the NuttX scheduler:
|
|
|
|
- :c:func:`sched_setparam`
|
|
- :c:func:`sched_getparam`
|
|
- :c:func:`sched_setscheduler`
|
|
- :c:func:`sched_getscheduler`
|
|
- :c:func:`sched_yield`
|
|
- :c:func:`sched_get_priority_max`
|
|
- :c:func:`sched_get_priority_min`
|
|
- :c:func:`sched_get_rr_interval`
|
|
|
|
Functions
|
|
=========
|
|
|
|
.. c:function:: int sched_setparam(pid_t pid, FAR const struct sched_param *param)
|
|
|
|
This function sets the priority of the task specified
|
|
by pid input parameter.
|
|
|
|
:param pid: The task ID of the task. If ``pid`` is zero, the priority of
|
|
the calling task is set.
|
|
:param param: A structure whose member ``sched_priority`` is the integer
|
|
priority. The range of valid priority numbers is from
|
|
``SCHED_PRIORITY_MIN`` through ``SCHED_PRIORITY_MAX``.
|
|
|
|
:return: On success, sched_setparam() returns 0 (``OK``). On
|
|
error, -1 (``ERROR``) is returned, and ```errno`` <#ErrnoAccess>`__ is
|
|
set appropriately.
|
|
|
|
- ``EINVAL``. The parameter ``param`` is invalid or does not make sense
|
|
for the current scheduling policy.
|
|
- ``EPERM``. The calling task does not have appropriate privileges.
|
|
- ``ESRCH``. The task whose ID is ``pid`` could not be found.
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name. Differences from the full POSIX implementation include:
|
|
|
|
- The range of priority values for the POSIX call is 0 to 255. The
|
|
priority 0 is the lowest priority and 255 is the highest priority.
|
|
|
|
.. note:: Setting a task's priority to the same value has the similar effect
|
|
to ``sched_yield()``: The task will be moved to after all other tasks
|
|
with the same priority.
|
|
|
|
.. c:function:: int sched_getparam(pid_t pid, FAR struct sched_param *param)
|
|
|
|
This function gets the scheduling priority of the task
|
|
specified by pid.
|
|
|
|
:param pid: The task ID of the task. If pid is zero, the priority of the
|
|
calling task is returned.
|
|
:param param: A structure whose member ``sched_priority`` is the integer
|
|
priority. The task's priority is copied to the ``sched_priority``
|
|
element of this structure.
|
|
|
|
:return: 0 (``OK``) if successful, otherwise -1 (``ERROR``).
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name.
|
|
|
|
.. c:function:: int sched_setscheduler (pid_t pid, int policy, const struct sched_param *param)
|
|
|
|
``sched_setscheduler()`` sets both the scheduling
|
|
policy and the priority for the task identified by ``pid``. If ``pid``
|
|
equals zero, the scheduler of the calling thread will be set. The
|
|
parameter ``param`` holds the priority of the thread under the new
|
|
policy.
|
|
|
|
:param pid: The task ID of the task. If ``pid`` is zero, the priority of
|
|
the calling task is set.
|
|
:param policy: Scheduling policy requested (either ``SCHED_FIFO`` or
|
|
``SCHED_RR``).
|
|
:param param: A structure whose member ``sched_priority`` is the integer
|
|
priority. The range of valid priority numbers is from
|
|
``SCHED_PRIORITY_MIN`` through ``SCHED_PRIORITY_MAX``.
|
|
|
|
:return: On success, ``sched_setscheduler()`` returns ``OK``
|
|
(zero). On error, ``ERROR`` (-1) is returned, and
|
|
``errno`` is set appropriately:
|
|
|
|
- ``EINVAL``: The scheduling ``policy`` is not one of the recognized
|
|
policies.
|
|
- ``ESRCH``: The task whose ID is ``pid`` could not be found.
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name.
|
|
|
|
.. c:function:: int sched_getscheduler (pid_t pid)
|
|
|
|
``sched_getscheduler()`` returns the scheduling policy
|
|
currently applied to the task identified by ``pid``. If ``pid`` equals
|
|
zero, the policy of the calling process will be retrieved.
|
|
|
|
:param pid: The task ID of the task to query. If ``pid`` is zero, the
|
|
calling task is queried.
|
|
|
|
:return: On success, ``sched_getscheduler()`` returns the policy for the task
|
|
(either ``SCHED_FIFO`` or ``SCHED_RR``). On error, ``ERROR`` (-1) is
|
|
returned, and ``errno`` is set appropriately:
|
|
|
|
- ``ESRCH``: The task whose ID is pid could not be found.
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name.
|
|
|
|
.. c:function:: int sched_yield(void)
|
|
|
|
This function forces the calling task to give up the
|
|
CPU (only to other tasks at the same priority).
|
|
|
|
:return: 0 (``OK``) or -1 (``ERROR``)
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name.
|
|
|
|
.. c:function:: int sched_get_priority_max (int policy)
|
|
|
|
This function returns the value of the highest possible
|
|
task priority for a specified scheduling policy.
|
|
|
|
:param policy: Scheduling policy requested.
|
|
|
|
:return: The maximum priority value or -1 (``ERROR``).
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name.
|
|
|
|
.. c:function:: int sched_get_priority_min (int policy)
|
|
|
|
This function returns the value of the lowest possible
|
|
task priority for a specified scheduling policy.
|
|
|
|
:param policy: Scheduling policy requested.
|
|
|
|
:return: The minimum priority value or -1 (``ERROR``)
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name.
|
|
|
|
.. c:function:: int sched_get_rr_interval (pid_t pid, struct timespec *interval)
|
|
|
|
``sched_rr_get_interval()`` writes the timeslice
|
|
interval for task identified by ``pid`` into the timespec structure
|
|
pointed to by ``interval``. If pid is zero, the timeslice for the
|
|
calling process is written into 'interval. The identified process should
|
|
be running under the SCHED_RR scheduling policy.'
|
|
|
|
:param pid: The task ID of the task. If pid is zero, the priority of the
|
|
calling task is returned.
|
|
:param interval: A structure used to return the time slice.
|
|
|
|
:return: On success, sched_rr_get_interval() returns OK (0).
|
|
On error, ERROR (-1) is returned, and ``errno`` is
|
|
set to:
|
|
|
|
- ``EFAULT``: Cannot copy to interval
|
|
- ``EINVAL``: Invalid pid.
|
|
- ``ENOSYS``: The system call is not yet implemented.
|
|
- ``ESRCH``: The process whose ID is pid could not be found.
|
|
|
|
**POSIX Compatibility:** Comparable to the POSIX interface of the same
|
|
name.
|