intel_rdt_ui.txt 40 KB

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