docs/ANDROID-QEMU-PIPE.TXT

Android QEMU FAST PIPES
=======================

Introduction:
-------------

The Android emulator implements a special virtual device used to provide
_very_ fast communication channels between the guest system and the
emulator itself.

From the guest, usage is simply as follows:

  1/ Open the /dev/qemu_pipe device for read+write

     NOTE: Starting with Linux 3.10, the device was renamed as
           /dev/goldfish_pipe but behaves exactly in the same way.

  2/ Write a zero-terminated string describing which service you want to
     connect.

  3/ Simply use read() and write() to communicate with the service.

In other words:

   fd = open("/dev/qemu_pipe", O_RDWR);
   const char* pipeName = "<pipename>";
   ret = write(fd, pipeName, strlen(pipeName)+1);
   if (ret < 0) {
       // error
   }
   ... ready to go

Where <pipename> is the name of a specific emulator service you want to use.
Supported service names are listed later in this document.


Implementation details:
-----------------------

In the emulator source tree:

    ./hw/android/goldfish/pipe.c implements the virtual driver.

    ./hw/android/goldfish/pipe.h provides the interface that must be
    implemented by any emulator pipe service.

    ./android/hw-pipe-net.c contains the implementation of the network pipe
    services (i.e. 'tcp' and 'unix'). See below for details.

In the kernel source tree:

    drivers/misc/qemupipe/qemu_pipe.c contains the driver source code
    that will be accessible as /dev/qemu_pipe within the guest.


Device / Driver Protocol details:
---------------------------------

The device and driver use an I/O memory page and an IRQ to communicate.

  - The driver writes to various I/O registers to send commands to the
    device.

  - The device raises an IRQ to instruct the driver that certain events
    occured.

  - The driver reads I/O registers to get the status of its latest command,
    or the list of events that occured in case of interrupt.

Each opened file descriptor to /dev/qemu_pipe in the guest corresponds to a
32-bit 'channel' value allocated by the driver.

