1 Android QEMU FAST PIPES 2 ======================= 3 4 Introduction: 5 ------------- 6 7 The Android emulator implements a special virtual device used to provide 8 _very_ fast communication channels between the guest system and the 9 emulator itself. 10 11 From the guest, usage is simply as follows: 12 13 1/ Open the /dev/qemu_pipe device for read+write 14 15 NOTE: Starting with Linux 3.10, the device was renamed as 16 /dev/goldfish_pipe but behaves exactly in the same way. 17 18 2/ Write a zero-terminated string describing which service you want to 19 connect. 20 21 3/ Simply use read() and write() to communicate with the service. 22 23 In other words: 24 25 fd = open("/dev/qemu_pipe", O_RDWR); 26 const char* pipeName = "<pipename>"; 27 ret = write(fd, pipeName, strlen(pipeName)+1); 28 if (ret < 0) { 29 // error 30 } 31 ... ready to go 32 33 Where <pipename> is the name of a specific emulator service you want to use. 34 Supported service names are listed later in this document. 35 36 37 Implementation details: 38 ----------------------- 39 40 In the emulator source tree: 41 42 ./hw/android/goldfish/pipe.c implements the virtual driver. 43 44 ./hw/android/goldfish/pipe.h provides the interface that must be 45 implemented by any emulator pipe service. 46 47 ./android/hw-pipe-net.c contains the implementation of the network pipe 48 services (i.e. 'tcp' and 'unix'). See below for details. 49 50 In the kernel source tree: 51 52 drivers/misc/qemupipe/qemu_pipe.c contains the driver source code 53 that will be accessible as /dev/qemu_pipe within the guest. 54 55 56 Device / Driver Protocol details: 57 --------------------------------- 58 59 The device and driver use an I/O memory page and an IRQ to communicate. 60 61 - The driver writes to various I/O registers to send commands to the 62 device. 63 64 - The device raises an IRQ to instruct the driver that certain events 65 occured. 66 67 - The driver reads I/O registers to get the status of its latest command, 68 or the list of events that occured in case of interrupt. 69 70 Each opened file descriptor to /dev/qemu_pipe in the guest corresponds to a 71 32-bit 'channel' value allocated by the driver. 72 73 The following is a description of the various commands sent by the driver 74 to the device. Variable names beginning with REG_ correspond to 32-bit I/O 75 registers: 76 77 0/ Channel and address values: 78 79 Each communication channel is identified by a unique non-zero value 80 which is either 32-bit or 64-bit, depending on the guest CPU 81 architecture. 82 83 The channel value sent from the kernel to the emulator with: 84 85 void write_channel(channel) { 86 #if 64BIT_GUEST_CPU 87 REG_CHANNEL_HIGH = (channel >> 32); 88 #endif 89 REG_CHANNEL = (channel & 0xffffffffU); 90 } 91 92 Similarly, when passing a kernel address to the emulator: 93 94 void write_address(buffer_address) { 95 #if 64BIT_GUEST_CPU 96 REG_ADDRESS_HIGH = (buffer_address >> 32); 97 #endif 98 REG_ADDRESS = (buffer_address & 0xffffffffU); 99 } 100 101 1/ Creating a new channel: 102 103 Used by the driver to indicate that the guest just opened /dev/qemu_pipe 104 that will be identified by a named '<channel>': 105 106 write_channel(<channel>) 107 REG_CMD = CMD_OPEN 108 109 IMPORTANT: <channel> should never be 0 110 111 2/ Closing a channel: 112 113 Used by the driver to indicate that the guest called 'close' on the 114 channel file descriptor. 115 116 write_channel(<channel>) 117 REG_CMD = CMD_CLOSE 118 119 3/ Writing data to the channel: 120 121 Corresponds to when the guest does a write() or writev() on the 122 channel's file descriptor. This command is used to send a single 123 memory buffer: 124 125 write_channel(<channel>) 126 write_address(<buffer-address>) 127 REG_SIZE = <buffer-size> 128 REG_CMD = CMD_WRITE_BUFFER 129 130 status = REG_STATUS 131 132 NOTE: The <buffer-address> is the *GUEST* buffer address, not the 133 physical/kernel one. 134 135 IMPORTANT: The buffer sent through this command SHALL ALWAYS be entirely 136 contained inside a single page of guest memory. This is 137 enforced to simplify both the driver and the device. 138 139 When a write() spans several pages of guest memory, the 140 driver will issue several CMD_WRITE_BUFFER commands in 141 succession, transparently to the client. 142 143 The value returned by REG_STATUS should be: 144 145 > 0 The number of bytes that were written to the pipe 146 0 To indicate end-of-stream status 147 < 0 A negative error code (see below). 148 149 On important error code is PIPE_ERROR_AGAIN, used to indicate that 150 writes can't be performed yet. See CMD_WAKE_ON_WRITE for more. 151 152 4/ Reading data from the channel: 153 154 Corresponds to when the guest does a read() or readv() on the 155 channel's file descriptor. 156 157 write_channel(<channel>) 158 write_address(<buffer-address>) 159 REG_SIZE = <buffer-size> 160 REG_CMD = CMD_READ_BUFFER 161 162 status = REG_STATUS 163 164 Same restrictions on buffer addresses/lengths and same set of error 165 codes. 166 167 5/ Waiting for write ability: 168 169 If CMD_WRITE_BUFFER returns PIPE_ERROR_AGAIN, and the file descriptor 170 is not in non-blocking mode, the driver must put the client task on a 171 wait queue until the pipe service can accept data again. 172 173 Before this, the driver will do: 174 175 write_channel(<channel>) 176 REG_CMD = CMD_WAKE_ON_WRITE 177 178 To indicate to the virtual device that it is waiting and should be woken 179 up when the pipe becomes writable again. How this is done is explained 180 later. 181 182 6/ Waiting for read ability: 183 184 This is the same than CMD_WAKE_ON_WRITE, but for readability instead. 185 186 write_channel(<channel>) 187 REG_CMD = CMD_WAKE_ON_READ 188 189 7/ Polling for write-able/read-able state: 190 191 The following command is used by the driver to implement the select(), 192 poll() and epoll() system calls where a pipe channel is involved. 193 194 write_channel(<channel>) 195 REG_CMD = CMD_POLL 196 mask = REG_STATUS 197 198 The mask value returned by REG_STATUS is a mix of bit-flags for 199 which events are available / have occured since the last call. 200 See PIPE_POLL_READ / PIPE_POLL_WRITE / PIPE_POLL_CLOSED. 201 202 8/ Signaling events to the driver: 203 204 The device can signal events to the driver by raising its IRQ. 205 The driver's interrupt handler will then have to read a list of 206 (channel,mask) pairs, terminated by a single 0 value for the channel. 207 208 In other words, the driver's interrupt handler will do: 209 210 for (;;) { 211 channel = REG_CHANNEL 212 if (channel == 0) // END OF LIST 213 break; 214 215 mask = REG_WAKES // BIT FLAGS OF EVENTS 216 ... process events 217 } 218 219 The events reported through this list are simply: 220 221 PIPE_WAKE_READ :: the channel is now readable. 222 PIPE_WAKE_WRITE :: the channel is now writable. 223 PIPE_WAKE_CLOSED :: the pipe service closed the connection. 224 225 The PIPE_WAKE_READ and PIPE_WAKE_WRITE are only reported for a given 226 channel if CMD_WAKE_ON_READ or CMD_WAKE_ON_WRITE (respectively) were 227 issued for it. 228 229 PIPE_WAKE_CLOSED can be signaled at any time. 230 231 232 9/ Faster read/writes through parameter blocks: 233 234 Recent Goldfish kernels implement a faster way to perform reads and writes 235 that perform a single I/O write per operation (which is useful when 236 emulating x86 system through KVM or HAX). 237 238 This uses the following structure known to both the virtual device and 239 the kernel, defined in $QEMU/hw/android/goldfish/pipe.h: 240 241 For 32-bit guest CPUs: 242 243 struct access_params { 244 uint32_t channel; 245 uint32_t size; 246 uint32_t address; 247 uint32_t cmd; 248 uint32_t result; 249 /* reserved for future extension */ 250 uint32_t flags; 251 }; 252 253 And the 64-bit variant: 254 255 struct access_params_64 { 256 uint64_t channel; 257 uint32_t size; 258 uint64_t address; 259 uint32_t cmd; 260 uint32_t result; 261 /* reserved for future extension */ 262 uint32_t flags; 263 }; 264 265 This is simply a way to pack several parameters into a single structure. 266 Preliminary, e.g. at boot time, the kernel will allocate one such structure 267 and pass its physical address with: 268 269 PARAMS_ADDR_LOW = (params & 0xffffffff); 270 PARAMS_ADDR_HIGH = (params >> 32) & 0xffffffff; 271 272 Then for each operation, it will do something like: 273 274 params.channel = channel; 275 params.address = buffer; 276 params.size = buffer_size; 277 params.cmd = CMD_WRITE_BUFFER (or CMD_READ_BUFFER) 278 279 REG_ACCESS_PARAMS = <any> 280 281 status = params.status 282 283 The write to REG_ACCESS_PARAMS will trigger the operation, i.e. QEMU will 284 read the content of the params block, use its fields to perform the 285 operation then write back the return value into params.status. 286 287 288 Available services: 289 ------------------- 290 291 tcp:<port> 292 293 Open a TCP socket to a given localhost port. This provides a very fast 294 pass-through that doesn't depend on the very slow internal emulator 295 NAT router. Note that you can only use the file descriptor with read() 296 and write() though, send() and recv() will return an ENOTSOCK error, 297 as well as any socket ioctl(). 298 299 For security reasons, it is not possible to connect to non-localhost 300 ports. 301 302 unix:<path> 303 304 Open a Unix-domain socket on the host. 305 306 opengles 307 308 Connects to the OpenGL ES emulation process. For now, the implementation 309 is equivalent to tcp:22468, but this may change in the future. 310 311 qemud 312 313 Connects to the QEMUD service inside the emulator. This replaces the 314 connection that was performed through /dev/ttyS1 in older Android platform 315 releases. See $QEMU/docs/ANDROID-QEMUD.TXT for details. 316 317
