diff --git a/Documentation/NuttXDemandPaging.html b/Documentation/NuttXDemandPaging.html index cf4bb0ce42a..fb0894d6bef 100755 --- a/Documentation/NuttXDemandPaging.html +++ b/Documentation/NuttXDemandPaging.html @@ -72,7 +72,7 @@
g_waitingforfillg_pendingfillg_pendingfilltcbg_pgworkerpg_callback()pg_miss()TCB
Declarations for g_waitingforfill, g_pgworker, and other
internal, private definitions will be provided in sched/pg_internal.h.
- All public definitions that should be used by the chip-specific code will be available
- in include/nuttx/page.h and include/nuttx/arch.h.
+ All public definitions that should be used by the architecture-specific code will be available
+ in include/nuttx/page.h.
+ Most architecture-specific functions are declared in include/nuttx/arch.h,
+ but for the case of this paging logic, those architecture specific functions are instead declared in include/nuttx/page.h.
g_waitingforfill list.
If the priority of that task is higher than the current priority of the page fill worker thread, then boost the priority of the page fill worker thread to that priority.
+ Thus, the page fill worker thread will always run at the priority of the highest priority task that is waiting for a fill.
- Locking code in Memory. - One way to accomplish this would be a two phase link: -
.text and .rodata sections of this partial link should be collected into a single section.
- - The page fill worker thread will be awakened on one of two conditions: + The page fill worker thread will be awakened on one of three conditions:
pg_miss(), the page fill worker thread will be awakenend (see above), or
+ When signaled by pg_miss(), the page fill worker thread will be awakenend (see above),
pg_fillcomplete() after completing last fill (see below).
+ From pg_callback() after completing last fill (when CONFIG_PAGING_BLOCKINGFILL is defined... see below), or
+
- The page fill worker thread will maintain a static variable called _TCB *g_pendingfill.
- If not fill is in progress, g_pendingfill will be NULL.
- Otherwise, will point to the TCB of the task which is receiving the fill that is in progess.
+ The page fill worker thread will maintain a static variable called _TCB *g_pendingfilltcb.
+ If no fill is in progress, g_pendingfilltcb will be NULL.
+ Otherwise, it will point to the TCB of the task which is receiving the fill that is in progess.
- When awakened from pg_miss(), no fill will be in progress and g_pendingfill will be NULL.
+ When awakened from pg_miss(), no fill will be in progress and g_pendingfilltcb will be NULL.
In this case, the page fill worker thread will call pg_startfill().
That function will perform the following operations:
up_allocpage(tcb, &vpage).
- This chip-specific function will set aside page in memory and map to virtual address (vpage).
- If all pages available pages are in-use (the typical case),
+ This architecture-specific function will set aside page in memory and map to virtual address (vpage).
+ If all available pages are in-use (the typical case),
this function will select a page in-use, un-map it, and make it available.
up_fillpage(page, pg_callback).
- This will start asynchronous page fill.
- The page fill worker thread will provide a callback function, pg_callback,
- that will be called when the page fill is finished (or an error occurs).
- This callback will probably from interrupt level.
- up_fillpage().
+ Two versions of the up_fillpage function are supported -- a blocking and a non-blocking version based upon the configuratin setting CONFIG_PAGING_BLOCKINGFILL.
+ CONFIG_PAGING_BLOCKINGFILL is defined, then up_fillpage is blocking call.
+ In this case, up_fillpage() will accept only (1) a reference to the TCB that requires the fill.
+ Architecture-specific context information within the TCB will be sufficient to perform the fill.
+ And (2) the (virtual) address of the allocated page to be filled.
+ The resulting status of the fill will be provided by return value from up_fillpage().
+ CONFIG_PAGING_BLOCKINGFILL is defined, then up_fillpage is non-blocking call.
+ In this case up_fillpage() will accept an additional argument:
+ The page fill worker thread will provide a callback function, pg_callback.
+ This function is non-blocking, it will start an asynchronous page fill.
+ After calling the non-blocking up_fillpage(), the page fill worker thread will wait to be signaled for the next event -- the fill completion event.
+ The callback function will be called when the page fill is finished (or an error occurs).
+ The resulting status of the fill will be providing as an argument to the callback functions.
+ This callback will probably occur from interrupt level.
+
- While the fill is in progress, other tasks may execute.
- If another page fault occurs during this time, the faulting task will be blocked and its TCB will be added (in priority order) to g_waitingforfill.
+ In any case, while the fill is in progress, other tasks may execute.
+ If another page fault occurs during this time, the faulting task will be blocked, its TCB will be added (in priority order) to g_waitingforfill, and the priority of the page worker task may be boosted.
But no action will be taken until the current page fill completes.
NOTE: The IDLE task must also be fully locked in memory.
The IDLE task cannot be blocked.
It the case where all tasks are blocked waiting for a page fill, the IDLE task must still be available to run.
- The chip-specific functions, up_allocpage(tcb, &vpage) and up_fillpage(page, pg_callback)
+ The architecture-specific functions, up_checkmapping(), up_allocpage(tcb, &vpage) and up_fillpage(page, pg_callback)
will be prototyped in include/nuttx/arch.h
- When the chip-specific driver completes the page fill, it will call the pg_callback() that was provided to up_fillpage.
- pg_callback() will probably be called from driver interrupt-level logic.
- The driver ill provide the result of the fill as an argument.
+ For the blocking up_fillpage(), the result of the fill will be returned directly from the call to up_fillpage.
+
+ For the non-blocking up_fillpage(), the architecture-specific driver call the pg_callback() that was provided to up_fillpage() when the fill completes.
+ In this case, the pg_callback() will probably be called from driver interrupt-level logic.
+ The driver will provide the result of the fill as an argument to the callback function.
NOTE: pg_callback() must also be locked in memory.
- When pg_callback() is called, it will perform the following operations:
+ In this non-blocking case, the callback pg_callback() will perform the following operations when it is notified that the fill has completed:
g_pendingfill is non-NULL.
+ Verify that g_pendingfilltcb is non-NULL.
g_pendingfill is higher than page fill worker thread, boost work thread to that level.
+ Find the higher priority between the task waiting for the fill to complete in g_pendingfilltcb and the task waiting at the head of the g_waitingforfill list.
+ That will be the priority of he highest priority task waiting for a fill.
+
- When the page fill worker thread is awakened and g_pendingfill is non-NULL (and other state variables are in concurrence),
- the page fill thread will know that is was awakened because of a page fill completion event.
- In this case, the page fill worker thread will:
+ For the non-blocking up_fillpage(), the page fill worker thread will detect that the page fill is complete when it is awakened with g_pendingfilltcb non-NULL and fill completion status from pg_callback.
+ In the non-blocking case, the page fill worker thread will know that the page fill is complete when up_fillpage() returns.
+
+ In this either, the page fill worker thread will:
g_pendingfill.
+ Verify consistency of state information and g_pendingfilltcb.
up_unblocktask(g_pendingfill) to make the task that just received the fill ready-to-run.
+ Call up_unblocktask(g_pendingfilltcb) to make the task that just received the fill ready-to-run.
g_waitingforfill list is empty.
@@ -409,10 +432,10 @@
Remove the highest priority task waiting for a page fill from g_waitingforfill,
g_pendingfill,
+ Save the task's TCB in g_pendingfilltcb,
g_pendingfill, is higher in priority than the default priority of the page fill worker thread, then set the priority of the page fill worker thread to that priority.
+ If the priority of the thread in g_pendingfilltcb, is higher in priority than the default priority of the page fill worker thread, then set the priority of the page fill worker thread to that priority.
pg_startfill() which will start the next fill (as described above).
@@ -423,7 +446,7 @@
Otherwise,
g_pendingfill to NULL.
+ Set g_pendingfilltcb to NULL.
+ Memory Regions. Chip specific logic will map the virtual and physical address spaces into three general regions:
pg_miss() that is called from the page fault handler.
It also includes the pg_callback() function that wakes up the page fill worker thread
- and whatever chip-specific logic that calls pg_callback().
+ and whatever architecture-specific logic that calls pg_callback().
+ Example. As an example, suppose that the size of the SRAM is 192Kb (as in the NXP LPC3131). And suppose further that:
- Then, the size of the locked, memory resident code is 32Kb (32 pages). + Then, the size of the locked, memory resident code is 32Kb (m=32 pages). The size of the physical page region is 96Kb (96 pages), and the size of the data region is 64 pages. - And the size of the virtual paged region must then be greater than or equal to (1024-32) or 992 pages (m). + And the size of the virtual paged region must then be greater than or equal to (1024-32) or 992 pages (n). +
+ ++ Building the Locked, In-Memory Image. + One way to accomplish this would be a two phase link: +
.text and .rodata sections of this partial link should be collected into a single section.
+
- Standard functions that should already be provided in the architecture port:
+ Most standard, architecture-specific functions are declared in include/nuttx/arch.h.
+ However, for the case of this paging logic, the architecture specific functions are declared in include/nuttx/page.h.
+ Standard, architecture-specific functions that should already be provided in the architecture port.
+ The following are used by the common paging logic:
int up_checkmapping(FAR _TCB *tcb);
up_checkmapping() returns an indication that checks if the page fill still needs to performed or not.
+ The function up_checkmapping() returns an indication if the page fill still needs to performed or not.
In certain conditions, the page fault may occur on several threads and be queued multiple times.
This function will prevent the same page from be filled multiple times.
int up_allocpage(FAR _TCB *tcb, FAR void *vpage);
paddr.
- The size of a physical page is determined by the configuration setting CONFIG_PAGING_PAGESIZE.
+ This architecture-specific function will set aside page in memory and map to its correct virtual address.
+ Architecture-specific context information saved within the TCB will provide the function with the information needed to identify the virtual miss address.
+ This function will return the allocated physical page address in vpage.
+ The size of the underlying physical page is determined by the configuration setting CONFIG_PAGING_PAGESIZE.
NOTE: This function must always return a page allocation.
- If all pages available pages are in-use (the typical case), then this function will select a page in-use, un-map it, and make it available.
+ If all available pages are in-use (the typical case), then this function will select a page in-use, un-map it, and make it available.
int up_fillpage(FAR _TCB *tcb, FAR const void *vpage, void (*pg_callback)(FAR _TCB *tcb, int result));
up_fillpage().
+ The actual filling of the page with data from the non-volatile, must be performed by a separate call to the architecture-specific function, up_fillpage().
This will start asynchronous page fill.
- The common logic will provide a callback function, pg_callback, that will be called when the page fill is finished (or an error occurs).
+ The common paging logic will provide a callback function, pg_callback, that will be called when the page fill is finished (or an error occurs).
This callback is assumed to occur from an interrupt level when the device driver completes the fill operation.