diff options
| -rw-r--r-- | nuttx/Documentation/NuttXBinfmt.html | 14 | ||||
| -rw-r--r-- | nuttx/Documentation/NuttxPortingGuide.html | 259 | ||||
| -rw-r--r-- | nuttx/arch/z80/include/z180/arch.h | 23 | ||||
| -rw-r--r-- | nuttx/arch/z80/src/z180/z180_mmu.c | 253 | ||||
| -rw-r--r-- | nuttx/include/nuttx/arch.h | 144 | ||||
| -rw-r--r-- | nuttx/include/nuttx/binfmt/binfmt.h | 4 |
6 files changed, 584 insertions, 113 deletions
diff --git a/nuttx/Documentation/NuttXBinfmt.html b/nuttx/Documentation/NuttXBinfmt.html index 830a05caa..9c9fd3a51 100644 --- a/nuttx/Documentation/NuttXBinfmt.html +++ b/nuttx/Documentation/NuttXBinfmt.html @@ -164,13 +164,13 @@ struct binary_s }; </pre></ul> -<ul><p><small> - <sup>1</sup>The <code>filename</code> must be the full, absolute path to the file to be executed unless <code>CONFIG_BINFMT_EXEPATH</code> is defined. - In that case, <code>filename</code> may be a relative path; - a set of candidate absolute paths will be generated using the <code>PATH</code> environment variable and <a href="#load_module"><code>load_module()</code></a> will attempt to load each file that is found at those absolute paths. -</small></p></ul> - -</p> +<ul> + <p><small> + <sup>1</sup>The <code>filename</code> must be the full, absolute path to the file to be executed unless <code>CONFIG_BINFMT_EXEPATH</code> is defined. + In that case, <code>filename</code> may be a relative path; + a set of candidate absolute paths will be generated using the <code>PATH</code> environment variable and <a href="#load_module"><code>load_module()</code></a> will attempt to load each file that is found at those absolute paths. + </small></p> +</ul> <p> Where the types <code>binfmt_ctor_t</code> and <code>binfmt_dtor_t</code> define the type of one C++ constructor or destructor: diff --git a/nuttx/Documentation/NuttxPortingGuide.html b/nuttx/Documentation/NuttxPortingGuide.html index 5361a2866..526892d3e 100644 --- a/nuttx/Documentation/NuttxPortingGuide.html +++ b/nuttx/Documentation/NuttxPortingGuide.html @@ -12,7 +12,7 @@ <h1><big><font color="#3c34ec"> <i>NuttX RTOS Porting Guide</i> </font></big></h1> - <p>Last Updated: December 17, 2012</p> + <p>Last Updated: December 18, 2012</p> </td> </tr> </table> @@ -92,7 +92,8 @@ <a href="#upenableirq">4.1.17 <code>up_enable_irq()</code></a><br> <a href="#upprioritizeirq">4.1.18 <code>up_prioritize_irq()</code></a></br> <a href="#upputc">4.1.19 <code>up_putc()</code></a></br> - <a href="#systemtime">4.1.20 System Time and Clock</a> + <a href="#systemtime">4.1.20 System Time and Clock</a><br> + <a href="#addrenv">4.1.21 Address Environments</a> </ul> <a href="#exports">4.2 APIs Exported by NuttX to Architecture-Specific Logic</a> <ul> @@ -1622,7 +1623,7 @@ The system can be re-made subsequently by just typing <code>make</code>. is defined. </p> -<p><b>Inputs</b>:</p> +<p><b>Input Parameters</b>:</p> <ul> <li> <code>tcb</code>: The TCB of new task. @@ -1658,7 +1659,7 @@ The system can be re-made subsequently by just typing <code>make</code>. is defined. </p> -<p><b>Inputs:</b></p> +<p><b>Input Parameters:</b></p> <ul> <li> <code>tcb</code>: The TCB of new task. @@ -1694,7 +1695,7 @@ The system can be re-made subsequently by just typing <code>make</code>. function is called. </p> -<p><b>Inputs</b>: +<p><b>Input Parameters</b>: <ul> <li><code>tcb</code>: Refers to the tcb to be unblocked. This tcb is in one of the waiting tasks lists. It must be moved to @@ -1715,7 +1716,7 @@ The system can be re-made subsequently by just typing <code>make</code>. logic. Interrupts will always be disabled when this function is called. -<p><b>Inputs:</b></p> +<p><b>Input Parameters:</b></p> <ul> <li><code>tcb</code>: Refers to a task in the ready-to-run list (normally the task at the head of the list). It most be @@ -1771,7 +1772,7 @@ The system can be re-made subsequently by just typing <code>make</code>. function is called. </p> -<p><b>Inputs:</b></p> +<p><b>Input Parameters:</b></p> <ul> <li> <code>tcb</code>: The TCB of the task that has been reprioritized @@ -2110,6 +2111,236 @@ else To retrieve that variable use: </p> +<h3><a name="addrenv">4.1.21 Address Environments</a></h3> + +<p> + CPUs that support memory management units (MMUs) may provide <i>address environments</i> within which tasks and their child threads execute. + The configuration indicates the CPUs ability to support address environments by setting the configuration varabile <code>CONFIG_ADDRENV=y</code>. + These address environments are created only when tasks are created via <code>exec()</code> or <code>exec_module()</code> (see <code>include/nuttx/binfmt/binfmt.h</code>). +</p> +<p> + When <code>CONFIG_ADDRENV=y</code> is set in the board configuration, the CPU-specific logic must provide a set of interfaces as defined in the header file <code>include/nuttx/arch.h</code>. + These interfaces are listed below and described in detail in the following paragraphs. +</p> +<p> + The CPU-specific logic must provide two categories in interfaces: +</p> +<ol> + <li> + <p> + <b>Binary Loader Support</b>. + These are low-level interfaces used in <code>binfmt/</code> to instantiate tasks with address environments. + These interfaces all operate on type <code>task_addrenv_t</code> which is an abstract representation of a asks's address environment and must be defined in arch/arch.h if <code>CONFIG_ADDRENVM</code> is defined. + These low-level interfaces include: + </p> + <ul> + <li> + <a href="#up_addrenv_create">4.1.21.1 <code>up_addrenv_create()</code></a>: + Create an address environment. + </li> + <li> + <a href="#up_addrenv_vaddr">4.1.21.2 <code>up_addrenv_vaddr()</code></a>: + Returns the virtual base address of the address environment. + </li> + <li> + <a href="#up_addrenv_select">4.1.21.3 <code>up_addrenv_select()</code></a>: + Instantiate an address environment. + </li> + <li> + <a href="#up_addrenv_restore">4.1.21.4 <code>up_addrenv_restore()</code></a>: + Restore an address environment. + </li> + <li> + <a href="#up_addrenv_destroy">4.1.21.5 <code>up_addrenv_destroy()</code></a>: + Destroy an address environment. + </li> + <li> + <a href="#up_addrenv_assign">4.1.21.6 <code>up_addrenv_assign()</code></a>: + Assign an address environment to a TCB. + </li> + </ul> + </li> + <li> + <p> + <b>Tasking Support</b>. + Other interfaces must be provided to support higher-level interfaces used by the NuttX tasking logic. + These interfaces are* used by the functions in <code>sched/</code> and all operate on the TCB which as been assigned an address environment by <code>up_addrenv_assign()</code>. + </p> + <ul> + <li> + <a href="#up_addrenv_share">4.1.21.7 <code>up_addrenv_share()</code></a>: + Clone the address environment assigned to one TCB to another. + This operation is done when a pthread is created that share's the same address environment. + </li> + <li> + <a href="#up_addrenv_release">4.1.21.8 <code>up_addrenv_release()</code></a>: + ARelease the TCBs reference to an address environment when a task/thread exits. + </li> + </ul> + </li> +</ol> + + +<h4><a name="up_addrenv_create">4.1.21.1 <code>up_addrenv_create()</code></a></h4> +<p><b>Prototype</b>:</p> +<ul> + <code>int up_addrenv_create(size_t envsize, FAR task_addrenv_t *addrenv);</code> +</ul> +<p><b>Description</b>:</p> +<ul> + This function is called from the binary loader logic when a new task is created in order to instantiate an address environment for the task. + <code>up_addrenv_create()</code> is essentially the allocator of the physical memory for the new task. +</ul> +<p><b>Input Parameters</b>:</p> +<ul> + <li><code>envsize</code>: The size (in bytes) of the address environment needed by the task.</li> + <li><code>addrenv</code>: The location to return the representation of the task address environment.</li> +</ul> +<p><b>Returned Value</b>:</p> +<ul> + Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure. +</ul> + +<h4><a name="up_addrenv_vaddr">4.1.21.2 <code>up_addrenv_vaddr()</code></a></h4> +<p><b>Prototype</b>:<p> +<ul> + <code>int up_addrenv_vaddr(FAR task_addrenv_t addrenv, FAR void **vaddr);</code> +</ul> +<p><b>Description</b>:</p> +<ul> + Return the virtual address associated with the newly create address environment. + This function is used by the binary loaders in order get an address that can be used to initialize the new task. +</ul> +<p><b>Input Parameters</b>:</p> +<ul> + <li><code>addrenv</code>: The representation of the task address environment previously returned by up_addrenv_create.</li> + <li><code>vaddr</code>: The location to return the virtual address.</li> +</ul> +<p><b>Returned Value</b>:</p> +<ul> + Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure. +</ul> + +<h4><a name="up_addrenv_select">4.1.21.3 <code>up_addrenv_select()</code></a></h4> +<p><b>Prototype</b>:<p> +<ul> + <code>int up_addrenv_select(task_addrenv_t addrenv, hw_addrenv_t *oldenv);</code> +</ul> +<p><b>Description</b>:</p> +<ul> + After an address environment has been established for a task (via <code>up_addrenv_create())</code>, this function may be called to to instantiate that address environment in the virtual address space. + This might be necessary, for example, to load the code for the task from a file or to access address environment private data. +</ul> +<p><b>Input Parameters</b>:</p> +<ul> + <li><code>addrenv</code>: The representation of the task address environment previously returned by up_addrenv_create.</li> + <li><code>oldenv</code>: + The address environment that was in place before <code>up_addrenv_select()</code> was called. + This may be used with <code>up_addrenv_restore()</code> to restore the original address environment that was in place before <code>up_addrenv_select()</code> was called. + Note that this may be a task agnostic, hardware representation that is different from <code>task_addrenv_t</code>. + </li> +</ul> +<p><b>Returned Value</b>:</p> +<ul> + Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure. +</ul> + +<h4><a name="up_addrenv_restore">4.1.21.4 <code>up_addrenv_restore()</code></a></h4> +<p><b>Prototype</b>:<p> +<ul> + <code>int up_addrenv_restore(hw_addrenv_t oldenv);</code> +</ul> +<p><b>Description</b>:</p> +<ul> + After an address environment has been temporarilty instantiated by <code>up_addrenv_select</code>, + this function may be called to to restore the original address environment. +</ul> +<p><b>Input Parameters</b>:</p> +<ul> + <li><code>oldenv</code>: The hardware representation of the address environment previously returned by <code>up_addrenv_select()</code>.</li> +</ul> +<p><b>Returned Value</b>:</p> +<ul> + Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure. +</ul> + +<h4><a name="up_addrenv_destroy">4.1.21.5 <code>up_addrenv_destroy()</code></a></h4> +<p><b>Prototype</b>:<p> +<ul> + <code>int up_addrenv_destroy(task_addrenv_t addrenv);</code> +</ul> +<p><b>Description</b>:</p> +<ul> + Called from the binary loader loader during error handling to destroy the address environment previously created by <code>up_addrenv_create()</code>. +</ul> +<p><b>Input Parameters</b>:</p> +<ul> + <li><code>addrenv</code>: The representation of the task address environment previously returned by up_addrenv_create.</li> +</ul> +<p><b>Returned Value</b>:</p> +<ul> + Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure. +</ul> + +<h4><a name="up_addrenv_assign">4.1.21.6 <code>up_addrenv_assign()</code></a></h4> +<p><b>Prototype</b>:<p> +<ul> + <code>int up_addrenv_assign(task_addrenv_t addrenv, FAR _TCB *tcb);</code> +</ul> +<p><b>Description</b>:</p> +<ul> + Assign an address environment to a TCB. +</ul> +<p><b>Input Parameters</b>:</p> +<ul> + <li><code>addrenv</code>: The representation of the task address environment previously returned by up_addrenv_create.</li> + <li><code>tcb</code>: The TCB of the task to receive the address environment.</li> +</ul> +<p><b>Returned Value</b>:</p> +<ul> + Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure. +</ul> + +<h4><a name="up_addrenv_share">4.1.21.7 <code>up_addrenv_share()</code></a></h4> +<p><b>Prototype</b>:<p> +<ul> + <code>int up_addrenv_share(FAR const _TCB *ptcb, FAR _TCB *ctcb);</code> +</ul> +<p><b>Description</b>:</p> +<ul> + This function is called from the core scheduler logic when a thread is created that needs to share the address ennvironment of its parent task. + In this case, the parent's address environment needs to be "cloned" for the child thread. +</ul> +<p><b>Input Parameters</b>:</p> +<ul> + <li><code>ptcb</code>: The TCB of the parent task that has the address environment.</li> + <li><code>ctcb</code>: The TCB of the child thread needing the address environment.</li> +</ul> +<p><b>Returned Value</b>:</p> +<ul> + Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure. +</ul> + +<h4><a name="up_addrenv_release">4.1.21.8 <code>up_addrenv_release()</code></a></h4> +<p><b>Prototype</b>:<p> +<ul> + <code>int up_addrenv_release(FAR _TCB *tcb);</code> +</ul> +<p><b>Description</b>:</p> +<ul> + This function is called when a task or thread exits in order to release its reference to an address environment. + When there are no furtherreferences to an address environment, that address environment should + be destroyed. +</ul> +<p><b>Input Parameters</b>:</p> +<ul> + <li><code>tcb</code>: The TCB of the task or thread whose the address environment will be released.</li> +</ul> +<p><b>Returned Value</b>:</p> +<ul> + Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure. +</ul> + <h2><a name="exports">4.2 APIs Exported by NuttX to Architecture-Specific Logic</a></h2> <p> These are standard interfaces that are exported by the OS @@ -3470,7 +3701,7 @@ extern void up_ledoff(int led); All PM interfaces are declared in the file <code>include/nuttx/power/pm.h</code>. </p> -<h4><a name="pminitialize">6.4.2.1 pm_initialize()</a></h4> +<h4><a name="pminitialize">6.4.2.1 <code>pm_initialize()</code></a></h4> <p><b>Function Prototype:</b></p> <ul><pre> #include <nuttx/power/pm.h> @@ -3487,7 +3718,7 @@ None None </p> -<h4><a name="pmregister">6.4.2.2 pm_register()</a></h4> +<h4><a name="pmregister">6.4.2.2 <code>pm_register()</code></a></h4> <p><b>Function Prototype:</b></p> <ul><pre> #include <nuttx/power/pm.h> @@ -3507,7 +3738,7 @@ int pm_register(FAR struct pm_callback_s *callbacks); Zero (<code>OK</code>) on success; otherwise a negater <code>errno</code> value is returned. </p> -<h4><a name="pmactivity">6.4.2.3 pm_activity()</a></h4> +<h4><a name="pmactivity">6.4.2.3 <code>pm_activity()</code></a></h4> <p><b>Function Prototype:</b></p> <ul><pre> #include <nuttx/power/pm.h> @@ -3534,7 +3765,7 @@ void pm_activity(int priority); This function may be called from an interrupt handler (this is the ONLY PM function that may be called from an interrupt handler!). </p> -<h4><a name="pmcheckstate">6.4.2.4 pm_checkstate()</a></h4> +<h4><a name="pmcheckstate">6.4.2.4 <code>pm_checkstate()</code></a></h4> <p><b>Function Prototype:</b></p> <ul><pre> #include <nuttx/power/pm.h> @@ -3561,7 +3792,7 @@ enum pm_state_e pm_checkstate(void); The recommended power management state. </p> -<h4><a name="pmchangestate">6.4.2.5 pm_changestate()</a></h4> +<h4><a name="pmchangestate">6.4.2.5 <code>pm_changestate()</code></a></h4> <p><b>Function Prototype:</b></p> <ul><pre> #include <nuttx/power/pm.h> @@ -3596,7 +3827,7 @@ enum pm_state_e pm_checkstate(void); These callback functions can be used to provide power management information to the driver. </p> -<h4><a name="pmprepare">6.4.3.1 prepare()</a></h4> +<h4><a name="pmprepare">6.4.3.1 <code>prepare()</code></a></h4> <p><b>Function Prototype:</b></p> <ul><pre> int (*prepare)(FAR struct pm_callback_s *cb, enum pm_state_e pmstate); @@ -3624,7 +3855,7 @@ int (*prepare)(FAR struct pm_callback_s *cb, enum pm_state_e pmstate); consumption modes! </p> -<h4><a name="pmnotify">6.4.3.1 notify()</a></h4> +<h4><a name="pmnotify">6.4.3.1 <code>notify()</code></a></h4> <p><b>Function Prototype:</b></p> <ul><pre> #include <nuttx/power/pm.h> diff --git a/nuttx/arch/z80/include/z180/arch.h b/nuttx/arch/z80/include/z180/arch.h index 9e2197522..d7cf82a26 100644 --- a/nuttx/arch/z80/include/z180/arch.h +++ b/nuttx/arch/z80/include/z180/arch.h @@ -45,6 +45,12 @@ * Included Files ****************************************************************************/ +#include <nuttx/config.h> + +#include <stdint.h> + +#include <arch/irq.h> + /**************************************************************************** * Pre-processor Definitions ****************************************************************************/ @@ -52,6 +58,23 @@ /**************************************************************************** * Public Types ****************************************************************************/ +/* The z180 address environment is represented in hardware as the 8-bit + * Common Base Register (CBR). CBR specifies the base address (on 4KB + * boundaries) used to generate a 20-bit physical address for Common Area 1 + * accesses. CBR is the upper 8-bits of the 20-bit address; the lower 14-bits + * of the base address are implicitly zero (hence the 4KB boundary alignment). + */ + +#ifdef CONFIG_ADDRENV +typedef uint8_t hw_addrenv_t; + +/* At the task-level, the z180 address environment is represented as struct + * z180_cbr_s which is defined in irq.h. + */ + +struct z180_cbr_s; +typedef FAR struct z180_cbr_s *task_addrenv_t; +#endif /**************************************************************************** * Public Variables diff --git a/nuttx/arch/z80/src/z180/z180_mmu.c b/nuttx/arch/z80/src/z180/z180_mmu.c index e24b22b8e..5f9b26be2 100644 --- a/nuttx/arch/z80/src/z180/z180_mmu.c +++ b/nuttx/arch/z80/src/z180/z180_mmu.c @@ -79,7 +79,7 @@ static struct z180_cbr_s g_cbrs[CONFIG_MAX_TASKS]; ****************************************************************************/ /**************************************************************************** - * Name: z180_mmu_findcbr + * Name: z180_mmu_alloccbr * * Description: * Find an unused struture in g_cbrs (i.e., one with reference count == 0). @@ -88,7 +88,7 @@ static struct z180_cbr_s g_cbrs[CONFIG_MAX_TASKS]; * ****************************************************************************/ -static FAR struct z180_cbr_s *z180_mmu_findcbr(void) +static inline FAR struct z180_cbr_s *z180_mmu_alloccbr(void) { int i; @@ -177,24 +177,53 @@ return g_physhandle ? OK : -ENOMEM; } /**************************************************************************** + * Address Environment Interfaces + * + * Low-level interfaces used in binfmt/ to instantiate tasks with address + * environments. These interfaces all operate on task_addrenv_t which is an + * abstract representation of the address environment and must be provided + * by arch/arch.h is CONFIG_ADDRENV is defined. + * + * up_addrenv_create - Create an address environment + * up_addrenv_vaddr - Returns the virtual base address of the address + * environment + * up_addrenv_select - Instantiate an address environment + * up_addrenv_destroy - Destroy an address environment. + * up_addrenv_assign - Assign an address environment to a TCB + * + * Higher-level interfaces used by the tasking logic. These interfaces are + * used by the functions in sched/ and all operate on the TCB which as been + * assigned an address environment by up_addrenv_assign(). + * + * up_addrenv_share - Clone the address environment assigned to one TCB + * to another. This operation is done when a pthread + * is created that share's the same address + * environment. + * up_addrenv_release - Release the TCBs reference to an address + * environment when a task/thread exists. + * + ****************************************************************************/ +/**************************************************************************** * Name: up_addrenv_create * * Description: * This function is called from the binary loader logic when a new - * task is created in RAM in order to instantiate an address environment for - * the task. + * task is created in order to instantiate an address environment for the + * task. up_addrenv_create is essentially the allocator of the physical + * memory for the new task. * * Input Parameters: - * tcb - The TCB of the task needing the address environment. * envsize - The size (in bytes) of the address environment needed by the * task. + * addrenv - The location to return the representation of the task address + * environment. * * Returned Value: * Zero (OK) on success; a negated errno value on failure. * ****************************************************************************/ -int up_addrenv_create(FAR _TCB *tcb, size_t envsize) +int up_addrenv_create(size_t envsize, FAR task_addrenv_t *addrenv) { FAR struct z180_cbr_s *cbr; irqstate_t flags; @@ -202,10 +231,6 @@ int up_addrenv_create(FAR _TCB *tcb, size_t envsize) unsigned int npages; int ret; - /* Make sure that there is no address environment in place on this TCB */ - - DEBUGASSERT(tcb->xcp.cbr == NULL); - /* Convert the size from bytes to numbers of pages */ npages = PHYS_ALIGNUP(envsize); @@ -225,7 +250,7 @@ int up_addrenv_create(FAR _TCB *tcb, size_t envsize) */ flags = irqsave(); - cbr = z180_mmu_findcbr(); + cbr = z180_mmu_alloccbr(); if (!cbr) { sdbg("ERROR: No free CBR structures\n"); @@ -235,7 +260,6 @@ int up_addrenv_create(FAR _TCB *tcb, size_t envsize) /* Now allocate the physical memory to back up the address environment */ - #ifdef CONFIG_GRAN_SINGLE alloc = (uintptr_t)gran_alloc(npages); #else @@ -254,9 +278,9 @@ int up_addrenv_create(FAR _TCB *tcb, size_t envsize) DEBUGASSERT(alloc <= 0xff); - cbr->cbr = alloc; - cbr->pages = npages; - tcb->xcp.cbr = cbr; + cbr->cbr = (uint8_t)alloc; + cbr->pages = (uint8_t)npages; + *addrenv = (task_addrenv_t)cbr; irqrestore(flags); return OK; @@ -270,111 +294,204 @@ errout_with_irq: } /**************************************************************************** - * Name: up_addrenv_share + * Name: up_addrenv_vaddr * * Description: - * This function is called from the core scheduler logic when a thread - * is created that needs to share the address ennvironment of its parent - * task. In this case, the parent's address environment needs to be - * "cloned" for the child. + * Return the virtual address associated with the newly create address + * environment. This function is used by the binary loaders in order + * get an address that can be used to initialize the new task.. * * Input Parameters: - * ptcb - The TCB of the parent task that has the address environment. - * ctcb - The TCB of the child thread needing the address environment. + * addrenv - The representation of the task address environment previously + * returned by up_addrenv_create. + * vaddr - The location to return the virtual address. * * Returned Value: * Zero (OK) on success; a negated errno value on failure. * ****************************************************************************/ -int up_addrenv_share(FAR const _TCB *ptcb, FAR _TCB *ctcb) +int up_addrenv_vaddr(FAR task_addrenv_t addrenv, FAR void **vaddr) +{ + return CONFIG_Z180_COMMON1AREA_VIRTBASE; +} + +/**************************************************************************** + * Name: up_addrenv_select + * + * Description: + * After an address environment has been established for a task (via + * up_addrenv_create()), this function may be called to to instantiate + * that address environment in the virtual address space. This might be + * necessary, for example, to load the code for the task from a file or + * to access address environment private data. + * + * Input Parameters: + * addrenv - The representation of the task address environment previously + * returned by up_addrenv_create. + * oldenv + * The address environment that was in place before up_addrenv_select(). + * This may be used with up_addrenv_restore() to restore the original + * address environment that was in place before up_addrenv_select() was + * called. Note that this may be a task agnostic, hardware + * representation that is different from task_addrenv_t. + * + * Returned Value: + * Zero (OK) on success; a negated errno value on failure. + * + ****************************************************************************/ + +int up_addrenv_select(task_addrenv_t addrenv, hw_addrenv_t *oldenv) { + FAR struct z180_cbr_s *cbr = (FAR struct z180_cbr_s *)addrenv; irqstate_t flags; - /* Make sure that the child has no address environment. It is okay if - * if the parent does not have one. - */ + DEBUGASSERT(cbr && oldenv); - DEBUGASSERT(ctcb->xcp.cbr == NULL); + /* Return the current CBR value from the CBR register */ flags = irqsave(); - if (ptcb->xcp.cbr) - { - /* Clone the CBR by incrementing the reference counting and saving a - * copy in the child thread's TCB. - */ + *oldenv = (hw_addrenv_t)inp(Z180_MMU_CBR); - ptcb->xcp.cbr->crefs++; - ctcb->xcp.cbr = ptcb->xcp.cbr; - } + /* Write the new CBR value into CBR register */ + outp(Z180_MMU_CBR, cbr->cbr); irqrestore(flags); return OK; } /**************************************************************************** - * Name: up_addrenv_instantiate + * Name: up_addrenv_restore * * Description: - * After an address environment has been established for a task (via - * up_addrenv_create(). This function may be called to to instantiate - * that address environment in the virtual address space. this might be - * necessary, for example, to load the code for the task from a file or - * to access address environment private data. + * After an address environment has been temporarilty instantiated by + * up_addrenv_select, this function may be called to to restore the + * original address environment. * * Input Parameters: - * tcb - The TCB of the task or thread whose the address environment will - * be instantiated. + * oldenv - The hardware representation of the address environment + * previously returned by up_addrenv_select. * * Returned Value: - * A handle that may be used with up_addrenv_restore() to restore the - * address environment before up_addrenv_instantiate() was called. + * Zero (OK) on success; a negated errno value on failure. * ****************************************************************************/ -FAR void *up_addrenv_instantiate(FAR _TCB *tcb) +int up_addrenv_restore(hw_addrenv_t oldenv) { - uint8_t oldcbr; - irqstate_t flags; + outp(Z180_MMU_CBR, (uint8_t)oldenv); + return OK; +} - /* Get the current CBR value from the CBR register */ +/**************************************************************************** + * Name: up_addrenv_destroy + * + * Description: + * Called from the binary loader loader during error handling to destroy + * the address environment previously created by up_addrenv_create(). + * + * Input Parameters: + * addrenv - The representation of the task address environment previously + * returned by up_addrenv_create. + * + * Returned Value: + * Zero (OK) on success; a negated errno value on failure. + * + ****************************************************************************/ - flags = irqsave(); - oldcbr = inp(Z180_MMU_CBR); +int up_addrenv_destroy(task_addrenv_t addrenv) +{ + FAR struct z180_cbr_s *cbr = (FAR struct z180_cbr_s *)addrenv; - /* Check if the task has an address environment. */ + DEBUGASSERT(cbr); - if (tcb->xcp.cbr) - { - /* Yes.. Write the new CBR value into CBR register */ + /* Free the physical address space backing up the mapping */ - outp(Z180_MMU_CBR, tcb->xcp.cbr->cbr); - } +#ifdef CONFIG_GRAN_SINGLE + gran_free((FAR void *)cbr->cbr, cbr->pages); +#else + gran_free(g_physhandle, (FAR void *)cbr->cbr, cbr->pages); +#endif - irqrestore(flags); - return (FAR void *)oldcbr; + /* And make the CBR structure available for re-use */ + + z180_mmu_freecbr(cbr); + return OK; } /**************************************************************************** - * Name: up_addrenv_restore + * Name: up_addrenv_assign * * Description: - * Restore an address environment using a handle previously returned by - * up_addrenv_instantiate(). + * Assign an address environment to a TCB. * * Input Parameters: - * handle - A handle previously returned by up_addrenv_instantiate. + * addrenv - The representation of the task address environment previously + * returned by up_addrenv_create. + * tcb - The TCB of the task to receive the address environment. * * Returned Value: * Zero (OK) on success; a negated errno value on failure. * ****************************************************************************/ -int up_addrenv_restore(FAR void *handle) +int up_addrenv_assign(task_addrenv_t addrenv, FAR _TCB *tcb) { - /* Restore the CBR value */ + FAR struct z180_cbr_s *cbr = (FAR struct z180_cbr_s *)addrenv; + int ret; + + /* Make sure that there is no address environment in place on this TCB */ - outp(Z180_MMU_CBR, (uint8_t)handle); + DEBUGASSERT(cbr && tcb->xcp.cbr == NULL); + + /* Save the CBR strucure in the TCB. This is an atomic operation so no + * special precautions should be needed. + */ + + tcb->xcp.cbr = cbr; + return OK; +} + +/**************************************************************************** + * Name: up_addrenv_share + * + * Description: + * This function is called from the core scheduler logic when a thread + * is created that needs to share the address ennvironment of its parent + * task. In this case, the parent's address environment needs to be + * "cloned" for the child. + * + * Input Parameters: + * ptcb - The TCB of the parent task that has the address environment. + * ctcb - The TCB of the child thread needing the address environment. + * + * Returned Value: + * Zero (OK) on success; a negated errno value on failure. + * + ****************************************************************************/ + +int up_addrenv_share(FAR const _TCB *ptcb, FAR _TCB *ctcb) +{ + irqstate_t flags; + + /* Make sure that the child has no address environment. It is okay if + * if the parent does not have one. + */ + + DEBUGASSERT(ctcb->xcp.cbr == NULL); + + flags = irqsave(); + if (ptcb->xcp.cbr) + { + /* Clone the CBR by incrementing the reference counting and saving a + * copy in the child thread's TCB. + */ + + ptcb->xcp.cbr->crefs++; + ctcb->xcp.cbr = ptcb->xcp.cbr; + } + + irqrestore(flags); return OK; } @@ -407,7 +524,7 @@ int up_addrenv_release(FAR _TCB *tcb) cbr = tcb->xcp.cbr; if (cbr) { - /* Nullify the reference to the CBR structgure and decrement the number + /* Nullify the reference to the CBR structure and decrement the number * of references on the CBR. */ @@ -419,7 +536,7 @@ int up_addrenv_release(FAR _TCB *tcb) if (cbr->crefs <= 1) { - z180_mmu_freecbr(cbr); + up_addrenv_destroy(cbr); } else { diff --git a/nuttx/include/nuttx/arch.h b/nuttx/include/nuttx/arch.h index 7c444602e..8b4b10ade 100644 --- a/nuttx/include/nuttx/arch.h +++ b/nuttx/include/nuttx/arch.h @@ -46,6 +46,7 @@ #include <stdint.h> #include <stdbool.h> #include <sched.h> + #include <arch/arch.h> /**************************************************************************** @@ -381,17 +382,47 @@ void up_allocate_heap(FAR void **heap_start, size_t *heap_size); #endif /**************************************************************************** + * Address Environment Interfaces + * + * Low-level interfaces used in binfmt/ to instantiate tasks with address + * environments. These interfaces all operate on type task_addrenv_t which + * is an abstract representation of a task's address environment and must be + * defined in arch/arch.h if CONFIG_ADDRENV is defined. + * + * up_addrenv_create - Create an address environment + * up_addrenv_vaddr - Returns the virtual base address of the address + * environment + * up_addrenv_select - Instantiate an address environment + * up_addrenv_restore - Restore an address environment + * up_addrenv_destroy - Destroy an address environment. + * up_addrenv_assign - Assign an address environment to a TCB + * + * Higher-level interfaces used by the tasking logic. These interfaces are + * used by the functions in sched/ and all operate on the TCB which as been + * assigned an address environment by up_addrenv_assign(). + * + * up_addrenv_share - Clone the address environment assigned to one TCB + * to another. This operation is done when a pthread + * is created that share's the same address + * environment. + * up_addrenv_release - Release the TCBs reference to an address + * environment when a task/thread exits. + * + ****************************************************************************/ +/**************************************************************************** * Name: up_addrenv_create * * Description: * This function is called from the binary loader logic when a new - * task is created in RAM in order to instantiate an address environment for - * the task. + * task is created in order to instantiate an address environment for the + * task. up_addrenv_create is essentially the allocator of the physical + * memory for the new task. * * Input Parameters: - * tcb - The TCB of the task needing the address environment. * envsize - The size (in bytes) of the address environment needed by the * task. + * addrenv - The location to return the representation of the task address + * environment. * * Returned Value: * Zero (OK) on success; a negated errno value on failure. @@ -399,21 +430,21 @@ void up_allocate_heap(FAR void **heap_start, size_t *heap_size); ****************************************************************************/ #ifdef CONFIG_ADDRENV -int up_addrenv_create(FAR _TCB *tcb, size_t envsize); +int up_addrenv_create(size_t envsize, FAR task_addrenv_t *addrenv); #endif /**************************************************************************** - * Name: up_addrenv_share + * Name: up_addrenv_vaddr * * Description: - * This function is called from the core scheduler logic when a thread - * is created that needs to share the address ennvironment of its parent - * task. In this case, the parent's address environment needs to be - * "cloned" for the child. + * Return the virtual address associated with the newly create address + * environment. This function is used by the binary loaders in order + * get an address that can be used to initialize the new task. * * Input Parameters: - * ptcb - The TCB of the parent task that has the address environment. - * ctcb - The TCB of the child thread needing the address environment. + * addrenv - The representation of the task address environment previously + * returned by up_addrenv_create. + * vaddr - The location to return the virtual address. * * Returned Value: * Zero (OK) on success; a negated errno value on failure. @@ -421,11 +452,11 @@ int up_addrenv_create(FAR _TCB *tcb, size_t envsize); ****************************************************************************/ #ifdef CONFIG_ADDRENV -int up_addrenv_share(FAR const _TCB *ptcb, FAR _TCB *ctcb); +int up_addrenv_vaddr(FAR task_addrenv_t addrenv, FAR void **vaddr); #endif /**************************************************************************** - * Name: up_addrenv_instantiate + * Name: up_addrenv_select * * Description: * After an address environment has been established for a task (via @@ -435,28 +466,97 @@ int up_addrenv_share(FAR const _TCB *ptcb, FAR _TCB *ctcb); * to access address environment private data. * * Input Parameters: - * tcb - The TCB of the task or thread whose the address environment will - * be instantiated. + * addrenv - The representation of the task address environment previously + * returned by up_addrenv_create. + * oldenv + * The address environment that was in place before up_addrenv_select(). + * This may be used with up_addrenv_restore() to restore the original + * address environment that was in place before up_addrenv_select() was + * called. Note that this may be a task agnostic, hardware + * representation that is different from task_addrenv_t. * * Returned Value: - * A handle that may be used with up_addrenv_restore() to restore the - * address environment before up_addrenv_instantiate() was called. + * Zero (OK) on success; a negated errno value on failure. * ****************************************************************************/ #ifdef CONFIG_ADDRENV -FAR void *up_addrenv_instantiate(FAR _TCB *tcb); +int up_addrenv_select(task_addrenv_t addrenv, hw_addrenv_t *oldenv); #endif /**************************************************************************** * Name: up_addrenv_restore * * Description: - * Restore an address environment using a handle previously returned by - * up_addrenv_instantiate(). + * After an address environment has been temporarilty instantiated by + * up_addrenv_select, this function may be called to to restore the + * original address environment. + * + * Input Parameters: + * oldenv - The hardware representation of the address environment + * previously returned by up_addrenv_select. + * + * Returned Value: + * Zero (OK) on success; a negated errno value on failure. + * + ****************************************************************************/ + +#ifdef CONFIG_ADDRENV +int up_addrenv_restore(hw_addrenv_t oldenv); +#endif + +/**************************************************************************** + * Name: up_addrenv_destroy + * + * Description: + * Called from the binary loader loader during error handling to destroy + * the address environment previously created by up_addrenv_create(). + * + * Input Parameters: + * addrenv - The representation of the task address environment previously + * returned by up_addrenv_create. + * + * Returned Value: + * Zero (OK) on success; a negated errno value on failure. + * + ****************************************************************************/ + +#ifdef CONFIG_ADDRENV +int up_addrenv_destroy(task_addrenv_t addrenv); +#endif + +/**************************************************************************** + * Name: up_addrenv_assign + * + * Description: + * Assign an address environment to a TCB. + * + * Input Parameters: + * addrenv - The representation of the task address environment previously + * returned by up_addrenv_create. + * tcb - The TCB of the task to receive the address environment. + * + * Returned Value: + * Zero (OK) on success; a negated errno value on failure. + * + ****************************************************************************/ + +#ifdef CONFIG_ADDRENV +int up_addrenv_assign(task_addrenv_t addrenv, FAR _TCB *tcb); +#endif + +/**************************************************************************** + * Name: up_addrenv_share + * + * Description: + * This function is called from the core scheduler logic when a thread + * is created that needs to share the address ennvironment of its parent + * task. In this case, the parent's address environment needs to be + * "cloned" for the child. * * Input Parameters: - * handle - A handle previously returned by up_addrenv_instantiate. + * ptcb - The TCB of the parent task that has the address environment. + * ctcb - The TCB of the child thread needing the address environment. * * Returned Value: * Zero (OK) on success; a negated errno value on failure. @@ -464,7 +564,7 @@ FAR void *up_addrenv_instantiate(FAR _TCB *tcb); ****************************************************************************/ #ifdef CONFIG_ADDRENV -int up_addrenv_restore(FAR void *handle); +int up_addrenv_share(FAR const _TCB *ptcb, FAR _TCB *ctcb); #endif /**************************************************************************** diff --git a/nuttx/include/nuttx/binfmt/binfmt.h b/nuttx/include/nuttx/binfmt/binfmt.h index 200823bb8..2e2c6dda8 100644 --- a/nuttx/include/nuttx/binfmt/binfmt.h +++ b/nuttx/include/nuttx/binfmt/binfmt.h @@ -69,7 +69,7 @@ typedef FAR void (*binfmt_dtor_t)(void); /* This describes the file to be loaded. * - * NOTE: The 'filename' must be the full, absolute path to the file to be + * NOTE 1: The 'filename' must be the full, absolute path to the file to be * executed unless CONFIG_BINFMT_EXEPATH is defined. In that case, * 'filename' may be a relative path; a set of candidate absolute paths * will be generated using the PATH environment variable and load_module() @@ -81,7 +81,7 @@ struct binary_s { /* Information provided to the loader to load and bind a module */ - FAR const char *filename; /* Full path to the binary to be loaded (See NOTE above) */ + FAR const char *filename; /* Full path to the binary to be loaded (See NOTE 1 above) */ FAR const char **argv; /* Argument list */ FAR const struct symtab_s *exports; /* Table of exported symbols */ int nexports; /* The number of symbols in exports[] */ |