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 <stdint.h> 16#include "hw/hw.h" 17 18/* TECHNICAL NOTE: 19 * 20 * A goldfish pipe is a very fast communication channel between the guest 21 * system and the emulator program. 22 * 23 * To open a new pipe to the emulator, a guest client will do the following: 24 * 25 * fd = open("/dev/qemu_pipe", O_RDWR); 26 * char invite[64]; 27 * snprintf(invite, sizeof invite, "%s", pipeName); 28 * ret = write(fd, invite, strlen(invite)); 29 * 30 * if (ret < 0) { 31 * // something bad happened, see errno 32 * } 33 * 34 * now read()/write() to communicate with <pipeName> service in the 35 * emulator. 36 * 37 * This header provides the interface used by pipe services in the emulator 38 * to receive new client connection and deal with them. 39 * 40 * 41 * 1/ Call goldfish_pipe_add_type() to register a new pipe service by name. 42 * This must provide a pointer to a series of functions that will be called 43 * during normal pipe operations. 44 * 45 * 2/ When a client connects to the service, the 'init' callback will be called 46 * to create a new service-specific client identifier (which must returned 47 * by the function). 48 * 49 * 3/ Call goldfish_pipe_close() to force the closure of a given pipe. 50 * 51 * 4/ Call goldfish_pipe_signal() to signal a change of state to the pipe. 52 * 53 */ 54 55/* Buffer descriptor for sendBuffers() and recvBuffers() callbacks */ 56typedef struct GoldfishPipeBuffer { 57 uint8_t* data; 58 size_t size; 59} GoldfishPipeBuffer; 60 61/* Pipe handler funcs */ 62typedef struct { 63 /* Create new client connection, 'hwpipe' must be passed to other 64 * goldfish_pipe_xxx functions, while the returned value will be passed 65 * to other callbacks (e.g. close). 'pipeOpaque' is the value passed 66 * to goldfish_pipe_add_type() when registering a given pipe service. 67 */ 68 void* (*init)( void* hwpipe, void* pipeOpaque, const char* args ); 69 70 /* Called when the guest kernel has finally closed a pipe connection. 71 * This is the only place where you can release/free the client connection. 72 * You should never invoke this callback directly. Call goldfish_pipe_close() 73 * instead. 74 */ 75 void (*close)( void* pipe ); 76 77 /* Called when the guest is write()-ing to the pipe. Should return the 78 * number of bytes transfered, 0 for EOF status, or a negative error 79 * value otherwise, including PIPE_ERROR_AGAIN to indicate that the 80 * emulator is not ready to receive data yet. 81 */ 82 int (*sendBuffers)( void* pipe, const GoldfishPipeBuffer* buffers, int numBuffers ); 83 84 /* Same as sendBuffers when the guest is read()-ing from the pipe. */ 85 int (*recvBuffers)( void* pipe, GoldfishPipeBuffer* buffers, int numBuffers ); 86 87 /* Called when guest wants to poll the read/write status for the pipe. 88 * Should return a combination of PIPE_POLL_XXX flags. 89 */ 90 unsigned (*poll)( void* pipe ); 91 92 /* Called to signal that the guest wants to be woken when the set of 93 * PIPE_WAKE_XXX bit-flags in 'flags' occur. When the condition occurs, 94 * then the pipe implementation shall call goldfish_pipe_wake(). 95 */ 96 void (*wakeOn)( void* opaque, int flags ); 97} GoldfishPipeFuncs; 98 99/* Register a new pipe handler type. 'pipeOpaque' is passed directly 100 * to 'init() when a new pipe is connected to. 101 */ 102extern void goldfish_pipe_add_type(const char* pipeName, 103 void* pipeOpaque, 104 const GoldfishPipeFuncs* pipeFuncs ); 105 106/* This tells the guest system that we want to close the pipe and that 107 * further attempts to read or write to it will fail. This will not 108 * necessarily call the 'close' callback immediately though. 109 * 110 * This will also wake-up any blocked guest threads waiting for i/o. 111 */ 112extern void goldfish_pipe_close( void* hwpipe ); 113 114/* Signal that the pipe can be woken up. 'flags' must be a combination of 115 * PIPE_WAKE_READ and PIPE_WAKE_WRITE. 116 */ 117extern void goldfish_pipe_wake( void* hwpipe, unsigned flags ); 118 119/* The following definitions must match those under: 120 * 121 * $KERNEL/drivers/misc/qemupipe/qemu_pipe.c 122 * 123 * Where $KERNEL points to the android-goldfish-2.6.xx branch on: 124 * 125 * android.git.kernel.org/kernel/qemu.git. 126 */ 127 128/* pipe device registers */ 129#define PIPE_REG_COMMAND 0x00 /* write: value = command */ 130#define PIPE_REG_STATUS 0x04 /* read */ 131#define PIPE_REG_CHANNEL 0x08 /* read/write: channel id */ 132#define PIPE_REG_SIZE 0x0c /* read/write: buffer size */ 133#define PIPE_REG_ADDRESS 0x10 /* write: physical address */ 134#define PIPE_REG_WAKES 0x14 /* read: wake flags */ 135 136/* list of commands for PIPE_REG_COMMAND */ 137#define PIPE_CMD_OPEN 1 /* open new channel */ 138#define PIPE_CMD_CLOSE 2 /* close channel (from guest) */ 139#define PIPE_CMD_POLL 3 /* poll read/write status */ 140 141/* List of bitflags returned in status of CMD_POLL command */ 142#define PIPE_POLL_IN (1 << 0) 143#define PIPE_POLL_OUT (1 << 1) 144#define PIPE_POLL_HUP (1 << 2) 145 146/* The following commands are related to write operations */ 147#define PIPE_CMD_WRITE_BUFFER 4 /* send a user buffer to the emulator */ 148#define PIPE_CMD_WAKE_ON_WRITE 5 /* tell the emulator to wake us when writing is possible */ 149 150/* The following commands are related to read operations, they must be 151 * listed in the same order than the corresponding write ones, since we 152 * will use (CMD_READ_BUFFER - CMD_WRITE_BUFFER) as a special offset 153 * in qemu_pipe_read_write() below. 154 */ 155#define PIPE_CMD_READ_BUFFER 6 /* receive a page-contained buffer from the emulator */ 156#define PIPE_CMD_WAKE_ON_READ 7 /* tell the emulator to wake us when reading is possible */ 157 158/* Possible status values used to signal errors - see qemu_pipe_error_convert */ 159#define PIPE_ERROR_INVAL -1 160#define PIPE_ERROR_AGAIN -2 161#define PIPE_ERROR_NOMEM -3 162#define PIPE_ERROR_IO -4 163 164/* Bit-flags used to signal events from the emulator */ 165#define PIPE_WAKE_CLOSED (1 << 0) /* emulator closed pipe */ 166#define PIPE_WAKE_READ (1 << 1) /* pipe can now be read from */ 167#define PIPE_WAKE_WRITE (1 << 2) /* pipe can now be written to */ 168 169void pipe_dev_init(void); 170 171#endif /* _HW_GOLDFISH_PIPE_H */ 172