1 // Copyright 2020 The Android Open Source Project 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 #pragma once 15 16 #include "base/Stream.h" 17 #include "base/export.h" 18 #include "android_pipe_common.h" 19 20 #include <stdbool.h> 21 #include <stdint.h> 22 23 #define ANDROID_PIPE_DEVICE_EXPORT extern AEMU_EXPORT 24 25 // TECHNICAL NOTE: 26 // 27 // An Android pipe is a very fast communication channel between the guest 28 // system and the emulator program. 29 // 30 // To open a new pipe to the emulator, a guest client will do the following: 31 // 32 // fd = open("/dev/qemu_pipe", O_RDWR); 33 // ret = write(fd, pipeServiceName, strlen(pipeServiceName) + 1); 34 // if (ret < 0) { 35 // // something bad happened, see errno 36 // } 37 // 38 // Where 'pipeServiceName' is a string that looke like "pipe:<service>" 39 // or "pipe:<service>:<args>", terminated by a zero. 40 // 41 // now read()/write() to communicate with <pipeServiceName> service in the 42 // emulator. select() and non-blocking i/o will also work properly. 43 // 44 45 // The Goldfish pipe virtual device is in charge of communicating with the 46 // kernel to manage pipe operations. 47 // 48 // Each pipe connection corresponds to two objects: 49 // 50 // - A hardware-side opaque object (implemented by the virtual pipe device) 51 // identified here as a |hwpipe| value. 52 // 53 // - A host-specific opaque object, identified here either as |host-pipe|. 54 // 55 // (virtual device) |hwpipe| <-----> |host-pipe| (emulator) 56 // 57 // Expected usage is the following: 58 // 59 // 1/ During setup, the virtual device should call android_pipe_set_hw_funcs() 60 // to point to callbacks it provides to implement a few functions called 61 // from the host, later at runtime. 62 // 63 // 2/ During setup, the emulator should register host pipe service instances, 64 // each one identified by a name, before the VM starts. 65 // 66 // 3/ At runtime, when a guest opens /dev/goldfish_pipe, this ends up creating 67 // a new |hwpipe| object in the virtual device, which will then call 68 // android_pipe_guest_open() to create a corresponding |host-pipe| 69 // object. 70 // 71 // Note that at this point, the |host-pipe| corresponds to a special 72 // host-side pipe state that waits for the name of the pipe service to 73 // connect to, and potential arguments. This is called a |connect-pipe| 74 // here: 75 // 76 // android_pipe_guest_open() 77 // |hwpipe| <---------------------------> |connect-pipe| 78 // 79 // 4/ When the pipe service name is fully written, the |connect-pipe| finds a 80 // service registered for it, and calls its ::init() callback to create 81 // a new |service-pipe| instance. 82 // 83 // |hwpipe| <---------------------------> |connect-pipe| 84 // 85 // |service-pipe| 86 // 87 // 5/ It then calls the AndroidPipeHwFuncs::resetPipe() callback provided 88 // by the virtual device to reattach the |hwpipe| to the |service-pipe| 89 // then later delete the now-useless |connect-pipe|. 90 // 91 // |hwpipe| <------------+ |connect-pipe| 92 // | 93 // +---------------->|service-pipe| 94 // 95 // VERY IMPORTANT NOTE: 96 // 97 // All operations should happen on the thread that currently holds the 98 // global VM state lock (see host-common/VmLock.h). It's up to 99 // the host implementation to ensure that this is always the case. 100 // 101 102 //////////////////////////////////////////////////////////////////////////// 103 // 104 // The following functions are called from the virtual device only and are 105 // implemented by AndroidEmu. They will always be called from the device thread 106 // context as well. 107 108 // Open a new Android pipe. |hwpipe| is a unique pointer value identifying the 109 // hardware-side view of the pipe, and will be passed to the 'init' callback 110 // from AndroidPipeHwFuncs. This returns a new |internal-pipe| value that is 111 // only used by the virtual device to call android_pipe_xxx() functions below. 112 ANDROID_PIPE_DEVICE_EXPORT void* android_pipe_guest_open( 113 void* hwpipe); 114 115 // Similar to android_pipe_guest_open(), but has a flags parameter that is used 116 // to communicate unique transport properties about the pipe. 117 ANDROID_PIPE_DEVICE_EXPORT void* android_pipe_guest_open_with_flags( 118 void* hwpipe, uint32_t flags); 119 120 // Close and free an Android pipe. |pipe| must be the result of a previous 121 // android_pipe_guest_open() call or the second parameter to 122 // android_pipe_reset(). 123 // This must *not* be called from the host side, see android_pipe_host_close() 124 // instead. 125 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_close( 126 void* internal_pipe, PipeCloseReason reason); 127 128 // Hooks for a start/end of save/load operations, called once per each snapshot. 129 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_pre_load(android::base::Stream* file); 130 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_post_load(android::base::Stream* file); 131 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_pre_save(android::base::Stream* file); 132 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_post_save(android::base::Stream* file); 133 134 // Save the state of an Android pipe to a stream. |internal_pipe| is the pipe 135 // instance from android_pipe_guest_open() or android_pipe_guest_load(), and 136 // |file| is the 137 // output stream. 138 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_save( 139 void* internal_pipe, android::base::Stream* file); 140 141 // Load the state of an Android pipe from a stream. |file| is the input stream, 142 // |hwpipe| is the hardware-side pipe descriptor. On success, return a new 143 // internal pipe instance (similar to one returned by 144 // android_pipe_guest_open()), and 145 // sets |*force_close| to 1 to indicate that the pipe must be force-closed 146 // just after its load/creation (only useful for certain services that can't 147 // preserve state into streams). Return NULL on faillure. 148 ANDROID_PIPE_DEVICE_EXPORT void* android_pipe_guest_load( 149 android::base::Stream* file, void* hwpipe, char* force_close); 150 151 // Similar to android_pipe_guest_load(), but this function is only called from 152 // the 153 // QEMU1 virtual pipe device, to support legacy snapshot formats. It can be 154 // ignored by the QEMU2 virtual device implementation. 155 // 156 // The difference is that this must also read the hardware-specific state 157 // fields, and store them into |*channel|, |*wakes| and |*closed| on 158 // success. 159 ANDROID_PIPE_DEVICE_EXPORT void* android_pipe_guest_load_legacy( 160 android::base::Stream* file, void* hwpipe, uint64_t* channel, 161 unsigned char* wakes, unsigned char* closed, char* force_close); 162 163 // Call the poll() callback of the client associated with |pipe|. 164 ANDROID_PIPE_DEVICE_EXPORT unsigned android_pipe_guest_poll(void* internal_pipe); 165 166 // Call the recvBuffers() callback of the client associated with |pipe|. 167 ANDROID_PIPE_DEVICE_EXPORT int android_pipe_guest_recv( 168 void* internal_pipe, AndroidPipeBuffer* buffers, int numBuffers); 169 170 // Call the sendBuffers() callback of the client associated with |pipe|. 171 ANDROID_PIPE_DEVICE_EXPORT int android_pipe_guest_send( 172 void** internal_pipe, const AndroidPipeBuffer* buffer, int numBuffer); 173 174 // Call the wakeOn() callback of the client associated with |pipe|. 175 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_wake_on( 176 void* internal_pipe, unsigned wakes); 177 178 // Utility functions to look up pipe instances and ids. 179 ANDROID_PIPE_DEVICE_EXPORT int android_pipe_get_id(void* internal_pipe); 180 ANDROID_PIPE_DEVICE_EXPORT void* android_pipe_lookup_by_id(int id); 181 182 // Each pipe type should regiter its callback to lookup instances by it. 183 // |android_pipe_lookup_by_id| will go through the list of callbacks and 184 // will check if no more than one value is returned, it will crash otherwise. 185 // The |tag| argiment will be used in the crash message. 186 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_append_lookup_by_id_callback( 187 void*(*callback)(int), const char* tag); 188