#include <oskit/io/bufio.h>OSKIT_COMDECL wire(oskit_bufio_t *io, [out] oskit_addr_t *phys_addr, oskit_off_t offset, oskit_size_t amount);
This method attempts to wire down some or all of this buffer into memory directly accessible by DMA hardware. The operation may or may not succeed, depending on the parameters and the implementation of the object; if it fails, the client must be prepared to fall back to the basic read and write methods.If the wiring operation succeeds, the physical address of the buffer is guaranteed not to change or otherwise become invalid until the region is unwired or the bufio object is released. The wired buffer is not guaranteed to have any particular alignment or location properties: for example, on a PC, if the device that is going to be accessing the buffer requires memory below 16MB, then it must be prepared to use appropriate bounce buffers if the wired buffer turns out to be above 16MB.
If a call to the wire method requests only a subset of the buffer to be mapped, the object may actually wire more than the requested amount; however, since no information is passed back indicating how much of the buffer was actually wired, the client must only attempt to use the region it requested.
- io
- The object whose contents are to be wired.
- addr
- On success, the method returns in this parameter the physical address at which DMA hardware can directly access the requested buffer region.
- offset
- The offset into the buffer of the region to be wired.
- size
- The size of the region to be wired.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.