This chapter defines the I/O-related COM interfaces which are defined by header files in the oskit/io directory. Most of these interfaces are fairly generic and can be used in a wide variety of situations. Some of these interfaces, such as the bufio interface, are extensions to other more primitive interfaces, and allow objects to export the same functionality in different forms, permitting clients to select the service that most directly meets their needs thereby reducing interface crossing overhead and increasing overall performance.
The oskit_absio interface supports reading from and writing to objects at specified absolute offsets, with no concept of a seek pointer. The oskit_absio interface is identical to the oskit_blkio COM interface, except that the block size is always one, since absolute IO is byte-oriented. In fact, an object that supports byte-granularity reads and writes can easily export both oskit_blkio and oskit_absio using exactly the same function pointer table, simply by implementing an oskit_blkio interface that always returns one from getblocksize, and then returning a pointer to that interface on queries for either oskit_blkio or oskit_absio.
The oskit_absio COM interface inherits from IUnknown, and has the following additional methods:
#include <oskit/io/absio.h>
OSKIT_COMDECL oskit_absio_read(oskit_absio_t *f, void *buf, oskit_off_t offset, oskit_size_t amount, [out] oskit_size_t *out_actual);
This method reads no more than amount bytes into buf from this object, starting at offset. out_actual is set to the actual number of bytes read.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/absio.h>
OSKIT_COMDECL oskit_absio_write(oskit_absio_t *f, const void *buf, oskit_off_t offset, oskit_size_t amount, [out] oskit_size_t *out_actual);
This method writes no more than amount bytes from buf into this object, starting at offset. out_actual is set to the actual number of bytes written.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/absio.h>
OSKIT_COMDECL oskit_absio_getsize(oskit_absio_t *f, [out] oskit_off_t *out_size);
This method returns the current size of this object in bytes.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/absio.h>
OSKIT_COMDECL oskit_absio_setsize(oskit_absio_t *f, oskit_off_t new_size);
This method sets the size of this object to new_size bytes. If new_size is larger than the former size of this object, then the contents of the object between its former end and its new end are undefined.
Note that some absolute I/O objects may be fixed-size, such as objects representing preallocated memory buffers; in such cases, this method will always return OSKIT_E_NOTIMPL.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
The oskit_asyncio interface provides interfaces in support of basic asynchronous I/O, based on registered callback objects (see Section 4.9). This can be used, for example, to implement Unix SIGIO or select or POSIX.1b aio.
This interface supports a notion of three kinds of interesting events: readability, writeability, and “other” exceptional conditions. These are defined via the flags: OSKIT_ASYNCIO_READABLE, OSKIT_ASYNCIO_WRITEABLE, and OSKIT_ASYNCIO_EXCEPTION which are passed and returned in a mask in the various methods.
The oskit_asyncio COM interface inherits from IUnknown, and has the following additional methods:
Poll for currently pending asynchronous I/O conditions, returning a mask indicating which conditions are currently present.
If successful, returns a mask of the OSKIT_ASYNCIO flags above. Otherwise, returns an error code specified in <oskit/error.h>.
#include <oskit/io/asyncio.h>
OSKIT_COMDECL oskit_asyncio_add_listener(oskit_asyncio_t *io, oskit_listener_t *l, oskit_s32_t mask);
Add a callback listener object to handle asynchronous I/O events. When an event of interest occurs on this I/O object (i.e., when one of the one to three I/O conditions becomes true), all registered listeners will be called.
The mask parameter is an OR’ed combination of the OSKIT_ASYNCIO flags above. It specifies which events the listener is interested in. Note that spurious notifications are possible, the listener must use oskit_asyncio_poll to determine the actual state of affairs.
Also, if successful, this method returns a mask describing which of the OSKIT_ASYNCIO conditions are already true, which the caller must check in order to avoid missing events that occur just before the listener is registered.
If successful, returns a mask of the OSKIT_ASYNCIO currently pending. Otherwise, returns an error code specified in <oskit/error.h>.
#include <oskit/io/asyncio.h>
OSKIT_COMDECL oskit_asyncio_remove_listener(oskit_asyncio_t *io, oskit_listener_t *l);
Remove a previously registered listener callback object. Returns an error if the specified callback has not been registered.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
Returns the number of bytes that can be read from the I/O object.
The number of bytes available for reading.
The oskit_blkio interface supports reading and writing of raw data in units of fixed-sized blocks which are some power of two. This interface is identical to the oskit_absio interface except for the addition of a getblocksize method; in fact, an object that supports byte-granularity reads and writes can easily export both oskit_blkio and oskit_absio using exactly the same function pointer table, simply by implementing an oskit_blkio interface that always returns one from getblocksize, and then returning a pointer to that interface on queries for either oskit_blkio or oskit_absio.
The oskit_blkio interface inherits from IUnknown, and has the following additional methods:
This method simply returns the block size of the object, which must be a power of two. Calls by the client to read from or write to the object must only use offsets and sizes that are evenly divisible by this block size.
Returns the block size of the object.
#include <oskit/io/blkio.h>
OSKIT_COMDECL oskit_blkio_read(oskit_blkio_t *f, void *buf, oskit_off_t offset, oskit_size_t amount, [out] oskit_size_t *out_actual);
This method reads no more than amount bytes into buf from this object, starting at offset. out_actual is set to the actual number of bytes read.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/blkio.h>
OSKIT_COMDECL oskit_blkio_write(oskit_blkio_t *f, const void *buf, oskit_off_t offset, oskit_size_t amount, [out] oskit_size_t *out_actual);
This method writes no more than amount bytes from buf into this object, starting at offset. out_actual is set to the actual number of bytes written.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/blkio.h>
OSKIT_COMDECL oskit_blkio_getsize(oskit_blkio_t *f, [out] oskit_off_t *out_size);
This method returns the current size of this object in bytes.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/blkio.h>
OSKIT_COMDECL oskit_blkio_setsize(oskit_blkio_t *f, oskit_off_t new_size);
This method sets the size of this object to new_size bytes. If new_size is larger than the former size of this object, then the contents of the object between its former end and its new end are undefined.
Note that some block I/O objects may be fixed-size, such as objects representing physical disks or partitions; in such cases, this method will always return OSKIT_E_NOTIMPL.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
The oskit_bufio interface extends the oskit_absio interface, providing additional alternative methods of accessing the object’s data. In particular, for objects whose data is stored in an in-memory buffer of some kind, this interface allows clients to obtain direct access to the buffer itself so that they can read and write data using loads and stores, rather than having to copy data into and out of the buffer using the read and write methods. In addition, this interface provides similar methods to allow clients to “wire” the buffer’s contents to physical memory, enabling DMA-based hardware devices to access the buffer directly.
However, note that only the read/write methods, inherited from oskit_absio, are mandatory; the others may consistently fail with OSKIT_E_NOTIMPL if they cannot be implemented efficiently in a particular situation. In that case, the caller must use the basic read and write methods instead to copy the data. In other words, oskit_bufio object implementations are not required to implement direct buffer access, either software- or DMA-based; the purpose of this interface is merely to allow them to provide this optional functionality easily and consistently. In general, the map and wire methods should only be implemented if they can be done more efficiently than simply copying the data. Further, even if a buffer I/O implementation does implement map and/or wire it may allow only one mapping or wiring to be in effect at once, failing if the client attempts to map or wire the buffer a second time before the first mapping is undone. Similarly, on some buffer I/O implementations, these operations may only work on certain areas of the buffer or only when the request has certain size or alignment properties: for example, a buffer object that stores data in discontiguous segments, such as BSD’s mbuf system, may only allow a buffer to be mapped if the requested region happens to fall entirely within one segment. Thus, the client of a bufio object should call the map or wire methods whenever it can take advantage of direct buffer access, but must always be prepared to fall back to the basic copying methods.
A particular buffer object may be semantically read-only or write-only; it is assumed that parties passing bufio objects around will agree upon this as part of their protocols. For a read-only buffer, the write method may or may not fail, and a mapping established using the map method may or may not actually be a read-only memory mapping; it is the client’s responsibility not to attempt to write to the buffer. Similarly, for a write-only buffer, the read method may or may not fail; it is the client’s responsibility not to attempt to read from the buffer.
The oskit_bufio interface extends the oskit_absio interface with the following additional methods:
#include <oskit/io/bufio.h>
OSKIT_COMDECL map(oskit_bufio_t *io, [out] void **addr, oskit_off_t offset, oskit_size_t amount);
This method attempts to map some or all of this buffer into memory directly accessible to the client, so that the client can access it using loads and stores. 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 mapping operation succeeds, the pointer returned is not guaranteed to have any particular alignment.
If a call to the map method requests only a subset of the buffer to be mapped, the object may actually map more than the requested amount; however, since no information is passed back indicating how much of the buffer was actually mapped, the client must only attempt to access the region it requested.
Note that this method does not necessarily twiddle with virtual memory, as its name may seem to imply; in fact in most cases in which it is implemented at all, it just returns a pointer to a buffer if the data is already in locally-accessible memory.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/bufio.h>
OSKIT_COMDECL unmap(oskit_bufio_t *io, void *addr, oskit_off_t offset, oskit_size_t amount);
After a successful call to the map method, the client should call this method after it is finished accessing the buffer directly, so that the buffer object can clean up and free any resources that might be associated with the mapping.
The addr parameter passed to this method must be exactly the value returned by the map request, and the offset and amount parameters must be exactly the same as the values previously passed in the corresponding map call. In other words, clients must only attempt to unmap whole regions; they must not attempt to unmap only part of a region, or to unmap two previously mapped regions in one call, even if the two regions appear to be contiguous in memory.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#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.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/bufio.h>
OSKIT_COMDECL unwire(oskit_bufio_t *io, void *addr, oskit_off_t offset, oskit_size_t amount);
After a successful call to the wire method, the client should call this method after the hardware is finished accessing the buffer directly, so that the buffer object can clean up and free any resources that might be associated with the wiring.
The addr parameter passed to this method must be exactly the value returned by the wire request, and the offset and amount parameters must be exactly the same as the values previously passed in the corresponding wire call. In other words, clients must only attempt to unwire whole regions; they must not attempt to unwire only part of a region, or to unwire two previously wired regions in one call, even if the two regions appear to be contiguous in physical memory.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/bufio.h>
OSKIT_COMDECL copy(oskit_bufio_t *io, oskit_off_t offset, oskit_size_t amount, [out] oskit_bufio_t **out_io);
This method attempts to create a logical copy of a portion of this buffer object (possibly the whole buffer), returning a new oskit_bufio object representing the copy. As with the map and wire methods, this method should only be implemented by an object if it can be done more efficiently than a simple “brute-force” copy using read. For example, in virtual memory environments, the object may be able to use copy-on-write optimizations. Similarly, if the buffer’s contents are stored in special memory not efficiently accessible to the processor, such as memory on a video or coprocessor board, this method could use on-board hardware to perform a much faster copy.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
This interface builds on the above interfaces to provide a clean and simple but powerful interface for passing network packets between device drivers and protocol stacks, and possibly between layers of a protocol stack as well.
The oskit_netio interface uses a symmetric sender-driven model for asynchronous communication. Each party involved (e.g., the network device driver and the protocol stack) must implement a netio object and pass a reference to its own netio object to the other party. For example, in the oskit_netdev interface, which represents a network device of some kind, this exchange of netio objects occurs when the protocol stack or other client opens the device. The oskit_netio interface defines only a single additional method beyond the basic methods inherited from oskit_iunknown; this method, appropriately named push, is used to “push” a network packet to the “other” party. For example, when a network device driver receives a packet from the hardware, the driver calls the push method on the netio object provided by the protocol stack; conversely, when the protocol stack needs to send a packet, it calls the netio object returned by the device driver at the time the device was opened. Thus, a netio object essentially represents a “packet consumer.”
The following section describes the specifics of the push method.
#include <oskit/io/netio.h>
OSKIT_COMDECL push(oskit_netio_t *io, oskit_bufio *buf, oskit_size_t size);
This method feeds a network packet to the packet consumer represented by the netio object; what the consumer does with the packet depends entirely on who the consumer is and how it is configured. The packet is contained in a bufio object which must be at least the size of the packet, but may be larger; the size parameter on the push call indicates the actual size of the packet.
If the consumer needs to hold on to the provided bufio object after returning from the call, it must call addref on the bufio object to obtain its own reference; then it must release this reference at some later time when it is done with the buffer. Otherwise, if the consumer doesn’t obtain its own reference, the caller may recycle the buffer as soon as the call returns.
The passed buffer object is logically read-only; the consumer must not attempt to write to it. The size parameter to this call is the actual size of the packet; the size of the buffer, as returned by the getsize method, may be larger than the size of the packet.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
The oskit_posixio interface defines the minimal POSIX I/O interface that any POSIX I/O object (file, device, pipe, socket, etc) can be expected to support. Only per-object methods are provided by this interface. Additional I/O operations are supported through separate interfaces, such as the oskit_stream interface and oskit_absio COM interface.
The oskit_posixio COM interface inherits from oskit_iunknown, and has the following additional methods:
#include <oskit/io/posixio.h>
OSKIT_COMDECL oskit_posixio_stat(oskit_posixio_t *f, [out] oskit_stat_t *out_stats);
This method returns the attributes of this object. Depending on the type of object, only some of the attributes may be meaningful. out_stats is a pointer to a oskit_stat_t structure defined as follows:
struct oskit_stat {
| oskit_dev_t | dev; | /* device on which inode resides | */ | |
| oskit_ino_t | ino; | /* inode’s number | */ | |
| oskit_mode_t | mode; | /* file mode | */ | |
| oskit_nlink_t | nlink; | /* number of hard links to file | */ | |
| oskit_uid_t | uid; | /* user id of owner | */ | |
| oskit_gid_t | gid; | /* group id of owner | */ | |
| oskit_dev_t | rdev; | /* device number, for device files | */ | |
| oskit_timespec_t | atime; | /* time of last access | */ | |
| oskit_timespec_t | mtime; | /* time of last data modification | */ | |
| oskit_timespec_t | ctime; | /* time of last attribute change | */ | |
| oskit_off_t | size; | /* size in bytes | */ | |
| oskit_u64_t | blocks; | /* blocks allocated for file | */ | |
| oskit_u32_t | blksize; | /* optimal block size in bytes | */ | |
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/posixio.h>
OSKIT_COMDECL oskit_posixio_setstat(oskit_posixio_t *f, oskit_u32_t mask, const oskit_stat_t *stat);
This method sets the attributes specified in mask to the values specified in stat. mask may be any combination of the following:
Typically, this method is not supported for symbolic links.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/posixio.h>
OSKIT_COMDECL oskit_posixio_pathconf(oskit_posixio_t *f, oskit_s32_t option, [out] oskit_s32_t *out_val);
This method returns the value of the specified configuration option variable for this object. The value of option may be one of the following:
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
This interface extends the standard COM IStream interface with POSIX/Unix TTY functionality, such as methods to control serial port settings, enable, disable, and control line editing, flush the input and output queues, etc.
This interface is currently exported by character-oriented device drivers incorporated into the OSKit from legacy systems such as BSD and Linux, in which full Unix TTY functionality can be provided easily. In the future, these drivers are expected to export more minimal, lower-level interfaces instead of or in addition to this interface; however, in the short term, this interface allows clients to obtain full Unix terminal functionality quickly and easily.
The oskit_ttystream interface inherits from oskit_stream, and has the following additional methods:
In addition, this header file defines a structure called oskit_termios, corresponding to the standard POSIX termios structure, and a set of related definitions used to specify terminal-related settings. See the POSIX and Unix standards for details on the exact contents and meaning of this structure.
#include <oskit/io/ttystream.h>
OSKIT_COMDECL getattr(oskit_ttystream_t *tty, [out] struct oskit_termios *attr);
This method retrieves the current line settings of this stream and returns them in the specified oskit_termios structure. This method corresponds to the POSIX tcgetattr function; see the POSIX standard for details.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/ttystream.h>
OSKIT_COMDECL setattr(oskit_ttystream_t *tty, const struct oskit_termios *attr);
This method sets the line settings of this stream based on the specified oskit_termios structure. This method corresponds to the POSIX tcsetattr function; see the POSIX standard for details.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/io/ttystream.h>
OSKIT_COMDECL sendbreak(oskit_ttystream_t *tty, oskit_u32_t duration);
On streams controlling asynchronous serial communication, this method sends a break signal (a continuous stream of zero-valued bits) for a specific duration. This method corresponds to the POSIX tcsendbreak function; see the POSIX standard for details.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
This method waits until any buffered output data that has been written to the stream is successfully transmitted. This method corresponds to the POSIX tcdrain function; see the POSIX standard for details.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
This method discards any buffered output data that has not yet been transmitted, and/or any buffered input data that has not yet been read, depending on the queue_selector parameter. This method corresponds to the POSIX tcflush function; see the POSIX standard for details.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
This method controls the transmission or reception of data on this TTY stream. This method corresponds to the POSIX tcflow function; see the POSIX standard for details.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.