unixio_hidd
Index
unixio.hidd is a simple driver for host-side I/O on UNIX system. Its primary
purpose is to handle non-blocking I/O on AROS task level. Also it provides
common file access operations (open, close, read, write and ioctl) in order
to avoid code duplication.
I/O operations you perform must never block. The whole AROS with all its tasks
is just one process from host OS' point of view, so blocking operation would
halt all the system. In order to avoid this you need to make sure that the
file descriptor is actually ready to perform I/O. If this is not the case,
your task needs to wait until file descriptor becomes available. unixio.hidd
offers a simple way of doing it by adding an interrupt handler to the file
descriptor using moHidd_UnixIO_AddInterrupt method. The interrupt handler
will be called whenever SIGIO arrives from the specified descriptor and specified
conditions are met. You do not need to explicitly enable asynchronous I/O
on the file descriptor, unixio.hidd takes care about all this itself.
There's also a convenience moHidd_UnixIO_Wait method. It allows you to simulate
a normal blocking I/O in a simple way.
Starting from v42 unixio.hidd is a singletone. This means that all calls to
OOP_NewObject() will actually return the same object which is never really
disposed. This object pointer can be freely transferred between tasks. It's
not necessary t call OOP_DisposeObject() on it. It is safe, but will do nothing.
Usage counter is maintained by OpenLibrary()/CloseLibrary() calls.
Remember that all values (like file mode flags and errno values) are host-specific!
Different hosts may use different values, and even different structure layouts
(especially this affects ioctl). When opening unixio.hidd it is adviced to check
that host OS matches what is expected (what your client program/driver/whatever
is compiled for). Use aoHidd_UnixIO_Architecture attribute for this.
Specifiers architecture name to match against current system's architecture.
Architecture name needs to be supplied in the form "arch-cpu", for example
"linux-ppc" or "darwin-i386". Usually this comes from a definition when
you compile your module.
struct TagItem tags = {
{aHidd_UnixIO_Opener, "tap.device"},
{aHidd_UnixIO_Architecture, "linux-i386"},
{TAG_DONE, 0}
};
uio = OOP_NewObject(CLID_Hidd_UnixIO, tags);
// If uio == NULL, the system you're running on is not linux-i386. The error
// requester has been already presented to the user.
This attribute allows you to ensure that your module is running on the same
architecture it was compiled for. This is needed because unixio.hidd by its
nature works with host OS structures and values (especially ioctl operation).
Different host OSes (for example Linux and Darwin) are not binary compatible
even on the same CPU. This is why the architecture check is generally needed,
especially for disk-based components.
It is adviced to specify your module name using aoHidd_UnixIO_Opener. This needed
in order to display the correct name to the user if the check fails, so the user
will see what module causes the error.
Specifiers opener name for architecture check routine.
This attribute's sole purpose is to be presented to the user in an error requester
if the architecture check fails. For example if you specify "tap.device" here,
the user will see a requester telling that "This version of tap.device is built
for XXX architecture, while current system architecture is YYY".
If this attribute is not specified, but architecture check is requested using
aoHidd_UnixIO_Architecture, current task's name will be used. This can be not
always approptiate, so it's adviced to always specify your driver or program
name here.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_AddInterrupt *msg);
int Hidd_UnixIO_AddInterrupt(OOP_Object *obj, struct uioInterrupt *interrupt);
Install a filedescriptor-specific event interrupt handler
obj - An pointer to a UnixIO object
interrupt - A pointer to an interrupt descriptor structure initialized as follows:
fd - Number of file descriptor to watch
mode - one or more of mode flags
handler - A pointer to a handler routine.
handlerData - User-specified data for the interrupt handler
The interrupt handler routine will be called using C calling convention:
void handler(int fd, int mode, void *data)
where:
fd - File descriptor number
mode - Flags reflecting set of occured events
data - User data (specified in handlerData member of uioInterrupt structure)
Zero if interrupt was successfully installed and UNIX errno value if
there was an error during setting up the filedescriptor.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_CloseFile *msg);
int Hidd_UnixIO_CloseFile (OOP_Object *obj, int fd, int *errno_ptr);
Close a UNIX file descriptor.
obj - A pointer to a UnixIO object.
fd - A file descriptor to close.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
errno variable) will be written.
0 in case of success and -1 on failure.
Despite there's no return value, error code still can be set.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_ClosePacket *msg);
int Hidd_UnixIO_ClosePacket (OOP_Object *obj, int fd, int *errno_ptr);
Close a UNIX packet descriptor.
obj - A pointer to a UnixIO object.
pd - A packet descriptor to close.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
errno variable) will be written.
0 in case of success and -1 on failure.
Despite there's no return value, error code still can be set.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_IOControlFile *msg);
int Hidd_UnixIO_IOControlFile(OOP_Object *obj, int fd, int request, void *param, int *errno_ptr);
Perform a special operation (ioctl) on a UNIX file descriptor.
obj - A pointer to a UnixIO object.
fd - A file descriptor to operate on.
request - A device-specific operation code.
param - A pointer to a request-specific parameter block.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
errno variable) will be written.
Operation-specific value (actually a return value of ioctl() function called).
This method can be called from within interrupts.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_MemoryMap *msg);
int Hidd_UnixIO_MemoryMap(OOP_Object *obj, OOP_Object *o, void *addr, int len, int prot, int flags, int fd, int offset, int *errno_ptr);
Maps address into file descriptor.
obj - A pointer to a UnixIO object.
fd - A file descriptor to check.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
errno variable) will be written.
Actuall mapping address or MAP_FAILED for errors.
This method can be called from within interrupts.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_MemoryUnMap *msg);
int Hidd_UnixIO_MemoryUnMap(OOP_Object *obj, OOP_Object *o, void *addr, int len, int *errno_ptr);
obj - A pointer to a UnixIO object.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
errno variable) will be written.
0 for success, -1 for failure
This method can be called from within interrupts.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_OpenFile *msg);
int Hidd_UnixIO_OpenFile (OOP_Object *obj, const char *filename, int flags, int mode, int *errno_ptr);
Open a UNIX file descriptor
obj - An pointer to a UnixIO object
filename - File name to open. File name should meet host OS conventions.
flags - Flags specifying open mode. These are the same flags as for
open() C function. Note that this value is passed directly to
the host OS, and its definition can differ from AROS one.
errno_ptr - An optional pointer to a location where error code (value of
UNIX errno variable) will be written
A number of the opened file descriptor or -1 for an error.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_OpenPacket *msg);
int Hidd_UnixIO_OpenPacket (OOP_Object *obj, const char *Interface, int *errno_ptr);
Open a UNIX packet descriptor to a raw network interface
obj - An pointer to a UnixIO object
interface - Name of a network interace (ie eth0)
errno_ptr - An optional pointer to a location where error code (value of
UNIX errno variable) will be written
A number of the opened packet descriptor or -1 for an error.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_Poll *msg);
int Hidd_UnixIO_Poll(OOP_Object *obj, int fd, int mode, int *errno_ptr);
Check current status of UNIX file descriptor or -1 if an error occured.
obj - A pointer to a UnixIO object.
fd - A file descriptor to check.
mode - Mask of modes we are interested in.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
errno variable) will be written.
Current set of filedescriptor modes.
This method can be called from within interrupts.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_ReadFile *msg);
int Hidd_UnixIO_ReadFile(OOP_Object *obj, int fd, void *buffer, int count, int *errno_ptr);
Read data from a UNIX file descriptor.
obj - A pointer to a UnixIO object.
fd - A file descriptor to read from.
buffer - A pointer to a buffer for data.
count - Number of bytes to read.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
errno variable) will be written.
Number of bytes actually read or -1 if error happened.
If there's no errno pointer supplied read operation will be automatically repeated if one
of EINTR or EAGAIN error happens. If you supplied valid own errno_ptr you should be ready
to handle these conditions yourself.
This method can be called from within interrupts.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_RecvPacket *msg);
int Hidd_UnixIO_RecvPacket(OOP_Object *obj, int fd, void *buffer, int count, int *errno_ptr);
Read packet from a Unix packet descriptor
obj - A pointer to a UnixIO object.
pd - A packet descriptor to read from.
buffer - A pointer to a buffer for data.
count - Number of bytes to read.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
errno variable) will be written.
Number of bytes actually read or -1 if error happened.
If there's no errno pointer supplied read operation will be automatically repeated if one
of EINTR or EAGAIN error happens. If you supplied valid own errno_ptr you should be ready
to handle these conditions yourself.
This method can be called from within interrupts.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_RemInterrupt *msg);
void Hidd_UnixIO_RemInterrupt(OOP_Object *obj, struct uioInterrupt *interrupt);
Remove previously installed file descriptor event interrupt structure
obj - An pointer to a UnixIO object
interrupt - A pointer to a previously installed interrupt descriptor structure
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_SendPacket *msg);
int Hidd_UnixIO_SendPacket(OOP_Object *obj, int fd, void *buffer, int count, int *errno_ptr);
Write data to a UNIX packet descriptor.
obj - A pointer to a UnixIO object.
pd - A packet descriptor to write to.
buffer - A pointer to a buffer containing data.
count - Number of bytes to write.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
errno variable) will be written.
Number of bytes actually written or -1 if error happened.
If there's no errno pointer supplied read operation will be automatically repeated if one
of EINTR or EAGAIN error happens. If you supplied valid own errno_ptr you should be ready
to handle these conditions yourself.
This method can be called from within interrupts.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_ *msg);
IPTR Hidd_UnixIO_Wait(OOP_Object *obj, ULONG fd, ULONG mode);
Wait for an event on the file descriptor.
obj - A pointer to a UnixIO object
fd - A file descriptor to wait on
mode - A combination of two flags:
- vHidd_UnixIO_Read - to request waiting until read is permitted
- vHidd_UnixIO_Write - to request waiting until write is permitted
0 in case of success or UNIX errno value in case if the operation failed.
OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_WriteFile *msg);
int Hidd_UnixIO_WriteFile(OOP_Object *obj, int fd, void *buffer, int count, int *errno_ptr);
Write data to a UNIX file descriptor.
obj - A pointer to a UnixIO object.
fd - A file descriptor to write to.
buffer - A pointer to a buffer containing data.
count - Number of bytes to write.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
errno variable) will be written.
Number of bytes actually written or -1 if error happened.
If there's no errno pointer supplied read operation will be automatically repeated if one
of EINTR or EAGAIN error happens. If you supplied valid own errno_ptr you should be ready
to handle these conditions yourself.
This method can be called from within interrupts.
|
|
