goldfish_pipe.h revision 89217f57a256796b67b4d3f319e0f18f6225666a 
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 "android/hw-qemud.h"
17
18/* The following functions should called from hw/goldfish_trace.c and are
19 * used to implement QEMUD 'fast-pipes' in the Android emulator.
20 */
21extern void      goldfish_pipe_thread_death(int  tid);
22extern void      goldfish_pipe_write(int tid, int offset, uint32_t value);
23extern uint32_t  goldfish_pipe_read(int tid, int offset);
24
25/* The following definitions are used to define a "pipe handler" type.
26 * Each pipe handler manages a given, named pipe type, and must provide
27 * a few callbacks that will be used at appropriate times:
28 *
29 * - init ::
30 *       is called when a guest client has connected to a given
31 *       pipe. The function should return an opaque pointer that
32 *       will be passed as the first parameter to other callbacks.
33 *
34 *       Note: pipeOpaque is the value that was passed to
35 *             goldfish_pipe_add_type() to register the pipe handler.
36 *
37 * - close ::
38 *       is called when the pipe is closed.(either from the guest, or
39 *       when the handler itself calls qemud_client_close() on the
40 *       corresponding QemudClient object passed to init()).
41 *
42 * - sendBuffers ::
43 *       is called when the guest is sending data through the pipe. This
44 *       callback receives a list of buffer descriptors that indicate
45 *       where the data is located in memory.
46 *
47 *       Must return 0 on success, or -1 on failure, with errno of:
48 *
49 *           ENOMEM -> indicates that the message is too large
50 *           EAGAIN -> indicates that the handler is not ready
51 *                     to accept the message yet.
52 *
53 * - recvBuffers ::
54 *       Is called when the guest wants to receive data from the pipe.
55 *       The caller provides a list of memory buffers to put the data into.
56 *
57 *       Must return the size of the incoming data on success, or -1
58 *       on error, with errno of:
59 *
60 *           ENOMEM -> buffer too small to receive the message
61 *           EAGAIN -> no incoming data yet
62 *
63 * - wakeOn ::
64 *       is called to indicate that the guest wants to be waked when the
65 *       pipe becomes able to either receive data from the guest, or send it
66 *       new incoming data. It is the responsability of the pipe handler to
67 *       signal the corresponding events by sending a single byte containing
68 *       QEMUD_PIPE_WAKE_XXX bit flags through qemud_client_send() to do so.
69 */
70
71enum {
72    QEMUD_PIPE_WAKE_ON_SEND = (1 << 0),
73    QEMUD_PIPE_WAKE_ON_RECV = (1 << 1),
74};
75
76/* Buffer descriptor for sendBuffers() and recvBuffers() callbacks */
77typedef struct GoldfishPipeBuffer {
78    uint8_t*  data;
79    size_t    size;
80} GoldfishPipeBuffer;
81
82/* Pipe handler funcs */
83typedef struct {
84    void*        (*init)( QemudClient*  client, void* pipeOpaque );
85    void         (*close)( void* opaque );
86    int          (*sendBuffers)( void* opaque, const GoldfishPipeBuffer*  buffers, int numBuffers );
87    int          (*recvBuffers)( void* opaque, GoldfishPipeBuffer* buffers, int numBuffers );
88    void         (*wakeOn)( void* opaque, int flags );
89} QemudPipeHandlerFuncs;
90
91/* Register a new pipe handler type. 'pipeOpaque' is passed directly
92 * to 'init() when a new pipe is connected to.
93 */
94extern void  goldfish_pipe_add_type(const char*                   pipeName,
95                                     void*                         pipeOpaque,
96                                     const QemudPipeHandlerFuncs*  pipeFuncs );
97
98#endif /* _HW_GOLDFISH_PIPE_H */
99