The following is a description of the various commands sent by the driver
to the device. Variable names beginning with REG_ correspond to 32-bit I/O
registers:

  0/ Channel and address values:

     Each communication channel is identified by a unique non-zero value
     which is either 32-bit or 64-bit, depending on the guest CPU
     architecture.

     The channel value sent from the kernel to the emulator with:

        void write_channel(channel) {
        #if 64BIT_GUEST_CPU
          REG_CHANNEL_HIGH = (channel >> 32);
        #endif
          REG_CHANNEL = (channel & 0xffffffffU);
        }

    Similarly, when passing a kernel address to the emulator:

        void write_address(buffer_address) {
        #if 64BIT_GUEST_CPU
          REG_ADDRESS_HIGH = (buffer_address >> 32);
        #endif
          REG_ADDRESS = (buffer_address & 0xffffffffU);
        }

  1/ Creating a new channel:

     Used by the driver to indicate that the guest just opened /dev/qemu_pipe
     that will be identified by a named '<channel>':

        write_channel(<channel>)
        REG_CMD = CMD_OPEN

     IMPORTANT: <channel> should never be 0

  2/ Closing a channel:

     Used by the driver to indicate that the guest called 'close' on the
     channel file descriptor.

        write_channel(<channel>)
        REG_CMD = CMD_CLOSE

  3/ Writing data to the channel:

     Corresponds to when the guest does a write() or writev() on the
     channel's file descriptor. This command is used to send a single
     memory buffer:

        write_channel(<channel>)
        write_address(<buffer-address>)
        REG_SIZE    = <buffer-size>
        REG_CMD     = CMD_WRITE_BUFFER

        status = REG_STATUS

    NOTE: The <buffer-address> is the *GUEST* buffer address, not the
          physical/kernel one.

    IMPORTANT: The buffer sent through this command SHALL ALWAYS be entirely
               contained inside a single page of guest memory. This is
               enforced to simplify both the driver and the device.

               When a write() spans several pages of guest memory, the
               driver will issue several CMD_WRITE_BUFFER commands in
               succession, transparently to the client.

    The value returned by REG_STATUS should be:

       > 0    The number of bytes that were written to the pipe
       0      To indicate end-of-stream status
       < 0    A negative error code (see below).

    On important error code is PIPE_ERROR_AGAIN, used to indicate that
    writes can't be performed yet. See CMD_WAKE_ON_WRITE for more.

  4/ Reading data from the channel:

    Corresponds to when the guest does a read() or readv() on the
    channel's file descriptor.

        write_channel(<channel>)
        write_address(<buffer-address>)
        REG_SIZE    = <buffer-size>
        REG_CMD     = CMD_READ_BUFFER

        status = REG_STATUS

    Same restrictions on buffer addresses/lengths and same set of error
    codes.

  5/ Waiting for write ability:

    If CMD_WRITE_BUFFER returns PIPE_ERROR_AGAIN, and the file descriptor
    is not in non-blocking mode, the driver must put the client task on a
    wait queue until the pipe service can accept data again.

    Before this, the driver will do:

        write_channel(<channel>)
        REG_CMD     = CMD_WAKE_ON_WRITE

    To indicate to the virtual device that it is waiting and should be woken
    up when the pipe becomes writable again. How this is done is explained
    later.

  6/ Waiting for read ability:

    This is the same than CMD_WAKE_ON_WRITE, but for readability instead.

        write_channel(<channel>)
        REG_CMD     = CMD_WAKE_ON_READ

  7/ Polling for write-able/read-able state:

    The following command is used by the driver to implement the select(),
    poll() and epoll() system calls where a pipe channel is involved.

        write_channel(<channel>)
        REG_CMD     = CMD_POLL
        mask = REG_STATUS

    The mask value returned by REG_STATUS is a mix of bit-flags for
    which events are available / have occured since the last call.
    See PIPE_POLL_READ / PIPE_POLL_WRITE / PIPE_POLL_CLOSED.

  8/ Signaling events to the driver:

    The device can signal events to the driver by raising its IRQ.
    The driver's interrupt handler will then have to read a list of
    (channel,mask) pairs, terminated by a single 0 value for the channel.

    In other words, the driver's interrupt handler will do:

        for (;;) {
            channel = REG_CHANNEL
            if (channel == 0)  // END OF LIST
                break;

            mask = REG_WAKES  // BIT FLAGS OF EVENTS
            ... process events
        }

    The events reported through this list are simply:

       PIPE_WAKE_READ   :: the channel is now readable.
       PIPE_WAKE_WRITE  :: the channel is now writable.
       PIPE_WAKE_CLOSED :: the pipe service closed the connection.

    The PIPE_WAKE_READ and PIPE_WAKE_WRITE are only reported for a given
    channel if CMD_WAKE_ON_READ or CMD_WAKE_ON_WRITE (respectively) were
    issued for it.

    PIPE_WAKE_CLOSED can be signaled at any time.


  9/ Faster read/writes through parameter blocks:

    Recent Goldfish kernels implement a faster way to perform reads and writes
    that perform a single I/O write per operation (which is useful when
    emulating x86 system through KVM or HAX).

    This uses the following structure known to both the virtual device and
    the kernel, defined in $QEMU/hw/android/goldfish/pipe.h:

    For 32-bit guest CPUs:

        struct access_params {
            uint32_t channel;
            uint32_t size;
            uint32_t address;
            uint32_t cmd;
            uint32_t result;
            /* reserved for future extension */
            uint32_t flags;
        };

    And the 64-bit variant:

        struct access_params_64 {
            uint64_t channel;
            uint32_t size;
            uint64_t address;
            uint32_t cmd;
            uint32_t result;
            /* reserved for future extension */
            uint32_t flags;
        };

    This is simply a way to pack several parameters into a single structure.
    Preliminary, e.g. at boot time, the kernel will allocate one such structure
    and pass its physical address with:

       PARAMS_ADDR_LOW  = (params & 0xffffffff);
       PARAMS_ADDR_HIGH = (params >> 32) & 0xffffffff;

    Then for each operation, it will do something like:

        params.channel = channel;
        params.address = buffer;
        params.size = buffer_size;
        params.cmd = CMD_WRITE_BUFFER (or CMD_READ_BUFFER)

        REG_ACCESS_PARAMS = <any>

        status = params.status

    The write to REG_ACCESS_PARAMS will trigger the operation, i.e. QEMU will
    read the content of the params block, use its fields to perform the
    operation then write back the return value into params.status.


Available services:
-------------------

  tcp:<port>

     Open a TCP socket to a given localhost port. This provides a very fast
     pass-through that doesn't depend on the very slow internal emulator
     NAT router. Note that you can only use the file descriptor with read()
     and write() though, send() and recv() will return an ENOTSOCK error,
     as well as any socket ioctl().

     For security reasons, it is not possible to connect to non-localhost
     ports.

  unix:<path>

     Open a Unix-domain socket on the host.

  opengles

     Connects to the OpenGL ES emulation process. For now, the implementation
     is equivalent to tcp:22468, but this may change in the future.

  qemud

     Connects to the QEMUD service inside the emulator. This replaces the
     connection that was performed through /dev/ttyS1 in older Android platform
     releases. See $QEMU/docs/ANDROID-QEMUD.TXT for details.