Skip to content

Commit 097bc98

Browse files
Robert BaldygaJan Musial
Robert Baldyga
authored and
Jan Musial
committed
doc: Add composite volume requirements documentation
Signed-off-by: Robert Baldyga <[email protected]>
1 parent 8858e73 commit 097bc98

File tree

1 file changed

+172
-0
lines changed

1 file changed

+172
-0
lines changed

‎doc/requirements/composite_volume

+172
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
---
2+
group: composite_volume
3+
---
4+
5+
The OCF composite volume provides functionality of composing mutiple OCF volume
6+
instances into one bigger volume. The component volumes are linearly mapped into
7+
address space of the composite volume (unlike RAID0, which uses interleaved
8+
mapping a.k.a. striping).
9+
10+
+-----------------------+---------------+-----------------------------+
11+
| volume A | volume B | volume C |
12+
*-----------------------|---------------|-----------------------------+
13+
LBA | 0 | 1 | 2 | 3 | 4 | 5 | 0 | 1 | 2 | 3 | 0 | 1 | 2 | 3 | 4 | 5 |
14+
+---------------------------------------------------------------------+
15+
| composite volume |
16+
+---------------------------------------------------------------------+
17+
LBA | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
18+
+---------------------------------------------------------------------+
19+
20+
--------------------------------------------------------------------------------
21+
--------------------------------------------------------------------------------
22+
title: Creation of composite volume instance
23+
id: creation
24+
---
25+
26+
It shall be possible to create an instance of a composite volume using a
27+
constructor function.
28+
29+
--------------------------------------------------------------------------------
30+
--------------------------------------------------------------------------------
31+
title: Destruction of composite volume instance
32+
id: destruction
33+
---
34+
35+
It shall be possible to destroy an instance of a composite volume using
36+
standard ocf_volume API.
37+
38+
--------------------------------------------------------------------------------
39+
--------------------------------------------------------------------------------
40+
title: Adding new component volume
41+
id: adding_component_volume
42+
---
43+
44+
If shall be possible to add new component volume to the composite volume using
45+
dedicated function.
46+
47+
--------------------------------------------------------------------------------
48+
--------------------------------------------------------------------------------
49+
title: Instatiation of component volumes
50+
id: instatiation_component_volumes
51+
---
52+
53+
Adding component volume to composite volume shall automatically instatiate
54+
component volume based on type, uuid and volume_params parameters.
55+
56+
--------------------------------------------------------------------------------
57+
--------------------------------------------------------------------------------
58+
title: Destrution of component volumes
59+
id: destruction_component_volumes
60+
---
61+
62+
Component volume instances shall be destroyed on composite volume destruction.
63+
64+
--------------------------------------------------------------------------------
65+
--------------------------------------------------------------------------------
66+
title: Adding component volumes of different types
67+
id: component_volume_types
68+
---
69+
70+
It shall be possible to add component volumes of different volume types to
71+
single composite volume. The only requirement is that those types shall be
72+
registered within the same ocf_ctx.
73+
74+
--------------------------------------------------------------------------------
75+
--------------------------------------------------------------------------------
76+
title: Maximum number of composite volumes
77+
id: max_composite_volumes
78+
---
79+
80+
It shall be possible to add up to 16 component volumes to a single composite
81+
volume.
82+
83+
--------------------------------------------------------------------------------
84+
--------------------------------------------------------------------------------
85+
title: Volume API
86+
id: volume_api
87+
---
88+
89+
Composite volume shall conform to regular ocf_volume API. I.e. it shall be
90+
possible to perform on it following volume operations: open, close,
91+
get_max_io_size, get_length, submit_io, submit_flush and submit_discard.
92+
93+
--------------------------------------------------------------------------------
94+
--------------------------------------------------------------------------------
95+
title: Volume open
96+
id: volume_open
97+
---
98+
99+
Composite volume shall open all component volumes when it's being opened.
100+
101+
--------------------------------------------------------------------------------
102+
--------------------------------------------------------------------------------
103+
title: Volume close
104+
id: volume_close
105+
---
106+
107+
Composite volume shall close all component volumes when it's being closed.
108+
109+
--------------------------------------------------------------------------------
110+
--------------------------------------------------------------------------------
111+
title: Getting maximum io size
112+
id: get_max_io_size
113+
---
114+
115+
Composite volume shall report a maximum io size being the lowest maximum io
116+
size among all the component volumes.
117+
118+
--------------------------------------------------------------------------------
119+
--------------------------------------------------------------------------------
120+
title: Getting volume length
121+
id: get_length
122+
---
123+
124+
Composite volume shall report a lenght being a sum of lenghs of all component
125+
volumes.
126+
127+
--------------------------------------------------------------------------------
128+
--------------------------------------------------------------------------------
129+
title: Request passing
130+
id: request_passing
131+
---
132+
133+
Composite volume shall pass io, flush and discard request or its fragments to
134+
component volumes based on their mapping.
135+
136+
--------------------------------------------------------------------------------
137+
--------------------------------------------------------------------------------
138+
title: IO Flags passing
139+
id: io_flags_passing
140+
---
141+
142+
Composite volume shall pass all IO flags associated with request to all requests
143+
issued to component volumes as part of fulfilling the master request.
144+
145+
--------------------------------------------------------------------------------
146+
--------------------------------------------------------------------------------
147+
title: I/O request completion
148+
id: io_request_completion
149+
---
150+
151+
The I/O request shall be completed only when all sub-I/Os submitted to component
152+
volumes are completed.
153+
154+
--------------------------------------------------------------------------------
155+
--------------------------------------------------------------------------------
156+
title: I/O error handling
157+
id: io_error_handling
158+
---
159+
160+
If I/O error occures on any I/O request submitted to composite volume, that
161+
error shall be passed to the completion of the original I/O request. If multiple
162+
sub-I/Os reported errors, the first error that occured shall be passed to the
163+
completion of the original I/O request.
164+
165+
--------------------------------------------------------------------------------
166+
--------------------------------------------------------------------------------
167+
title: Attaching/loading the cache
168+
id: cache_attach_load
169+
---
170+
171+
It shall be possible to attach/load the cache using instance of a composite
172+
volume.

0 commit comments

Comments
 (0)