1Android QEMU FAST PIPES 2======================= 3 4Introduction: 5------------- 6 7The Android emulator implements a special virtual device used to provide 8_very_ fast communication channels between the guest system and the 9emulator itself. 10 11From the guest, usage is simply as follows: 12 13 1/ Open the /dev/qemu_pipe device for read+write 14 15 2/ Write a zero-terminated string describing which service you want to 16 connect. 17 18 3/ Simply use read() and write() to communicate with the service. 19 20In other words: 21 22 fd = open("/dev/qemu_pipe", O_RDWR); 23 const char* pipeName = "<pipename>"; 24 ret = write(fd, pipeName, strlen(pipeName)+1); 25 if (ret < 0) { 26 // error 27 } 28 ... ready to go 29 30Where <pipename> is the name of a specific emulator service you want to use. 31Supported service names are listed later in this document. 32 33 34Implementation details: 35----------------------- 36 37In the emulator source tree: 38 39 ./hw/goldfish_pipe.c implements the virtual driver. 40 41 ./hw/goldfish_pipe.h provides the interface that must be 42 implemented by any emulator pipe service. 43 44 ./android/hw-pipe-net.c contains the implementation of the network pipe 45 services (i.e. 'tcp' and 'unix'). See below for details. 46 47In the kernel source tree: 48 49 drivers/misc/qemupipe/qemu_pipe.c contains the driver source code 50 that will be accessible as /dev/qemu_pipe within the guest. 51 52 53Device / Driver Protocol details: 54--------------------------------- 55 56The device and driver use an I/O memory page and an IRQ to communicate. 57 58 - The driver writes to various I/O registers to send commands to the 59 device. 60 61 - The device raises an IRQ to instruct the driver that certain events 62 occured. 63 64 - The driver reads I/O registers to get the status of its latest command, 65 or the list of events that occured in case of interrupt. 66 67Each opened file descriptor to /dev/qemu_pipe in the guest corresponds to a 6832-bit 'channel' value allocated by the driver. 69 70The following is a description of the various commands sent by the driver 71to the device. Variable names beginning with REG_ correspond to 32-bit I/O 72registers: 73 74 1/ Creating a new channel: 75 76 Used by the driver to indicate that the guest just opened /dev/qemu_pipe 77 that will be identified by a 32-bit value named '<channel>' here: 78 79 REG_CHANNEL = <channel> 80 REG_CMD = CMD_OPEN 81 82 IMPORTANT: <channel> should never be 0 83 84 2/ Closing a channel: 85 86 Used by the driver to indicate that the guest called 'close' on the 87 channel file descriptor. 88 89 REG_CHANNEL = <channel> 90 REG_CMD = CMD_CLOSE 91 92 3/ Writing data to the channel: 93 94 Corresponds to when the guest does a write() or writev() on the 95 channel's file descriptor. This command is used to send a single 96 memory buffer: 97 98 REG_CHANNEL = <channel> 99 REG_ADDRESS = <buffer-address> 100 REG_SIZE = <buffer-size> 101 REG_CMD = CMD_WRITE_BUFFER 102 103 status = REG_STATUS 104 105 NOTE: The <buffer-address> is the *GUEST* buffer address, not the 106 physical/kernel one. 107 108 IMPORTANT: The buffer sent through this command SHALL ALWAYS be entirely 109 contained inside a single page of guest memory. This is 110 enforced to simplify both the driver and the device. 111 112 When a write() spans several pages of guest memory, the 113 driver will issue several CMD_WRITE_BUFFER commands in 114 succession, transparently to the client. 115 116 The value returned by REG_STATUS should be: 117 118 > 0 The number of bytes that were written to the pipe 119 0 To indicate end-of-stream status 120 < 0 A negative error code (see below). 121 122 On important error code is PIPE_ERROR_AGAIN, used to indicate that 123 writes can't be performed yet. See CMD_WAKE_ON_WRITE for more. 124 125 4/ Reading data from the channel: 126 127 Corresponds to when the guest does a read() or readv() on the 128 channel's file descriptor. 129 130 REG_CHANNEL = <channel> 131 REG_ADDRESS = <buffer-address> 132 REG_SIZE = <buffer-size> 133 REG_CMD = CMD_READ_BUFFER 134 135 status = REG_STATUS 136 137 Same restrictions on buffer addresses/lengths and same set of error 138 codes. 139 140 5/ Waiting for write ability: 141 142 If CMD_WRITE_BUFFER returns PIPE_ERROR_AGAIN, and the file descriptor 143 is not in non-blocking mode, the driver must put the client task on a 144 wait queue until the pipe service can accept data again. 145 146 Before this, the driver will do: 147 148 REG_CHANNEL = <channel> 149 REG_CMD = CMD_WAKE_ON_WRITE 150 151 To indicate to the virtual device that it is waiting and should be woken 152 up when the pipe becomes writable again. How this is done is explained 153 later. 154 155 6/ Waiting for read ability: 156 157 This is the same than CMD_WAKE_ON_WRITE, but for readability instead. 158 159 REG_CHANNEL = <channel> 160 REG_CMD = CMD_WAKE_ON_WRITE 161 162 7/ Polling for write-able/read-able state: 163 164 The following command is used by the driver to implement the select(), 165 poll() and epoll() system calls where a pipe channel is involved. 166 167 REG_CHANNEL = <channel> 168 REG_CMD = CMD_POLL 169 mask = REG_STATUS 170 171 The mask value returned by REG_STATUS is a mix of bit-flags for 172 which events are available / have occured since the last call. 173 See PIPE_POLL_READ / PIPE_POLL_WRITE / PIPE_POLL_CLOSED. 174 175 8/ Signaling events to the driver: 176 177 The device can signal events to the driver by raising its IRQ. 178 The driver's interrupt handler will then have to read a list of 179 (channel,mask) pairs, terminated by a single 0 value for the channel. 180 181 In other words, the driver's interrupt handler will do: 182 183 for (;;) { 184 channel = REG_CHANNEL 185 if (channel == 0) // END OF LIST 186 break; 187 188 mask = REG_WAKES // BIT FLAGS OF EVENTS 189 ... process events 190 } 191 192 The events reported through this list are simply: 193 194 PIPE_WAKE_READ :: the channel is now readable. 195 PIPE_WAKE_WRITE :: the channel is now writable. 196 PIPE_WAKE_CLOSED :: the pipe service closed the connection. 197 198 The PIPE_WAKE_READ and PIPE_WAKE_WRITE are only reported for a given 199 channel if CMD_WAKE_ON_READ or CMD_WAKE_ON_WRITE (respectively) were 200 issued for it. 201 202 PIPE_WAKE_CLOSED can be signaled at any time. 203 204 205Available services: 206------------------- 207 208 tcp:<port> 209 tcp:<hostname>:<port> 210 211 Open a TCP socket to a given port. This provides a very fast 212 pass-through that doesn't depend on the very slow internal emulator 213 NAT router. Note that you can only use the file descriptor with read() 214 and write() though, send() and recv() will return an ENOTSOCK error, 215 as well as any socket ioctl(). 216 217 unix:<path> 218 219 Open a Unix-domain socket on the host. 220 221 opengles 222 223 Connects to the OpenGL ES emulation process. For now, the implementation 224 is equivalent to tcp:22468, but this may change in the future. 225