Last Updated: September 10, 2014
+Last Updated: September 13, 2014
@@ -115,7 +115,11 @@ 4.4.7up_addrenv_restore()
4.4.8 up_addrenv_clone()
4.4.9 up_addrenv_attach()
- 4.4.10 up_addrenv_detach()
+ 4.4.10 up_addrenv_detach()
+ 4.4.11 up_addrenv_stackalloc()
+ 4.4.12 up_addrenv_stackfree()
+ 4.4.13 up_addrenv_vstack()
+ 4.4.14 up_addrenv_stackselect()
4.5 APIs Exported by NuttX to Architecture-Specific Logic
+ Dynamic Stack Support.
+ CONFIG_ARCH_STACK_DYNAMIC=y indicates that the user process stack resides in its own address space.
+ This options is also required if CONFIG_BUILD_KERNEL and CONFIG_LIBC_EXECFUNCS are selected.
+ Why?
+ Because the caller's stack must be preserved in its own address space when we instantiate the environment of the new process in order to initialize it.
+
+ NOTE: The naming of the CONFIG_ARCH_STACK_DYNAMIC selection implies that dynamic stack allocation is supported.
+ Certainly this option must be set if dynamic stack allocation is supported by a platform.
+ But the more general meaning of this configuration environment is simply that the stack has its own address space.
+
+ If CONFIG_ARCH_STACK_DYNAMIC=y is selected then the platform specific code must export these additional interfaces:
+
up_addrenv_stackalloc():
+ Create a stack address environment
+ up_addrenv_stackfree():
+ Destroy a stack address environment.
+ up_addrenv_vstack():
+ Returns the virtual base address of the stack
+ up_addrenv_stackselect():
+ Instantiate a stack address environment
+ up_addrenv_create()OK) on success; a negated errno value on failure.
+up_addrenv_stackalloc()Function Prototype:
+
int up_addrenv_stackalloc(FAR struct tcb_s *tcb, size_t stacksize);
+Description:
+
+ This function is called when a new thread is created in order to instantiate an address environment for the new thread's stack.
+ up_addrenv_stackalloc() is essentially the allocator of the physical memory for the new task's stack.
+
Input Parameters:
+tcb: The TCB of the thread that requires the stack address environment.stacksize: The size (in bytes) of the initial stack address environment needed by the task. This region may be read/write only.Returned Value:
+OK) on success; a negated errno value on failure.
+up_addrenv_stackfree()Function Prototype:
+
int up_addrenv_stackfree(FAR struct tcb_s *tcb);
+Description:
++ This function is called when any thread exits. + This function then destroys the defunct address environment for the thread's stack, releasing the underlying physical memory. +
+Input Parameters:
+tcb: The TCB of the thread that no longer requires the stack address environment.Returned Value:
+OK) on success; a negated errno value on failure.
+up_addrenv_vstack()Function Prototype:
+
int up_addrenv_vstack(FAR const struct tcb_s *tcb, FAR void **vstack);
+Description:
++ Return the virtual address associated with the newly create stack address environment. +
+Input Parameters:
+tcb:The TCB of the thread with the stack address environment of interest. vstack: The location to return the stack virtual base address.Returned Value:
+OK) on success; a negated errno value on failure.
+up_addrenv_stackselect()Function Prototype:
+
int up_addrenv_stackselect(FAR const struct tcb_s *tcb);
+Description:
+
+ After an address environment has been established for a task's stack (via up_addrenv_stackalloc().
+ This function may be called to instantiate that address environment in the virtual address space.
+ This is a necessary step before each context switch to the newly created thread (including the initial thread startup).
+
Input Parameters:
+tcb: The TCB of the thread with the stack address environment to be instantiated.Returned Value:
+OK) on success; a negated errno value on failure.
+These are standard interfaces that are exported by the OS