From a641b354b744cc0478339e4616997aa960f5e19e Mon Sep 17 00:00:00 2001
From: Gregory Nutt <gnutt@nuttx.org>
Date: Sun, 24 Aug 2014 11:54:14 -0600
Subject: [PATCH] addrenv interface changes: up_addrenv_create() may need to
 create .text and .bss/.data separately because of differing access privileges
 (read/execute vs read/write).  And, as a consequence, up_addrenv_vaddr()
 needs to be split into up_addrenv_vtext(0 and up_addrenv_vdata().

---
 Documentation/NuttxPortingGuide.html | 79 +++++++++++++++++++---------
 1 file changed, 53 insertions(+), 26 deletions(-)

diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html
index e76b2ce0a5..f67ccdc0d3 100644
--- a/Documentation/NuttxPortingGuide.html
+++ b/Documentation/NuttxPortingGuide.html
@@ -12,7 +12,7 @@
       <h1><big><font color="#3c34ec">
         <i>NuttX RTOS Porting Guide</i>
       </font></big></h1>
-      <p>Last Updated: August 22, 2014</p>
+      <p>Last Updated: August 24, 2014</p>
     </td>
   </tr>
 </table>
@@ -108,12 +108,13 @@
     <ul>
       <a href="#up_addrenv_create">4.4.1 <code>up_addrenv_create()</code></a></br>
       <a href="#up_addrenv_destroy">4.4.2 <code>up_addrenv_destroy()</code></a></br>
-      <a href="#up_addrenv_vaddr">4.4.3 <code>up_addrenv_vaddr()</code></a></br>
-      <a href="#up_addrenv_select">4.4.4 <code>up_addrenv_select()</code></a></br>
-      <a href="#up_addrenv_restore">4.4.5 <code>up_addrenv_restore()</code></a></br>
-      <a href="#up_addrenv_assign">4.4.6 <code>up_addrenv_assign()</code></a></br>
-      <a href="#up_addrenv_attach">4.4.7 <code>up_addrenv_attach()</code></a></br>
-      <a href="#up_addrenv_detach">4.4.8 <code>up_addrenv_detach()</code></a>
+      <a href="#up_addrenv_vtext">4.4.3 <code>up_addrenv_vtext()</code></a></br>
+      <a href="#up_addrenv_vdata">4.4.4 <code>up_addrenv_vdata()</code></a></br>
+      <a href="#up_addrenv_select">4.4.5 <code>up_addrenv_select()</code></a></br>
+      <a href="#up_addrenv_restore">4.4.6 <code>up_addrenv_restore()</code></a></br>
+      <a href="#up_addrenv_assign">4.4.7 <code>up_addrenv_assign()</code></a></br>
+      <a href="#up_addrenv_attach">4.4.8 <code>up_addrenv_attach()</code></a></br>
+      <a href="#up_addrenv_detach">4.4.9 <code>up_addrenv_detach()</code></a>
     </ul>
     <a href="#exports">4.5 APIs Exported by NuttX to Architecture-Specific Logic</a>
     <ul>
@@ -2943,19 +2944,23 @@ VxWorks provides the following comparable interface:
         Destroy an address environment.
       </li>
       <li>
-        <a href="#up_addrenv_vaddr">4.4.3 <code>up_addrenv_vaddr()</code></a>:
-        Returns the virtual base address of the address environment.
+        <a href="#up_addrenv_vtext">4.4.3 <code>up_addrenv_vtext()</code></a>:
+        Returns the virtual base address of the <code>.text</code> address environment.
       </li>
       <li>
-        <a href="#up_addrenv_select">4.4.4 <code>up_addrenv_select()</code></a>:
+        <a href="#up_addrenv_vdata">4.4.4 <code>up_addrenv_vdata()</code></a>:
+        Returns the virtual base address of the <code>.bss</code>/<code>.data</code> address environment.
+      </li>
+      <li>
+        <a href="#up_addrenv_select">4.4.5 <code>up_addrenv_select()</code></a>:
         Instantiate an address environment.
       </li>
       <li>
-        <a href="#up_addrenv_restore">4.4.5 <code>up_addrenv_restore()</code></a>:
+        <a href="#up_addrenv_restore">4.4.6 <code>up_addrenv_restore()</code></a>:
         Restore an address environment.
       </li>
       <li>
-        <a href="#up_addrenv_assign">4.4.6 <code>up_addrenv_assign()</code></a>:
+        <a href="#up_addrenv_assign">4.4.7 <code>up_addrenv_assign()</code></a>:
         Assign an address environment to a thread.
       </li>
     </ul>
@@ -2968,12 +2973,12 @@ VxWorks provides the following comparable interface:
     </p>
     <ul>
       <li>
-        <a href="#up_addrenv_attach">4.4.7 <code>up_addrenv_attach()</code></a>:
+        <a href="#up_addrenv_attach">4.4.8 <code>up_addrenv_attach()</code></a>:
         Clone the group address environment assigned to a new thread.
         This operation is done when a pthread is created that share's the same address environment.
       </li>
       <li>
-        <a href="#up_addrenv_detach">4.4.8 <code>up_addrenv_detach()</code></a>:
+        <a href="#up_addrenv_detach">4.4.9 <code>up_addrenv_detach()</code></a>:
         Release the thread's reference to a group address environment when a task/thread exits.
       </li>
     </ul>
@@ -2983,7 +2988,7 @@ VxWorks provides the following comparable interface:
 <h3><a name="up_addrenv_create">4.4.1 <code>up_addrenv_create()</code></a></h3>
 <p><b>Function Prototype</b>:</p>
 <ul>
-  <code>int up_addrenv_create(size_t envsize, FAR group_addrenv_t *addrenv);</code>
+  <code>int up_addrenv_create(size_t textsize, size_t datasize, FAR group_addrenv_t *addrenv);</code>
 </ul>
 <p><b>Description</b>:</p>
 <ul>
@@ -2992,7 +2997,8 @@ VxWorks provides the following comparable interface:
 </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>textsize</code>: The size (in bytes) of the <code>.text</code> address environment needed by the task.  This region may be read/execute only.</li>
+  <li><code>datasize</code>: The size (in bytes) of the <code>.bss/.data</code> address environment needed by the task.   This region may be read/write only.</li>
   <li><code>addrenv</code>: The location to return the representation of the task address environment.</li>
 </ul>
 <p><b>Returned Value</b>:</p>
@@ -3018,27 +3024,48 @@ VxWorks provides the following comparable interface:
   Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure.
 </ul>
 
-<h3><a name="up_addrenv_vaddr">4.4.3 <code>up_addrenv_vaddr()</code></a></h3>
+<h3><a name="up_addrenv_vtext">4.4.3 <code>up_addrenv_vtext()</code></a></h3>
 <p><b>Function Prototype</b>:<p>
 <ul>
-  <code>int up_addrenv_vaddr(FAR group_addrenv_t addrenv, FAR void **vaddr);</code>
+  <code>int up_addrenv_vtext(FAR group_addrenv_t addrenv, FAR void **vtext);</code>
 </ul>
 <p><b>Description</b>:</p>
 <ul>
-  Return the virtual address associated with the newly create address environment.
+  Return the virtual <code>.text</code> 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>
+  <li><code>vtext</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>
 
-<h3><a name="up_addrenv_select">4.4.4 <code>up_addrenv_select()</code></a></h3>
+<h3><a name="up_addrenv_vdata">4.4.4 <code>up_addrenv_vdata()</code></a></h3>
+<p><b>Function Prototype</b>:<p>
+<ul>
+  <code>int up_addrenv_vdata(FAR group_addrenv_t addrenv, size_t textsize, FAR void **vdata);</code>
+</ul>
+<p><b>Description</b>:</p>
+<ul>
+  Return the virtual <code>.text</code> 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>textsize</code>: For some implementations, the text and data will be saved in the same memory region (read/write/execute) and, in this case, the virtual address of the data just lies at this offset into the common region.</li>
+  <li><code>vdata</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>
+
+<h3><a name="up_addrenv_select">4.4.5 <code>up_addrenv_select()</code></a></h3>
 <p><b>Function Prototype</b>:<p>
 <ul>
   <code>int up_addrenv_select(group_addrenv_t addrenv, save_addrenv_t *oldenv);</code>
@@ -3062,7 +3089,7 @@ VxWorks provides the following comparable interface:
   Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure.
 </ul>
 
-<h3><a name="up_addrenv_restore">4.4.5 <code>up_addrenv_restore()</code></a></h3>
+<h3><a name="up_addrenv_restore">4.4.6 <code>up_addrenv_restore()</code></a></h3>
 <p><b>Function Prototype</b>:<p>
 <ul>
   <code>int up_addrenv_restore(save_addrenv_t oldenv);</code>
@@ -3081,10 +3108,10 @@ VxWorks provides the following comparable interface:
   Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure.
 </ul>
 
-<h3><a name="up_addrenv_assign">4.4.6 <code>up_addrenv_assign()</code></a></h3>
+<h3><a name="up_addrenv_assign">4.4.7 <code>up_addrenv_assign()</code></a></h3>
 <p><b>Function Prototype</b>:<p>
 <ul>
-  <code>int up_addrenv_assign(group_addrenv_t addrenv, FAR struct task_group_s *group);</code>
+  <code>int up_addrenv_assign(FAR const group_addrenv_t *addrenv, FAR struct task_group_s *group);</code>
 </ul>
 <p><b>Description</b>:</p>
 <ul>
@@ -3100,7 +3127,7 @@ VxWorks provides the following comparable interface:
   Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure.
 </ul>
 
-<h3><a name="up_addrenv_attach">4.4.7 <code>up_addrenv_attach()</code></a></h3>
+<h3><a name="up_addrenv_attach">4.4.8 <code>up_addrenv_attach()</code></a></h3>
 <p><b>Function Prototype</b>:<p>
 <ul>
   <code>int up_addrenv_attach(FAR struct task_group_s *group, FAR struct tcb_s *tcb);</code>
@@ -3126,7 +3153,7 @@ VxWorks provides the following comparable interface:
   Zero (<code>OK</code>) on success; a negated <code>errno</code> value on failure.
 </ul>
 
-<h3><a name="up_addrenv_detach">4.4.8 <code>up_addrenv_detach()</code></a></h3>
+<h3><a name="up_addrenv_detach">4.4.9 <code>up_addrenv_detach()</code></a></h3>
 <p><b>Function Prototype</b>:<p>
 <ul>
   <code>int up_addrenv_detach(FAR struct task_group_s *group, FAR struct task_group_s *tcb);</code>