• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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