1 | /** |
---|
2 | * @file rtems/bdbuf.h |
---|
3 | * |
---|
4 | * block device buffer management |
---|
5 | */ |
---|
6 | |
---|
7 | /* |
---|
8 | * Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia |
---|
9 | * Author: Victor V. Vengerov <vvv@oktet.ru> |
---|
10 | * |
---|
11 | * @(#) bdbuf.h,v 1.9 2005/02/02 00:06:18 joel Exp |
---|
12 | */ |
---|
13 | |
---|
14 | #ifndef _RTEMS_BDBUF_H |
---|
15 | #define _RTEMS_BDBUF_H |
---|
16 | |
---|
17 | #ifdef __cplusplus |
---|
18 | extern "C" { |
---|
19 | #endif |
---|
20 | |
---|
21 | #include <rtems.h> |
---|
22 | #include <rtems/libio.h> |
---|
23 | #include <rtems/chain.h> |
---|
24 | |
---|
25 | #include "rtems/blkdev.h" |
---|
26 | #include "rtems/diskdevs.h" |
---|
27 | |
---|
28 | |
---|
29 | /* |
---|
30 | * To manage buffers we using Buffer Descriptors. |
---|
31 | * To speed-up buffer lookup descriptors are organized in AVL-Tree. |
---|
32 | * The fields 'dev' and 'block' are search key. |
---|
33 | */ |
---|
34 | |
---|
35 | /* Buffer descriptors |
---|
36 | * Descriptors organized in AVL-tree to speedup buffer lookup. |
---|
37 | * dev and block fields are search key in AVL-tree. |
---|
38 | * Modified buffers, free buffers and used buffers linked in 'mod', 'free' and |
---|
39 | * 'lru' chains appropriately. |
---|
40 | */ |
---|
41 | |
---|
42 | typedef struct bdbuf_buffer { |
---|
43 | Chain_Node link; /* Link in the lru, mod or free chains */ |
---|
44 | |
---|
45 | struct bdbuf_avl_node { |
---|
46 | signed char cache; /* Cache */ |
---|
47 | |
---|
48 | struct bdbuf_buffer* left; /* Left Child */ |
---|
49 | struct bdbuf_buffer* right; /* Right Child */ |
---|
50 | |
---|
51 | signed char bal; /* The balance of the sub-tree */ |
---|
52 | } avl; |
---|
53 | |
---|
54 | dev_t dev; /* device number */ |
---|
55 | blkdev_bnum block; /* block number on the device */ |
---|
56 | |
---|
57 | unsigned char *buffer; /* Pointer to the buffer memory area */ |
---|
58 | rtems_status_code status; /* Last I/O operation completion status */ |
---|
59 | int error; /* If status != RTEMS_SUCCESSFUL, this field contains |
---|
60 | errno value which can be used by user later */ |
---|
61 | boolean modified:1; /* =1 if buffer was modified */ |
---|
62 | boolean in_progress:1; /* =1 if exchange with disk is in progress; |
---|
63 | need to wait on semaphore */ |
---|
64 | boolean actual:1; /* Buffer contains actual data */ |
---|
65 | int use_count; /* Usage counter; incremented when somebody use |
---|
66 | this buffer; decremented when buffer released |
---|
67 | without modification or when buffer is flushed |
---|
68 | by swapout task */ |
---|
69 | |
---|
70 | rtems_bdpool_id pool; /* Identifier of buffer pool to which this buffer |
---|
71 | belongs */ |
---|
72 | CORE_mutex_Control transfer_sema; |
---|
73 | /* Transfer operation semaphore */ |
---|
74 | } bdbuf_buffer; |
---|
75 | |
---|
76 | |
---|
77 | /* |
---|
78 | * the following data structures are internal to the bdbuf layer, |
---|
79 | * but it is convenient to have them visible from the outside for inspection |
---|
80 | */ |
---|
81 | /* |
---|
82 | * The groups of the blocks with the same size are collected in the |
---|
83 | * bd_pool. Note that a several of the buffer's groups with the |
---|
84 | * same size can exists. |
---|
85 | */ |
---|
86 | typedef struct bdbuf_pool |
---|
87 | { |
---|
88 | bdbuf_buffer *tree; /* Buffer descriptor lookup AVL tree root */ |
---|
89 | |
---|
90 | Chain_Control free; /* Free buffers list */ |
---|
91 | Chain_Control lru; /* Last recently used list */ |
---|
92 | |
---|
93 | int blksize; /* The size of the blocks (in bytes) */ |
---|
94 | int nblks; /* Number of blocks in this pool */ |
---|
95 | rtems_id bufget_sema; /* Buffer obtain counting semaphore */ |
---|
96 | void *mallocd_bufs; /* Pointer to the malloc'd buffer memory, |
---|
97 | or NULL, if buffer memory provided in |
---|
98 | buffer configuration */ |
---|
99 | bdbuf_buffer *bdbufs; /* Pointer to table of buffer descriptors |
---|
100 | allocated for this buffer pool. */ |
---|
101 | } bdbuf_pool; |
---|
102 | |
---|
103 | /* Buffering layer context definition */ |
---|
104 | struct bdbuf_context { |
---|
105 | bdbuf_pool *pool; /* Table of buffer pools */ |
---|
106 | int npools; /* Number of entries in pool table */ |
---|
107 | |
---|
108 | Chain_Control mod; /* Modified buffers list */ |
---|
109 | rtems_id flush_sema; /* Buffer flush semaphore; counting |
---|
110 | semaphore; incremented when buffer |
---|
111 | flushed to the disk; decremented when |
---|
112 | buffer modified */ |
---|
113 | rtems_id swapout_task; /* Swapout task ID */ |
---|
114 | }; |
---|
115 | /* |
---|
116 | * the context of the buffering layer, visible for inspection |
---|
117 | */ |
---|
118 | extern struct bdbuf_context rtems_bdbuf_ctx; |
---|
119 | |
---|
120 | /* bdbuf_config structure describes block configuration (size, |
---|
121 | * amount, memory location) for buffering layer |
---|
122 | */ |
---|
123 | typedef struct rtems_bdbuf_config { |
---|
124 | int size; /* Size of block */ |
---|
125 | int num; /* Number of blocks of appropriate size */ |
---|
126 | unsigned char *mem_area; |
---|
127 | /* Pointer to the blocks location or NULL, in this |
---|
128 | case memory for blocks will be allocated by |
---|
129 | Buffering Layer with the help of RTEMS partition |
---|
130 | manager */ |
---|
131 | } rtems_bdbuf_config; |
---|
132 | |
---|
133 | extern rtems_bdbuf_config rtems_bdbuf_configuration[]; |
---|
134 | extern int rtems_bdbuf_configuration_size; |
---|
135 | |
---|
136 | #define SWAPOUT_TASK_DEFAULT_PRIORITY 15 |
---|
137 | extern rtems_task_priority swapout_task_priority; |
---|
138 | |
---|
139 | /* rtems_bdbuf_init -- |
---|
140 | * Prepare buffering layer to work - initialize buffer descritors |
---|
141 | * and (if it is neccessary) buffers. Buffers will be allocated accoriding |
---|
142 | * to the configuration table, each entry describes kind of block and |
---|
143 | * amount requested. After initialization all blocks is placed into |
---|
144 | * free elements lists. |
---|
145 | * |
---|
146 | * PARAMETERS: |
---|
147 | * conf_table - pointer to the buffers configuration table |
---|
148 | * size - number of entries in configuration table |
---|
149 | * |
---|
150 | * RETURNS: |
---|
151 | * RTEMS status code (RTEMS_SUCCESSFUL if operation completed successfully |
---|
152 | * or error code if error is occured) |
---|
153 | */ |
---|
154 | rtems_status_code |
---|
155 | rtems_bdbuf_init(rtems_bdbuf_config *conf_table, int size); |
---|
156 | |
---|
157 | |
---|
158 | /* rtems_bdbuf_get -- |
---|
159 | * Obtain block buffer. If specified block already cached (i.e. there's |
---|
160 | * block in the _modified_, or _recently_used_), return address |
---|
161 | * of appropriate buffer descriptor and increment reference counter to 1. |
---|
162 | * If block is not cached, allocate new buffer and return it. Data |
---|
163 | * shouldn't be read to the buffer from media; buffer may contains |
---|
164 | * arbitrary data. This primitive may be blocked if there are no free |
---|
165 | * buffer descriptors available and there are no unused non-modified |
---|
166 | * (or synchronized with media) buffers available. |
---|
167 | * |
---|
168 | * PARAMETERS: |
---|
169 | * device - device number (constructed of major and minor device number) |
---|
170 | * block - linear media block number |
---|
171 | * bd - address of variable to store pointer to the buffer descriptor |
---|
172 | * |
---|
173 | * RETURNS: |
---|
174 | * RTEMS status code (RTEMS_SUCCESSFUL if operation completed successfully |
---|
175 | * or error code if error is occured) |
---|
176 | * |
---|
177 | * SIDE EFFECTS: |
---|
178 | * bufget_sema semaphore obtained by this primitive. |
---|
179 | */ |
---|
180 | rtems_status_code |
---|
181 | rtems_bdbuf_get(dev_t device, blkdev_bnum block, bdbuf_buffer **bdb_ptr); |
---|
182 | |
---|
183 | /* rtems_bdbuf_read -- |
---|
184 | * (Similar to the rtems_bdbuf_get, except reading data from media) |
---|
185 | * Obtain block buffer. If specified block already cached, return address |
---|
186 | * of appropriate buffer and increment reference counter to 1. If block is |
---|
187 | * not cached, allocate new buffer and read data to it from the media. |
---|
188 | * This primitive may be blocked on waiting until data to be read from |
---|
189 | * media, if there are no free buffer descriptors available and there are |
---|
190 | * no unused non-modified (or synchronized with media) buffers available. |
---|
191 | * |
---|
192 | * PARAMETERS: |
---|
193 | * device - device number (consists of major and minor device number) |
---|
194 | * block - linear media block number |
---|
195 | * bd - address of variable to store pointer to the buffer descriptor |
---|
196 | * |
---|
197 | * RETURNS: |
---|
198 | * RTEMS status code (RTEMS_SUCCESSFUL if operation completed successfully |
---|
199 | * or error code if error is occured) |
---|
200 | * |
---|
201 | * SIDE EFFECTS: |
---|
202 | * bufget_sema and transfer_sema semaphores obtained by this primitive. |
---|
203 | */ |
---|
204 | rtems_status_code |
---|
205 | rtems_bdbuf_read(dev_t device, blkdev_bnum block, bdbuf_buffer **bdb_ptr); |
---|
206 | |
---|
207 | /* rtems_bdbuf_release -- |
---|
208 | * Release buffer allocated before. This primitive decrease the |
---|
209 | * usage counter. If it is zero, further destiny of buffer depends on |
---|
210 | * 'modified' status. If buffer was modified, it is placed to the end of |
---|
211 | * mod list and flush task waken up. If buffer was not modified, |
---|
212 | * it is placed to the end of lru list, and bufget_sema released, allowing |
---|
213 | * to reuse this buffer. |
---|
214 | * |
---|
215 | * PARAMETERS: |
---|
216 | * bd_buf - pointer to the bdbuf_buffer structure previously obtained using |
---|
217 | * get/read primitive. |
---|
218 | * |
---|
219 | * RETURNS: |
---|
220 | * RTEMS status code (RTEMS_SUCCESSFUL if operation completed successfully |
---|
221 | * or error code if error is occured) |
---|
222 | * |
---|
223 | * SIDE EFFECTS: |
---|
224 | * flush_sema and bufget_sema semaphores may be released by this primitive. |
---|
225 | */ |
---|
226 | rtems_status_code |
---|
227 | rtems_bdbuf_release(bdbuf_buffer *bd_buf); |
---|
228 | |
---|
229 | /* rtems_bdbuf_release_modified -- |
---|
230 | * Release buffer allocated before, assuming that it is _modified_ by |
---|
231 | * it's owner. This primitive decrease usage counter for buffer, mark |
---|
232 | * buffer descriptor as modified. If usage counter is 0, insert it at |
---|
233 | * end of mod chain and release flush_sema semaphore to activate the |
---|
234 | * flush task. |
---|
235 | * |
---|
236 | * PARAMETERS: |
---|
237 | * bd_buf - pointer to the bdbuf_buffer structure previously obtained using |
---|
238 | * get/read primitive. |
---|
239 | * |
---|
240 | * RETURNS: |
---|
241 | * RTEMS status code (RTEMS_SUCCESSFUL if operation completed successfully |
---|
242 | * or error code if error is occured) |
---|
243 | * |
---|
244 | * SIDE EFFECTS: |
---|
245 | * flush_sema semaphore may be released by this primitive. |
---|
246 | */ |
---|
247 | rtems_status_code |
---|
248 | rtems_bdbuf_release_modified(bdbuf_buffer *bd_buf); |
---|
249 | |
---|
250 | /* rtems_bdbuf_sync -- |
---|
251 | * Wait until specified buffer synchronized with disk. Invoked on exchanges |
---|
252 | * critical for data consistency on the media. This primitive mark owned |
---|
253 | * block as modified, decrease usage counter. If usage counter is 0, |
---|
254 | * block inserted to the mod chain and flush_sema semaphore released. |
---|
255 | * Finally, primitives blocked on transfer_sema semaphore. |
---|
256 | * |
---|
257 | * PARAMETERS: |
---|
258 | * bd_buf - pointer to the bdbuf_buffer structure previously obtained using |
---|
259 | * get/read primitive. |
---|
260 | * |
---|
261 | * RETURNS: |
---|
262 | * RTEMS status code (RTEMS_SUCCESSFUL if operation completed successfully |
---|
263 | * or error code if error is occured) |
---|
264 | * |
---|
265 | * SIDE EFFECTS: |
---|
266 | * Primitive may be blocked on transfer_sema semaphore. |
---|
267 | */ |
---|
268 | rtems_status_code |
---|
269 | rtems_bdbuf_sync(bdbuf_buffer *bd_buf); |
---|
270 | |
---|
271 | /* rtems_bdbuf_syncdev -- |
---|
272 | * Synchronize with disk all buffers containing the blocks belonging to |
---|
273 | * specified device. |
---|
274 | * |
---|
275 | * PARAMETERS: |
---|
276 | * dev - block device number |
---|
277 | * |
---|
278 | * RETURNS: |
---|
279 | * RTEMS status code (RTEMS_SUCCESSFUL if operation completed successfully |
---|
280 | * or error code if error is occured) |
---|
281 | */ |
---|
282 | rtems_status_code |
---|
283 | rtems_bdbuf_syncdev(dev_t dev); |
---|
284 | |
---|
285 | /* rtems_bdbuf_find_pool -- |
---|
286 | * Find first appropriate buffer pool. This primitive returns the index |
---|
287 | * of first buffer pool which block size is greater than or equal to |
---|
288 | * specified size. |
---|
289 | * |
---|
290 | * PARAMETERS: |
---|
291 | * block_size - requested block size |
---|
292 | * pool - placeholder for result |
---|
293 | * |
---|
294 | * RETURNS: |
---|
295 | * RTEMS status code: RTEMS_SUCCESSFUL if operation completed successfully, |
---|
296 | * RTEMS_INVALID_SIZE if specified block size is invalid (not a power |
---|
297 | * of 2), RTEMS_NOT_DEFINED if buffer pool for this or greater block size |
---|
298 | * is not configured. |
---|
299 | */ |
---|
300 | rtems_status_code |
---|
301 | rtems_bdbuf_find_pool(int block_size, rtems_bdpool_id *pool); |
---|
302 | |
---|
303 | /* rtems_bdbuf_get_pool_info -- |
---|
304 | * Obtain characteristics of buffer pool with specified number. |
---|
305 | * |
---|
306 | * PARAMETERS: |
---|
307 | * pool - buffer pool number |
---|
308 | * block_size - block size for which buffer pool is configured returned |
---|
309 | * there |
---|
310 | * blocks - number of buffers in buffer pool returned there |
---|
311 | * |
---|
312 | * RETURNS: |
---|
313 | * RTEMS status code: RTEMS_SUCCESSFUL if operation completed successfully, |
---|
314 | * RTEMS_INVALID_NUMBER if appropriate buffer pool is not configured. |
---|
315 | * |
---|
316 | * NOTE: |
---|
317 | * Buffer pools enumerated contiguously starting from 0. |
---|
318 | */ |
---|
319 | rtems_status_code |
---|
320 | rtems_bdbuf_get_pool_info(rtems_bdpool_id pool, int *block_size, int *blocks); |
---|
321 | |
---|
322 | #ifdef __cplusplus |
---|
323 | } |
---|
324 | #endif |
---|
325 | |
---|
326 | #endif |
---|