Update On-demand paging documentation

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

1 files changed, 70 insertions, 16 deletions

diff --git a/nuttx/Documentation/NuttxPortingGuide.html b/nuttx/Documentation/NuttxPortingGuide.html
index 13a4775ef..e0947657b 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: August 16, 2010</p>
+      <p>Last Updated: August 21, 2010</p>
     </td>
   </tr>
 </table>
@@ -2390,7 +2390,6 @@ extern void up_ledoff(int led);
   If CONFIG_PAGING is selected, then the following also apply:
 </p>
 <ul>
-  </li>
   <li>
     <code>CONFIG_PAGING_PAGESIZE</code>:
     The size of one managed page.
@@ -2403,30 +2402,68 @@ extern void up_ledoff(int led);
     (<code>CONFIG_DRAM_VSTART</code> + <code>CONFIG_PAGING_PAGESIZE</code>*<code>CONFIG_PAGING_NLOCKED</code>)
   </li>
   <li>
-    <code>CONFIG_PAGING_NPAGES</code>:
-    The number of pages in the paged region of the memory map. 
-    This paged region then begins at
-    (<code>CONFIG_DRAM_VSTART</code> + <code>CONFIG_PAGING_PAGESIZE</code>*<code>CONFIG_PAGING_NLOCKED</code>)
-    and continues until (<code>CONFIG_DRAM_VSTART</code> +
-    <code>CONFIG_PAGING_PAGESIZE</code>*(<code>CONFIG_PAGING_NLOCKED</code> + <code>CONFIG_PAGING_NPAGES</code>)
+    <code>CONFIG_PAGING_LOCKED_PBASE</code> and <code>CONFIG_PAGING_LOCKED_VBASE</code>:
+    These may be defined to determine the base address of the locked page regions.
+    If neither are defined, the logic will be set the bases to <code>CONFIG_DRAM_START</code>
+    and <code>CONFIG_DRAM_VSTART</code> (i.e., it assumes that the base address of the locked
+    region is at the beginning of RAM).
+    <b>NOTE</b>:
+    In some architectures, it may be necessary to take some memory from the beginning
+    of this region for vectors or for a page table.
+    In such cases, <code>CONFIG_PAGING_LOCKED_P/VBASE</code> should take that into consideration
+    to prevent overlapping the locked memory region and the system data at the beginning of SRAM.
+  </li>
+  <li>
+    <code>CONFIG_PAGING_NPPAGED</code>:
+    This is the number of physical pages available to support the paged text region.
+    This paged region begins at
+    (<code>CONFIG_PAGING_LOCKED_PBASE</code> + <code>CONFIG_PAGING_PAGESIZE</code>*<code>CONFIG_PAGING_NPPAGED</code>)
+    and continues until
+    (<code>CONFIG_PAGING_LOCKED_PBASE</code> + <code>CONFIG_PAGING_PAGESIZE</code>*(<code>CONFIG_PAGING_NLOCKED</code> +
+    <code>CONFIG_PAGING_NPPAGED</code>)
+  </li>
+  <li>
+    <code>CONFIG_PAGING_NVPAGED</code>:
+    This actual size of the paged text region (in pages).
+    This is also the number of virtual pages required to support the entire paged region.
+    The on-demand paging feature is intended to support only the case where the virtual paged text
+    area is much larger the available physical pages.
+    Otherwise, why would you enable on-demand paging?
+  </li>
+  <li>
+    <code>CONFIG_PAGING_NDATA</code>:
+    This is the number of data pages in the memory map.
+    The data region will extend to the end of RAM unless overridden by a setting in the configuration file.
+    <b>NOTE</b>:
+    In some architectures, it may be necessary to take some memory from the end of RAM for page tables
+    or other system usage.
+    The configuration settings and linker directives must be cognizant of that:
+    <code>CONFIG_PAGING_NDATA</code> should be defined to prevent the data region from extending all the way to the end of memory. 
   </li>
   <li>
     <code>CONFIG_PAGING_DEFPRIO</code>:
     The default, minimum priority of the page fill worker thread.
-    The priority of the page fill work thread will be boosted boosted dynmically so that it matches the priority of the task on behalf of which it peforms the fill.
-    This defines the minimum priority that will be used.
-    Default: 50.
+    The priority of the page fill work thread will be boosted boosted dynmically so that it matches the
+    priority of the task on behalf of which it peforms the fill.
+    This defines the minimum priority that will be used. Default: 50.
   </li>
   <li>
-    <code>CONFIG_PAGING_STACKSIZE </code>:
-    Defines the size of the allocated stack for the page fill worker thread.
-    Default: 1024.
+    <code>CONFIG_PAGING_STACKSIZE</code>:
+    Defines the size of the allocated stack for the page fill worker thread. Default: 1024.
   </li>
   <li>
     <code>CONFIG_PAGING_BLOCKINGFILL</code>:
     The architecture specific <code>up_fillpage()</code> function may be blocking or non-blocking.
-    If defined, this setting indicates that the <code>up_fillpage()</code> implementation will block until the transfer is completed.
-    Default:  Undefined (non-blocking).
+    If defined, this setting indicates that the <code>up_fillpage()</code> implementation will block until the
+    transfer is completed. Default:  Undefined (non-blocking).
+  </li>
+  <li>
+    <code>CONFIG_PAGING_WORKPERIOD</code>:
+    The page fill worker thread will wake periodically even if there is no mapping to do.
+    This selection controls that wake-up period (in microseconds).
+    This wake-up a failsafe that will handle any cases where a single is lost (that would
+    really be a bug and shouldn't happen!)
+    and also supports timeouts for case of non-blocking, asynchronous fills (see <code>CONFIG_PAGING_TIMEOUT_TICKS</code>).
   </li>
   <li>
     <code>CONFIG_PAGING_TIMEOUT_TICKS</code>:
@@ -2434,6 +2471,23 @@ extern void up_ledoff(int led);
     If the fill takes longer than this number if microseconds, then a fatal error will be declared.
     Default: No timeouts monitored.
   </li>
+  <p>
+    Some architecture-specific settings. 
+    Defaults are architecture specific.
+    If you don't know what you are doing, it is best to leave these undefined and try the system defaults:
+  </p>
+  <li>
+    <code>CONFIG_PAGING_VECPPAGE</code>:
+    This the physical address of the page in memory to be mapped to the vector address.
+  </li>
+  <li>
+    <code>CONFIG_PAGING_VECL2PADDR</code>:
+    This is the physical address of the L2 page table entry to use for the vector mapping.
+  </li>
+  <li>
+    <code>CONFIG_PAGING_VECL2VADDR</code>:
+    This is the virtual address of the L2 page table entry to use for the vector mapping.
+  </li>
 </ul>
 <p>
   The following can be used to disable categories of APIs supported