Merge tag 'armsoc-dt' of git://git.kernel.org/pub/scm/linux/kernel/git/soc/soc
[sfrench/cifs-2.6.git] / Documentation / x86 / resctrl_ui.rst
1 .. SPDX-License-Identifier: GPL-2.0
2 .. include:: <isonum.txt>
3
4 ===========================================
5 User Interface for Resource Control feature
6 ===========================================
7
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>
12
13
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).
16
17 This feature is enabled by the CONFIG_X86_CPU_RESCTRL and the x86 /proc/cpuinfo
18 flag bits:
19
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::
30
31  # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps]] /sys/fs/resctrl
32
33 mount options are:
34
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
42
43 L2 and L3 CDP are controlled seperately.
44
45 RDT features are orthogonal. A particular system may support only
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
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.
56
57 Info directory
58 ==============
59
60 The 'info' directory contains information about the enabled
61 resources. Each resource has its own subdirectory. The subdirectory
62 names reflect the resource names.
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:
69
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
94                               resources have been allocated and a "0" is found
95                               in "bit_usage" it is a sign that resources are
96                               wasted.
97
98                         "H":
99                               Corresponding region is used by hardware only
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".
106                         "X":
107                               Corresponding region is available for sharing and
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.
111                         "S":
112                               Corresponding region is used by software
113                               and available for sharing.
114                         "E":
115                               Corresponding region is used exclusively by
116                               one resource group. No sharing allowed.
117                         "P":
118                               Corresponding region is pseudo-locked. No
119                               sharing allowed.
120
121 Memory bandwitdh(MB) subdirectory contains the following files
122 with respect to allocation:
123
124 "min_bandwidth":
125                 The minimum memory bandwidth percentage which
126                 user can request.
127
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.
135
136 "delay_linear":
137                 Indicates if the delay scale is linear or
138                 non-linear. This field is purely informational
139                 only.
140
141 If RDT monitoring is available there will be an "L3_MON" directory
142 with the following files:
143
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.
148
149 "mon_features":
150                 Lists the monitoring events if
151                 monitoring is enabled for the resource.
152
153 "max_threshold_occupancy":
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.
157
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.
164 ::
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
170
171 Resource alloc and monitor groups
172 =================================
173
174 Resource groups are represented as directories in the resctrl file
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.
212         When the resouce group is in pseudo-locked mode this file will
213         only be readable, reflecting the CPUs associated with the
214         pseudo-locked region.
215
216
217 "cpus_list":
218         Just like "cpus", only using ranges of CPUs instead of bitmasks.
219
220
221 When control is enabled all CTRL_MON groups will also contain:
222
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.
226
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
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".
241
242 When monitoring is enabled all MON groups will also contain:
243
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.
254
255 Resource allocation rules
256 -------------------------
257
258 When a task is running the following rules define which resources are
259 available to it:
260
261 1) If the task is a member of a non-default group, then the schemata
262    for that group is used.
263
264 2) Else if the task belongs to the default group, but is running on a
265    CPU that is assigned to some specific group, then the schemata for the
266    CPU's group is used.
267
268 3) Otherwise the schemata for the default group is used.
269
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
284 ===============================================
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.
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
345 the resctrl file system in "info/{resource}/cbm_mask". X86 hardware
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
352 Memory bandwidth Allocation and monitoring
353 ==========================================
354
355 For Memory bandwidth resource, by default the user controls the resource
356 by indicating the percentage of total memory bandwidth.
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
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%
383 << 100%. Hence increasing the bandwidth percentage will not yeild any
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
401 and adjust the memowy bandwidth percentages to ensure::
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.
409
410 L3 schemata file details (code and data prioritization disabled)
411 ----------------------------------------------------------------
412 With CDP disabled the L3 schemata format is::
413
414         L3:<cache_id0>=<cbm>;<cache_id1>=<cbm>;...
415
416 L3 schemata file details (CDP enabled via mount option to resctrl)
417 ------------------------------------------------------------------
418 When CDP is enabled L3 control is split into two separate resources
419 so you can specify independent masks for code and data like this::
420
421         L3data:<cache_id0>=<cbm>;<cache_id1>=<cbm>;...
422         L3code:<cache_id0>=<cbm>;<cache_id1>=<cbm>;...
423
424 L2 schemata file details
425 ------------------------
426 L2 cache does not support code and data prioritization, so the
427 schemata format is always::
428
429         L2:<cache_id0>=<cbm>;<cache_id1>=<cbm>;...
430
431 Memory bandwidth Allocation (default mode)
432 ------------------------------------------
433
434 Memory b/w domain is L3 cache.
435 ::
436
437         MB:<cache_id0>=bandwidth0;<cache_id1>=bandwidth1;...
438
439 Memory bandwidth Allocation specified in MBps
440 ---------------------------------------------
441
442 Memory bandwidth domain is L3 cache.
443 ::
444
445         MB:<cache_id0>=bw_MBps0;<cache_id1>=bw_MBps1;...
446
447 Reading/writing the schemata file
448 ---------------------------------
449 Reading the schemata file will show the state of all resources
450 on all domains. When writing you only need to specify those values
451 which you wish to change.  E.g.
452 ::
453
454   # cat schemata
455   L3DATA:0=fffff;1=fffff;2=fffff;3=fffff
456   L3CODE:0=fffff;1=fffff;2=fffff;3=fffff
457   # echo "L3DATA:2=3c0;" > schemata
458   # cat schemata
459   L3DATA:0=fffff;1=fffff;2=3c0;3=fffff
460   L3CODE:0=fffff;1=fffff;2=fffff;3=fffff
461
462 Cache Pseudo-Locking
463 ====================
464 CAT enables a user to specify the amount of cache space that an
465 application can fill. Cache pseudo-locking builds on the fact that a
466 CPU can still read and write data pre-allocated outside its current
467 allocated area on a cache hit. With cache pseudo-locking, data can be
468 preloaded into a reserved portion of cache that no application can
469 fill, and from that point on will only serve cache hits. The cache
470 pseudo-locked memory is made accessible to user space where an
471 application can map it into its virtual address space and thus have
472 a region of memory with reduced average read latency.
473
474 The creation of a cache pseudo-locked region is triggered by a request
475 from the user to do so that is accompanied by a schemata of the region
476 to be pseudo-locked. The cache pseudo-locked region is created as follows:
477
478 - Create a CAT allocation CLOSNEW with a CBM matching the schemata
479   from the user of the cache region that will contain the pseudo-locked
480   memory. This region must not overlap with any current CAT allocation/CLOS
481   on the system and no future overlap with this cache region is allowed
482   while the pseudo-locked region exists.
483 - Create a contiguous region of memory of the same size as the cache
484   region.
485 - Flush the cache, disable hardware prefetchers, disable preemption.
486 - Make CLOSNEW the active CLOS and touch the allocated memory to load
487   it into the cache.
488 - Set the previous CLOS as active.
489 - At this point the closid CLOSNEW can be released - the cache
490   pseudo-locked region is protected as long as its CBM does not appear in
491   any CAT allocation. Even though the cache pseudo-locked region will from
492   this point on not appear in any CBM of any CLOS an application running with
493   any CLOS will be able to access the memory in the pseudo-locked region since
494   the region continues to serve cache hits.
495 - The contiguous region of memory loaded into the cache is exposed to
496   user-space as a character device.
497
498 Cache pseudo-locking increases the probability that data will remain
499 in the cache via carefully configuring the CAT feature and controlling
500 application behavior. There is no guarantee that data is placed in
501 cache. Instructions like INVD, WBINVD, CLFLUSH, etc. can still evict
502 “locked” data from cache. Power management C-states may shrink or
503 power off cache. Deeper C-states will automatically be restricted on
504 pseudo-locked region creation.
505
506 It is required that an application using a pseudo-locked region runs
507 with affinity to the cores (or a subset of the cores) associated
508 with the cache on which the pseudo-locked region resides. A sanity check
509 within the code will not allow an application to map pseudo-locked memory
510 unless it runs with affinity to cores associated with the cache on which the
511 pseudo-locked region resides. The sanity check is only done during the
512 initial mmap() handling, there is no enforcement afterwards and the
513 application self needs to ensure it remains affine to the correct cores.
514
515 Pseudo-locking is accomplished in two stages:
516
517 1) During the first stage the system administrator allocates a portion
518    of cache that should be dedicated to pseudo-locking. At this time an
519    equivalent portion of memory is allocated, loaded into allocated
520    cache portion, and exposed as a character device.
521 2) During the second stage a user-space application maps (mmap()) the
522    pseudo-locked memory into its address space.
523
524 Cache Pseudo-Locking Interface
525 ------------------------------
526 A pseudo-locked region is created using the resctrl interface as follows:
527
528 1) Create a new resource group by creating a new directory in /sys/fs/resctrl.
529 2) Change the new resource group's mode to "pseudo-locksetup" by writing
530    "pseudo-locksetup" to the "mode" file.
531 3) Write the schemata of the pseudo-locked region to the "schemata" file. All
532    bits within the schemata should be "unused" according to the "bit_usage"
533    file.
534
535 On successful pseudo-locked region creation the "mode" file will contain
536 "pseudo-locked" and a new character device with the same name as the resource
537 group will exist in /dev/pseudo_lock. This character device can be mmap()'ed
538 by user space in order to obtain access to the pseudo-locked memory region.
539
540 An example of cache pseudo-locked region creation and usage can be found below.
541
542 Cache Pseudo-Locking Debugging Interface
543 ----------------------------------------
544 The pseudo-locking debugging interface is enabled by default (if
545 CONFIG_DEBUG_FS is enabled) and can be found in /sys/kernel/debug/resctrl.
546
547 There is no explicit way for the kernel to test if a provided memory
548 location is present in the cache. The pseudo-locking debugging interface uses
549 the tracing infrastructure to provide two ways to measure cache residency of
550 the pseudo-locked region:
551
552 1) Memory access latency using the pseudo_lock_mem_latency tracepoint. Data
553    from these measurements are best visualized using a hist trigger (see
554    example below). In this test the pseudo-locked region is traversed at
555    a stride of 32 bytes while hardware prefetchers and preemption
556    are disabled. This also provides a substitute visualization of cache
557    hits and misses.
558 2) Cache hit and miss measurements using model specific precision counters if
559    available. Depending on the levels of cache on the system the pseudo_lock_l2
560    and pseudo_lock_l3 tracepoints are available.
561
562 When a pseudo-locked region is created a new debugfs directory is created for
563 it in debugfs as /sys/kernel/debug/resctrl/<newdir>. A single
564 write-only file, pseudo_lock_measure, is present in this directory. The
565 measurement of the pseudo-locked region depends on the number written to this
566 debugfs file:
567
568 1:
569      writing "1" to the pseudo_lock_measure file will trigger the latency
570      measurement captured in the pseudo_lock_mem_latency tracepoint. See
571      example below.
572 2:
573      writing "2" to the pseudo_lock_measure file will trigger the L2 cache
574      residency (cache hits and misses) measurement captured in the
575      pseudo_lock_l2 tracepoint. See example below.
576 3:
577      writing "3" to the pseudo_lock_measure file will trigger the L3 cache
578      residency (cache hits and misses) measurement captured in the
579      pseudo_lock_l3 tracepoint.
580
581 All measurements are recorded with the tracing infrastructure. This requires
582 the relevant tracepoints to be enabled before the measurement is triggered.
583
584 Example of latency debugging interface
585 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
586 In this example a pseudo-locked region named "newlock" was created. Here is
587 how we can measure the latency in cycles of reading from this region and
588 visualize this data with a histogram that is available if CONFIG_HIST_TRIGGERS
589 is set::
590
591   # :> /sys/kernel/debug/tracing/trace
592   # echo 'hist:keys=latency' > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/trigger
593   # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable
594   # echo 1 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure
595   # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable
596   # cat /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/hist
597
598   # event histogram
599   #
600   # trigger info: hist:keys=latency:vals=hitcount:sort=hitcount:size=2048 [active]
601   #
602
603   { latency:        456 } hitcount:          1
604   { latency:         50 } hitcount:         83
605   { latency:         36 } hitcount:         96
606   { latency:         44 } hitcount:        174
607   { latency:         48 } hitcount:        195
608   { latency:         46 } hitcount:        262
609   { latency:         42 } hitcount:        693
610   { latency:         40 } hitcount:       3204
611   { latency:         38 } hitcount:       3484
612
613   Totals:
614       Hits: 8192
615       Entries: 9
616     Dropped: 0
617
618 Example of cache hits/misses debugging
619 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
620 In this example a pseudo-locked region named "newlock" was created on the L2
621 cache of a platform. Here is how we can obtain details of the cache hits
622 and misses using the platform's precision counters.
623 ::
624
625   # :> /sys/kernel/debug/tracing/trace
626   # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable
627   # echo 2 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure
628   # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable
629   # cat /sys/kernel/debug/tracing/trace
630
631   # tracer: nop
632   #
633   #                              _-----=> irqs-off
634   #                             / _----=> need-resched
635   #                            | / _---=> hardirq/softirq
636   #                            || / _--=> preempt-depth
637   #                            ||| /     delay
638   #           TASK-PID   CPU#  ||||    TIMESTAMP  FUNCTION
639   #              | |       |   ||||       |         |
640   pseudo_lock_mea-1672  [002] ....  3132.860500: pseudo_lock_l2: hits=4097 miss=0
641
642
643 Examples for RDT allocation usage
644 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
645
646 1) Example 1
647
648 On a two socket machine (one L3 cache per socket) with just four bits
649 for cache bit masks, minimum b/w of 10% with a memory bandwidth
650 granularity of 10%.
651 ::
652
653   # mount -t resctrl resctrl /sys/fs/resctrl
654   # cd /sys/fs/resctrl
655   # mkdir p0 p1
656   # echo "L3:0=3;1=c\nMB:0=50;1=50" > /sys/fs/resctrl/p0/schemata
657   # echo "L3:0=3;1=3\nMB:0=50;1=50" > /sys/fs/resctrl/p1/schemata
658
659 The default resource group is unmodified, so we have access to all parts
660 of all caches (its schemata file reads "L3:0=f;1=f").
661
662 Tasks that are under the control of group "p0" may only allocate from the
663 "lower" 50% on cache ID 0, and the "upper" 50% of cache ID 1.
664 Tasks in group "p1" use the "lower" 50% of cache on both sockets.
665
666 Similarly, tasks that are under the control of group "p0" may use a
667 maximum memory b/w of 50% on socket0 and 50% on socket 1.
668 Tasks in group "p1" may also use 50% memory b/w on both sockets.
669 Note that unlike cache masks, memory b/w cannot specify whether these
670 allocations can overlap or not. The allocations specifies the maximum
671 b/w that the group may be able to use and the system admin can configure
672 the b/w accordingly.
673
674 If the MBA is specified in MB(megabytes) then user can enter the max b/w in MB
675 rather than the percentage values.
676 ::
677
678   # echo "L3:0=3;1=c\nMB:0=1024;1=500" > /sys/fs/resctrl/p0/schemata
679   # echo "L3:0=3;1=3\nMB:0=1024;1=500" > /sys/fs/resctrl/p1/schemata
680
681 In the above example the tasks in "p1" and "p0" on socket 0 would use a max b/w
682 of 1024MB where as on socket 1 they would use 500MB.
683
684 2) Example 2
685
686 Again two sockets, but this time with a more realistic 20-bit mask.
687
688 Two real time tasks pid=1234 running on processor 0 and pid=5678 running on
689 processor 1 on socket 0 on a 2-socket and dual core machine. To avoid noisy
690 neighbors, each of the two real-time tasks exclusively occupies one quarter
691 of L3 cache on socket 0.
692 ::
693
694   # mount -t resctrl resctrl /sys/fs/resctrl
695   # cd /sys/fs/resctrl
696
697 First we reset the schemata for the default group so that the "upper"
698 50% of the L3 cache on socket 0 and 50% of memory b/w cannot be used by
699 ordinary tasks::
700
701   # echo "L3:0=3ff;1=fffff\nMB:0=50;1=100" > schemata
702
703 Next we make a resource group for our first real time task and give
704 it access to the "top" 25% of the cache on socket 0.
705 ::
706
707   # mkdir p0
708   # echo "L3:0=f8000;1=fffff" > p0/schemata
709
710 Finally we move our first real time task into this resource group. We
711 also use taskset(1) to ensure the task always runs on a dedicated CPU
712 on socket 0. Most uses of resource groups will also constrain which
713 processors tasks run on.
714 ::
715
716   # echo 1234 > p0/tasks
717   # taskset -cp 1 1234
718
719 Ditto for the second real time task (with the remaining 25% of cache)::
720
721   # mkdir p1
722   # echo "L3:0=7c00;1=fffff" > p1/schemata
723   # echo 5678 > p1/tasks
724   # taskset -cp 2 5678
725
726 For the same 2 socket system with memory b/w resource and CAT L3 the
727 schemata would look like(Assume min_bandwidth 10 and bandwidth_gran is
728 10):
729
730 For our first real time task this would request 20% memory b/w on socket 0.
731 ::
732
733   # echo -e "L3:0=f8000;1=fffff\nMB:0=20;1=100" > p0/schemata
734
735 For our second real time task this would request an other 20% memory b/w
736 on socket 0.
737 ::
738
739   # echo -e "L3:0=f8000;1=fffff\nMB:0=20;1=100" > p0/schemata
740
741 3) Example 3
742
743 A single socket system which has real-time tasks running on core 4-7 and
744 non real-time workload assigned to core 0-3. The real-time tasks share text
745 and data, so a per task association is not required and due to interaction
746 with the kernel it's desired that the kernel on these cores shares L3 with
747 the tasks.
748 ::
749
750   # mount -t resctrl resctrl /sys/fs/resctrl
751   # cd /sys/fs/resctrl
752
753 First we reset the schemata for the default group so that the "upper"
754 50% of the L3 cache on socket 0, and 50% of memory bandwidth on socket 0
755 cannot be used by ordinary tasks::
756
757   # echo "L3:0=3ff\nMB:0=50" > schemata
758
759 Next we make a resource group for our real time cores and give it access
760 to the "top" 50% of the cache on socket 0 and 50% of memory bandwidth on
761 socket 0.
762 ::
763
764   # mkdir p0
765   # echo "L3:0=ffc00\nMB:0=50" > p0/schemata
766
767 Finally we move core 4-7 over to the new group and make sure that the
768 kernel and the tasks running there get 50% of the cache. They should
769 also get 50% of memory bandwidth assuming that the cores 4-7 are SMT
770 siblings and only the real time threads are scheduled on the cores 4-7.
771 ::
772
773   # echo F0 > p0/cpus
774
775 4) Example 4
776
777 The resource groups in previous examples were all in the default "shareable"
778 mode allowing sharing of their cache allocations. If one resource group
779 configures a cache allocation then nothing prevents another resource group
780 to overlap with that allocation.
781
782 In this example a new exclusive resource group will be created on a L2 CAT
783 system with two L2 cache instances that can be configured with an 8-bit
784 capacity bitmask. The new exclusive resource group will be configured to use
785 25% of each cache instance.
786 ::
787
788   # mount -t resctrl resctrl /sys/fs/resctrl/
789   # cd /sys/fs/resctrl
790
791 First, we observe that the default group is configured to allocate to all L2
792 cache::
793
794   # cat schemata
795   L2:0=ff;1=ff
796
797 We could attempt to create the new resource group at this point, but it will
798 fail because of the overlap with the schemata of the default group::
799
800   # mkdir p0
801   # echo 'L2:0=0x3;1=0x3' > p0/schemata
802   # cat p0/mode
803   shareable
804   # echo exclusive > p0/mode
805   -sh: echo: write error: Invalid argument
806   # cat info/last_cmd_status
807   schemata overlaps
808
809 To ensure that there is no overlap with another resource group the default
810 resource group's schemata has to change, making it possible for the new
811 resource group to become exclusive.
812 ::
813
814   # echo 'L2:0=0xfc;1=0xfc' > schemata
815   # echo exclusive > p0/mode
816   # grep . p0/*
817   p0/cpus:0
818   p0/mode:exclusive
819   p0/schemata:L2:0=03;1=03
820   p0/size:L2:0=262144;1=262144
821
822 A new resource group will on creation not overlap with an exclusive resource
823 group::
824
825   # mkdir p1
826   # grep . p1/*
827   p1/cpus:0
828   p1/mode:shareable
829   p1/schemata:L2:0=fc;1=fc
830   p1/size:L2:0=786432;1=786432
831
832 The bit_usage will reflect how the cache is used::
833
834   # cat info/L2/bit_usage
835   0=SSSSSSEE;1=SSSSSSEE
836
837 A resource group cannot be forced to overlap with an exclusive resource group::
838
839   # echo 'L2:0=0x1;1=0x1' > p1/schemata
840   -sh: echo: write error: Invalid argument
841   # cat info/last_cmd_status
842   overlaps with exclusive group
843
844 Example of Cache Pseudo-Locking
845 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
846 Lock portion of L2 cache from cache id 1 using CBM 0x3. Pseudo-locked
847 region is exposed at /dev/pseudo_lock/newlock that can be provided to
848 application for argument to mmap().
849 ::
850
851   # mount -t resctrl resctrl /sys/fs/resctrl/
852   # cd /sys/fs/resctrl
853
854 Ensure that there are bits available that can be pseudo-locked, since only
855 unused bits can be pseudo-locked the bits to be pseudo-locked needs to be
856 removed from the default resource group's schemata::
857
858   # cat info/L2/bit_usage
859   0=SSSSSSSS;1=SSSSSSSS
860   # echo 'L2:1=0xfc' > schemata
861   # cat info/L2/bit_usage
862   0=SSSSSSSS;1=SSSSSS00
863
864 Create a new resource group that will be associated with the pseudo-locked
865 region, indicate that it will be used for a pseudo-locked region, and
866 configure the requested pseudo-locked region capacity bitmask::
867
868   # mkdir newlock
869   # echo pseudo-locksetup > newlock/mode
870   # echo 'L2:1=0x3' > newlock/schemata
871
872 On success the resource group's mode will change to pseudo-locked, the
873 bit_usage will reflect the pseudo-locked region, and the character device
874 exposing the pseudo-locked region will exist::
875
876   # cat newlock/mode
877   pseudo-locked
878   # cat info/L2/bit_usage
879   0=SSSSSSSS;1=SSSSSSPP
880   # ls -l /dev/pseudo_lock/newlock
881   crw------- 1 root root 243, 0 Apr  3 05:01 /dev/pseudo_lock/newlock
882
883 ::
884
885   /*
886   * Example code to access one page of pseudo-locked cache region
887   * from user space.
888   */
889   #define _GNU_SOURCE
890   #include <fcntl.h>
891   #include <sched.h>
892   #include <stdio.h>
893   #include <stdlib.h>
894   #include <unistd.h>
895   #include <sys/mman.h>
896
897   /*
898   * It is required that the application runs with affinity to only
899   * cores associated with the pseudo-locked region. Here the cpu
900   * is hardcoded for convenience of example.
901   */
902   static int cpuid = 2;
903
904   int main(int argc, char *argv[])
905   {
906     cpu_set_t cpuset;
907     long page_size;
908     void *mapping;
909     int dev_fd;
910     int ret;
911
912     page_size = sysconf(_SC_PAGESIZE);
913
914     CPU_ZERO(&cpuset);
915     CPU_SET(cpuid, &cpuset);
916     ret = sched_setaffinity(0, sizeof(cpuset), &cpuset);
917     if (ret < 0) {
918       perror("sched_setaffinity");
919       exit(EXIT_FAILURE);
920     }
921
922     dev_fd = open("/dev/pseudo_lock/newlock", O_RDWR);
923     if (dev_fd < 0) {
924       perror("open");
925       exit(EXIT_FAILURE);
926     }
927
928     mapping = mmap(0, page_size, PROT_READ | PROT_WRITE, MAP_SHARED,
929             dev_fd, 0);
930     if (mapping == MAP_FAILED) {
931       perror("mmap");
932       close(dev_fd);
933       exit(EXIT_FAILURE);
934     }
935
936     /* Application interacts with pseudo-locked memory @mapping */
937
938     ret = munmap(mapping, page_size);
939     if (ret < 0) {
940       perror("munmap");
941       close(dev_fd);
942       exit(EXIT_FAILURE);
943     }
944
945     close(dev_fd);
946     exit(EXIT_SUCCESS);
947   }
948
949 Locking between applications
950 ----------------------------
951
952 Certain operations on the resctrl filesystem, composed of read/writes
953 to/from multiple files, must be atomic.
954
955 As an example, the allocation of an exclusive reservation of L3 cache
956 involves:
957
958   1. Read the cbmmasks from each directory or the per-resource "bit_usage"
959   2. Find a contiguous set of bits in the global CBM bitmask that is clear
960      in any of the directory cbmmasks
961   3. Create a new directory
962   4. Set the bits found in step 2 to the new directory "schemata" file
963
964 If two applications attempt to allocate space concurrently then they can
965 end up allocating the same bits so the reservations are shared instead of
966 exclusive.
967
968 To coordinate atomic operations on the resctrlfs and to avoid the problem
969 above, the following locking procedure is recommended:
970
971 Locking is based on flock, which is available in libc and also as a shell
972 script command
973
974 Write lock:
975
976  A) Take flock(LOCK_EX) on /sys/fs/resctrl
977  B) Read/write the directory structure.
978  C) funlock
979
980 Read lock:
981
982  A) Take flock(LOCK_SH) on /sys/fs/resctrl
983  B) If success read the directory structure.
984  C) funlock
985
986 Example with bash::
987
988   # Atomically read directory structure
989   $ flock -s /sys/fs/resctrl/ find /sys/fs/resctrl
990
991   # Read directory contents and create new subdirectory
992
993   $ cat create-dir.sh
994   find /sys/fs/resctrl/ > output.txt
995   mask = function-of(output.txt)
996   mkdir /sys/fs/resctrl/newres/
997   echo mask > /sys/fs/resctrl/newres/schemata
998
999   $ flock /sys/fs/resctrl/ ./create-dir.sh
1000
1001 Example with C::
1002
1003   /*
1004   * Example code do take advisory locks
1005   * before accessing resctrl filesystem
1006   */
1007   #include <sys/file.h>
1008   #include <stdlib.h>
1009
1010   void resctrl_take_shared_lock(int fd)
1011   {
1012     int ret;
1013
1014     /* take shared lock on resctrl filesystem */
1015     ret = flock(fd, LOCK_SH);
1016     if (ret) {
1017       perror("flock");
1018       exit(-1);
1019     }
1020   }
1021
1022   void resctrl_take_exclusive_lock(int fd)
1023   {
1024     int ret;
1025
1026     /* release lock on resctrl filesystem */
1027     ret = flock(fd, LOCK_EX);
1028     if (ret) {
1029       perror("flock");
1030       exit(-1);
1031     }
1032   }
1033
1034   void resctrl_release_lock(int fd)
1035   {
1036     int ret;
1037
1038     /* take shared lock on resctrl filesystem */
1039     ret = flock(fd, LOCK_UN);
1040     if (ret) {
1041       perror("flock");
1042       exit(-1);
1043     }
1044   }
1045
1046   void main(void)
1047   {
1048     int fd, ret;
1049
1050     fd = open("/sys/fs/resctrl", O_DIRECTORY);
1051     if (fd == -1) {
1052       perror("open");
1053       exit(-1);
1054     }
1055     resctrl_take_shared_lock(fd);
1056     /* code to read directory contents */
1057     resctrl_release_lock(fd);
1058
1059     resctrl_take_exclusive_lock(fd);
1060     /* code to read and write directory contents */
1061     resctrl_release_lock(fd);
1062   }
1063
1064 Examples for RDT Monitoring along with allocation usage
1065 =======================================================
1066 Reading monitored data
1067 ----------------------
1068 Reading an event file (for ex: mon_data/mon_L3_00/llc_occupancy) would
1069 show the current snapshot of LLC occupancy of the corresponding MON
1070 group or CTRL_MON group.
1071
1072
1073 Example 1 (Monitor CTRL_MON group and subset of tasks in CTRL_MON group)
1074 ------------------------------------------------------------------------
1075 On a two socket machine (one L3 cache per socket) with just four bits
1076 for cache bit masks::
1077
1078   # mount -t resctrl resctrl /sys/fs/resctrl
1079   # cd /sys/fs/resctrl
1080   # mkdir p0 p1
1081   # echo "L3:0=3;1=c" > /sys/fs/resctrl/p0/schemata
1082   # echo "L3:0=3;1=3" > /sys/fs/resctrl/p1/schemata
1083   # echo 5678 > p1/tasks
1084   # echo 5679 > p1/tasks
1085
1086 The default resource group is unmodified, so we have access to all parts
1087 of all caches (its schemata file reads "L3:0=f;1=f").
1088
1089 Tasks that are under the control of group "p0" may only allocate from the
1090 "lower" 50% on cache ID 0, and the "upper" 50% of cache ID 1.
1091 Tasks in group "p1" use the "lower" 50% of cache on both sockets.
1092
1093 Create monitor groups and assign a subset of tasks to each monitor group.
1094 ::
1095
1096   # cd /sys/fs/resctrl/p1/mon_groups
1097   # mkdir m11 m12
1098   # echo 5678 > m11/tasks
1099   # echo 5679 > m12/tasks
1100
1101 fetch data (data shown in bytes)
1102 ::
1103
1104   # cat m11/mon_data/mon_L3_00/llc_occupancy
1105   16234000
1106   # cat m11/mon_data/mon_L3_01/llc_occupancy
1107   14789000
1108   # cat m12/mon_data/mon_L3_00/llc_occupancy
1109   16789000
1110
1111 The parent ctrl_mon group shows the aggregated data.
1112 ::
1113
1114   # cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy
1115   31234000
1116
1117 Example 2 (Monitor a task from its creation)
1118 --------------------------------------------
1119 On a two socket machine (one L3 cache per socket)::
1120
1121   # mount -t resctrl resctrl /sys/fs/resctrl
1122   # cd /sys/fs/resctrl
1123   # mkdir p0 p1
1124
1125 An RMID is allocated to the group once its created and hence the <cmd>
1126 below is monitored from its creation.
1127 ::
1128
1129   # echo $$ > /sys/fs/resctrl/p1/tasks
1130   # <cmd>
1131
1132 Fetch the data::
1133
1134   # cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy
1135   31789000
1136
1137 Example 3 (Monitor without CAT support or before creating CAT groups)
1138 ---------------------------------------------------------------------
1139
1140 Assume a system like HSW has only CQM and no CAT support. In this case
1141 the resctrl will still mount but cannot create CTRL_MON directories.
1142 But user can create different MON groups within the root group thereby
1143 able to monitor all tasks including kernel threads.
1144
1145 This can also be used to profile jobs cache size footprint before being
1146 able to allocate them to different allocation groups.
1147 ::
1148
1149   # mount -t resctrl resctrl /sys/fs/resctrl
1150   # cd /sys/fs/resctrl
1151   # mkdir mon_groups/m01
1152   # mkdir mon_groups/m02
1153
1154   # echo 3478 > /sys/fs/resctrl/mon_groups/m01/tasks
1155   # echo 2467 > /sys/fs/resctrl/mon_groups/m02/tasks
1156
1157 Monitor the groups separately and also get per domain data. From the
1158 below its apparent that the tasks are mostly doing work on
1159 domain(socket) 0.
1160 ::
1161
1162   # cat /sys/fs/resctrl/mon_groups/m01/mon_L3_00/llc_occupancy
1163   31234000
1164   # cat /sys/fs/resctrl/mon_groups/m01/mon_L3_01/llc_occupancy
1165   34555
1166   # cat /sys/fs/resctrl/mon_groups/m02/mon_L3_00/llc_occupancy
1167   31234000
1168   # cat /sys/fs/resctrl/mon_groups/m02/mon_L3_01/llc_occupancy
1169   32789
1170
1171
1172 Example 4 (Monitor real time tasks)
1173 -----------------------------------
1174
1175 A single socket system which has real time tasks running on cores 4-7
1176 and non real time tasks on other cpus. We want to monitor the cache
1177 occupancy of the real time threads on these cores.
1178 ::
1179
1180   # mount -t resctrl resctrl /sys/fs/resctrl
1181   # cd /sys/fs/resctrl
1182   # mkdir p1
1183
1184 Move the cpus 4-7 over to p1::
1185
1186   # echo f0 > p1/cpus
1187
1188 View the llc occupancy snapshot::
1189
1190   # cat /sys/fs/resctrl/p1/mon_data/mon_L3_00/llc_occupancy
1191   11234000