1 // Copyright 2018 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/utils/compiler.h" 17 18 ANDROID_BEGIN_HEADER 19 20 #include <stdbool.h> 21 #include <stdint.h> 22 23 #define RING_BUFFER_SHIFT 11 24 #define RING_BUFFER_SIZE (1 << RING_BUFFER_SHIFT) 25 #define NUM_CONFIG_FIELDS 32 26 27 // Single producer/consumer ring buffer struct that can be shared 28 // between host and guest as-is. 29 struct ring_buffer { 30 uint32_t host_version; 31 uint32_t guest_version; 32 uint32_t write_pos; // Atomically updated for the consumer 33 uint32_t unused0[13]; // Separate cache line 34 uint32_t read_pos; // Atomically updated for the producer 35 uint32_t read_live_count; 36 uint32_t read_yield_count; 37 uint32_t read_sleep_us_count; 38 uint32_t unused1[12]; // Separate cache line 39 uint8_t buf[RING_BUFFER_SIZE]; 40 uint32_t state; // An atomically updated variable from both 41 // producer and consumer for other forms of 42 // coordination. 43 // Configuration fields 44 uint32_t config[NUM_CONFIG_FIELDS]; 45 }; 46 47 void ring_buffer_init(struct ring_buffer* r); 48 49 // Writes or reads step_size at a time. Sets errno=EAGAIN if full or empty. 50 // Returns the number of step_size steps read. 51 long ring_buffer_write( 52 struct ring_buffer* r, const void* data, uint32_t step_size, uint32_t steps); 53 long ring_buffer_read( 54 struct ring_buffer* r, void* data, uint32_t step_size, uint32_t steps); 55 // Like ring_buffer_write / ring_buffer_read, but merely advances the counters 56 // without reading or writing anything. Returns the number of step_size steps 57 // advanced. 58 long ring_buffer_advance_write( 59 struct ring_buffer* r, uint32_t step_size, uint32_t steps); 60 long ring_buffer_advance_read( 61 struct ring_buffer* r, uint32_t step_size, uint32_t steps); 62 63 // If we want to work with dynamically allocated buffers, a separate struct is 64 // needed; the host and guest are in different address spaces and thus have 65 // different views of the same memory, with the host and guest having different 66 // copies of this struct. 67 struct ring_buffer_view { 68 uint8_t* buf; 69 uint32_t size; 70 uint32_t mask; 71 }; 72 73 // Convenience struct that holds a pointer to a ring along with a view. It's a 74 // common pattern for the ring and the buffer of the view to be shared between 75 // two entities (in this case, usually guest and host). 76 struct ring_buffer_with_view { 77 struct ring_buffer* ring; 78 struct ring_buffer_view view; 79 }; 80 81 // Calculates the highest power of 2 so that 82 // (1 << shift) <= size. 83 uint32_t ring_buffer_calc_shift(uint32_t size); 84 85 // Initializes ring buffer with view using |buf|. If |size| is not a power of 86 // two, then the buffer will assume a size equal to the greater power of two 87 // less than |size|. 88 void ring_buffer_view_init( 89 struct ring_buffer* r, 90 struct ring_buffer_view* v, 91 uint8_t* buf, 92 uint32_t size); 93 94 void ring_buffer_init_view_only( 95 struct ring_buffer_view* v, 96 uint8_t* buf, 97 uint32_t size); 98 99 // Read/write functions with the view. 100 long ring_buffer_view_write( 101 struct ring_buffer* r, 102 struct ring_buffer_view* v, 103 const void* data, uint32_t step_size, uint32_t steps); 104 long ring_buffer_view_read( 105 struct ring_buffer* r, 106 struct ring_buffer_view* v, 107 void* data, uint32_t step_size, uint32_t steps); 108 109 // Usage of ring_buffer as a waitable object. 110 // These functions will back off if spinning too long. 111 // 112 // if |v| is null, it is assumed that the statically allocated ring buffer is 113 // used. 114 // 115 // Returns true if ring buffer became available, false if timed out. 116 bool ring_buffer_wait_write( 117 const struct ring_buffer* r, 118 const struct ring_buffer_view* v, 119 uint32_t bytes, 120 uint64_t timeout_us); 121 bool ring_buffer_wait_read( 122 const struct ring_buffer* r, 123 const struct ring_buffer_view* v, 124 uint32_t bytes, 125 uint64_t timeout_us); 126 127 // read/write fully, blocking if there is nothing to read/write. 128 void ring_buffer_write_fully( 129 struct ring_buffer* r, 130 struct ring_buffer_view* v, 131 const void* data, 132 uint32_t bytes); 133 void ring_buffer_read_fully( 134 struct ring_buffer* r, 135 struct ring_buffer_view* v, 136 void* data, 137 uint32_t bytes); 138 139 // Like read/write fully, but with an abort value. The value is read from 140 // |abortPtr| each time. If |abortPtr| is null, then behaves the same 141 // as ring_buffer_(read|write)_fully. 142 // Returns the actual number of bytes sent or received. 143 uint32_t ring_buffer_write_fully_with_abort( 144 struct ring_buffer* r, 145 struct ring_buffer_view* v, 146 const void* data, 147 uint32_t bytes, 148 uint32_t abort_value, 149 const volatile uint32_t* abort_ptr); 150 uint32_t ring_buffer_read_fully_with_abort( 151 struct ring_buffer* r, 152 struct ring_buffer_view* v, 153 void* data, 154 uint32_t bytes, 155 uint32_t abort_value, 156 const volatile uint32_t* abort_ptr); 157 158 uint32_t ring_buffer_view_get_ring_pos( 159 const struct ring_buffer_view* v, 160 uint32_t index); 161 162 bool ring_buffer_can_write( 163 const struct ring_buffer* r, uint32_t bytes); 164 bool ring_buffer_can_read( 165 const struct ring_buffer* r, uint32_t bytes); 166 bool ring_buffer_view_can_write( 167 const struct ring_buffer* r, 168 const struct ring_buffer_view* v, 169 uint32_t bytes); 170 bool ring_buffer_view_can_read( 171 const struct ring_buffer* r, 172 const struct ring_buffer_view* v, 173 uint32_t bytes); 174 uint32_t ring_buffer_available_read( 175 const struct ring_buffer* r, 176 const struct ring_buffer_view* v); 177 // Copies out contents from the consumer side of 178 // ring buffer/view |r,v|. 179 // If there is less available read than |wanted_bytes|, 180 // returns -1. 181 // On success, returns 0. 182 int ring_buffer_copy_contents( 183 const struct ring_buffer* r, 184 const struct ring_buffer_view* v, 185 uint32_t wanted_bytes, 186 uint8_t* res); 187 188 // Lockless synchronization where the consumer is allowed to hang up and go to 189 // sleep. This can be considered a sort of asymmetric lock for two threads, 190 // where the consumer can be more sleepy. It captures the pattern we usually use 191 // for emulator devices; the guest asks the host for something, and some host 192 // thread services the request and goes back to sleep. 193 enum ring_buffer_sync_state { 194 RING_BUFFER_SYNC_PRODUCER_IDLE = 0, 195 RING_BUFFER_SYNC_PRODUCER_ACTIVE = 1, 196 RING_BUFFER_SYNC_CONSUMER_HANGING_UP = 2, 197 RING_BUFFER_SYNC_CONSUMER_HUNG_UP = 3, 198 }; 199 200 // Sync state is RING_BUFFER_SYNC_PRODUCER_IDLE. 201 void ring_buffer_sync_init(struct ring_buffer* r); 202 203 // Tries to acquire the channel for sending. 204 // Returns false if the consumer was in the middle of hanging up, 205 // true if the producer successfully acquired the channel 206 // (put it in the RING_BUFFER_SYNC_PRODUCER_ACTIVE state). 207 bool ring_buffer_producer_acquire(struct ring_buffer* r); 208 // Same as above, but acquires from RING_BUFFER_SYNC_CONSUMER_HUNG_UP. 209 bool ring_buffer_producer_acquire_from_hangup(struct ring_buffer* r); 210 // Waits until the consumer hangs up. 211 void ring_buffer_producer_wait_hangup(struct ring_buffer* r); 212 // Sets the state back to RING_BUFFER_SYNC_PRODUCER_IDLE. 213 void ring_buffer_producer_idle(struct ring_buffer* r); 214 215 // There is no symmetric consumer acquire because the consumer can consume with 216 // the ring buffer being in any state (albeit with long waiting if the producer 217 // does not send anything) 218 219 // Tries to acquire the channel on the consumer side for 220 // hanging up. Returns false if the producer is in the middle of sending, 221 // true if the consumer successfully hung up the channel 222 // (put it in the RING_BUFFER_SYNC_CONSUMER_HUNG_UP state). 223 bool ring_buffer_consumer_hangup(struct ring_buffer* r); 224 // Waits until the producer has set the state to 225 // RING_BUFFER_SYNC_PRODUCER_IDLE. 226 void ring_buffer_consumer_wait_producer_idle(struct ring_buffer* r); 227 // Sets the state to hung up. 228 void ring_buffer_consumer_hung_up(struct ring_buffer* r); 229 230 // Convenient function to reschedule thread 231 void ring_buffer_yield(); 232 ANDROID_END_HEADER 233