Section 8.9. Universal Page Lists (UPLs)

8.9. Universal Page Lists (UPLs)

The kernel provides an abstraction called a universal page list (UPL), which can be thought of as a wrapper around a bounded set of pages.^[15] A UPL describes a set of physical pages associated with some address range of a VM object. In particular, a UPL provides a snapshot of various properties of its pages, such as whether the pages are mapped, dirty, encrypted, busy (access-blocked), or correspond to I/O memory.

^[15] A UPL can be considered as a Mach or BSD equivalent of an instance of the IOMemoryDescriptor class instance in the I/O Kit.

A UPL is internally created by upl_create() [osfmk/vm/vm_pageout.c], which allocates and initializes a UPL structure (struct upl [osfmk/vm/vm_pageout.h]). If the UPL is being created with the UPL_SET_INTERNAL control flag, all information about the UPL is contained in a single memory object, allowing convenient transportation of the UPL within the kernel. In the case of an internal UPL, upl_create() allocates additional memory to hold a upl_page_info structure [osfmk/mach/memory_object_types.h] for each page in the UPL. The maximum number of pages a UPL can handle is MAX_UPL_TRANSFER, which is defined to be 256that is, 1MB of memory.

The primary clients of the UPL API include pagers, the file system layer, and the unified buffer cache (UBC). Clients of the UPL API do not call upl_create() directly when they need to create a UPL based on the contents of a VM object; instead, they call other, higher-level functions such as vm_object_upl_request(), vm_object_iopl_request(), and vm_map_get_upl(). The latter is useful when you do not have the VM object in question, since it looks up the underlying VM object given an address range in a VM map. However, this function returns a UPL only for the first VM objectif the requested range is not covered by the first VM object, the caller must make another call to retrieve another UPL, and so on.

Once a UPL has been modified, the changes can be committed or aborted through upl_commit() and upl_abort(), respectively. These functions operate on the entire UPL. A specific range of the UPL can be committed or aborted through upl_commit_range() and upl_abort_range(), respectively. The UBC functions ubc_upl_commit_range() and ubc_upl_abort_range() are wrappers around the UPL functionsthey additionally deallocate the UPL if its associated VM object has no resident pages after the commit or abort, respectively.