Skip to content

Commit 8eb2399

Browse files
author
Michal Mielewczyk
committed
doc: Requirements for IO classes
Signed-off-by: Michal Mielewczyk <michal.mielewczyk@intel.com>
1 parent c2c1d9e commit 8eb2399

File tree

1 file changed

+315
-30
lines changed

1 file changed

+315
-30
lines changed

‎doc/requirements/io_class‎

Lines changed: 315 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -19,65 +19,350 @@ It shall be possible to set a maximum size of an IO class.
1919

2020
--------------------------------------------------------------------------------
2121
--------------------------------------------------------------------------------
22-
title: Allowed occupancy values
23-
id: occupancy_allowed_values
22+
title: Respecting occupancy limit on a cache miss
23+
id: occupancy_respecting_limit_on_miss
2424
---
2525

26-
The product shall accept integer and fixed point values for a max size of an IO class
27-
in range from 0.00 to 1.00 and interpret them as a fraction of a cache size.
26+
When an IO request is a miss and the target IO class has reached its occupancy limit,
27+
the software shall evict a number of missing cache blocks from the target IO class
28+
before inserting new data into it.
2829

2930
--------------------------------------------------------------------------------
3031
--------------------------------------------------------------------------------
31-
title: Default occupancy limit
32-
id: occupancy_default_limit
32+
title: IO request to a disabled IO class
33+
id: occupancy_disabled_io_class
3334
---
3435

35-
When initializing a cache the software shall set IO class's max occupancy to 1.00.
36+
When a target IO class max occupancy has been set to 0.00 the software shall submit
37+
IO requests in the Pass-Through mode.
3638

3739
--------------------------------------------------------------------------------
3840
--------------------------------------------------------------------------------
39-
title: Setting an occupancy limit on loading a cache
40-
id: occupancy_limit_on_load
41+
title: Reassign cachelines to another IO class regardless of occupancy limit
42+
id: occupancy_limit_on_repart
4143
---
4244

43-
When a cache state is loaded, the occupancy limit for each IO class shall be set
44-
to the value used before the cache had been shut down.
45+
When an IO request is a hit and it triggers reassigning a cache line to another
46+
IO class, the software shall reassign the cache line regardless of the target
47+
IO class's occupancy limit.
4548

4649
--------------------------------------------------------------------------------
4750
--------------------------------------------------------------------------------
48-
title: Display an occupancy limit value
49-
id: occupancy_display_limit
51+
title: Directory based classification
52+
id: rule_directory
5053
---
5154

52-
It shall be possible to display the currently set value of the occupancy limit
53-
for each configured ioclass. The value shall be displayed as a fraction of a cache
54-
size.
55+
The product shall allow to classify the file IO requests around an absolute
56+
path to a directory. The classification condition shall be fulfilled when the target
57+
file is located in the directory or in any of its subdirectories.
5558

5659
--------------------------------------------------------------------------------
5760
--------------------------------------------------------------------------------
58-
title: Respecting occupancy limit on a cache miss
59-
id: occupancy_respecting_limit_on_miss
61+
title: Directory existance detection
62+
id: rule_existing_directory
6063
---
6164

62-
When an IO request is a miss and the target IO class has reached its occupancy limit,
63-
the software shall evict a number of missing cache blocks from the target IO class
64-
before inserting new data into it.
65+
While an existing directory is detected under the given path the product shall
66+
probe for its existence every 5 seconds. Upon detecting the directory move or
67+
removal during the probe no further IO request shall be assigned to the IO class.
68+
6569

6670
--------------------------------------------------------------------------------
6771
--------------------------------------------------------------------------------
68-
title: IO request to a disabled IO class
69-
id: occupancy_disabled_io_class
72+
title: Directory non existance detection
73+
id: rule_non_existing_directory
7074
---
7175

72-
When a target IO class max occupancy has been set to 0.00 the software shall submit
73-
IO requests in the Pass-Through mode.
76+
While a directory is not detected under the given path the product shall probe
77+
for its existence every 1 second. Upon detecting a change in the directory
78+
metadata during the probe the product shall allow to classify IO requests to
79+
the IO class.
7480

7581
--------------------------------------------------------------------------------
7682
--------------------------------------------------------------------------------
77-
title: Reassign cachelines to another IO class regardless of occupancy limit
78-
id: occupancy_limit_on_repart
83+
title: Classifying direct IO requests
84+
id: rule_direct
7985
---
8086

