XXX typedef unsigned osenv_memflags_t;
All of the memory allocation functions used by device drivers in the OSKit device framework take a parameter of type osenv_memflags_t, which is a bit field describing various option flags that affect how memory allocation is done. Device drivers often need to allocate memory that satisfies certain constraints, such as being physically contiguous, or page aligned, or accessible to DMA controllers. These flags abstract out these various requirements, so that all memory allocation requests made by device drivers are sent to a single set of routines; this design allows the OS maximum flexibility in mapping device memory allocation requests onto its internal kernel memory allocation mechanisms.Routing all memory allocations through a single interface this way may have some impact on performance, due to the cost of decoding the flags argument on every allocation or deallocation call. However, this cost is expected to be small compared to the typical cost of actually performing the requested operation.
The specific flags currently defined are as follows:
- OSENV_AUTO_SIZE
- The memory allocator must keep track of the size of allocated blocks allocated using this flag; in this case, the value size parameter passed in the corresponding osenv_mem_free call is meaningless. For blocks allocated without this flag set, the caller (device driver) promises to keep track of the size of the allocated block, and pass it back to osenv_mem_free on deallocation.
It is possible for the OS to implement these memory allocation routines so that they ignore the OSENV_AUTO_SIZE flag and simply always keep track of block sizes themselves. However, note that in some situations, doing so may produce extremely inefficient memory usage. For example, if the OS memory allocation mechanism prefixes each block with a word containing the block's length, then any request by a device driver to allocate a page-aligned page (or some other naturally-aligned, power-of-two-sized block) will consume that page plus the last word of the previous page. If many successive allocations are done in this way, only every other page will be usable, and half of the available memory will be wasted. Therefore, it is generally a good idea for the memory allocation functions to pay attention to the OSENV_AUTO_SIZE flag, at least for allocations with alignment restrictions.
- OSENV_NONBLOCKING
- If set, this flag indicates that the memory allocator must not block during the allocation or deallocation operation. More specifically, the flag indicates that the device driver code must not be run in the context of other, concurrent processes while the allocation is taking place. Any calls to the allocation functions from interrupt handlers must specify the OSENV_NONBLOCKING flag.
- OSENV_PHYS_WIRED
- Indicates that the must must be non-pageable. Accesses to the returned memory must not fault.
- OSENV_PHYS_CONTIG
- Indicates the underlying physical memory must be contiguous.
- OSENV_VIRT_EQ_PHYS
- Indicates the virtual address must exactly equal the physical address so the driver may use them interchangeably. The OSENV_PHYS_CONTIG flag must also be set whenever this flag is set.
- OSENV_ISADMA_MEM
- This flag applies only to machines with ISA busses or other busses that are software compatible with ISA, such as EISA, MCA, or PCI. It indicates that the memory allocated must be appropriate for DMA access using the system's built-in DMA controller. In particular, it means that the buffer must be physically contiguous, must be entirely contained in the low 16MB of physical memory, and must not cross a 64KB boundary. (By implication, this means that allocations using this flag are limited to at most 64KB in size.) The OSENV_PHYS_CONTIG flag must also be set if this flag is set.
- OSENV_X861MB_MEM
- This flag only applies to x86 machines, in which some device drivers may need to call 16-bit real-mode BIOS routines. Such drivers may need to allocate physical memory in the low 1MB region accessible to real-mode code; this flag allows drivers to request such memory. This is not used by existing driver sets.