/* Copyright (C) 2011 The Android Open Source Project
**
** This software is licensed under the terms of the GNU General Public
** License version 2, as published by the Free Software Foundation, and
** may be copied, distributed, and modified under those terms.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
** GNU General Public License for more details.
*/
#ifndef _HW_GOLDFISH_PIPE_H
#define _HW_GOLDFISH_PIPE_H
#include <stdint.h>
#include "hw/hw.h"
/* TECHNICAL NOTE:
*
* A goldfish pipe is a very fast communication channel between the guest
* system and the emulator program.
*
* To open a new pipe to the emulator, a guest client will do the following:
*
* fd = open("/dev/qemu_pipe", O_RDWR);
* char invite[64];
* snprintf(invite, sizeof invite, "%s", pipeName);
* ret = write(fd, invite, strlen(invite));
*
* if (ret < 0) {
* // something bad happened, see errno
* }
*
* now read()/write() to communicate with <pipeName> service in the
* emulator.
*
* This header provides the interface used by pipe services in the emulator
* to receive new client connection and deal with them.
*
*
* 1/ Call goldfish_pipe_add_type() to register a new pipe service by name.
* This must provide a pointer to a series of functions that will be called
* during normal pipe operations.
*
* 2/ When a client connects to the service, the 'init' callback will be called
* to create a new service-specific client identifier (which must returned
* by the function).
*
* 3/ Call goldfish_pipe_close() to force the closure of a given pipe.
*
* 4/ Call goldfish_pipe_signal() to signal a change of state to the pipe.
*
*/
/* Buffer descriptor for sendBuffers() and recvBuffers() callbacks */
typedef struct GoldfishPipeBuffer {
uint8_t* data;
size_t size;
} GoldfishPipeBuffer;
/* Pipe handler funcs */
typedef struct {
/* Create new client connection, 'hwpipe' must be passed to other
* goldfish_pipe_xxx functions, while the returned value will be passed
* to other callbacks (e.g. close). 'pipeOpaque' is the value passed
* to goldfish_pipe_add_type() when registering a given pipe service.
*/
void* (*init)( void* hwpipe, void* pipeOpaque, const char* args );
/* Called when the guest kernel has finally closed a pipe connection.
* This is the only place where you can release/free the client connection.
* You should never invoke this callback directly. Call goldfish_pipe_close()
* instead.
*/
void (*close)( void* pipe );
/* Called when the guest is write()-ing to the pipe. Should return the
* number of bytes transfered, 0 for EOF status, or a negative error
* value otherwise, including PIPE_ERROR_AGAIN to indicate that the
* emulator is not ready to receive data yet.
*/
int (*sendBuffers)( void* pipe, const GoldfishPipeBuffer* buffers, int numBuffers );
/* Same as sendBuffers when the guest is read()-ing from the pipe. */
int (*recvBuffers)( void* pipe, GoldfishPipeBuffer* buffers, int numBuffers );
/* Called when guest wants to poll the read/write status for the pipe.
* Should return a combination of PIPE_POLL_XXX flags.
*/
unsigned (*poll)( void* pipe );
/* Called to signal that the guest wants to be woken when the set of
* PIPE_WAKE_XXX bit-flags in 'flags' occur. When the condition occurs,
* then the pipe implementation shall call goldfish_pipe_wake().
*/
void (*wakeOn)( void* opaque, int flags );
/* Called to save the pipe's state to a QEMUFile, i.e. when saving
* snapshots. This can be NULL to indicate that no state can be saved.
* In this case, when the pipe is loaded, the emulator will automatically
* force-close so the next operation the guest performs on it will return
* a PIPE_ERROR_IO error code.
*/
void (*save)( void* pipe, QEMUFile* file );
/* Called to load the sate of a pipe from a QEMUFile. This will always
* correspond to the state of the pipe as saved by a previous call to
* the 'save' method. Can be NULL to indicate that the pipe state cannot
* be loaded. In this case, the emulator will automatically force-close
* it.
*
* In case of success, this returns 0, and the new pipe object is returned
* in '*ppipe'. In case of errno code is returned to indicate a failure.
* 'hwpipe' and 'pipeOpaque' are the same arguments than those passed
* to 'init'.
*/
void* (*load)( void* hwpipe, void* pipeOpaque, const char* args, QEMUFile* file);
} GoldfishPipeFuncs;
/* Register a new pipe handler type. 'pipeOpaque' is passed directly
* to 'init() when a new pipe is connected to.
*/
extern void goldfish_pipe_add_type(const char* pipeName,
void* pipeOpaque,
const GoldfishPipeFuncs* pipeFuncs );
/* This tells the guest system that we want to close the pipe and that
* further attempts to read or write to it will fail. This will not
* necessarily call the 'close' callback immediately though.
*
* This will also wake-up any blocked guest threads waiting for i/o.
*/
extern void goldfish_pipe_close( void* hwpipe );
/* Signal that the pipe can be woken up. 'flags' must be a combination of
* PIPE_WAKE_READ and PIPE_WAKE_WRITE.
*/
extern void goldfish_pipe_wake( void* hwpipe, unsigned flags );
/* The following definitions must match those under:
*
* $KERNEL/drivers/misc/qemupipe/qemu_pipe.c
*
* Where $KERNEL points to the android-goldfish-2.6.xx branch on:
*
* android.git.kernel.org/kernel/qemu.git.
*/
/* pipe device registers */
#define PIPE_REG_COMMAND 0x00 /* write: value = command */
#define PIPE_REG_STATUS 0x04 /* read */
#define PIPE_REG_CHANNEL 0x08 /* read/write: channel id */
#define PIPE_REG_SIZE 0x0c /* read/write: buffer size */
#define PIPE_REG_ADDRESS 0x10 /* write: physical address */
#define PIPE_REG_WAKES 0x14 /* read: wake flags */
/* list of commands for PIPE_REG_COMMAND */
#define PIPE_CMD_OPEN 1 /* open new channel */
#define PIPE_CMD_CLOSE 2 /* close channel (from guest) */
#define PIPE_CMD_POLL 3 /* poll read/write status */
/* List of bitflags returned in status of CMD_POLL command */
#define PIPE_POLL_IN (1 << 0)
#define PIPE_POLL_OUT (1 << 1)
#define PIPE_POLL_HUP (1 << 2)
/* The following commands are related to write operations */
#define PIPE_CMD_WRITE_BUFFER 4 /* send a user buffer to the emulator */
#define PIPE_CMD_WAKE_ON_WRITE 5 /* tell the emulator to wake us when writing is possible */
/* The following commands are related to read operations, they must be
* listed in the same order than the corresponding write ones, since we
* will use (CMD_READ_BUFFER - CMD_WRITE_BUFFER) as a special offset
* in qemu_pipe_read_write() below.
*/
#define PIPE_CMD_READ_BUFFER 6 /* receive a page-contained buffer from the emulator */
#define PIPE_CMD_WAKE_ON_READ 7 /* tell the emulator to wake us when reading is possible */
/* Possible status values used to signal errors - see qemu_pipe_error_convert */
#define PIPE_ERROR_INVAL -1
#define PIPE_ERROR_AGAIN -2
#define PIPE_ERROR_NOMEM -3
#define PIPE_ERROR_IO -4
/* Bit-flags used to signal events from the emulator */
#define PIPE_WAKE_CLOSED (1 << 0) /* emulator closed pipe */
#define PIPE_WAKE_READ (1 << 1) /* pipe can now be read from */
#define PIPE_WAKE_WRITE (1 << 2) /* pipe can now be written to */
void pipe_dev_init(void);
#endif /* _HW_GOLDFISH_PIPE_H */