1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
/*
* Copyright (C) 2012-2017 Samsung Electronics, Inc.
*
* This software is licensed under the terms of the GNU General Public
* License version 2, as published by the Free Software Foundation, and
* may be copied, distributed, and modified under those terms.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*/
#ifndef __LIB_CIRC_BUF_H__
#define __LIB_CIRC_BUF_H__
#include <linux/types.h>
/* One more byte is used for differentiating between empty and full buffer */
#define CIRC_BUF_EMPTY_FLAG_SIZE 1
#define CIRC_BUF_META_SIZE (sizeof(struct circ_buf) + CIRC_BUF_EMPTY_FLAG_SIZE)
struct circ_buf {
u32 write_count;
u32 read_count;
char buffer[];
} __packed;
struct circ_buf_desc {
struct circ_buf *circ_buf;
unsigned int size;
/* These are local copies of circ_buf counters
* for tracking actual state (circ_buf counters are shared
* between reader and writer and thus should only be updated
* when new state is ok for the reader to see). */
unsigned int write_count;
unsigned int read_count;
};
enum circ_buf_user_mode {
CIRC_BUF_MODE_KERNEL,
CIRC_BUF_MODE_USER,
CIRC_BUF_MODE_DROP
};
/**
* Function creates circ_buf_desc structure with circ_buf of specified size.
* @param[in] size size of circ_buf
* @return descriptor of allocated circ_buf, or NULL if allocation failed
*/
struct circ_buf_desc *circ_buf_create(unsigned long size);
/**
* Function destroys circ_buf_desc structure along with its circ_buf.
* @param[in] circ_buf_desc descriptor of buffer to destroy
*/
void circ_buf_destroy(struct circ_buf_desc *circ_buf_desc);
/**
* Function allocates circ_buf_desc structure and initializes its fields.
* @return allocated circ_buf descriptor, or NULL if allocation failed
*/
struct circ_buf_desc *circ_buf_desc_alloc(void);
/**
* Function sets circ_buf_desc structure pointing to previously allocated buffer
* and initializes its fields.
* @return allocated circ_buf descriptor, or NULL if allocation failed
*/
struct circ_buf *circ_buf_set(void *buf);
/**
* Function frees circ_buf descriptor.
* @param[in] circ_buf_desc circ_buf descriptor to free
*/
void circ_buf_desc_free(struct circ_buf_desc *circ_buf_desc);
/**
* Function allocates circ_buf of specified size.
* @param[in] size size of circ_buf
* @return pointer to allocated circ_buf, or NULL of allocation failed
*/
struct circ_buf *circ_buf_alloc(unsigned long size);
/**
* Function frees circ_buf.
* @param[in] circ_buf circ_buf to free
*/
void circ_buf_free(struct circ_buf *circ_buf);
/**
* Function initialized circ_buf to be empty.
* @param[in] circ_buf circ_buf to initialize
*/
void circ_buf_init(struct circ_buf *circ_buf);
/**
* Function connects circ_buf of specified size to the circ_buf desc.
* @param[in] circ_buf_desc descriptor to connect circ_buf to
* @param[in] circ_buf circ_buf to connect
* @param[in] size size of circ_buf
* @return error code
*/
void circ_buf_connect(struct circ_buf_desc *circ_buf_desc,
struct circ_buf *circ_buf, unsigned long size);
/**
* Function writes specified buf to circ_buf and updates
* circ_buf write counter.
* @param[in] circ_buf_desc descriptor of circ_buf to write buf to
* @param[in] buf input buf to write to circ_buf
* @param[in] length amount of bytes to write
* @param[in] mode enum indicating whether passed buf
* belongs to userspace or kernel memory
* @return number on bytes written on success or error code
*/
ssize_t circ_buf_write(struct circ_buf_desc *circ_buf_desc, const char *buf,
size_t length, enum circ_buf_user_mode mode);
/**
* Function writes specified buf to circ_buf without updating circ_buf write counter.
* @param[in] circ_buf_desc descriptor of circ_buf to write buf to
* @param[in] buf input buf to write to circ_buf
* @param[in] length amount of bytes to write
* @param[in] mode enum indicating whether passed buf
* belongs to userspace or kernel memory
* @return number of bytes written on success or error code
*/
ssize_t circ_buf_write_local(struct circ_buf_desc *circ_buf_desc, const char *buf,
size_t length, enum circ_buf_user_mode mode);
/**
* Function reads contents of circ_buf to output buf and updates
* circ_buf read counter.
* @param[in] circ_buf_desc descriptor of circ_buf to read from
* @param[in] buf output buf to read from circ_buf
* @param[in] length amount of bytes to read
* @param[in] mode enum indicating whether passed buf
* belongs to userspace or kernel memory,
* or contents of circ_buf must be simply dropped.
* @return number of bytes read on success or error code
*/
ssize_t circ_buf_read(struct circ_buf_desc *circ_buf_desc, char *buf,
size_t length, enum circ_buf_user_mode mode);
/**
* Function reads contents of circ_buf to output buf without updating circ_buf read counter.
* @param[in] circ_buf_desc descriptor of circ_buf to read from
* @param[in] buf output buf to read from circ_buf
* @param[in] length amount of bytes to read
* @param[in] mode enum indicating whether passed buf
* belongs to userspace or kernel memory,
* or contents of circ_buf must be simply dropped.
* @return number of bytes read on success or error code
*/
ssize_t circ_buf_read_local(struct circ_buf_desc *circ_buf_desc, char *buf,
size_t length, enum circ_buf_user_mode mode);
/**
* Function reads contents of circ_buf by specified offset from read_count,
* not updating circ_buf read counter. Not intended to be used by clients,
* required for API extensions.
* @param[in] circ_buf_desc descriptor of circ_buf to read from
* @param[in] buf output buf to read from circ_buf
* @param[in] length amount of bytes to read
* @param[in] offset offset from read_count to start reading from
* @param[in] mode enum indicating whether passed buf
* belongs to userspace or kernel memory,
* or contents of circ_buf must be simply dropped.
* @return number of bytes read on success or error code
*/
ssize_t __circ_buf_read_local(struct circ_buf_desc *circ_buf_desc, char *buf,
size_t length, size_t offset, enum circ_buf_user_mode mode);
/**
* Function updates circ_buf write counter, so reader can see new value.
* @param[in] circ_buf_desc descriptor of circ_buf to update counter in
*/
void circ_buf_flush_write(struct circ_buf_desc *circ_buf_desc);
/**
* Function updates circ_buf read counter, so writer can see new value.
* @param[in] circ_buf_desc descriptor of circ_buf to update counter in
*/
void circ_buf_flush_read(struct circ_buf_desc *circ_buf_desc);
/**
* Function restores circ_buf_desc write counter to the value its circ_buf has.
* @param[in] circ_buf_desc descriptor of circ_buf to update counter in
*/
void circ_buf_rollback_write(struct circ_buf_desc *circ_buf_desc);
/**
* Function restores circ_buf_desc read counter to the value its circ_buf has.
* @param[in] circ_buf_desc descriptor of circ_buf to update counter in
*/
void circ_buf_rollback_read(struct circ_buf_desc *circ_buf_desc);
/**
* Function checks if circ_buf is empty.
* Should be used with care, because result is not guaranteed to be valid
* after the access, unless there is external locking mechanism.
* @param[in] circ_buf_desc descriptor of circ_buf to check
* @return non-0 is circ_buf is empty and 0 otherwise
*/
unsigned int circ_buf_is_empty(struct circ_buf_desc *circ_buf_desc);
/**
* Function checks if circ_buf is full.
* Should be used with care, because result is not guaranteed to be valid
* after the access, unless there is external locking mechanism.
* @param[in] circ_buf_desc descriptor of circ_buf to check
* @return non-0 is circ_bufis full and 0 otherwise
*/
unsigned int circ_buf_is_full(struct circ_buf_desc *circ_buf_desc);
/**
* Function calculates amount of bytes in buffer currently available to write.
* Should be used with care, because result is not guaranteed to be valid
* after the access, unless there is external locking mechanism.
* @param[in] circ_buf_desc descriptor of circ_buf to check
* @return number of free bytes
*/
size_t circ_buf_bytes_free(struct circ_buf_desc *circ_buf_desc);
/**
* Function calculates amount of bytes written in buffer and not read yet.
* Should be used with care, because result is not guaranteed to be valid
* after the access, unless there is external locking mechanism.
* @param[in] circ_buf_desc descriptor of circ_buf to check
* @return number of used bytes
*/
size_t circ_buf_bytes_used(struct circ_buf_desc *circ_buf_desc);
#endif /* __LIB_CIRC_BUF_H__ */
|