The comcerto_pci Linux driver is intended to provide a mechanism for
communicating with Comcerto M82xxx devices over its PCI/uP interface,
while dictating as little policy as possible.  In particular, it does
not have any direct support for boot loading, channels, message
contents, or anything else beyond queued mailbox and FIFO send and
receive.  This allows policies for such things to be determined by
user-mode code, such as the yAgent usermode-agent server.

File Operations Semantics
=========================

open()/close()

    FIFO and mailbox operation is enabled on the first open() of the
    device, and disabled on the last close().

ioctl()

    The supported ioctl() operations are:

    CIOC_RESET

        Takes no parameters.  Resets the device, and clears all
        buffered input and output messages.

    CIOC_GET_INFO

        Retrieves information about the device from the PCI bus
        configuration registers into a comcerto_info structure:

        struct comcerto_info {
                unsigned short  vendor;
                unsigned short  device;
                unsigned short  revision;
        };

write()

    The first 8 bytes of written messages are interpreted as the
    mailbox contents.  Any data beyond this, up to 65535 bytes, are
    interpreted as data to be written to the FIFO.

read()

    The first 8 bytes of read messages consist of the mailbox
    contents.  Any data beyond this, up to 256 bytes, is the
    associated FIFO contents.

Trace Buffer Semantics
======================

For each /dev/comcertoN device, there is a corresponding
/sys/class/comcerto/comcertoN/trace file.  Reading this file returns a
circular buffer containing the last PAGE_SIZE worth of messages sent
to and received from the device.  Each entry consists of a header with
the following structure, followed by up to 256 bytes of the FIFO contents.
The trace is decadable using the decode-trace.pl perl script

        #define COMCERTO_TRACE_RMAGIC   0xFEF1F0F6
        #define COMCERTO_TRACE_TMAGIC   0xFEF1F0F7

        struct comcerto_trace {
                unsigned long magic;
                unsigned long timestamp;
                struct comcerto_queue_msg {
                        unsigned short fifo_len;
                        u16 mailbox[4];
                } msg;
        };
