cache line locking on AMD x86_64 utilising L3 CAT pseudo-locking
update documentation
author
vm.fail
date
(Jan 18, 2026, 3:43 AM UTC)
commit
eb619c6e
eb619c6e9e7f5481f01828e29da9c45cf7a5a3cb
parent
149475eb
149475eb58ee2524e23dc2f513276b57be7503e7
vm.fail
date
(Jan 18, 2026, 3:43 AM UTC)
commit
eb619c6e
eb619c6e9e7f5481f01828e29da9c45cf7a5a3cb
parent
149475eb
149475eb58ee2524e23dc2f513276b57be7503e7
+20
-24
+20
-24
README.md
+20
-24
README.md
···
1
1
# icepick
2
2
3
-
icepick use cache ways from the llc using cat/rdt msr configuration. target memory regions are primed into isolated clos partitions to prevent eviction by competing workloads. i als found it personally useful for pinning cryptographic state against side-channel probing + eliminating tail latency in hot paths
3
+
kernel module for l3 cache pseudo-locking via cat and wc-mapped i/o space.
4
+
5
+
## overview
6
+
7
+
icepick exposes a character device for pinning data into isolated l3 cache ways. maps physical i/o space with write-combining via ioremap_wc and mtrr configuration, then primes cache lines using prefetcht2 and temporal loads. cat schemata configured through resctrl sysfs. pmu-based eviction monitoring via perf_event (amd zen l3 miss counter 0x0104e). useful for side-channel isolation or latency-critical data structures requiring deterministic cache residency.
8
+
9
+
requires cat-capable silicon (amd zen2+), resctrl mounted, and kernel headers for kbuild.
4
10
5
11
## build
6
12
···
8
14
make
9
15
```
10
16
11
-
```
12
-
dune build
13
-
```
17
+
outputs `icepick.ko` kernel module.
14
18
15
19
## usage
16
20
17
21
```
18
-
icepick topology # enumerate l3 geometry, way count, clos availability
19
-
icepick lock -s 4M -c 1 -v # allocate 4mb into clos 1, verify residency
20
-
icepick bench -s 2M # compare locked vs unlocked access latency
21
-
icepick status # dump current clos mask assignments
22
-
```
23
-
24
-
c api:
25
-
26
-
```c
27
-
icepick_topology_t *topo;
28
-
icepick_discover_topology(&topo);
22
+
insmod icepick.ko
23
+
chmod 666 /dev/cachemem
29
24
30
-
icepick_config_t cfg = { .size = 4*1024*1024, .clos_id = 1, .huge_pages = true };
31
-
icepick_region_t *region;
32
-
icepick_lock(topo, &cfg, ®ion);
25
+
echo "sensitive data" > /dev/cachemem # lock into l3 way 0
26
+
cat /dev/cachemem # read back, integrity check
27
+
dmesg | grep ICEPICK # check residency/eviction logs
33
28
34
-
void *ptr = icepick_region_ptr(region);
29
+
rmmod icepick
35
30
```
36
31
37
-
ocaml:
32
+
ioctl flush:
33
+
34
+
```c
35
+
#define ICEPICK_IOC_MAGIC 'k'
36
+
#define ICEPICK_FLUSH_CACHE _IOW(ICEPICK_IOC_MAGIC, 1, char *)
38
37
39
-
```ocaml
40
-
let topo = Icepick.Topology.discover () in
41
-
let region = Icepick.Region.lock topo ~size:0x400000 ~clos:1 () in
42
-
let ptr = Icepick.Region.ptr region in
38
+
ioctl(fd, ICEPICK_FLUSH_CACHE, "please flush my cachelines");
43
39
```