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 bool ring_buffer_wait_read( 121 const struct ring_buffer* r, 122 const struct ring_buffer_view* v, 123 uint32_t bytes); 124 125 // read/write fully, blocking if there is nothing to read/write. 126 void ring_buffer_write_fully( 127 struct ring_buffer* r, 128 struct ring_buffer_view* v, 129 const void* data, 130 uint32_t bytes); 131 void ring_buffer_read_fully( 132 struct ring_buffer* r, 133 struct ring_buffer_view* v, 134 void* data, 135 uint32_t bytes); 136 137 // Like read/write fully, but with an abort value. The value is read from 138 // |abortPtr| each time. If |abortPtr| is null, then behaves the same 139 // as ring_buffer_(read|write)_fully. 140 // Returns the actual number of bytes sent or received. 141 uint32_t ring_buffer_write_fully_with_abort( 142 struct ring_buffer* r, 143 struct ring_buffer_view* v, 144 const void* data, 145 uint32_t bytes, 146 uint32_t abort_value, 147 const volatile uint32_t* abort_ptr); 148 uint32_t ring_buffer_read_fully_with_abort( 149 struct ring_buffer* r, 150 struct ring_buffer_view* v, 151 void* data, 152 uint32_t bytes, 153 uint32_t abort_value, 154 const volatile uint32_t* abort_ptr); 155 156 uint32_t ring_buffer_view_get_ring_pos( 157 const struct ring_buffer_view* v, 158 uint32_t index); 159 160 bool ring_buffer_can_write( 161 const struct ring_buffer* r, uint32_t bytes); 162 bool ring_buffer_can_read( 163 const struct ring_buffer* r, uint32_t bytes); 164 bool ring_buffer_view_can_write( 165 const struct ring_buffer* r, 166 const struct ring_buffer_view* v, 167 uint32_t bytes); 168 bool ring_buffer_view_can_read( 169 const struct ring_buffer* r, 170 const struct ring_buffer_view* v, 171 uint32_t bytes); 172 uint32_t ring_buffer_available_read( 173 const struct ring_buffer* r, 174 const struct ring_buffer_view* v); 175 // Copies out contents from the consumer side of 176 // ring buffer/view |r,v|. 177 // If there is less available read than |wanted_bytes|, 178 // returns -1. 179 // On success, returns 0. 180 int ring_buffer_copy_contents( 181 const struct ring_buffer* r, 182 const struct ring_buffer_view* v, 183 uint32_t wanted_bytes, 184 uint8_t* res); 185 186 // Lockless synchronization where the consumer is allowed to hang up and go to 187 // sleep. This can be considered a sort of asymmetric lock for two threads, 188 // where the consumer can be more sleepy. It captures the pattern we usually use 189 // for emulator devices; the guest asks the host for something, and some host 190 // thread services the request and goes back to sleep. 191 enum ring_buffer_sync_state { 192 RING_BUFFER_SYNC_PRODUCER_IDLE = 0, 193 RING_BUFFER_SYNC_PRODUCER_ACTIVE = 1, 194 RING_BUFFER_SYNC_CONSUMER_HANGING_UP = 2, 195 RING_BUFFER_SYNC_CONSUMER_HUNG_UP = 3, 196 }; 197 198 // Sync state is RING_BUFFER_SYNC_PRODUCER_IDLE. 199 void ring_buffer_sync_init(struct ring_buffer* r); 200 201 // Tries to acquire the channel for sending. 202 // Returns false if the consumer was in the middle of hanging up, 203 // true if the producer successfully acquired the channel 204 // (put it in the RING_BUFFER_SYNC_PRODUCER_ACTIVE state). 205 bool ring_buffer_producer_acquire(struct ring_buffer* r); 206 // Same as above, but acquires from RING_BUFFER_SYNC_CONSUMER_HUNG_UP. 207 bool ring_buffer_producer_acquire_from_hangup(struct ring_buffer* r); 208 // Waits until the consumer hangs up. 209 void ring_buffer_producer_wait_hangup(struct ring_buffer* r); 210 // Sets the state back to RING_BUFFER_SYNC_PRODUCER_IDLE. 211 void ring_buffer_producer_idle(struct ring_buffer* r); 212 213 // There is no symmetric consumer acquire because the consumer can consume with 214 // the ring buffer being in any state (albeit with long waiting if the producer 215 // does not send anything) 216 217 // Tries to acquire the channel on the consumer side for 218 // hanging up. Returns false if the producer is in the middle of sending, 219 // true if the consumer successfully hung up the channel 220 // (put it in the RING_BUFFER_SYNC_CONSUMER_HUNG_UP state). 221 bool ring_buffer_consumer_hangup(struct ring_buffer* r); 222 // Waits until the producer has set the state to 223 // RING_BUFFER_SYNC_PRODUCER_IDLE. 224 void ring_buffer_consumer_wait_producer_idle(struct ring_buffer* r); 225 // Sets the state to hung up. 226 void ring_buffer_consumer_hung_up(struct ring_buffer* r); 227 228 // Convenient function to reschedule thread 229 void ring_buffer_yield(); 230 ANDROID_END_HEADER 231