/* Copyright 2015 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.
*/
#pragma once

#include "android/emulation/android_pipe_common.h"
#include "android/utils/compiler.h"
#include "android/utils/stream.h"

#include <stdbool.h>
#include <stdint.h>

ANDROID_BEGIN_HEADER

// TECHNICAL NOTE:
//
// An Android 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);
//     ret = write(fd, pipeServiceName, strlen(pipeServiceName) + 1);
//     if (ret < 0) {
//         // something bad happened, see errno
//     }
//
// Where 'pipeServiceName' is a string that looke like "pipe:<service>"
// or "pipe:<service>:<args>", terminated by a zero.
//
//     now read()/write() to communicate with <pipeServiceName> service in the
//     emulator. select() and non-blocking i/o will also work properly.
//

// The Goldfish pipe virtual device is in charge of communicating with the
// kernel to manage pipe operations.
//
// Each pipe connection corresponds to two objects:
//
//   - A hardware-side opaque object (implemented by the virtual pipe device)
//     identified here as a |hwpipe| value.
//
//  - A host-specific opaque object, identified here either as |host-pipe|.
//
//       (virtual device) |hwpipe|  <----->  |host-pipe|   (emulator)
//
// Expected usage is the following:
//
// 1/ During setup, the virtual device should call android_pipe_set_hw_funcs()
//    to point to callbacks it provides to implement a few functions called
//    from the host, later at runtime.
//
// 2/ During setup, the emulator should register host pipe service instances,
//    each one identified by a name, before the VM starts.
//
// 3/ At runtime, when a guest opens /dev/goldfish_pipe, this ends up creating
//    a new |hwpipe| object in the virtual device, which will then call
//    android_pipe_guest_open() to create a corresponding |host-pipe|
//    object.
//
//    Note that at this point, the |host-pipe| corresponds to a special
//    host-side pipe state that waits for the name of the pipe service to
//    connect to, and potential arguments. This is called a |connect-pipe|
//    here:
//
//                     android_pipe_guest_open()
//         |hwpipe|  <--------------------------->  |connect-pipe|
//
// 4/ When the pipe service name is fully written, the |connect-pipe| finds a
//    service registered for it, and calls its ::init() callback to create
//    a new |service-pipe| instance.
//
//         |hwpipe|  <--------------------------->  |connect-pipe|
//
//                                                  |service-pipe|
//
// 5/ It then calls the AndroidPipeHwFuncs::resetPipe() callback provided
//    by the virtual device to reattach the |hwpipe| to the |service-pipe|
//    then later delete the now-useless |connect-pipe|.
//
//         |hwpipe|  <------------+                 |connect-pipe|
//                                |
//                                +---------------->|service-pipe|
//
// VERY IMPORTANT NOTE:
//
// All operations should happen on the thread that currently holds the
// global VM state lock (see android/emulation/VmLock.h). It's up to
// the host implementation to ensure that this is always the case.
//

////////////////////////////////////////////////////////////////////////////
//
// The following functions are called from the virtual device only and are
// implemented by AndroidEmu. They will always be called from the device thread
// context as well.

// Open a new Android pipe. |hwpipe| is a unique pointer value identifying the
// hardware-side view of the pipe, and will be passed to the 'init' callback
// from AndroidPipeHwFuncs. This returns a new |internal-pipe| value that is
// only used by the virtual device to call android_pipe_xxx() functions below.
extern void* android_pipe_guest_open(void* hwpipe);

// Close and free an Android pipe. |pipe| must be the result of a previous
// android_pipe_guest_open() call or the second parameter to
// android_pipe_reset().
// This must *not* be called from the host side, see android_pipe_host_close()
// instead.
extern void android_pipe_guest_close(void* internal_pipe);

// Save the state of an Android pipe to a stream. |internal_pipe| is the pipe
// instance from android_pipe_guest_open() or android_pipe_guest_load(), and
// |file| is the
// output stream.
extern void android_pipe_guest_save(void* internal_pipe, Stream* file);

// Load the state of an Android pipe from a stream. |file| is the input stream,
// |hwpipe| is the hardware-side pipe descriptor. On success, return a new
// internal pipe instance (similar to one returned by
// android_pipe_guest_open()), and
// sets |*force_close| to 1 to indicate that the pipe must be force-closed
// just after its load/creation (only useful for certain services that can't
// preserve state into streams). Return NULL on faillure.
extern void* android_pipe_guest_load(Stream* file,
                                     void* hwpipe,
                                     char* force_close);

// Similar to android_pipe_guest_load(), but this function is only called from
// the
// QEMU1 virtual pipe device, to support legacy snapshot formats. It can be
// ignored by the QEMU2 virtual device implementation.
//
// The difference is that this must also read the hardware-specific state
// fields, and store them into |*channel|, |*wakes| and |*closed| on
// success.
extern void* android_pipe_guest_load_legacy(Stream* file,
                                            void* hwpipe,
                                            uint64_t* channel,
                                            unsigned char* wakes,
                                            unsigned char* closed,
                                            char* force_close);

// Call the poll() callback of the client associated with |pipe|.
extern unsigned android_pipe_guest_poll(void* internal_pipe);

// Call the recvBuffers() callback of the client associated with |pipe|.
extern int android_pipe_guest_recv(void* internal_pipe,
                                   AndroidPipeBuffer* buffers,
                                   int numBuffers);

// Call the sendBuffers() callback of the client associated with |pipe|.
extern int android_pipe_guest_send(void* internal_pipe,
                                   const AndroidPipeBuffer* buffer,
                                   int numBuffer);

// Call the wakeOn() callback of the client associated with |pipe|.
extern void android_pipe_guest_wake_on(void* internal_pipe, unsigned wakes);

// A set of functions that must be implemented by the virtual device
// implementation. Used with call android_pipe_set_hw_funcs().
typedef struct AndroidPipeHwFuncs {
    // Change the internal pipe associated with |hwpipe| to be |internal_pipe|
    void (*resetPipe)(void* hwpipe, void* internal_pipe);
    void (*closeFromHost)(void* hwpipe);
    void (*signalWake)(void* hwpipe, unsigned flags);
} AndroidPipeHwFuncs;

// Change the set of AndroidPipeHwFuncs corresponding to the hardware virtual
// device, return the old value. This must be called from the virtual device
// when it is realized / initialized.
extern const AndroidPipeHwFuncs* android_pipe_set_hw_funcs(
        const AndroidPipeHwFuncs* hw_funcs);

ANDROID_END_HEADER