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