1 /* Copyright (C) 2011 The Android Open Source Project 2 ** 3 ** This software is licensed under the terms of the GNU General Public 4 ** License version 2, as published by the Free Software Foundation, and 5 ** may be copied, distributed, and modified under those terms. 6 ** 7 ** This program is distributed in the hope that it will be useful, 8 ** but WITHOUT ANY WARRANTY; without even the implied warranty of 9 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 10 ** GNU General Public License for more details. 11 */ 12 #ifndef _HW_GOLDFISH_PIPE_H 13 #define _HW_GOLDFISH_PIPE_H 14 15 #include <stdbool.h> 16 #include <stdint.h> 17 #include "hw/hw.h" 18 19 /* TECHNICAL NOTE: 20 * 21 * A goldfish pipe is a very fast communication channel between the guest 22 * system and the emulator program. 23 * 24 * To open a new pipe to the emulator, a guest client will do the following: 25 * 26 * fd = open("/dev/qemu_pipe", O_RDWR); 27 * char invite[64]; 28 * snprintf(invite, sizeof invite, "%s", pipeName); 29 * ret = write(fd, invite, strlen(invite)); 30 * 31 * if (ret < 0) { 32 * // something bad happened, see errno 33 * } 34 * 35 * now read()/write() to communicate with <pipeName> service in the 36 * emulator. 37 * 38 * This header provides the interface used by pipe services in the emulator 39 * to receive new client connection and deal with them. 40 * 41 * 42 * 1/ Call goldfish_pipe_add_type() to register a new pipe service by name. 43 * This must provide a pointer to a series of functions that will be called 44 * during normal pipe operations. 45 * 46 * 2/ When a client connects to the service, the 'init' callback will be called 47 * to create a new service-specific client identifier (which must returned 48 * by the function). 49 * 50 * 3/ Call goldfish_pipe_close() to force the closure of a given pipe. 51 * 52 * 4/ Call goldfish_pipe_signal() to signal a change of state to the pipe. 53 * 54 */ 55 56 /* Buffer descriptor for sendBuffers() and recvBuffers() callbacks */ 57 typedef struct GoldfishPipeBuffer { 58 uint8_t* data; 59 size_t size; 60 } GoldfishPipeBuffer; 61 62 /* Pipe handler funcs */ 63 typedef struct { 64 /* Create new client connection, 'hwpipe' must be passed to other 65 * goldfish_pipe_xxx functions, while the returned value will be passed 66 * to other callbacks (e.g. close). 'pipeOpaque' is the value passed 67 * to goldfish_pipe_add_type() when registering a given pipe service. 68 */ 69 void* (*init)( void* hwpipe, void* pipeOpaque, const char* args ); 70 71 /* Called when the guest kernel has finally closed a pipe connection. 72 * This is the only place where you can release/free the client connection. 73 * You should never invoke this callback directly. Call goldfish_pipe_close() 74 * instead. 75 */ 76 void (*close)( void* pipe ); 77 78 /* Called when the guest is write()-ing to the pipe. Should return the 79 * number of bytes transfered, 0 for EOF status, or a negative error 80 * value otherwise, including PIPE_ERROR_AGAIN to indicate that the 81 * emulator is not ready to receive data yet. 82 */ 83 int (*sendBuffers)( void* pipe, const GoldfishPipeBuffer* buffers, int numBuffers ); 84 85 /* Same as sendBuffers when the guest is read()-ing from the pipe. */ 86 int (*recvBuffers)( void* pipe, GoldfishPipeBuffer* buffers, int numBuffers ); 87 88 /* Called when guest wants to poll the read/write status for the pipe. 89 * Should return a combination of PIPE_POLL_XXX flags. 90 */ 91 unsigned (*poll)( void* pipe ); 92 93 /* Called to signal that the guest wants to be woken when the set of 94 * PIPE_WAKE_XXX bit-flags in 'flags' occur. When the condition occurs, 95 * then the pipe implementation shall call goldfish_pipe_wake(). 96 */ 97 void (*wakeOn)( void* opaque, int flags ); 98 99 /* Called to save the pipe's state to a QEMUFile, i.e. when saving 100 * snapshots. This can be NULL to indicate that no state can be saved. 101 * In this case, when the pipe is loaded, the emulator will automatically 102 * force-close so the next operation the guest performs on it will return 103 * a PIPE_ERROR_IO error code. 104 */ 105 void (*save)( void* pipe, QEMUFile* file ); 106 107 /* Called to load the sate of a pipe from a QEMUFile. This will always 108 * correspond to the state of the pipe as saved by a previous call to 109 * the 'save' method. Can be NULL to indicate that the pipe state cannot 110 * be loaded. In this case, the emulator will automatically force-close 111 * it. 112 * 113 * In case of success, this returns 0, and the new pipe object is returned 114 * in '*ppipe'. In case of errno code is returned to indicate a failure. 115 * 'hwpipe' and 'pipeOpaque' are the same arguments than those passed 116 * to 'init'. 117 */ 118 void* (*load)( void* hwpipe, void* pipeOpaque, const char* args, QEMUFile* file); 119 } GoldfishPipeFuncs; 120 121 /* Register a new pipe handler type. 'pipeOpaque' is passed directly 122 * to 'init() when a new pipe is connected to. 123 */ 124 extern void goldfish_pipe_add_type(const char* pipeName, 125 void* pipeOpaque, 126 const GoldfishPipeFuncs* pipeFuncs ); 127 128 /* This tells the guest system that we want to close the pipe and that 129 * further attempts to read or write to it will fail. This will not 130 * necessarily call the 'close' callback immediately though. 131 * 132 * This will also wake-up any blocked guest threads waiting for i/o. 133 */ 134 extern void goldfish_pipe_close( void* hwpipe ); 135 136 /* Signal that the pipe can be woken up. 'flags' must be a combination of 137 * PIPE_WAKE_READ and PIPE_WAKE_WRITE. 138 */ 139 extern void goldfish_pipe_wake( void* hwpipe, unsigned flags ); 140 141 /* The following definitions must match those under: 142 * 143 * $KERNEL/drivers/misc/qemupipe/qemu_pipe.c 144 * 145 * Where $KERNEL points to the android-goldfish-2.6.xx branch on: 146 * 147 * android.googlesource.com/kernel/goldfish.git. 148 */ 149 150 /* pipe device registers */ 151 #define PIPE_REG_COMMAND 0x00 /* write: value = command */ 152 #define PIPE_REG_STATUS 0x04 /* read */ 153 #define PIPE_REG_CHANNEL 0x08 /* read/write: channel id */ 154 #define PIPE_REG_SIZE 0x0c /* read/write: buffer size */ 155 #define PIPE_REG_ADDRESS 0x10 /* write: physical address */ 156 #define PIPE_REG_WAKES 0x14 /* read: wake flags */ 157 /* read/write: parameter buffer address */ 158 #define PIPE_REG_PARAMS_ADDR_LOW 0x18 159 #define PIPE_REG_PARAMS_ADDR_HIGH 0x1c 160 /* write: access with paremeter buffer */ 161 #define PIPE_REG_ACCESS_PARAMS 0x20 162 #define PIPE_REG_CHANNEL_HIGH 0x30 /* read/write: high 32 bit channel id */ 163 #define PIPE_REG_ADDRESS_HIGH 0x34 /* write: high 32 bit physical address */ 164 165 /* list of commands for PIPE_REG_COMMAND */ 166 #define PIPE_CMD_OPEN 1 /* open new channel */ 167 #define PIPE_CMD_CLOSE 2 /* close channel (from guest) */ 168 #define PIPE_CMD_POLL 3 /* poll read/write status */ 169 170 /* List of bitflags returned in status of CMD_POLL command */ 171 #define PIPE_POLL_IN (1 << 0) 172 #define PIPE_POLL_OUT (1 << 1) 173 #define PIPE_POLL_HUP (1 << 2) 174 175 /* The following commands are related to write operations */ 176 #define PIPE_CMD_WRITE_BUFFER 4 /* send a user buffer to the emulator */ 177 #define PIPE_CMD_WAKE_ON_WRITE 5 /* tell the emulator to wake us when writing is possible */ 178 179 /* The following commands are related to read operations, they must be 180 * listed in the same order than the corresponding write ones, since we 181 * will use (CMD_READ_BUFFER - CMD_WRITE_BUFFER) as a special offset 182 * in qemu_pipe_read_write() below. 183 */ 184 #define PIPE_CMD_READ_BUFFER 6 /* receive a page-contained buffer from the emulator */ 185 #define PIPE_CMD_WAKE_ON_READ 7 /* tell the emulator to wake us when reading is possible */ 186 187 /* Possible status values used to signal errors - see qemu_pipe_error_convert */ 188 #define PIPE_ERROR_INVAL -1 189 #define PIPE_ERROR_AGAIN -2 190 #define PIPE_ERROR_NOMEM -3 191 #define PIPE_ERROR_IO -4 192 193 /* Bit-flags used to signal events from the emulator */ 194 #define PIPE_WAKE_CLOSED (1 << 0) /* emulator closed pipe */ 195 #define PIPE_WAKE_READ (1 << 1) /* pipe can now be read from */ 196 #define PIPE_WAKE_WRITE (1 << 2) /* pipe can now be written to */ 197 198 void pipe_dev_init(bool newDeviceNaming); 199 200 struct access_params{ 201 uint32_t channel; 202 uint32_t size; 203 uint32_t address; 204 uint32_t cmd; 205 uint32_t result; 206 /* reserved for future extension */ 207 uint32_t flags; 208 }; 209 210 struct access_params_64 { 211 uint64_t channel; 212 uint32_t size; 213 uint64_t address; 214 uint32_t cmd; 215 uint32_t result; 216 /* reserved for future extension */ 217 uint32_t flags; 218 }; 219 220 #endif /* _HW_GOLDFISH_PIPE_H */ 221
