h6. [[OS_DynamicArea]] h6(. » [[Dynamic Area Handler Code]] h6((. » Dynamic Area PreGrow |_<^{width:3em}. Entry | | |<^. R0 |<^. 0 (handler reason) | |<^. R1 |<^. Pointer to [[OS_Memory Page Blocks|page block array]], if the area has [[Dynamic Area Flags|flag bit 8]] set (otherwise, undefined) | |<^. R2 |<^. Number of entries in page block | |<^. R3 |<^. Amount area is growing by for this call (bytes), i.e. R2*R5 | |<^. R4 |<^. Current size of area (bytes)| |<^. R5 |<^. Page size (bytes)| |<^. R12 |<^. Workspace pointer passed to [[OS_DynamicArea 0]] or base of area| |_<^{width:3em}. Exit |_<^. (Success) | |<^. R0 |<^. "RESV" (&56534552) to signify intent to use [[OS_Memory 23|reserved pages]], or preserved | | |<^. All registers preserved | | |<^. V clear | | |<^. Physical page numbers in page block updated (optional) | |_<^{width:3em}. Exit |_<^. (Error) | |<^. R0 |<^. Pointer to error block, or 0 for a default error to be used | | |<^. All other registers preserved | | |<^. V set | h4. Use The call has two purposes: # Informing the dynamic area owner of a request to grow the area (e.g. in response to the user dragging the bar in the task manager) # Allowing areas which request specific pages (via bit 8 of the area flags) to control which pages they are given The handler can prevent the grow from taking place if by returning with an error. For areas which request specific pages, on entry the page block array will have the physical page numbers set to -1, and the other attributes undefined. On exit, the page block should either be in its original state (in which case the kernel will pick pages from the free pool as normal), or all the physical page numbers must have been replaced with valid values. The other fields in the page block (logical address, physical address) are not used. If the handler does request specific pages, then the page block array will be treated as if it lists the pages in increasing logical address order. I.e. the first entry in the page block will be used to determine which page to use for the lowest logical address in the grown area, and the last entry will be used to determine the page to use for the highest address. If pages are requested which are being used by another dynamic area then the kernel will give the owner of that page a replacement page taken from the free pool (copying the current contents into the replacement), as well as issue [[Service_PagesUnsafe]] and [[Service_PagesSafe]] to ensure that any DMA operations which are targeting the page(s) are aware of the change. The page copy will be performed with IRQs disabled and with the FIQ vector temporarily claimed by the kernel; this makes the page replacement entirely transparent to most software. If the handler requests specific page numbers, it can return with R0 set to "RESV" (&56534552) in order to allow the use of pages which have previously been reserved via [[OS_Memory 23]]. Otherwise, attempting to use a reserved page will fail. This is a simple safety feature aimed at reducing the risk of buggy dynamic area handlers accidentally claiming pages which had been reserved by someone else. Any specifically requested pages which are assigned to the dynamic area will be "locked" in place until the dynamic area releases them. I.e. the kernel will not replace them with different physical pages, or allow other dynamic areas to take the pages away. h4. See also * [[Dynamic Area Handler Code]] * [[OS_DynamicArea]] * [[OS_DynamicArea 0]] * [[Service_PagesUnsafe]] * [[Service_PagesSafe]] * [[OS_Memory 23]]