81-
When an IO request is a hit and triggers reassigning a cache line to another
82-
IO class, the software shall reassign the cache line regardless of the target
83-
IO class's occupancy limit.
87+
The product shall allow to classify IO requests around O_DIRECT flag.
88+
89+
--------------------------------------------------------------------------------
90+
--------------------------------------------------------------------------------
91+
title: Classifying filesystem metadata
92+
id: rule_metadata
93+
---
94+
95+
The product shall allow to classify IO requests around metadata of the following
96+
filesystems:
97+
98+
1. ext3
99+
2. ext4
100+
3. xfs
101+
102+
--------------------------------------------------------------------------------
103+
--------------------------------------------------------------------------------
104+
title: Core id based classification
105+
id: rule_core_id
106+
---
107+
108+
The product shall allow to classify IO requests around an id of a target core.
109+
It shall be possible to specify range of applicable core ids.
110+
111+
--------------------------------------------------------------------------------
112+
--------------------------------------------------------------------------------
113+
title: File size based classification
114+
id: rule_file_size
115+
---
116+
117+
The product shall allow to classify IO requests around a size of target file.
118+
It shall be possible to specify range of applicable sizes.
119+
120+
--------------------------------------------------------------------------------
121+
--------------------------------------------------------------------------------
122+
title: IO class based classification
123+
id: rule_io_class
124+
---
125+
126+
The product shall allow to classify IO requests around a previously defined
127+
IO class id. It shall be possible to specify range of applicable IO class ids.
128+
129+
--------------------------------------------------------------------------------
130+
--------------------------------------------------------------------------------
131+
title: File extension based classification
132+
id: rule_extension_based
133+
---
134+
135+
The product shall allow to classify IO requests around an extension of a target
136+
file.
137+
138+
--------------------------------------------------------------------------------
139+
--------------------------------------------------------------------------------
140+
title: File name prefix based classification
141+
id: rule_prefix
142+
---
143+
144+
The product shall allow to classify IO requests around target file name prefix.
145+
146+
--------------------------------------------------------------------------------
147+
--------------------------------------------------------------------------------
148+
title: LBA based classification
149+
id: rule_lba
150+
---
151+
152+
The product shall allow to classify IO requests around LBA. It shall be possible
153+
to specify range of applicable LBAs.
154+
155+
--------------------------------------------------------------------------------
156+
--------------------------------------------------------------------------------
157+
title: PID based classification
158+
id: rule_pid
159+
---
160+
161+
The product shall allow to classify IO requests around a submitter process PID.
162+
It shall be possible to specify range of applicable PIDs.
163+
164+
--------------------------------------------------------------------------------
165+
--------------------------------------------------------------------------------
166+
title: Process name based classification
167+
id: rule_process_name
168+
---
169+
170+
The product shall allow to classify IO requests around a submitter process name.
171+
172+
--------------------------------------------------------------------------------
173+
--------------------------------------------------------------------------------
174+
title: File offset based classification
175+
id: rule_file_offset
176+
---
177+
178+
The product shall allow to classify IO requests around an offset within a target
179+
file. It shall be possible to specify range of applicable offsets.
180+
181+
--------------------------------------------------------------------------------
182+
--------------------------------------------------------------------------------
183+
title: Request size based classification
184+
id: rule_request_size
185+
---
186+
187+
The product shall allow to classify IO requests around its size. It shall be possible
188+
to specify range of applicable sizes.
189+
190+
--------------------------------------------------------------------------------
191+
--------------------------------------------------------------------------------
192+
title: WLTH based classification
193+
id: rule_wlth
194+
---
195+
196+
The product shall allow to classify IO requests around write life time hints.
197+
It shall be possible to specify range of applicable write life time hints.
198+
199+
200+
--------------------------------------------------------------------------------
201+
--------------------------------------------------------------------------------
202+
title: Unclassified rule
203+
id: rule_unclassified
204+
---
205+
206+
When an IO request is not eligible for any of the configured IO classes the system
207+
shall classify it as **unclassified**.
208+
209+
--------------------------------------------------------------------------------
210+
--------------------------------------------------------------------------------
211+
title: Combining multiple conditions in one rule
212+
id: combining_rules
213+
---
214+
215+
The product shall allow to combine multiple classification rules into one
216+
classification rule.
217+
218+
It shall be possible to combine rules using the following boolean operators:
219+
220+
1. And
221+
2. Or
222+
223+
--------------------------------------------------------------------------------
224+
--------------------------------------------------------------------------------
225+
title: Display an IO class configuration
226+
id: display_configuration
227+
---
228+
229+
The product shall provide an option to display current configuration of IO classes.
230+
231+
--------------------------------------------------------------------------------
232+
--------------------------------------------------------------------------------
233+
title: Export an IO class configuration to csv
234+
id: export_csv
235+
---
236+
237+
The product shall provide an option to export current IO class configuration in
238+
the a format compatilbe with a config file.
239+
240+
--------------------------------------------------------------------------------
241+
--------------------------------------------------------------------------------
242+
title: Load configuration from file
243+
id: config_file
244+
---
245+
246+
The product shall provide an option to load IO class configuration from a file.
247+
248+
--------------------------------------------------------------------------------
249+
--------------------------------------------------------------------------------
250+
title: Setting an IO class configuration on loading a cache
251+
id: load_config
252+
---
253+
254+
When a cache is loaded, IO class configuration shall be restored to the values
255+
used before the cache had been shut down.
256+
257+
--------------------------------------------------------------------------------
258+
--------------------------------------------------------------------------------
259+
title: Max number of IO classes
260+
id: max_configured
261+
---
262+
263+
The product shall allow to configure up to 33 IO classes.
264+
265+
--------------------------------------------------------------------------------
266+
--------------------------------------------------------------------------------
267+
title: Attributes
268+
id: attributes
269+
---
270+
271+
The IO class configuration shall include the following attributes for each IO class:
272+
273+
1. Id
274+
2. Classification rule
275+
3. Eviction priority
276+
4. Occupancy limit
277+
278+
--------------------------------------------------------------------------------
279+
--------------------------------------------------------------------------------
280+
title: Allowed ids
281+
id: id_allowed_values
282+
---
283+
284+
The product shall accept the IO class ids in range 0-32 inclusive.
285+
286+
--------------------------------------------------------------------------------
287+
--------------------------------------------------------------------------------
288+
title: Allowed eviction priorities
289+
id: eviction_priorities_allowed_values
290+
---
291+
292+
The product shall accept the eviction priorities in range 0-255 inclusive.
293+
294+
--------------------------------------------------------------------------------
295+
--------------------------------------------------------------------------------
296+
title: Empty eviction priority
297+
id: empty_priority
298+
---
299+
300+
The product shall allow to omit eviction priority in IO class configuration.
301+
The IO class with empty eviction priority shall be thought of as pinned.
302+
303+
--------------------------------------------------------------------------------
304+
--------------------------------------------------------------------------------
305+
title: Pinning IO class
306+
id: pinning
307+
---
308+
309+
The product shall allow to pin an IO class. Data from the pinned IO class shall
310+
not be evicted unless its occupancy limit is not exceeded.
311+
312+
--------------------------------------------------------------------------------
313+
--------------------------------------------------------------------------------
314+
title: Allowed occupancy values
315+
id: occupancy_allowed_values
316+
---
317+
318+
The product shall accept integer and fixed point values for a max size of an IO class
319+
in range from 0.00 to 1.00 and interpret them as a fraction of a cache size.
320+
321+
--------------------------------------------------------------------------------
322+
--------------------------------------------------------------------------------
323+
title: Rules testing order
324+
id: rules_testing_order
325+
---
326+
327+
IO request shall be tested against classification rules in the order of
328+
increasing id.
329+
330+
--------------------------------------------------------------------------------
331+
--------------------------------------------------------------------------------
332+
title: Effective IO Class
333+
id: effective
334+
---
335+
336+
Effective IO class for given IO request shall be the latest one for which
337+
the IO request fulfill the condition.
338+
339+
--------------------------------------------------------------------------------
340+
--------------------------------------------------------------------------------
341+
title: Last processed rule
342+
id: last_processed
343+
---
344+
345+
The product shall allow to mark classification rule as a terminating one. When
346+
an IO requests matches a terminating rule the IO class is resolved as an effecitve
347+
one and no further processing is being performed.
348+
349+
--------------------------------------------------------------------------------
350+
--------------------------------------------------------------------------------
351+
title: Default IO class attribute
352+
id: default_ioclass_attribute
353+
---
354+
355+
The product shall initialize default IO class with attributes:
356+
357+
1. Id equal to 0
358+
2. Classification rule **unclassified**
359+
3. Eviction priority equal to 255
360+
4. Occupancy limit equal to 1.00
361+
362+
--------------------------------------------------------------------------------
363+
--------------------------------------------------------------------------------
364+
title: Immutable default rule
365+
id: immutable_default
366+
---
367+
368+
The default IO class rule shall be immutable.

0 commit comments

Comments
 (0)