Restructre address environment interfaces in preparation for incorporation into binfmt/ logic

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@5442 42af7a65-404d-4744-a932-0658087f49c3

2 files changed, 124 insertions, 24 deletions

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[] */