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 "aemu/base/utils/stream.h" 17 #include "aemu/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(void* hwpipe); 113 114 // Similar to android_pipe_guest_open(), but has a flags parameter that is used 115 // to communicate unique transport properties about the pipe. 116 ANDROID_PIPE_DEVICE_EXPORT void* android_pipe_guest_open_with_flags( 117 void* hwpipe, uint32_t flags); 118 119 // Close and free an Android pipe. |pipe| must be the result of a previous 120 // android_pipe_guest_open() call or the second parameter to 121 // android_pipe_reset(). 122 // This must *not* be called from the host side, see android_pipe_host_close() 123 // instead. 124 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_close( 125 void* internal_pipe, PipeCloseReason reason); 126 127 // Hooks for a start/end of save/load operations, called once per each snapshot. 128 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_pre_load(Stream* file); 129 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_post_load(Stream* file); 130 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_pre_save(Stream* file); 131 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_post_save(Stream* file); 132 133 // Save the state of an Android pipe to a stream. |internal_pipe| is the pipe 134 // instance from android_pipe_guest_open() or android_pipe_guest_load(), and 135 // |file| is the 136 // output stream. 137 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_save( 138 void* internal_pipe, Stream* file); 139 140 // Load the state of an Android pipe from a stream. |file| is the input stream, 141 // |hwpipe| is the hardware-side pipe descriptor. On success, return a new 142 // internal pipe instance (similar to one returned by 143 // android_pipe_guest_open()), and 144 // sets |*force_close| to 1 to indicate that the pipe must be force-closed 145 // just after its load/creation (only useful for certain services that can't 146 // preserve state into streams). Return NULL on faillure. 147 ANDROID_PIPE_DEVICE_EXPORT void* android_pipe_guest_load( 148 Stream* file, void* hwpipe, char* force_close); 149 150 // Similar to android_pipe_guest_load(), but this function is only called from 151 // the 152 // QEMU1 virtual pipe device, to support legacy snapshot formats. It can be 153 // ignored by the QEMU2 virtual device implementation. 154 // 155 // The difference is that this must also read the hardware-specific state 156 // fields, and store them into |*channel|, |*wakes| and |*closed| on 157 // success. 158 ANDROID_PIPE_DEVICE_EXPORT void* android_pipe_guest_load_legacy( 159 Stream* file, void* hwpipe, uint64_t* channel, 160 unsigned char* wakes, unsigned char* closed, char* force_close); 161 162 // Call the poll() callback of the client associated with |pipe|. 163 ANDROID_PIPE_DEVICE_EXPORT unsigned android_pipe_guest_poll(void* internal_pipe); 164 165 // Call the recvBuffers() callback of the client associated with |pipe|. 166 ANDROID_PIPE_DEVICE_EXPORT int android_pipe_guest_recv( 167 void* internal_pipe, AndroidPipeBuffer* buffers, int numBuffers); 168 169 // Blocking call that waits until guest is able to receive data. 170 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_wait_guest_recv(void* internal_pipe); 171 172 // Call the sendBuffers() callback of the client associated with |pipe|. 173 ANDROID_PIPE_DEVICE_EXPORT int android_pipe_guest_send( 174 void** internal_pipe, const AndroidPipeBuffer* buffer, int numBuffer); 175 176 // Blocking call that waits until guest is able to send data. 177 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_wait_guest_send(void* internal_pipe); 178 179 // Call the wakeOn() callback of the client associated with |pipe|. 180 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_guest_wake_on( 181 void* internal_pipe, unsigned wakes); 182 183 // Utility functions to look up pipe instances and ids. 184 ANDROID_PIPE_DEVICE_EXPORT int android_pipe_get_id(void* internal_pipe); 185 ANDROID_PIPE_DEVICE_EXPORT void* android_pipe_lookup_by_id(int id); 186 187 // Each pipe type should regiter its callback to lookup instances by it. 188 // |android_pipe_lookup_by_id| will go through the list of callbacks and 189 // will check if no more than one value is returned, it will crash otherwise. 190 // The |tag| argiment will be used in the crash message. 191 ANDROID_PIPE_DEVICE_EXPORT void android_pipe_append_lookup_by_id_callback( 192 void*(*callback)(int), const char* tag); 193