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 "android_pipe_common.h" 17 18 #include "base/Stream.h" 19 20 #include <stdbool.h> 21 #include <stdint.h> 22 23 // The set of methods implemented by an AndroidPipe instance. 24 // All these methods are called at runtime by the virtual device 25 // implementation. Note that transfers are always initiated by the virtual 26 // device through the sendBuffers() and recvBuffers() callbacks. 27 // 28 // More specifically: 29 // 30 // - When a pipe has data for the guest, it should signal it by calling 31 // 'android_pipe_host_signal_wake(pipe, PIPE_WAKE_READ)'. The guest kernel 32 // will be signaled and will later initiate a recvBuffers() call. 33 // 34 // - When a pipe is ready to accept data from the guest, it should signal 35 // it by calling 'android_pipe_host_signal_wake(pipe, PIPE_WAKE_WRITE)'. The 36 // guest kernel will be signaled, and will later initiate a sendBuffers() 37 // call when the guest client writes data to the pipe. 38 // 39 // - Finally, the guest kernel can signal whether it wants to be signaled 40 // on read or write events by calling the wakeOn() callback. 41 // 42 // - When the emulator wants to close a pipe, it shall call 43 // android_pipe_host_close(). This signals the guest kernel which will later 44 // initiate a close() call. 45 // 46 typedef struct AndroidPipeFuncs { 47 // Call to open a new pipe instance. |hwpipe| is a device-side view of the 48 // pipe that must be passed to android_pipe_host_signal_wake() and 49 // android_pipe_host_close() 50 // functions. |serviceOpaque| is the parameter passed to 51 // android_pipe_add_type(), and |args| is either NULL 52 // or parameters passed to the service when opening the connection. 53 // Return a new service pipe instance, or NULL on error. 54 void* (*init)(void* hwpipe, void* serviceOpaque, const char* args); 55 56 // Called when the guest kernel has finally closed a pipe connection. 57 // This is the only place one should release/free the instance, but never 58 // call this directly, use android_pipe_host_close() instead. |pipe| is a 59 // client 60 // instance returned by init() or load(). 61 void (*close)(void* service_pipe); 62 63 // Called when the guest wants to write data to the |pipe| client instance, 64 // |buffers| points to an array of |numBuffers| descriptors that describe 65 // where to copy the data from. Return the number of bytes that were 66 // actually transferred, 0 for EOF status, or a negative error value 67 // otherwise, including PIPE_ERROR_AGAIN to indicate that the emulator 68 // is not ready yet to receive data. 69 int (*sendBuffers)(void* service_pipe, 70 const AndroidPipeBuffer* buffers, 71 int numBuffers); 72 73 // Called when the guest wants to read data from the |pipe| client, 74 // |buffers| points to an array of |numBuffers| descriptors that describe 75 // where to copy the data to. Return the number of bytes that were 76 // actually transferred, 0 for EOF status, or a negative error value 77 // otherwise, including PIPE_ERROR_AGAIN to indicate that the emulator 78 // doesn't have data for the guest yet. 79 int (*recvBuffers)(void* service_pipe, 80 AndroidPipeBuffer* buffers, 81 int numBuffers); 82 83 // Called when guest wants to poll the read/write status for the |pipe| 84 // client. Should return a combination of PIPE_POLL_XXX flags. 85 unsigned (*poll)(void* service_pipe); 86 87 // Called to signal that the guest wants to be woken when the set of 88 // PIPE_WAKE_XXX bit-flags in |flags| occur. When the condition occurs, 89 // then the |service_pipe| client shall call 90 // android_pipe_host_signal_wake(). 91 void (*wakeOn)(void* service_pipe, int flags); 92 93 // Called to save the |service_pipe| client's state to a Stream, i.e. when 94 // saving snapshots. 95 void (*save)(void* service_pipe, android::base::Stream* file); 96 97 // Called to load the sate of a pipe client from a Stream. This will always 98 // correspond to the state of the client as saved by a previous call to 99 // the 'save' method. Can be NULL to indicate that the pipe state cannot 100 // be loaded. In this case, the emulator will automatically force-close 101 // it. Parameters are similar to init(), with the addition of |file| 102 // which is the input stream. 103 void* (*load)(void* hwpipe, void* serviceOpaque, const char* args, 104 android::base::Stream* file); 105 106 } AndroidPipeFuncs; 107 108 /* Register a new pipe service type. |serviceOpaque| is passed directly 109 * to 'init() when a new pipe is connected to. 110 */ 111 extern void android_pipe_add_type(const char* serviceName, 112 void* serviceOpaque, 113 const AndroidPipeFuncs* pipeFuncs); 114 115 // The following functions are only used during unit-testing. 116 117 // Reset the list of services registered through android_pipe_add_type(). 118 // Useful at the start and end of a unit-test. 119 extern void android_pipe_reset_services(void); 120 121 /* This tells the guest system that we want to close the pipe and that 122 * further attempts to read or write to it will fail. This will not 123 * necessarily destroys the |hwpipe| immediately. The latter will call 124 * android_pipe_guest_close() at destruction time though. 125 * 126 * This will also wake-up any blocked guest threads waiting for i/o. 127 * NOTE: This function can be called from any thread. 128 */ 129 extern void android_pipe_host_close(void* hwpipe); 130 131 /* Signal that the pipe can be woken up. 'flags' must be a combination of 132 * PIPE_WAKE_READ and PIPE_WAKE_WRITE. 133 * NOTE: This function can be called from any thread. 134 */ 135 extern void android_pipe_host_signal_wake(void* hwpipe, unsigned flags); 136