]>
Commit | Line | Data |
---|---|---|
1cd7af50 CD |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | .. include:: <isonum.txt> | |
3 | ||
4 | =========================================== | |
a6f771c9 | 5 | User Interface for Resource Control feature |
1cd7af50 | 6 | =========================================== |
a6f771c9 | 7 | |
1cd7af50 CD |
8 | :Copyright: |copy| 2016 Intel Corporation |
9 | :Authors: - Fenghua Yu <fenghua.yu@intel.com> | |
10 | - Tony Luck <tony.luck@intel.com> | |
11 | - Vikas Shivappa <vikas.shivappa@intel.com> | |
f20e5789 | 12 | |
f20e5789 | 13 | |
1cd7af50 CD |
14 | Intel refers to this feature as Intel Resource Director Technology(Intel(R) RDT). |
15 | AMD refers to this feature as AMD Platform Quality of Service(AMD QoS). | |
f20e5789 | 16 | |
e6d42931 | 17 | This feature is enabled by the CONFIG_X86_CPU_RESCTRL and the x86 /proc/cpuinfo |
a6f771c9 | 18 | flag bits: |
f20e5789 | 19 | |
1cd7af50 CD |
20 | ============================================= ================================ |
21 | RDT (Resource Director Technology) Allocation "rdt_a" | |
22 | CAT (Cache Allocation Technology) "cat_l3", "cat_l2" | |
23 | CDP (Code and Data Prioritization) "cdp_l3", "cdp_l2" | |
24 | CQM (Cache QoS Monitoring) "cqm_llc", "cqm_occup_llc" | |
25 | MBM (Memory Bandwidth Monitoring) "cqm_mbm_total", "cqm_mbm_local" | |
26 | MBA (Memory Bandwidth Allocation) "mba" | |
27 | ============================================= ================================ | |
28 | ||
29 | To use the feature mount the file system:: | |
f20e5789 | 30 | |
d6c64a4f | 31 | # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps]] /sys/fs/resctrl |
f20e5789 FY |
32 | |
33 | mount options are: | |
34 | ||
1cd7af50 CD |
35 | "cdp": |
36 | Enable code/data prioritization in L3 cache allocations. | |
37 | "cdpl2": | |
38 | Enable code/data prioritization in L2 cache allocations. | |
39 | "mba_MBps": | |
40 | Enable the MBA Software Controller(mba_sc) to specify MBA | |
41 | bandwidth in MBps | |
aa55d5a4 | 42 | |
57794aab | 43 | L2 and L3 CDP are controlled separately. |
f20e5789 | 44 | |
1640ae94 | 45 | RDT features are orthogonal. A particular system may support only |
e17e7330 RC |
46 | monitoring, only control, or both monitoring and control. Cache |
47 | pseudo-locking is a unique way of using cache control to "pin" or | |
48 | "lock" data in the cache. Details can be found in | |
49 | "Cache Pseudo-Locking". | |
50 | ||
1640ae94 VS |
51 | |
52 | The mount succeeds if either of allocation or monitoring is present, but | |
53 | only those files and directories supported by the system will be created. | |
54 | For more details on the behavior of the interface during monitoring | |
55 | and allocation, see the "Resource alloc and monitor groups" section. | |
f20e5789 | 56 | |
458b0d6e | 57 | Info directory |
1cd7af50 | 58 | ============== |
458b0d6e TG |
59 | |
60 | The 'info' directory contains information about the enabled | |
61 | resources. Each resource has its own subdirectory. The subdirectory | |
a9cad3d4 | 62 | names reflect the resource names. |
1640ae94 VS |
63 | |
64 | Each subdirectory contains the following files with respect to | |
65 | allocation: | |
66 | ||
67 | Cache resource(L3/L2) subdirectory contains the following files | |
68 | related to allocation: | |
458b0d6e | 69 | |
1cd7af50 CD |
70 | "num_closids": |
71 | The number of CLOSIDs which are valid for this | |
72 | resource. The kernel uses the smallest number of | |
73 | CLOSIDs of all enabled resources as limit. | |
74 | "cbm_mask": | |
75 | The bitmask which is valid for this resource. | |
76 | This mask is equivalent to 100%. | |
77 | "min_cbm_bits": | |
78 | The minimum number of consecutive bits which | |
79 | must be set when writing a mask. | |
80 | ||
81 | "shareable_bits": | |
82 | Bitmask of shareable resource with other executing | |
83 | entities (e.g. I/O). User can use this when | |
84 | setting up exclusive cache partitions. Note that | |
85 | some platforms support devices that have their | |
86 | own settings for cache use which can over-ride | |
87 | these bits. | |
88 | "bit_usage": | |
89 | Annotated capacity bitmasks showing how all | |
90 | instances of the resource are used. The legend is: | |
91 | ||
92 | "0": | |
93 | Corresponding region is unused. When the system's | |
cba1aab8 RC |
94 | resources have been allocated and a "0" is found |
95 | in "bit_usage" it is a sign that resources are | |
96 | wasted. | |
1cd7af50 CD |
97 | |
98 | "H": | |
99 | Corresponding region is used by hardware only | |
cba1aab8 RC |
100 | but available for software use. If a resource |
101 | has bits set in "shareable_bits" but not all | |
102 | of these bits appear in the resource groups' | |
103 | schematas then the bits appearing in | |
104 | "shareable_bits" but no resource group will | |
105 | be marked as "H". | |
1cd7af50 CD |
106 | "X": |
107 | Corresponding region is available for sharing and | |
cba1aab8 RC |
108 | used by hardware and software. These are the |
109 | bits that appear in "shareable_bits" as | |
110 | well as a resource group's allocation. | |
1cd7af50 CD |
111 | "S": |
112 | Corresponding region is used by software | |
cba1aab8 | 113 | and available for sharing. |
1cd7af50 CD |
114 | "E": |
115 | Corresponding region is used exclusively by | |
cba1aab8 | 116 | one resource group. No sharing allowed. |
1cd7af50 CD |
117 | "P": |
118 | Corresponding region is pseudo-locked. No | |
e17e7330 | 119 | sharing allowed. |
0dd2d749 | 120 | |
57794aab | 121 | Memory bandwidth(MB) subdirectory contains the following files |
1640ae94 | 122 | with respect to allocation: |
a9cad3d4 | 123 | |
1cd7af50 CD |
124 | "min_bandwidth": |
125 | The minimum memory bandwidth percentage which | |
126 | user can request. | |
a9cad3d4 | 127 | |
1cd7af50 CD |
128 | "bandwidth_gran": |
129 | The granularity in which the memory bandwidth | |
130 | percentage is allocated. The allocated | |
131 | b/w percentage is rounded off to the next | |
132 | control step available on the hardware. The | |
133 | available bandwidth control steps are: | |
134 | min_bandwidth + N * bandwidth_gran. | |
a9cad3d4 | 135 | |
1cd7af50 CD |
136 | "delay_linear": |
137 | Indicates if the delay scale is linear or | |
138 | non-linear. This field is purely informational | |
139 | only. | |
458b0d6e | 140 | |
1640ae94 VS |
141 | If RDT monitoring is available there will be an "L3_MON" directory |
142 | with the following files: | |
143 | ||
1cd7af50 CD |
144 | "num_rmids": |
145 | The number of RMIDs available. This is the | |
146 | upper bound for how many "CTRL_MON" + "MON" | |
147 | groups can be created. | |
1640ae94 | 148 | |
1cd7af50 CD |
149 | "mon_features": |
150 | Lists the monitoring events if | |
151 | monitoring is enabled for the resource. | |
1640ae94 VS |
152 | |
153 | "max_threshold_occupancy": | |
1cd7af50 CD |
154 | Read/write file provides the largest value (in |
155 | bytes) at which a previously used LLC_occupancy | |
156 | counter can be considered for re-use. | |
1640ae94 | 157 | |
165d3ad8 TL |
158 | Finally, in the top level of the "info" directory there is a file |
159 | named "last_cmd_status". This is reset with every "command" issued | |
160 | via the file system (making new directories or writing to any of the | |
161 | control files). If the command was successful, it will read as "ok". | |
162 | If the command failed, it will provide more information that can be | |
163 | conveyed in the error returns from file operations. E.g. | |
1cd7af50 | 164 | :: |
165d3ad8 TL |
165 | |
166 | # echo L3:0=f7 > schemata | |
167 | bash: echo: write error: Invalid argument | |
168 | # cat info/last_cmd_status | |
169 | mask f7 has non-consecutive 1-bits | |
1640ae94 VS |
170 | |
171 | Resource alloc and monitor groups | |
1cd7af50 | 172 | ================================= |
1640ae94 | 173 | |
f20e5789 | 174 | Resource groups are represented as directories in the resctrl file |
1640ae94 VS |
175 | system. The default group is the root directory which, immediately |
176 | after mounting, owns all the tasks and cpus in the system and can make | |
177 | full use of all resources. | |
178 | ||
179 | On a system with RDT control features additional directories can be | |
180 | created in the root directory that specify different amounts of each | |
181 | resource (see "schemata" below). The root and these additional top level | |
182 | directories are referred to as "CTRL_MON" groups below. | |
183 | ||
184 | On a system with RDT monitoring the root directory and other top level | |
185 | directories contain a directory named "mon_groups" in which additional | |
186 | directories can be created to monitor subsets of tasks in the CTRL_MON | |
187 | group that is their ancestor. These are called "MON" groups in the rest | |
188 | of this document. | |
189 | ||
190 | Removing a directory will move all tasks and cpus owned by the group it | |
191 | represents to the parent. Removing one of the created CTRL_MON groups | |
192 | will automatically remove all MON groups below it. | |
193 | ||
194 | All groups contain the following files: | |
195 | ||
196 | "tasks": | |
197 | Reading this file shows the list of all tasks that belong to | |
198 | this group. Writing a task id to the file will add a task to the | |
199 | group. If the group is a CTRL_MON group the task is removed from | |
200 | whichever previous CTRL_MON group owned the task and also from | |
201 | any MON group that owned the task. If the group is a MON group, | |
202 | then the task must already belong to the CTRL_MON parent of this | |
203 | group. The task is removed from any previous MON group. | |
204 | ||
205 | ||
206 | "cpus": | |
207 | Reading this file shows a bitmask of the logical CPUs owned by | |
208 | this group. Writing a mask to this file will add and remove | |
209 | CPUs to/from this group. As with the tasks file a hierarchy is | |
210 | maintained where MON groups may only include CPUs owned by the | |
211 | parent CTRL_MON group. | |
57794aab | 212 | When the resource group is in pseudo-locked mode this file will |
33dc3e41 RC |
213 | only be readable, reflecting the CPUs associated with the |
214 | pseudo-locked region. | |
1640ae94 VS |
215 | |
216 | ||
217 | "cpus_list": | |
218 | Just like "cpus", only using ranges of CPUs instead of bitmasks. | |
f20e5789 | 219 | |
f20e5789 | 220 | |
1640ae94 | 221 | When control is enabled all CTRL_MON groups will also contain: |
f20e5789 | 222 | |
1640ae94 VS |
223 | "schemata": |
224 | A list of all the resources available to this group. | |
225 | Each resource has its own line and format - see below for details. | |
f20e5789 | 226 | |
cba1aab8 RC |
227 | "size": |
228 | Mirrors the display of the "schemata" file to display the size in | |
229 | bytes of each allocation instead of the bits representing the | |
230 | allocation. | |
231 | ||
232 | "mode": | |
233 | The "mode" of the resource group dictates the sharing of its | |
234 | allocations. A "shareable" resource group allows sharing of its | |
e17e7330 RC |
235 | allocations while an "exclusive" resource group does not. A |
236 | cache pseudo-locked region is created by first writing | |
237 | "pseudo-locksetup" to the "mode" file before writing the cache | |
238 | pseudo-locked region's schemata to the resource group's "schemata" | |
239 | file. On successful pseudo-locked region creation the mode will | |
240 | automatically change to "pseudo-locked". | |
cba1aab8 | 241 | |
1640ae94 | 242 | When monitoring is enabled all MON groups will also contain: |
4ffa3c97 | 243 | |
1640ae94 VS |
244 | "mon_data": |
245 | This contains a set of files organized by L3 domain and by | |
246 | RDT event. E.g. on a system with two L3 domains there will | |
247 | be subdirectories "mon_L3_00" and "mon_L3_01". Each of these | |
248 | directories have one file per event (e.g. "llc_occupancy", | |
249 | "mbm_total_bytes", and "mbm_local_bytes"). In a MON group these | |
250 | files provide a read out of the current value of the event for | |
251 | all tasks in the group. In CTRL_MON groups these files provide | |
252 | the sum for all tasks in the CTRL_MON group and all tasks in | |
253 | MON groups. Please see example section for more details on usage. | |
f20e5789 | 254 | |
1640ae94 VS |
255 | Resource allocation rules |
256 | ------------------------- | |
1cd7af50 | 257 | |
1640ae94 VS |
258 | When a task is running the following rules define which resources are |
259 | available to it: | |
f20e5789 FY |
260 | |
261 | 1) If the task is a member of a non-default group, then the schemata | |
1640ae94 | 262 | for that group is used. |
f20e5789 FY |
263 | |
264 | 2) Else if the task belongs to the default group, but is running on a | |
1640ae94 VS |
265 | CPU that is assigned to some specific group, then the schemata for the |
266 | CPU's group is used. | |
f20e5789 FY |
267 | |
268 | 3) Otherwise the schemata for the default group is used. | |
269 | ||
1640ae94 VS |
270 | Resource monitoring rules |
271 | ------------------------- | |
272 | 1) If a task is a member of a MON group, or non-default CTRL_MON group | |
273 | then RDT events for the task will be reported in that group. | |
274 | ||
275 | 2) If a task is a member of the default CTRL_MON group, but is running | |
276 | on a CPU that is assigned to some specific group, then the RDT events | |
277 | for the task will be reported in that group. | |
278 | ||
279 | 3) Otherwise RDT events for the task will be reported in the root level | |
280 | "mon_data" group. | |
281 | ||
282 | ||
283 | Notes on cache occupancy monitoring and control | |
1cd7af50 | 284 | =============================================== |
1640ae94 VS |
285 | When moving a task from one group to another you should remember that |
286 | this only affects *new* cache allocations by the task. E.g. you may have | |
287 | a task in a monitor group showing 3 MB of cache occupancy. If you move | |
288 | to a new group and immediately check the occupancy of the old and new | |
289 | groups you will likely see that the old group is still showing 3 MB and | |
290 | the new group zero. When the task accesses locations still in cache from | |
291 | before the move, the h/w does not update any counters. On a busy system | |
292 | you will likely see the occupancy in the old group go down as cache lines | |
293 | are evicted and re-used while the occupancy in the new group rises as | |
294 | the task accesses memory and loads into the cache are counted based on | |
295 | membership in the new group. | |
296 | ||
297 | The same applies to cache allocation control. Moving a task to a group | |
298 | with a smaller cache partition will not evict any cache lines. The | |
299 | process may continue to use them from the old partition. | |
300 | ||
301 | Hardware uses CLOSid(Class of service ID) and an RMID(Resource monitoring ID) | |
302 | to identify a control group and a monitoring group respectively. Each of | |
303 | the resource groups are mapped to these IDs based on the kind of group. The | |
304 | number of CLOSid and RMID are limited by the hardware and hence the creation of | |
305 | a "CTRL_MON" directory may fail if we run out of either CLOSID or RMID | |
306 | and creation of "MON" group may fail if we run out of RMIDs. | |
307 | ||
308 | max_threshold_occupancy - generic concepts | |
309 | ------------------------------------------ | |
310 | ||
311 | Note that an RMID once freed may not be immediately available for use as | |
312 | the RMID is still tagged the cache lines of the previous user of RMID. | |
313 | Hence such RMIDs are placed on limbo list and checked back if the cache | |
314 | occupancy has gone down. If there is a time when system has a lot of | |
315 | limbo RMIDs but which are not ready to be used, user may see an -EBUSY | |
316 | during mkdir. | |
317 | ||
318 | max_threshold_occupancy is a user configurable value to determine the | |
319 | occupancy at which an RMID can be freed. | |
f20e5789 FY |
320 | |
321 | Schemata files - general concepts | |
322 | --------------------------------- | |
323 | Each line in the file describes one resource. The line starts with | |
324 | the name of the resource, followed by specific values to be applied | |
325 | in each of the instances of that resource on the system. | |
326 | ||
327 | Cache IDs | |
328 | --------- | |
329 | On current generation systems there is one L3 cache per socket and L2 | |
330 | caches are generally just shared by the hyperthreads on a core, but this | |
331 | isn't an architectural requirement. We could have multiple separate L3 | |
332 | caches on a socket, multiple cores could share an L2 cache. So instead | |
333 | of using "socket" or "core" to define the set of logical cpus sharing | |
334 | a resource we use a "Cache ID". At a given cache level this will be a | |
335 | unique number across the whole system (but it isn't guaranteed to be a | |
336 | contiguous sequence, there may be gaps). To find the ID for each logical | |
337 | CPU look in /sys/devices/system/cpu/cpu*/cache/index*/id | |
338 | ||
339 | Cache Bit Masks (CBM) | |
340 | --------------------- | |
341 | For cache resources we describe the portion of the cache that is available | |
342 | for allocation using a bitmask. The maximum value of the mask is defined | |
343 | by each cpu model (and may be different for different cache levels). It | |
344 | is found using CPUID, but is also provided in the "info" directory of | |
eb8ed28f | 345 | the resctrl file system in "info/{resource}/cbm_mask". Intel hardware |
f20e5789 FY |
346 | requires that these masks have all the '1' bits in a contiguous block. So |
347 | 0x3, 0x6 and 0xC are legal 4-bit masks with two bits set, but 0x5, 0x9 | |
348 | and 0xA are not. On a system with a 20-bit mask each bit represents 5% | |
349 | of the capacity of the cache. You could partition the cache into four | |
350 | equal parts with masks: 0x1f, 0x3e0, 0x7c00, 0xf8000. | |
351 | ||
d6c64a4f | 352 | Memory bandwidth Allocation and monitoring |
1cd7af50 | 353 | ========================================== |
d6c64a4f VS |
354 | |
355 | For Memory bandwidth resource, by default the user controls the resource | |
356 | by indicating the percentage of total memory bandwidth. | |
a9cad3d4 VS |
357 | |
358 | The minimum bandwidth percentage value for each cpu model is predefined | |
359 | and can be looked up through "info/MB/min_bandwidth". The bandwidth | |
360 | granularity that is allocated is also dependent on the cpu model and can | |
361 | be looked up at "info/MB/bandwidth_gran". The available bandwidth | |
362 | control steps are: min_bw + N * bw_gran. Intermediate values are rounded | |
363 | to the next control step available on the hardware. | |
364 | ||
365 | The bandwidth throttling is a core specific mechanism on some of Intel | |
366 | SKUs. Using a high bandwidth and a low bandwidth setting on two threads | |
367 | sharing a core will result in both threads being throttled to use the | |
d6c64a4f VS |
368 | low bandwidth. The fact that Memory bandwidth allocation(MBA) is a core |
369 | specific mechanism where as memory bandwidth monitoring(MBM) is done at | |
370 | the package level may lead to confusion when users try to apply control | |
371 | via the MBA and then monitor the bandwidth to see if the controls are | |
372 | effective. Below are such scenarios: | |
373 | ||
374 | 1. User may *not* see increase in actual bandwidth when percentage | |
375 | values are increased: | |
376 | ||
377 | This can occur when aggregate L2 external bandwidth is more than L3 | |
378 | external bandwidth. Consider an SKL SKU with 24 cores on a package and | |
379 | where L2 external is 10GBps (hence aggregate L2 external bandwidth is | |
380 | 240GBps) and L3 external bandwidth is 100GBps. Now a workload with '20 | |
381 | threads, having 50% bandwidth, each consuming 5GBps' consumes the max L3 | |
382 | bandwidth of 100GBps although the percentage value specified is only 50% | |
57794aab | 383 | << 100%. Hence increasing the bandwidth percentage will not yield any |
d6c64a4f VS |
384 | more bandwidth. This is because although the L2 external bandwidth still |
385 | has capacity, the L3 external bandwidth is fully used. Also note that | |
386 | this would be dependent on number of cores the benchmark is run on. | |
387 | ||
388 | 2. Same bandwidth percentage may mean different actual bandwidth | |
389 | depending on # of threads: | |
390 | ||
391 | For the same SKU in #1, a 'single thread, with 10% bandwidth' and '4 | |
392 | thread, with 10% bandwidth' can consume upto 10GBps and 40GBps although | |
393 | they have same percentage bandwidth of 10%. This is simply because as | |
394 | threads start using more cores in an rdtgroup, the actual bandwidth may | |
395 | increase or vary although user specified bandwidth percentage is same. | |
396 | ||
397 | In order to mitigate this and make the interface more user friendly, | |
398 | resctrl added support for specifying the bandwidth in MBps as well. The | |
399 | kernel underneath would use a software feedback mechanism or a "Software | |
400 | Controller(mba_sc)" which reads the actual bandwidth using MBM counters | |
57794aab | 401 | and adjust the memory bandwidth percentages to ensure:: |
d6c64a4f VS |
402 | |
403 | "actual bandwidth < user specified bandwidth". | |
404 | ||
405 | By default, the schemata would take the bandwidth percentage values | |
406 | where as user can switch to the "MBA software controller" mode using | |
407 | a mount option 'mba_MBps'. The schemata format is specified in the below | |
408 | sections. | |
f20e5789 | 409 | |
1640ae94 VS |
410 | L3 schemata file details (code and data prioritization disabled) |
411 | ---------------------------------------------------------------- | |
1cd7af50 | 412 | With CDP disabled the L3 schemata format is:: |
f20e5789 FY |
413 | |
414 | L3:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... | |
415 | ||
1640ae94 VS |
416 | L3 schemata file details (CDP enabled via mount option to resctrl) |
417 | ------------------------------------------------------------------ | |
f20e5789 | 418 | When CDP is enabled L3 control is split into two separate resources |
1cd7af50 | 419 | so you can specify independent masks for code and data like this:: |
f20e5789 | 420 | |
7c7a4995 JM |
421 | L3DATA:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... |
422 | L3CODE:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... | |
f20e5789 | 423 | |
1640ae94 VS |
424 | L2 schemata file details |
425 | ------------------------ | |
7c7a4995 JM |
426 | CDP is supported at L2 using the 'cdpl2' mount option. The schemata |
427 | format is either:: | |
f20e5789 FY |
428 | |
429 | L2:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... | |
430 | ||
7c7a4995 JM |
431 | or |
432 | ||
433 | L2DATA:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... | |
434 | L2CODE:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... | |
435 | ||
436 | ||
d6c64a4f VS |
437 | Memory bandwidth Allocation (default mode) |
438 | ------------------------------------------ | |
a9cad3d4 VS |
439 | |
440 | Memory b/w domain is L3 cache. | |
1cd7af50 | 441 | :: |
a9cad3d4 VS |
442 | |
443 | MB:<cache_id0>=bandwidth0;<cache_id1>=bandwidth1;... | |
444 | ||
d6c64a4f VS |
445 | Memory bandwidth Allocation specified in MBps |
446 | --------------------------------------------- | |
447 | ||
448 | Memory bandwidth domain is L3 cache. | |
1cd7af50 | 449 | :: |
d6c64a4f VS |
450 | |
451 | MB:<cache_id0>=bw_MBps0;<cache_id1>=bw_MBps1;... | |
452 | ||
c4026b7b TL |
453 | Reading/writing the schemata file |
454 | --------------------------------- | |
455 | Reading the schemata file will show the state of all resources | |
456 | on all domains. When writing you only need to specify those values | |
457 | which you wish to change. E.g. | |
1cd7af50 | 458 | :: |
c4026b7b | 459 | |
1cd7af50 CD |
460 | # cat schemata |
461 | L3DATA:0=fffff;1=fffff;2=fffff;3=fffff | |
462 | L3CODE:0=fffff;1=fffff;2=fffff;3=fffff | |
463 | # echo "L3DATA:2=3c0;" > schemata | |
464 | # cat schemata | |
465 | L3DATA:0=fffff;1=fffff;2=3c0;3=fffff | |
466 | L3CODE:0=fffff;1=fffff;2=fffff;3=fffff | |
c4026b7b | 467 | |
e17e7330 | 468 | Cache Pseudo-Locking |
1cd7af50 | 469 | ==================== |
e17e7330 RC |
470 | CAT enables a user to specify the amount of cache space that an |
471 | application can fill. Cache pseudo-locking builds on the fact that a | |
472 | CPU can still read and write data pre-allocated outside its current | |
473 | allocated area on a cache hit. With cache pseudo-locking, data can be | |
474 | preloaded into a reserved portion of cache that no application can | |
475 | fill, and from that point on will only serve cache hits. The cache | |
476 | pseudo-locked memory is made accessible to user space where an | |
477 | application can map it into its virtual address space and thus have | |
478 | a region of memory with reduced average read latency. | |
479 | ||
480 | The creation of a cache pseudo-locked region is triggered by a request | |
481 | from the user to do so that is accompanied by a schemata of the region | |
482 | to be pseudo-locked. The cache pseudo-locked region is created as follows: | |
1cd7af50 | 483 | |
e17e7330 RC |
484 | - Create a CAT allocation CLOSNEW with a CBM matching the schemata |
485 | from the user of the cache region that will contain the pseudo-locked | |
486 | memory. This region must not overlap with any current CAT allocation/CLOS | |
487 | on the system and no future overlap with this cache region is allowed | |
488 | while the pseudo-locked region exists. | |
489 | - Create a contiguous region of memory of the same size as the cache | |
490 | region. | |
491 | - Flush the cache, disable hardware prefetchers, disable preemption. | |
492 | - Make CLOSNEW the active CLOS and touch the allocated memory to load | |
493 | it into the cache. | |
494 | - Set the previous CLOS as active. | |
495 | - At this point the closid CLOSNEW can be released - the cache | |
496 | pseudo-locked region is protected as long as its CBM does not appear in | |
497 | any CAT allocation. Even though the cache pseudo-locked region will from | |
498 | this point on not appear in any CBM of any CLOS an application running with | |
499 | any CLOS will be able to access the memory in the pseudo-locked region since | |
500 | the region continues to serve cache hits. | |
501 | - The contiguous region of memory loaded into the cache is exposed to | |
502 | user-space as a character device. | |
503 | ||
504 | Cache pseudo-locking increases the probability that data will remain | |
505 | in the cache via carefully configuring the CAT feature and controlling | |
506 | application behavior. There is no guarantee that data is placed in | |
507 | cache. Instructions like INVD, WBINVD, CLFLUSH, etc. can still evict | |
508 | “locked” data from cache. Power management C-states may shrink or | |
6fc0de37 RC |
509 | power off cache. Deeper C-states will automatically be restricted on |
510 | pseudo-locked region creation. | |
e17e7330 RC |
511 | |
512 | It is required that an application using a pseudo-locked region runs | |
513 | with affinity to the cores (or a subset of the cores) associated | |
514 | with the cache on which the pseudo-locked region resides. A sanity check | |
515 | within the code will not allow an application to map pseudo-locked memory | |
516 | unless it runs with affinity to cores associated with the cache on which the | |
517 | pseudo-locked region resides. The sanity check is only done during the | |
518 | initial mmap() handling, there is no enforcement afterwards and the | |
519 | application self needs to ensure it remains affine to the correct cores. | |
520 | ||
521 | Pseudo-locking is accomplished in two stages: | |
1cd7af50 | 522 | |
e17e7330 RC |
523 | 1) During the first stage the system administrator allocates a portion |
524 | of cache that should be dedicated to pseudo-locking. At this time an | |
525 | equivalent portion of memory is allocated, loaded into allocated | |
526 | cache portion, and exposed as a character device. | |
527 | 2) During the second stage a user-space application maps (mmap()) the | |
528 | pseudo-locked memory into its address space. | |
529 | ||
530 | Cache Pseudo-Locking Interface | |
531 | ------------------------------ | |
532 | A pseudo-locked region is created using the resctrl interface as follows: | |
533 | ||
534 | 1) Create a new resource group by creating a new directory in /sys/fs/resctrl. | |
535 | 2) Change the new resource group's mode to "pseudo-locksetup" by writing | |
536 | "pseudo-locksetup" to the "mode" file. | |
537 | 3) Write the schemata of the pseudo-locked region to the "schemata" file. All | |
538 | bits within the schemata should be "unused" according to the "bit_usage" | |
539 | file. | |
540 | ||
541 | On successful pseudo-locked region creation the "mode" file will contain | |
542 | "pseudo-locked" and a new character device with the same name as the resource | |
543 | group will exist in /dev/pseudo_lock. This character device can be mmap()'ed | |
544 | by user space in order to obtain access to the pseudo-locked memory region. | |
545 | ||
546 | An example of cache pseudo-locked region creation and usage can be found below. | |
547 | ||
548 | Cache Pseudo-Locking Debugging Interface | |
1cd7af50 | 549 | ---------------------------------------- |
e17e7330 RC |
550 | The pseudo-locking debugging interface is enabled by default (if |
551 | CONFIG_DEBUG_FS is enabled) and can be found in /sys/kernel/debug/resctrl. | |
552 | ||
553 | There is no explicit way for the kernel to test if a provided memory | |
554 | location is present in the cache. The pseudo-locking debugging interface uses | |
555 | the tracing infrastructure to provide two ways to measure cache residency of | |
556 | the pseudo-locked region: | |
1cd7af50 | 557 | |
e17e7330 RC |
558 | 1) Memory access latency using the pseudo_lock_mem_latency tracepoint. Data |
559 | from these measurements are best visualized using a hist trigger (see | |
560 | example below). In this test the pseudo-locked region is traversed at | |
561 | a stride of 32 bytes while hardware prefetchers and preemption | |
562 | are disabled. This also provides a substitute visualization of cache | |
563 | hits and misses. | |
564 | 2) Cache hit and miss measurements using model specific precision counters if | |
565 | available. Depending on the levels of cache on the system the pseudo_lock_l2 | |
566 | and pseudo_lock_l3 tracepoints are available. | |
e17e7330 RC |
567 | |
568 | When a pseudo-locked region is created a new debugfs directory is created for | |
569 | it in debugfs as /sys/kernel/debug/resctrl/<newdir>. A single | |
570 | write-only file, pseudo_lock_measure, is present in this directory. The | |
dd45407c RC |
571 | measurement of the pseudo-locked region depends on the number written to this |
572 | debugfs file: | |
1cd7af50 CD |
573 | |
574 | 1: | |
575 | writing "1" to the pseudo_lock_measure file will trigger the latency | |
dd45407c RC |
576 | measurement captured in the pseudo_lock_mem_latency tracepoint. See |
577 | example below. | |
1cd7af50 CD |
578 | 2: |
579 | writing "2" to the pseudo_lock_measure file will trigger the L2 cache | |
dd45407c RC |
580 | residency (cache hits and misses) measurement captured in the |
581 | pseudo_lock_l2 tracepoint. See example below. | |
1cd7af50 CD |
582 | 3: |
583 | writing "3" to the pseudo_lock_measure file will trigger the L3 cache | |
dd45407c RC |
584 | residency (cache hits and misses) measurement captured in the |
585 | pseudo_lock_l3 tracepoint. | |
586 | ||
587 | All measurements are recorded with the tracing infrastructure. This requires | |
588 | the relevant tracepoints to be enabled before the measurement is triggered. | |
e17e7330 | 589 | |
1cd7af50 CD |
590 | Example of latency debugging interface |
591 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
e17e7330 RC |
592 | In this example a pseudo-locked region named "newlock" was created. Here is |
593 | how we can measure the latency in cycles of reading from this region and | |
594 | visualize this data with a histogram that is available if CONFIG_HIST_TRIGGERS | |
1cd7af50 CD |
595 | is set:: |
596 | ||
597 | # :> /sys/kernel/debug/tracing/trace | |
598 | # echo 'hist:keys=latency' > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/trigger | |
599 | # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable | |
600 | # echo 1 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure | |
601 | # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable | |
602 | # cat /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/hist | |
603 | ||
604 | # event histogram | |
605 | # | |
606 | # trigger info: hist:keys=latency:vals=hitcount:sort=hitcount:size=2048 [active] | |
607 | # | |
608 | ||
609 | { latency: 456 } hitcount: 1 | |
610 | { latency: 50 } hitcount: 83 | |
611 | { latency: 36 } hitcount: 96 | |
612 | { latency: 44 } hitcount: 174 | |
613 | { latency: 48 } hitcount: 195 | |
614 | { latency: 46 } hitcount: 262 | |
615 | { latency: 42 } hitcount: 693 | |
616 | { latency: 40 } hitcount: 3204 | |
617 | { latency: 38 } hitcount: 3484 | |
618 | ||
619 | Totals: | |
620 | Hits: 8192 | |
621 | Entries: 9 | |
622 | Dropped: 0 | |
623 | ||
624 | Example of cache hits/misses debugging | |
625 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
e17e7330 RC |
626 | In this example a pseudo-locked region named "newlock" was created on the L2 |
627 | cache of a platform. Here is how we can obtain details of the cache hits | |
628 | and misses using the platform's precision counters. | |
1cd7af50 | 629 | :: |
e17e7330 | 630 | |
1cd7af50 CD |
631 | # :> /sys/kernel/debug/tracing/trace |
632 | # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable | |
633 | # echo 2 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure | |
634 | # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable | |
635 | # cat /sys/kernel/debug/tracing/trace | |
e17e7330 | 636 | |
1cd7af50 CD |
637 | # tracer: nop |
638 | # | |
639 | # _-----=> irqs-off | |
640 | # / _----=> need-resched | |
641 | # | / _---=> hardirq/softirq | |
642 | # || / _--=> preempt-depth | |
643 | # ||| / delay | |
644 | # TASK-PID CPU# |||| TIMESTAMP FUNCTION | |
645 | # | | | |||| | | | |
646 | pseudo_lock_mea-1672 [002] .... 3132.860500: pseudo_lock_l2: hits=4097 miss=0 | |
e17e7330 RC |
647 | |
648 | ||
1cd7af50 CD |
649 | Examples for RDT allocation usage |
650 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
651 | ||
652 | 1) Example 1 | |
1640ae94 | 653 | |
f20e5789 | 654 | On a two socket machine (one L3 cache per socket) with just four bits |
a9cad3d4 | 655 | for cache bit masks, minimum b/w of 10% with a memory bandwidth |
1cd7af50 CD |
656 | granularity of 10%. |
657 | :: | |
f20e5789 | 658 | |
1cd7af50 CD |
659 | # mount -t resctrl resctrl /sys/fs/resctrl |
660 | # cd /sys/fs/resctrl | |
661 | # mkdir p0 p1 | |
662 | # echo "L3:0=3;1=c\nMB:0=50;1=50" > /sys/fs/resctrl/p0/schemata | |
663 | # echo "L3:0=3;1=3\nMB:0=50;1=50" > /sys/fs/resctrl/p1/schemata | |
f20e5789 FY |
664 | |
665 | The default resource group is unmodified, so we have access to all parts | |
666 | of all caches (its schemata file reads "L3:0=f;1=f"). | |
667 | ||
668 | Tasks that are under the control of group "p0" may only allocate from the | |
669 | "lower" 50% on cache ID 0, and the "upper" 50% of cache ID 1. | |
670 | Tasks in group "p1" use the "lower" 50% of cache on both sockets. | |
671 | ||
a9cad3d4 VS |
672 | Similarly, tasks that are under the control of group "p0" may use a |
673 | maximum memory b/w of 50% on socket0 and 50% on socket 1. | |
674 | Tasks in group "p1" may also use 50% memory b/w on both sockets. | |
675 | Note that unlike cache masks, memory b/w cannot specify whether these | |
676 | allocations can overlap or not. The allocations specifies the maximum | |
677 | b/w that the group may be able to use and the system admin can configure | |
678 | the b/w accordingly. | |
679 | ||
b5453a8e JM |
680 | If resctrl is using the software controller (mba_sc) then user can enter the |
681 | max b/w in MB rather than the percentage values. | |
1cd7af50 | 682 | :: |
d6c64a4f | 683 | |
1cd7af50 CD |
684 | # echo "L3:0=3;1=c\nMB:0=1024;1=500" > /sys/fs/resctrl/p0/schemata |
685 | # echo "L3:0=3;1=3\nMB:0=1024;1=500" > /sys/fs/resctrl/p1/schemata | |
d6c64a4f VS |
686 | |
687 | In the above example the tasks in "p1" and "p0" on socket 0 would use a max b/w | |
688 | of 1024MB where as on socket 1 they would use 500MB. | |
689 | ||
1cd7af50 CD |
690 | 2) Example 2 |
691 | ||
f20e5789 FY |
692 | Again two sockets, but this time with a more realistic 20-bit mask. |
693 | ||
694 | Two real time tasks pid=1234 running on processor 0 and pid=5678 running on | |
695 | processor 1 on socket 0 on a 2-socket and dual core machine. To avoid noisy | |
696 | neighbors, each of the two real-time tasks exclusively occupies one quarter | |
697 | of L3 cache on socket 0. | |
1cd7af50 | 698 | :: |
f20e5789 | 699 | |
1cd7af50 CD |
700 | # mount -t resctrl resctrl /sys/fs/resctrl |
701 | # cd /sys/fs/resctrl | |
f20e5789 FY |
702 | |
703 | First we reset the schemata for the default group so that the "upper" | |
a9cad3d4 | 704 | 50% of the L3 cache on socket 0 and 50% of memory b/w cannot be used by |
1cd7af50 | 705 | ordinary tasks:: |
f20e5789 | 706 | |
1cd7af50 | 707 | # echo "L3:0=3ff;1=fffff\nMB:0=50;1=100" > schemata |
f20e5789 FY |
708 | |
709 | Next we make a resource group for our first real time task and give | |
710 | it access to the "top" 25% of the cache on socket 0. | |
1cd7af50 | 711 | :: |
f20e5789 | 712 | |
1cd7af50 CD |
713 | # mkdir p0 |
714 | # echo "L3:0=f8000;1=fffff" > p0/schemata | |
f20e5789 FY |
715 | |
716 | Finally we move our first real time task into this resource group. We | |
717 | also use taskset(1) to ensure the task always runs on a dedicated CPU | |
718 | on socket 0. Most uses of resource groups will also constrain which | |
719 | processors tasks run on. | |
1cd7af50 | 720 | :: |
f20e5789 | 721 | |
1cd7af50 CD |
722 | # echo 1234 > p0/tasks |
723 | # taskset -cp 1 1234 | |
f20e5789 | 724 | |
1cd7af50 | 725 | Ditto for the second real time task (with the remaining 25% of cache):: |
f20e5789 | 726 | |
1cd7af50 CD |
727 | # mkdir p1 |
728 | # echo "L3:0=7c00;1=fffff" > p1/schemata | |
729 | # echo 5678 > p1/tasks | |
730 | # taskset -cp 2 5678 | |
f20e5789 | 731 | |
a9cad3d4 VS |
732 | For the same 2 socket system with memory b/w resource and CAT L3 the |
733 | schemata would look like(Assume min_bandwidth 10 and bandwidth_gran is | |
734 | 10): | |
735 | ||
1cd7af50 CD |
736 | For our first real time task this would request 20% memory b/w on socket 0. |
737 | :: | |
a9cad3d4 | 738 | |
1cd7af50 | 739 | # echo -e "L3:0=f8000;1=fffff\nMB:0=20;1=100" > p0/schemata |
a9cad3d4 VS |
740 | |
741 | For our second real time task this would request an other 20% memory b/w | |
742 | on socket 0. | |
1cd7af50 | 743 | :: |
a9cad3d4 | 744 | |
1cd7af50 | 745 | # echo -e "L3:0=f8000;1=fffff\nMB:0=20;1=100" > p0/schemata |
a9cad3d4 | 746 | |
1cd7af50 | 747 | 3) Example 3 |
f20e5789 FY |
748 | |
749 | A single socket system which has real-time tasks running on core 4-7 and | |
750 | non real-time workload assigned to core 0-3. The real-time tasks share text | |
751 | and data, so a per task association is not required and due to interaction | |
752 | with the kernel it's desired that the kernel on these cores shares L3 with | |
753 | the tasks. | |
1cd7af50 | 754 | :: |
f20e5789 | 755 | |
1cd7af50 CD |
756 | # mount -t resctrl resctrl /sys/fs/resctrl |
757 | # cd /sys/fs/resctrl | |
f20e5789 FY |
758 | |
759 | First we reset the schemata for the default group so that the "upper" | |
a9cad3d4 | 760 | 50% of the L3 cache on socket 0, and 50% of memory bandwidth on socket 0 |
1cd7af50 | 761 | cannot be used by ordinary tasks:: |
f20e5789 | 762 | |
1cd7af50 | 763 | # echo "L3:0=3ff\nMB:0=50" > schemata |
f20e5789 | 764 | |
a9cad3d4 VS |
765 | Next we make a resource group for our real time cores and give it access |
766 | to the "top" 50% of the cache on socket 0 and 50% of memory bandwidth on | |
767 | socket 0. | |
1cd7af50 | 768 | :: |
f20e5789 | 769 | |
1cd7af50 CD |
770 | # mkdir p0 |
771 | # echo "L3:0=ffc00\nMB:0=50" > p0/schemata | |
f20e5789 FY |
772 | |
773 | Finally we move core 4-7 over to the new group and make sure that the | |
a9cad3d4 VS |
774 | kernel and the tasks running there get 50% of the cache. They should |
775 | also get 50% of memory bandwidth assuming that the cores 4-7 are SMT | |
776 | siblings and only the real time threads are scheduled on the cores 4-7. | |
1cd7af50 | 777 | :: |
f20e5789 | 778 | |
1cd7af50 | 779 | # echo F0 > p0/cpus |
3c2a769d | 780 | |
1cd7af50 | 781 | 4) Example 4 |
cba1aab8 RC |
782 | |
783 | The resource groups in previous examples were all in the default "shareable" | |
784 | mode allowing sharing of their cache allocations. If one resource group | |
785 | configures a cache allocation then nothing prevents another resource group | |
786 | to overlap with that allocation. | |
787 | ||
788 | In this example a new exclusive resource group will be created on a L2 CAT | |
789 | system with two L2 cache instances that can be configured with an 8-bit | |
790 | capacity bitmask. The new exclusive resource group will be configured to use | |
791 | 25% of each cache instance. | |
1cd7af50 | 792 | :: |
cba1aab8 | 793 | |
1cd7af50 CD |
794 | # mount -t resctrl resctrl /sys/fs/resctrl/ |
795 | # cd /sys/fs/resctrl | |
cba1aab8 RC |
796 | |
797 | First, we observe that the default group is configured to allocate to all L2 | |
1cd7af50 | 798 | cache:: |
cba1aab8 | 799 | |
1cd7af50 CD |
800 | # cat schemata |
801 | L2:0=ff;1=ff | |
cba1aab8 RC |
802 | |
803 | We could attempt to create the new resource group at this point, but it will | |
1cd7af50 CD |
804 | fail because of the overlap with the schemata of the default group:: |
805 | ||
806 | # mkdir p0 | |
807 | # echo 'L2:0=0x3;1=0x3' > p0/schemata | |
808 | # cat p0/mode | |
809 | shareable | |
810 | # echo exclusive > p0/mode | |
811 | -sh: echo: write error: Invalid argument | |
812 | # cat info/last_cmd_status | |
813 | schemata overlaps | |
cba1aab8 RC |
814 | |
815 | To ensure that there is no overlap with another resource group the default | |
816 | resource group's schemata has to change, making it possible for the new | |
817 | resource group to become exclusive. | |
1cd7af50 CD |
818 | :: |
819 | ||
820 | # echo 'L2:0=0xfc;1=0xfc' > schemata | |
821 | # echo exclusive > p0/mode | |
822 | # grep . p0/* | |
823 | p0/cpus:0 | |
824 | p0/mode:exclusive | |
825 | p0/schemata:L2:0=03;1=03 | |
826 | p0/size:L2:0=262144;1=262144 | |
cba1aab8 RC |
827 | |
828 | A new resource group will on creation not overlap with an exclusive resource | |
1cd7af50 CD |
829 | group:: |
830 | ||
831 | # mkdir p1 | |
832 | # grep . p1/* | |
833 | p1/cpus:0 | |
834 | p1/mode:shareable | |
835 | p1/schemata:L2:0=fc;1=fc | |
836 | p1/size:L2:0=786432;1=786432 | |
837 | ||
838 | The bit_usage will reflect how the cache is used:: | |
839 | ||
840 | # cat info/L2/bit_usage | |
841 | 0=SSSSSSEE;1=SSSSSSEE | |
842 | ||
843 | A resource group cannot be forced to overlap with an exclusive resource group:: | |
844 | ||
845 | # echo 'L2:0=0x1;1=0x1' > p1/schemata | |
846 | -sh: echo: write error: Invalid argument | |
847 | # cat info/last_cmd_status | |
848 | overlaps with exclusive group | |
cba1aab8 | 849 | |
e17e7330 | 850 | Example of Cache Pseudo-Locking |
1cd7af50 | 851 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
e17e7330 RC |
852 | Lock portion of L2 cache from cache id 1 using CBM 0x3. Pseudo-locked |
853 | region is exposed at /dev/pseudo_lock/newlock that can be provided to | |
854 | application for argument to mmap(). | |
1cd7af50 | 855 | :: |
e17e7330 | 856 | |
1cd7af50 CD |
857 | # mount -t resctrl resctrl /sys/fs/resctrl/ |
858 | # cd /sys/fs/resctrl | |
e17e7330 RC |
859 | |
860 | Ensure that there are bits available that can be pseudo-locked, since only | |
861 | unused bits can be pseudo-locked the bits to be pseudo-locked needs to be | |
1cd7af50 CD |
862 | removed from the default resource group's schemata:: |
863 | ||
864 | # cat info/L2/bit_usage | |
865 | 0=SSSSSSSS;1=SSSSSSSS | |
866 | # echo 'L2:1=0xfc' > schemata | |
867 | # cat info/L2/bit_usage | |
868 | 0=SSSSSSSS;1=SSSSSS00 | |
e17e7330 RC |
869 | |
870 | Create a new resource group that will be associated with the pseudo-locked | |
871 | region, indicate that it will be used for a pseudo-locked region, and | |
1cd7af50 | 872 | configure the requested pseudo-locked region capacity bitmask:: |
e17e7330 | 873 | |
1cd7af50 CD |
874 | # mkdir newlock |
875 | # echo pseudo-locksetup > newlock/mode | |
876 | # echo 'L2:1=0x3' > newlock/schemata | |
e17e7330 RC |
877 | |
878 | On success the resource group's mode will change to pseudo-locked, the | |
879 | bit_usage will reflect the pseudo-locked region, and the character device | |
1cd7af50 CD |
880 | exposing the pseudo-locked region will exist:: |
881 | ||
882 | # cat newlock/mode | |
883 | pseudo-locked | |
884 | # cat info/L2/bit_usage | |
885 | 0=SSSSSSSS;1=SSSSSSPP | |
886 | # ls -l /dev/pseudo_lock/newlock | |
887 | crw------- 1 root root 243, 0 Apr 3 05:01 /dev/pseudo_lock/newlock | |
888 | ||
889 | :: | |
890 | ||
891 | /* | |
892 | * Example code to access one page of pseudo-locked cache region | |
893 | * from user space. | |
894 | */ | |
895 | #define _GNU_SOURCE | |
896 | #include <fcntl.h> | |
897 | #include <sched.h> | |
898 | #include <stdio.h> | |
899 | #include <stdlib.h> | |
900 | #include <unistd.h> | |
901 | #include <sys/mman.h> | |
902 | ||
903 | /* | |
904 | * It is required that the application runs with affinity to only | |
905 | * cores associated with the pseudo-locked region. Here the cpu | |
906 | * is hardcoded for convenience of example. | |
907 | */ | |
908 | static int cpuid = 2; | |
909 | ||
910 | int main(int argc, char *argv[]) | |
911 | { | |
912 | cpu_set_t cpuset; | |
913 | long page_size; | |
914 | void *mapping; | |
915 | int dev_fd; | |
916 | int ret; | |
917 | ||
918 | page_size = sysconf(_SC_PAGESIZE); | |
919 | ||
920 | CPU_ZERO(&cpuset); | |
921 | CPU_SET(cpuid, &cpuset); | |
922 | ret = sched_setaffinity(0, sizeof(cpuset), &cpuset); | |
923 | if (ret < 0) { | |
924 | perror("sched_setaffinity"); | |
925 | exit(EXIT_FAILURE); | |
926 | } | |
927 | ||
928 | dev_fd = open("/dev/pseudo_lock/newlock", O_RDWR); | |
929 | if (dev_fd < 0) { | |
930 | perror("open"); | |
931 | exit(EXIT_FAILURE); | |
932 | } | |
933 | ||
934 | mapping = mmap(0, page_size, PROT_READ | PROT_WRITE, MAP_SHARED, | |
935 | dev_fd, 0); | |
936 | if (mapping == MAP_FAILED) { | |
937 | perror("mmap"); | |
938 | close(dev_fd); | |
939 | exit(EXIT_FAILURE); | |
940 | } | |
941 | ||
942 | /* Application interacts with pseudo-locked memory @mapping */ | |
943 | ||
944 | ret = munmap(mapping, page_size); | |
945 | if (ret < 0) { | |
946 | perror("munmap"); | |
947 | close(dev_fd); | |
948 | exit(EXIT_FAILURE); | |
949 | } | |
950 | ||
951 | close(dev_fd); | |
952 | exit(EXIT_SUCCESS); | |
953 | } | |
e17e7330 | 954 | |
cba1aab8 RC |
955 | Locking between applications |
956 | ---------------------------- | |
3c2a769d MT |
957 | |
958 | Certain operations on the resctrl filesystem, composed of read/writes | |
959 | to/from multiple files, must be atomic. | |
960 | ||
961 | As an example, the allocation of an exclusive reservation of L3 cache | |
962 | involves: | |
963 | ||
cba1aab8 | 964 | 1. Read the cbmmasks from each directory or the per-resource "bit_usage" |
3c2a769d MT |
965 | 2. Find a contiguous set of bits in the global CBM bitmask that is clear |
966 | in any of the directory cbmmasks | |
967 | 3. Create a new directory | |
968 | 4. Set the bits found in step 2 to the new directory "schemata" file | |
969 | ||
970 | If two applications attempt to allocate space concurrently then they can | |
971 | end up allocating the same bits so the reservations are shared instead of | |
972 | exclusive. | |
973 | ||
974 | To coordinate atomic operations on the resctrlfs and to avoid the problem | |
975 | above, the following locking procedure is recommended: | |
976 | ||
977 | Locking is based on flock, which is available in libc and also as a shell | |
978 | script command | |
979 | ||
980 | Write lock: | |
981 | ||
982 | A) Take flock(LOCK_EX) on /sys/fs/resctrl | |
983 | B) Read/write the directory structure. | |
984 | C) funlock | |
985 | ||
986 | Read lock: | |
987 | ||
988 | A) Take flock(LOCK_SH) on /sys/fs/resctrl | |
989 | B) If success read the directory structure. | |
990 | C) funlock | |
991 | ||
1cd7af50 CD |
992 | Example with bash:: |
993 | ||
994 | # Atomically read directory structure | |
995 | $ flock -s /sys/fs/resctrl/ find /sys/fs/resctrl | |
996 | ||
997 | # Read directory contents and create new subdirectory | |
998 | ||
999 | $ cat create-dir.sh | |
1000 | find /sys/fs/resctrl/ > output.txt | |
1001 | mask = function-of(output.txt) | |
1002 | mkdir /sys/fs/resctrl/newres/ | |
1003 | echo mask > /sys/fs/resctrl/newres/schemata | |
1004 | ||
1005 | $ flock /sys/fs/resctrl/ ./create-dir.sh | |
1006 | ||
1007 | Example with C:: | |
1008 | ||
1009 | /* | |
1010 | * Example code do take advisory locks | |
1011 | * before accessing resctrl filesystem | |
1012 | */ | |
1013 | #include <sys/file.h> | |
1014 | #include <stdlib.h> | |
1015 | ||
1016 | void resctrl_take_shared_lock(int fd) | |
1017 | { | |
1018 | int ret; | |
1019 | ||
1020 | /* take shared lock on resctrl filesystem */ | |
1021 | ret = flock(fd, LOCK_SH); | |
1022 | if (ret) { | |
1023 | perror("flock"); | |
1024 | exit(-1); | |
1025 | } | |
1026 | } | |
1027 | ||
1028 | void resctrl_take_exclusive_lock(int fd) | |
1029 | { | |
1030 | int ret; | |
1031 | ||
1032 | /* release lock on resctrl filesystem */ | |
1033 | ret = flock(fd, LOCK_EX); | |
1034 | if (ret) { | |
1035 | perror("flock"); | |
1036 | exit(-1); | |
1037 | } | |
1038 | } | |
1039 | ||
1040 | void resctrl_release_lock(int fd) | |
1041 | { | |
1042 | int ret; | |
1043 | ||
1044 | /* take shared lock on resctrl filesystem */ | |
1045 | ret = flock(fd, LOCK_UN); | |
1046 | if (ret) { | |
1047 | perror("flock"); | |
1048 | exit(-1); | |
1049 | } | |
1050 | } | |
1051 | ||
1052 | void main(void) | |
1053 | { | |
1054 | int fd, ret; | |
1055 | ||
1056 | fd = open("/sys/fs/resctrl", O_DIRECTORY); | |
1057 | if (fd == -1) { | |
1058 | perror("open"); | |
1059 | exit(-1); | |
1060 | } | |
1061 | resctrl_take_shared_lock(fd); | |
1062 | /* code to read directory contents */ | |
1063 | resctrl_release_lock(fd); | |
1064 | ||
1065 | resctrl_take_exclusive_lock(fd); | |
1066 | /* code to read and write directory contents */ | |
1067 | resctrl_release_lock(fd); | |
1068 | } | |
1069 | ||
1070 | Examples for RDT Monitoring along with allocation usage | |
1071 | ======================================================= | |
1640ae94 VS |
1072 | Reading monitored data |
1073 | ---------------------- | |
1074 | Reading an event file (for ex: mon_data/mon_L3_00/llc_occupancy) would | |
1075 | show the current snapshot of LLC occupancy of the corresponding MON | |
1076 | group or CTRL_MON group. | |
1077 | ||
1078 | ||
1079 | Example 1 (Monitor CTRL_MON group and subset of tasks in CTRL_MON group) | |
1cd7af50 | 1080 | ------------------------------------------------------------------------ |
1640ae94 | 1081 | On a two socket machine (one L3 cache per socket) with just four bits |
1cd7af50 | 1082 | for cache bit masks:: |
1640ae94 | 1083 | |
1cd7af50 CD |
1084 | # mount -t resctrl resctrl /sys/fs/resctrl |
1085 | # cd /sys/fs/resctrl | |
1086 | # mkdir p0 p1 | |
1087 | # echo "L3:0=3;1=c" > /sys/fs/resctrl/p0/schemata | |
1088 | # echo "L3:0=3;1=3" > /sys/fs/resctrl/p1/schemata | |
1089 | # echo 5678 > p1/tasks | |
1090 | # echo 5679 > p1/tasks | |
1640ae94 VS |
1091 | |
1092 | The default resource group is unmodified, so we have access to all parts | |
1093 | of all caches (its schemata file reads "L3:0=f;1=f"). | |
1094 | ||
1095 | Tasks that are under the control of group "p0" may only allocate from the | |
1096 | "lower" 50% on cache ID 0, and the "upper" 50% of cache ID 1. | |
1097 | Tasks in group "p1" use the "lower" 50% of cache on both sockets. | |
1098 | ||
1099 | Create monitor groups and assign a subset of tasks to each monitor group. | |
1cd7af50 | 1100 | :: |
1640ae94 | 1101 | |
1cd7af50 CD |
1102 | # cd /sys/fs/resctrl/p1/mon_groups |
1103 | # mkdir m11 m12 | |
1104 | # echo 5678 > m11/tasks | |
1105 | # echo 5679 > m12/tasks | |
1640ae94 VS |
1106 | |
1107 | fetch data (data shown in bytes) | |
1cd7af50 | 1108 | :: |
1640ae94 | 1109 | |
1cd7af50 CD |
1110 | # cat m11/mon_data/mon_L3_00/llc_occupancy |
1111 | 16234000 | |
1112 | # cat m11/mon_data/mon_L3_01/llc_occupancy | |
1113 | 14789000 | |
1114 | # cat m12/mon_data/mon_L3_00/llc_occupancy | |
1115 | 16789000 | |
1640ae94 VS |
1116 | |
1117 | The parent ctrl_mon group shows the aggregated data. | |
1cd7af50 | 1118 | :: |
1640ae94 | 1119 | |
1cd7af50 CD |
1120 | # cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy |
1121 | 31234000 | |
1640ae94 VS |
1122 | |
1123 | Example 2 (Monitor a task from its creation) | |
1cd7af50 CD |
1124 | -------------------------------------------- |
1125 | On a two socket machine (one L3 cache per socket):: | |
1640ae94 | 1126 | |
1cd7af50 CD |
1127 | # mount -t resctrl resctrl /sys/fs/resctrl |
1128 | # cd /sys/fs/resctrl | |
1129 | # mkdir p0 p1 | |
1640ae94 VS |
1130 | |
1131 | An RMID is allocated to the group once its created and hence the <cmd> | |
1132 | below is monitored from its creation. | |
1cd7af50 | 1133 | :: |
1640ae94 | 1134 | |
1cd7af50 CD |
1135 | # echo $$ > /sys/fs/resctrl/p1/tasks |
1136 | # <cmd> | |
1640ae94 | 1137 | |
1cd7af50 | 1138 | Fetch the data:: |
1640ae94 | 1139 | |
1cd7af50 CD |
1140 | # cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy |
1141 | 31789000 | |
1640ae94 VS |
1142 | |
1143 | Example 3 (Monitor without CAT support or before creating CAT groups) | |
1cd7af50 | 1144 | --------------------------------------------------------------------- |
1640ae94 VS |
1145 | |
1146 | Assume a system like HSW has only CQM and no CAT support. In this case | |
1147 | the resctrl will still mount but cannot create CTRL_MON directories. | |
1148 | But user can create different MON groups within the root group thereby | |
1149 | able to monitor all tasks including kernel threads. | |
1150 | ||
1151 | This can also be used to profile jobs cache size footprint before being | |
1152 | able to allocate them to different allocation groups. | |
1cd7af50 | 1153 | :: |
1640ae94 | 1154 | |
1cd7af50 CD |
1155 | # mount -t resctrl resctrl /sys/fs/resctrl |
1156 | # cd /sys/fs/resctrl | |
1157 | # mkdir mon_groups/m01 | |
1158 | # mkdir mon_groups/m02 | |
1640ae94 | 1159 | |
1cd7af50 CD |
1160 | # echo 3478 > /sys/fs/resctrl/mon_groups/m01/tasks |
1161 | # echo 2467 > /sys/fs/resctrl/mon_groups/m02/tasks | |
1640ae94 VS |
1162 | |
1163 | Monitor the groups separately and also get per domain data. From the | |
1164 | below its apparent that the tasks are mostly doing work on | |
1165 | domain(socket) 0. | |
1cd7af50 | 1166 | :: |
1640ae94 | 1167 | |
1cd7af50 CD |
1168 | # cat /sys/fs/resctrl/mon_groups/m01/mon_L3_00/llc_occupancy |
1169 | 31234000 | |
1170 | # cat /sys/fs/resctrl/mon_groups/m01/mon_L3_01/llc_occupancy | |
1171 | 34555 | |
1172 | # cat /sys/fs/resctrl/mon_groups/m02/mon_L3_00/llc_occupancy | |
1173 | 31234000 | |
1174 | # cat /sys/fs/resctrl/mon_groups/m02/mon_L3_01/llc_occupancy | |
1175 | 32789 | |
1640ae94 VS |
1176 | |
1177 | ||
1178 | Example 4 (Monitor real time tasks) | |
1179 | ----------------------------------- | |
1180 | ||
1181 | A single socket system which has real time tasks running on cores 4-7 | |
1182 | and non real time tasks on other cpus. We want to monitor the cache | |
1183 | occupancy of the real time threads on these cores. | |
1cd7af50 CD |
1184 | :: |
1185 | ||
1186 | # mount -t resctrl resctrl /sys/fs/resctrl | |
1187 | # cd /sys/fs/resctrl | |
1188 | # mkdir p1 | |
1640ae94 | 1189 | |
1cd7af50 | 1190 | Move the cpus 4-7 over to p1:: |
1640ae94 | 1191 | |
1cd7af50 | 1192 | # echo f0 > p1/cpus |
1640ae94 | 1193 | |
1cd7af50 | 1194 | View the llc occupancy snapshot:: |
1640ae94 | 1195 | |
1cd7af50 CD |
1196 | # cat /sys/fs/resctrl/p1/mon_data/mon_L3_00/llc_occupancy |
1197 | 11234000 |