nuttx/Documentation/reference/os/arch.rst
Michał Łyszczek a5bcb2dc46 Documentation: fix multiple errors and warnings
Multiple files were badly formatted, which resulted in many
warnings. This made it harder to check for errors in newly
written documentation.

What's worse, badly formatted text resulted in butchered
output in generated html.

This patch fixes most of the errors, but alas, not all of
the errors can be fixed. Anyway, this should be way easier
to spot errors in newly written docs now.

Signed-off-by: Michał Łyszczek <michal.lyszczek@bofc.pl>
2022-06-08 03:02:32 +08:00

345 lines
14 KiB
ReStructuredText

=====================================================
APIs Exported by Architecture-Specific Logic to NuttX
=====================================================
.. c:function:: void up_initialize(void)
Called once during OS
initialization after the basic OS services have been initialized.
The architecture specific details of initializing the OS will be
handled here. Such things as setting up interrupt service
routines, starting the clock, and registering device
are some of the things that are
different for each processor and hardware platform.
``up_initialize()`` is called after the OS initialized but before
the init process has been started and before the libraries have
been initialized. OS services and driver services are available.
.. c:function:: void up_idle(void)
The logic that will be executed
when their is no other ready-to-run task. This is processor idle
time and will continue until some interrupt occurs to cause a
context switch from the idle task.
Processing in this state may be processor-specific. e.g., this is
where power management operations might be performed.
.. c:function:: void up_initial_state(FAR struct tcb_s *tcb)
A new thread is being started and a new TCB has
been created. This function is called to initialize the processor
specific portions of the new TCB.
This function must setup the initial architecture registers and/or
stack so that execution will begin at tcb->start on the next
context switch.
This function may also need to set up processor registers so that
the new thread executes with the correct privileges. If
``CONFIG_BUILD_PROTECTED`` or ``CONFIG_BUILD_KERNEL`` have been
selected in the NuttX configuration, then special initialization
may need to be performed depending on the task type specified in
the TCB's flags field: Kernel threads will require kernel-mode
privileges; User tasks and pthreads should have only user-mode
privileges. If neither ``CONFIG_BUILD_PROTECTED`` nor
``CONFIG_BUILD_KERNEL`` have been selected, then all threads
should have kernel-mode privileges.
.. c:function:: STATUS up_create_stack(FAR struct tcb_s *tcb, size_t stack_size, uint8_t ttype)
Allocate a stack for a new thread and setup up
stack-related information in the TCB.
The following TCB fields must be initialized:
- ``adj_stack_size``: Stack size after adjustment for hardware,
processor, etc. This value is retained only for debug purposes.
- ``stack_alloc_ptr``: Pointer to allocated stack
- ``stack_base_ptr``: Adjusted stack base pointer after the TLS Data
and Arguments has been removed from the stack allocation.
:param tcb: The TCB of new task.
:param stack_size: The requested stack size. At least this much
must be allocated.
:param ttype: The thread type. This may be one of following
(defined in ``include/nuttx/sched.h``):
- ``TCB_FLAG_TTYPE_TASK``: Normal user task
- ``TCB_FLAG_TTYPE_PTHREAD``: User pthread
- ``TCB_FLAG_TTYPE_KERNEL``: Kernel thread
This thread type is normally available in the flags field of
the TCB, however, there are certain contexts where the TCB may
not be fully initialized when up_create_stack is called.
If ``CONFIG_BUILD_PROTECTED`` or ``CONFIG_BUILD_KERNEL`` are
defined, then this thread type may affect how the stack is
allocated. For example, kernel thread stacks should be
allocated from protected kernel memory. Stacks for user tasks
and threads must come from memory that is accessible to user
code.
.. c:function:: STATUS up_use_stack(FAR struct tcb_s *tcb, FAR void *stack, size_t stack_size)
Setup up stack-related information in the TCB
using pre-allocated stack memory. This function is called only
from ``nxtask_init()`` when a task or kernel thread is started
(never for pthreads).
The following TCB fields must be initialized:
- ``adj_stack_size``: Stack size after adjustment for hardware,
processor, etc. This value is retained only for debug purposes.
- ``stack_alloc_ptr``: Pointer to allocated stack
- ``stack_base_ptr``: Adjusted stack base pointer after the TLS Data
and Arguments has been removed from the stack allocation.
:param tcb: The TCB of new task.
:param stack_size: The allocated stack size.
NOTE: Unlike ``up_stack_create()`` and ``up_stack_release``, this
function does not require the task type (``ttype``) parameter. The
TCB flags will always be set to provide the task type to
``up_use_stack()`` if the information needs that information.
.. c:function:: FAR void *up_stack_frame(FAR struct tcb_s *tcb, size_t frame_size)
Allocate a stack frame in the TCB's stack to hold
thread-specific data. This function may be called any time after
``up_create_stack()`` or ``up_use_stack()`` have been called but
before the task has been started.
Thread data may be kept in the stack (instead of in the TCB) if it
is accessed by the user code directly. This includes such things
as ``argv[]``. The stack memory is guaranteed to be in the same
protection domain as the thread.
The following TCB fields will be re-initialized:
- ``adj_stack_size``: Stack size after removal of the stack frame
from the stack.
- ``stack_base_ptr``: Adjusted stack base pointer after the TLS Data
and Arguments has been removed from the stack allocation.
Here is the diagram after some allocation(tls, arg)::
+-------------+ <-stack_alloc_ptr(lowest)
| TLS Data |
+-------------+
| Arguments |
stack_base_ptr-> +-------------+\
| Available | +
| Stack | |
| | | |
| | | +->adj_stack_size
v | | |
| | |
| | +
+-------------+/
:param tcb: The TCB of new task.
:param frame_size: The size of the stack frame to allocate.
:return:
A pointer to bottom of the allocated stack
frame. NULL will be returned on any failures. The alignment of the
returned value is the same as the alignment of the stack itself
.. c:function:: void up_release_stack(FAR struct tcb_s *dtcb)
A task has been stopped. Free all stack related
resources retained int the defunct TCB.
:param dtcb: The TCB containing information about the stack to be
released.
:param ttype: The thread type. This may be one of following
(defined in ``include/nuttx/sched.h``):
- ``TCB_FLAG_TTYPE_TASK``: Normal user task
- ``TCB_FLAG_TTYPE_PTHREAD``: User pthread
- ``TCB_FLAG_TTYPE_KERNEL``: Kernel thread
This thread type is normally available in the flags field of
the TCB, however, there are certain error recovery contexts
where the TCB may not be fully initialized when
up_release_stack is called.
If ``CONFIG_BUILD_PROTECTED`` or ``CONFIG_BUILD_KERNEL`` are
defined, then this thread type may affect how the stack is
freed. For example, kernel thread stacks may have been
allocated from protected kernel memory. Stacks for user tasks
and threads must have come from memory that is accessible to
user
.. c:function:: void up_unblock_task(FAR struct tcb_s *tcb)
A task is currently in an inactive task list but
has been prepped to execute. Move the TCB to the ready-to-run
list, restore its context, and start execution.
This function is called only from the NuttX scheduling logic.
Interrupts will always be disabled when this function is called.
:param tcb: Refers to the tcb to be unblocked. This tcb is in one
of the waiting tasks lists. It must be moved to the
ready-to-run list and, if it is the highest priority ready to
run tasks, executed.
.. c:function:: void up_block_task(FAR struct tcb_s *tcb, tstate_t task_state)
The currently executing task at the head of the
ready to run list must be stopped. Save its context and move it to
the inactive list specified by task_state. This function is called
only from the NuttX scheduling logic. Interrupts will always be
disabled when this function is called.
:param tcb: Refers to a task in the ready-to-run list (normally
the task at the head of the list). It must be stopped, its
context saved and moved into one of the waiting task lists. If
it was the task at the head of the ready-to-run list, then a
context switch to the new ready to run task must be performed.
:param task_state: Specifies which waiting task list should be
hold the blocked task TCB.
.. c:function:: void up_release_pending(void)
When tasks become ready-to-run but cannot run
because pre-emption is disabled, they are placed into a pending
task list. This function releases and makes ready-to-run all of
the tasks that have collected in the pending task list. This can
cause a context switch if a new task is placed at the head of the
ready to run list.
This function is called only from the NuttX scheduling logic when
pre-emption is re-enabled. Interrupts will always be disabled when
this function is called.
.. c:function:: void up_reprioritize_rtr(FAR struct tcb_s *tcb, uint8_t priority)
Called when the priority of a running or
ready-to-run task changes and the reprioritization will cause a
context switch. Two cases:
#. The priority of the currently running task drops and the next
task in the ready to run list has priority.
#. An idle, ready to run task's priority has been raised above the
the priority of the current, running task and it now has the
priority.
This function is called only from the NuttX scheduling logic.
Interrupts will always be disabled when this function is called.
:param tcb: The TCB of the task that has been reprioritized
:param priority: The new task priority
.. c:macro:: noreturn_function
.. c:function:: void up_exit(int status) noreturn_function;
This function causes the currently executing task
to cease to exist. This is a special case of task_delete().
Unlike other UP APIs, this function may be called directly from
user programs in various states. The implementation of this
function should disable interrupts before performing scheduling
operations.
.. c:function:: void up_assert(FAR const char *filename, int linenum)
Assertions may be handled in an
architecture-specific way.
.. c:function:: void up_schedule_sigaction(FAR struct tcb_s *tcb, sig_deliver_t sigdeliver)
This function is called by the OS when one or
more signal handling actions have been queued for execution. The
architecture specific code must configure things so that the
'sigdeliver' callback is executed on the thread specified by 'tcb'
as soon as possible.
This function may be called from interrupt handling logic.
This operation should not cause the task to be unblocked nor
should it cause any immediate execution of sigdeliver. Typically,
a few cases need to be considered:
#. This function may be called from an interrupt handler During
interrupt processing, all xcptcontext structures should be
valid for all tasks. That structure should be modified to
invoke sigdeliver() either on return from (this) interrupt or
on some subsequent context switch to the recipient task.
#. If not in an interrupt handler and the tcb is NOT the currently
executing task, then again just modify the saved xcptcontext
structure for the recipient task so it will invoke sigdeliver
when that task is later resumed.
#. If not in an interrupt handler and the tcb IS the currently
executing task -- just call the signal handler now.
.. c:function:: void up_allocate_heap(FAR void **heap_start, size_t *heap_size)
This function will be called to dynamically set
aside the heap region.
For the kernel build (``CONFIG_BUILD_PROTECTED=y`` or
``CONFIG_BUILD_KERNEL=y``) with both kernel- and user-space heaps
(``CONFIG_MM_KERNEL_HEAP=y``), this function provides the size of
the unprotected, user-space heap. If a protected kernel-space heap
is provided, the kernel heap must be allocated (and protected) by
an analogous ``up_allocate_kheap()``.
.. c:function:: bool up_interrupt_context(void)
Return true if we are currently executing in the
interrupt handler context.
.. c:function:: void up_disable_irq(int irq)
Disable the IRQ specified by 'irq' On many
architectures, there are three levels of interrupt enabling: (1)
at the global level, (2) at the level of the interrupt controller,
and (3) at the device level. In order to receive interrupts, they
must be enabled at all three levels.
This function implements enabling of the device specified by 'irq'
at the interrupt controller level if supported by the architecture
(up_irq_save() supports the global level, the device level is
hardware specific).
If the architecture does not support ``up_disable_irq``,
``CONFIG_ARCH_NOINTC`` should be defined in the NuttX
configuration file. Since this API cannot be supported on all
architectures, it should be avoided in common implementations
where possible.
.. c:function:: void up_enable_irq(int irq)
This function implements disabling of the device
specified by 'irq' at the interrupt controller level if supported
by the architecture (up_irq_restore() supports the global level,
the device level is hardware specific).
If the architecture does not support ``up_disable_irq``,
``CONFIG_ARCH_NOINTC`` should be defined in the NuttX
configuration file. Since this API cannot be supported on all
architectures, it should be avoided in common implementations
where possible.
.. c:function:: void up_prioritize_irq(int irq)
Set the priority of an IRQ.
If the architecture supports ``up_enable_irq``,
``CONFIG_ARCH_IRQPRIO`` should be defined in the NuttX
configuration file. Since this API cannot be supported on all
architectures, it should be avoided in common implementations
where possible.
.. c:function:: int up_putc(int ch)
This is a debug interface exported by the
architecture-specific logic. Output one character on the console