296 lines
12 KiB
ReStructuredText
296 lines
12 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_switch_context(FAR struct tcb_s *tcb, FAR struct tcb_s *rtcb)
|
|
|
|
A task is currently in the ready-to-run list but has been preppe
|
|
to execute. 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 head task of the ready-to-run list
|
|
which will be executed.
|
|
:param rtcb: Refers to the running task which will be blocked.
|
|
|
|
.. 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_dump_register(FAR void *dumpregs)
|
|
|
|
Register dump 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
|
|
|