Google Git
Sign in
apache / nuttx-website / 77c27b31fd6440ff9d75a6f44bc732b0d70957da / . / content / docs / 12.4.0 / reference / os / arch.html
blob: c8545f3f0c3f7ad1d5818b592c16c1cbdf06f1ab [file] [log] [blame]
<!--
Documentation/_templates/layout.html
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership. The
ASF licenses this file 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, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>APIs Exported by Architecture-Specific Logic to NuttX &mdash; NuttX latest documentation</title>
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../_static/copybutton.css" type="text/css" />
<link rel="stylesheet" href="../../_static/tabs.css" type="text/css" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
<link rel="shortcut icon" href="../../_static/favicon.ico"/>
<!--[if lt IE 9]>
<script src="../../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="../../_static/jquery.js"></script>
<script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
<script src="../../_static/doctools.js"></script>
<script src="../../_static/sphinx_highlight.js"></script>
<script src="../../_static/clipboard.min.js"></script>
<script src="../../_static/copybutton.js"></script>
<script src="../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="APIs Exported by Board-Specific Logic to NuttX" href="board.html" />
<link rel="prev" title="Application OS vs. Internal OS Interfaces" href="app_vs_os.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../index.html" class="icon icon-home"> NuttX
</a>
<!-- this version selector is quite ugly, should be probably replaced by something
more modern -->
<div class="version-selector">
<select onchange="javascript:location.href = this.value;">
<option value="../../../latest" selected="selected">latest</option>
<option value="../../../10.0.0" >10.0.0</option>
<option value="../../../10.0.1" >10.0.1</option>
<option value="../../../10.1.0" >10.1.0</option>
<option value="../../../10.2.0" >10.2.0</option>
<option value="../../../10.3.0" >10.3.0</option>
<option value="../../../11.0.0" >11.0.0</option>
<option value="../../../12.0.0" >12.0.0</option>
<option value="../../../12.1.0" >12.1.0</option>
<option value="../../../12.2.0" >12.2.0</option>
<option value="../../../12.2.1" >12.2.1</option>
<option value="../../../12.3.0" >12.3.0</option>
<option value="../../../12.4.0" >12.4.0</option>
<option value="../../../12.5.0" >12.5.0</option>
<option value="../../../12.5.1" >12.5.1</option>
</select>
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Table of Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../index.html">Home</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../introduction/index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../quickstart/index.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contributing/index.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../platforms/index.html">Supported Platforms</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../components/index.html">OS Components</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../applications/index.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../implementation/index.html">Implementation Details</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">API Reference</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../user/index.html">Userspace API</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">Architecture APIs</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="addrenv.html">Address Environments</a></li>
<li class="toctree-l3"><a class="reference internal" href="app_vs_os.html">Application OS vs. Internal OS Interfaces</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">APIs Exported by Architecture-Specific Logic to NuttX</a></li>
<li class="toctree-l3"><a class="reference internal" href="board.html">APIs Exported by Board-Specific Logic to NuttX</a></li>
<li class="toctree-l3"><a class="reference internal" href="conventions.html">Naming and Header File Conventions</a></li>
<li class="toctree-l3"><a class="reference internal" href="iob.html">I/O Buffer Management</a></li>
<li class="toctree-l3"><a class="reference internal" href="led.html">LED Support</a></li>
<li class="toctree-l3"><a class="reference internal" href="mutex.html">Mutual Exclusion lock</a></li>
<li class="toctree-l3"><a class="reference internal" href="nat.html">Network Address Translation (NAT)</a></li>
<li class="toctree-l3"><a class="reference internal" href="newreno.html">Congestion Control NewReno</a></li>
<li class="toctree-l3"><a class="reference internal" href="notifier.html">Notifier Chain</a></li>
<li class="toctree-l3"><a class="reference internal" href="nuttx.html">APIs Exported by NuttX to Architecture-Specific Logic</a></li>
<li class="toctree-l3"><a class="reference internal" href="paging.html">On-Demand Paging</a></li>
<li class="toctree-l3"><a class="reference internal" href="shm.html">Shared Memory</a></li>
<li class="toctree-l3"><a class="reference internal" href="smp.html">Symmetric Multiprocessing (SMP) Application</a></li>
<li class="toctree-l3"><a class="reference internal" href="time_clock.html">System Time and Clock</a></li>
<li class="toctree-l3"><a class="reference internal" href="wqueue.html">Work Queues</a></li>
<li class="toctree-l3"><a class="reference internal" href="netdev.html">Network Devices</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../guides/index.html">Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">NuttX</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../index.html">API Reference</a></li>
<li class="breadcrumb-item"><a href="index.html">Architecture APIs</a></li>
<li class="breadcrumb-item active">APIs Exported by Architecture-Specific Logic to NuttX</li>
<li class="wy-breadcrumbs-aside">
<a href="../../_sources/reference/os/arch.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="apis-exported-by-architecture-specific-logic-to-nuttx">
<h1>APIs Exported by Architecture-Specific Logic to NuttX<a class="headerlink" href="#apis-exported-by-architecture-specific-logic-to-nuttx" title="Permalink to this heading"></a></h1>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_initialize">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_initialize</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_initialize" title="Permalink to this definition"></a><br /></dt>
<dd><p>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.</p>
<p><code class="docutils literal notranslate"><span class="pre">up_initialize()</span></code> 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.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_idle">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_idle</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_idle" title="Permalink to this definition"></a><br /></dt>
<dd><p>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.</p>
<p>Processing in this state may be processor-specific. e.g., this is
where power management operations might be performed.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_initial_state">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_initial_state</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="../user/structures.html#c.tcb_s" title="tcb_s"><span class="n"><span class="pre">tcb_s</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">tcb</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_initial_state" title="Permalink to this definition"></a><br /></dt>
<dd><p>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.</p>
<p>This function must setup the initial architecture registers and/or
stack so that execution will begin at tcb-&gt;start on the next
context switch.</p>
<p>This function may also need to set up processor registers so that
the new thread executes with the correct privileges. If
<code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_PROTECTED</span></code> or <code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_KERNEL</span></code> 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 <code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_PROTECTED</span></code> nor
<code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_KERNEL</span></code> have been selected, then all threads
should have kernel-mode privileges.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_create_stack">
<span class="n"><span class="pre">STATUS</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_create_stack</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="../user/structures.html#c.tcb_s" title="tcb_s"><span class="n"><span class="pre">tcb_s</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">tcb</span></span>, <a class="reference internal" href="../user/structures.html#c.size_t" title="size_t"><span class="n"><span class="pre">size_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">stack_size</span></span>, <span class="n"><span class="pre">uint8_t</span></span><span class="w"> </span><span class="n"><span class="pre">ttype</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_create_stack" title="Permalink to this definition"></a><br /></dt>
<dd><p>Allocate a stack for a new thread and setup up
stack-related information in the TCB.</p>
<p>The following TCB fields must be initialized:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">adj_stack_size</span></code>: Stack size after adjustment for hardware,
processor, etc. This value is retained only for debug purposes.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">stack_alloc_ptr</span></code>: Pointer to allocated stack</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">stack_base_ptr</span></code>: Adjusted stack base pointer after the TLS Data
and Arguments has been removed from the stack allocation.</p></li>
</ul>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>tcb</strong> – The TCB of new task.</p></li>
<li><p><strong>stack_size</strong> – The requested stack size. At least this much
must be allocated.</p></li>
<li><p><strong>ttype</strong> – <p>The thread type. This may be one of following
(defined in <code class="docutils literal notranslate"><span class="pre">include/nuttx/sched.h</span></code>):</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">TCB_FLAG_TTYPE_TASK</span></code>: Normal user task</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">TCB_FLAG_TTYPE_PTHREAD</span></code>: User pthread</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">TCB_FLAG_TTYPE_KERNEL</span></code>: Kernel thread</p></li>
</ul>
<p>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.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_PROTECTED</span></code> or <code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_KERNEL</span></code> 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.</p>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_use_stack">
<span class="n"><span class="pre">STATUS</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_use_stack</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="../user/structures.html#c.tcb_s" title="tcb_s"><span class="n"><span class="pre">tcb_s</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">tcb</span></span>, <span class="pre">FAR</span><span class="w"> </span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">stack</span></span>, <a class="reference internal" href="../user/structures.html#c.size_t" title="size_t"><span class="n"><span class="pre">size_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">stack_size</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_use_stack" title="Permalink to this definition"></a><br /></dt>
<dd><p>Setup up stack-related information in the TCB
using pre-allocated stack memory. This function is called only
from <code class="docutils literal notranslate"><span class="pre">nxtask_init()</span></code> when a task or kernel thread is started
(never for pthreads).</p>
<p>The following TCB fields must be initialized:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">adj_stack_size</span></code>: Stack size after adjustment for hardware,
processor, etc. This value is retained only for debug purposes.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">stack_alloc_ptr</span></code>: Pointer to allocated stack</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">stack_base_ptr</span></code>: Adjusted stack base pointer after the TLS Data
and Arguments has been removed from the stack allocation.</p></li>
</ul>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>tcb</strong> – The TCB of new task.</p></li>
<li><p><strong>stack_size</strong> – The allocated stack size.</p></li>
</ul>
</dd>
</dl>
<p>NOTE: Unlike <code class="docutils literal notranslate"><span class="pre">up_stack_create()</span></code> and <code class="docutils literal notranslate"><span class="pre">up_stack_release</span></code>, this
function does not require the task type (<code class="docutils literal notranslate"><span class="pre">ttype</span></code>) parameter. The
TCB flags will always be set to provide the task type to
<code class="docutils literal notranslate"><span class="pre">up_use_stack()</span></code> if the information needs that information.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_stack_frame">
<span class="pre">FAR</span><span class="w"> </span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">up_stack_frame</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="../user/structures.html#c.tcb_s" title="tcb_s"><span class="n"><span class="pre">tcb_s</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">tcb</span></span>, <a class="reference internal" href="../user/structures.html#c.size_t" title="size_t"><span class="n"><span class="pre">size_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">frame_size</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_stack_frame" title="Permalink to this definition"></a><br /></dt>
<dd><p>Allocate a stack frame in the TCB’s stack to hold
thread-specific data. This function may be called any time after
<code class="docutils literal notranslate"><span class="pre">up_create_stack()</span></code> or <code class="docutils literal notranslate"><span class="pre">up_use_stack()</span></code> have been called but
before the task has been started.</p>
<p>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 <code class="docutils literal notranslate"><span class="pre">argv[]</span></code>. The stack memory is guaranteed to be in the same
protection domain as the thread.</p>
<p>The following TCB fields will be re-initialized:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">adj_stack_size</span></code>: Stack size after removal of the stack frame
from the stack.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">stack_base_ptr</span></code>: Adjusted stack base pointer after the TLS Data
and Arguments has been removed from the stack allocation.</p></li>
</ul>
<p>Here is the diagram after some allocation(tls, arg):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> +-------------+ &lt;-stack_alloc_ptr(lowest)
| TLS Data |
+-------------+
| Arguments |
stack_base_ptr-&gt; +-------------+\
| Available | +
| Stack | |
| | | |
| | | +-&gt;adj_stack_size
v | | |
| | |
| | +
+-------------+/
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>tcb</strong> – The TCB of new task.</p></li>
<li><p><strong>frame_size</strong> – The size of the stack frame to allocate.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>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</p>
</dd>
</dl>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_release_stack">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_release_stack</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="../user/structures.html#c.tcb_s" title="tcb_s"><span class="n"><span class="pre">tcb_s</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">dtcb</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_release_stack" title="Permalink to this definition"></a><br /></dt>
<dd><p>A task has been stopped. Free all stack related
resources retained int the defunct TCB.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>dtcb</strong> – The TCB containing information about the stack to be
released.</p></li>
<li><p><strong>ttype</strong> – <p>The thread type. This may be one of following
(defined in <code class="docutils literal notranslate"><span class="pre">include/nuttx/sched.h</span></code>):</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">TCB_FLAG_TTYPE_TASK</span></code>: Normal user task</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">TCB_FLAG_TTYPE_PTHREAD</span></code>: User pthread</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">TCB_FLAG_TTYPE_KERNEL</span></code>: Kernel thread</p></li>
</ul>
<p>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.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_PROTECTED</span></code> or <code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_KERNEL</span></code> 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</p>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_switch_context">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_switch_context</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="../user/structures.html#c.tcb_s" title="tcb_s"><span class="n"><span class="pre">tcb_s</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">tcb</span></span>, <span class="pre">FAR</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="../user/structures.html#c.tcb_s" title="tcb_s"><span class="n"><span class="pre">tcb_s</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">rtcb</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_switch_context" title="Permalink to this definition"></a><br /></dt>
<dd><p>A task is currently in the ready-to-run list but has been preppe
to execute. Restore its context, and start execution.</p>
<p>This function is called only from the NuttX scheduling logic.
Interrupts will always be disabled when this function is called.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>tcb</strong> – Refers to the head task of the ready-to-run list
which will be executed.</p></li>
<li><p><strong>rtcb</strong> – Refers to the running task which will be blocked.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.noreturn_function">
<span class="sig-name descname"><span class="n"><span class="pre">noreturn_function</span></span></span><a class="headerlink" href="#c.noreturn_function" title="Permalink to this definition"></a><br /></dt>
<dd></dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_exit">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_exit</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">status</span></span><span class="sig-paren">)</span><span class="w"> </span><span class="pre">noreturn_function</span><span class="p"><span class="pre">;</span></span><a class="headerlink" href="#c.up_exit" title="Permalink to this definition"></a><br /></dt>
<dd><p>This function causes the currently executing task
to cease to exist. This is a special case of task_delete().</p>
<p>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.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_dump_register">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_dump_register</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">dumpregs</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_dump_register" title="Permalink to this definition"></a><br /></dt>
<dd><p>Register dump may be handled in an
architecture-specific way.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_schedule_sigaction">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_schedule_sigaction</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="../user/structures.html#c.tcb_s" title="tcb_s"><span class="n"><span class="pre">tcb_s</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">tcb</span></span>, <span class="n"><span class="pre">sig_deliver_t</span></span><span class="w"> </span><span class="n"><span class="pre">sigdeliver</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_schedule_sigaction" title="Permalink to this definition"></a><br /></dt>
<dd><p>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.</p>
<p>This function may be called from interrupt handling logic.</p>
<p>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:</p>
<blockquote>
<div><ol class="arabic simple">
<li><p>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.</p></li>
<li><p>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.</p></li>
<li><p>If not in an interrupt handler and the tcb IS the currently
executing task – just call the signal handler now.</p></li>
</ol>
</div></blockquote>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_allocate_heap">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_allocate_heap</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">heap_start</span></span>, <a class="reference internal" href="../user/structures.html#c.size_t" title="size_t"><span class="n"><span class="pre">size_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">heap_size</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_allocate_heap" title="Permalink to this definition"></a><br /></dt>
<dd><p>This function will be called to dynamically set
aside the heap region.</p>
<p>For the kernel build (<code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_PROTECTED=y</span></code> or
<code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_KERNEL=y</span></code>) with both kernel- and user-space heaps
(<code class="docutils literal notranslate"><span class="pre">CONFIG_MM_KERNEL_HEAP=y</span></code>), 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 <code class="docutils literal notranslate"><span class="pre">up_allocate_kheap()</span></code>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_interrupt_context">
<span class="kt"><span class="pre">bool</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_interrupt_context</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_interrupt_context" title="Permalink to this definition"></a><br /></dt>
<dd><p>Return true if we are currently executing in the
interrupt handler context.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_disable_irq">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_disable_irq</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">irq</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_disable_irq" title="Permalink to this definition"></a><br /></dt>
<dd><p>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.</p>
<p>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).</p>
<p>If the architecture does not support <code class="docutils literal notranslate"><span class="pre">up_disable_irq</span></code>,
<code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_NOINTC</span></code> 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.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_enable_irq">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_enable_irq</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">irq</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_enable_irq" title="Permalink to this definition"></a><br /></dt>
<dd><p>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).</p>
<p>If the architecture does not support <code class="docutils literal notranslate"><span class="pre">up_disable_irq</span></code>,
<code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_NOINTC</span></code> 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.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_prioritize_irq">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_prioritize_irq</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">irq</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_prioritize_irq" title="Permalink to this definition"></a><br /></dt>
<dd><p>Set the priority of an IRQ.</p>
<p>If the architecture supports <code class="docutils literal notranslate"><span class="pre">up_enable_irq</span></code>,
<code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_IRQPRIO</span></code> 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.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.up_putc">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">up_putc</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.up_putc" title="Permalink to this definition"></a><br /></dt>
<dd><p>This is a debug interface exported by the
architecture-specific logic. Output one character on the console</p>
</dd></dl>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="app_vs_os.html" class="btn btn-neutral float-left" title="Application OS vs. Internal OS Interfaces" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="board.html" class="btn btn-neutral float-right" title="APIs Exported by Board-Specific Logic to NuttX" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2023, The Apache Software Foundation.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>