final review

Author: Your Name

content/learning-paths/cross-platform/filesystem-cache-hit/_index.md

@@ -1,14 +1,14 @@
 ---
-title: Improve File System Cache hit rate with the posix_fadvise syscall 
+title: Improve File System Cache hit rate with the posix_fadvise function 
 
 minutes_to_complete: 15
 
-who_is_this_for: Developers who observe high-levels of file system cache misses in performance-critical sections of software
+who_is_this_for: Developers who want to boost performance of applications limited by file system cache misses. 
 
 learning_objectives: 
     - Learn the high-level operation and purpose of the file system cache
     - Learn how to measure and intepret cache miss rates
-    - Learn how to use the posix_fadvise syscall provide hints to the kernel about file access patterns 
+    - Learn how to use the posix_fadvise() function to provide hints to the kernel about file access patterns 
 
 prerequisites:
     - Basic understanding of C++ and Linux

content/learning-paths/cross-platform/filesystem-cache-hit/intro.md

@@ -8,31 +8,32 @@ layout: learningpathall
 
 ## Recap of File Systems
 
-A file system is the method an operating system uses to store, organize, and manage data on storage devices like hard drives or SSDs. Linux uses a **Virtual File System (VFS)** layer to provide a uniform interface to different file system types (e.g., `ext4`, `xfs`, `btrfs`), allowing programs to interact with them in a consistent way. 
+A file system is the method an operating system uses to store, organize, and manage data on storage devices like hard drives or SSDs. Linux uses a virtual file system (VFS) layer to provide a uniform interface to different file system types (e.g., `ext4`, `xfs`, `btrfs`), allowing programs to interact with them in a consistent way. 
 
-Developers typically interact with the file system through system calls or standard library functions—for example, using `open()`, `read()`, and `write()` in C to access files. For instance, reading a configuration file at `/etc/myapp/config.json` involves navigating the file system hierarchy and accessing the file’s contents through these interfaces. To speed up access to such files, the operating system creates a file system cache, managed by the kernel and residing in main memory (RAM). This cache temporarily stores recently accessed file data to speed up future reads and reduce disk I/O.
+Developers typically interact with the file system through system calls or standard library functions—for example, using `open()`, `read()`, and `write()` in C to access files. For instance, reading a configuration file at `/etc/myapp/config.json` involves navigating the file system hierarchy and accessing the file’s contents through these interfaces. To speed up access to such files, the operating system creates a file system cache, managed by the kernel and resides in main memory (RAM). This cache temporarily stores recently accessed file data and metadata to speed up future reads and reduce disk I/O.
 
 
-## Observing Memory Usage
+## Recap of Memory Usage
 
-The operating system has to manage the memory usage for the entire system.
+The hardware and operating system is responsible for managing the memory usage of the system.
 
-The command `free -h` provides a snapshot of memory usage. 
+The well-known command `free -wh` provides a snapshot of memory usage. The `cache` column includes the portion of memory used to store the file system cache. 
 
 ```output
-               total        used        free      shared  buff/cache   available
-Mem:           7.6Gi       533Mi       7.0Gi       948Ki       215Mi       7.1Gi
+               total        used        free      shared     buffers       cache   available
+Mem:           7.6Gi       1.1Gi       5.8Gi       960Ki        22Mi       832Mi       6.5Gi
 Swap:             0B          0B          0B
 ```
 
-The `free` command summarises the memory usage into the following columns. 
+The command summarises the memory usage into the following columns. 
 
 - `total`: Total installed memory
 - `used`: Memory in use (excluding cache/buffers)
 - `free`: Unused memory
 - `shared`: Memory used by tmpfs and shared between processes
-- `buff/cache`: Sum of memory used by kernel buffers and cache
-- `available`: An estimate of memory available to start new apps
+- `buffers`: Memory used by kernel buffers
+- `cache`:  Memory used by file system cache
+- `available`: An estimate of memory available (both free memory and memory that can be reclaimed) when a new process starts.
 
 
 ### What is the posix_fadvise syscall?

content/learning-paths/cross-platform/filesystem-cache-hit/with_hint.md

@@ -9,7 +9,7 @@ layout: learningpathall
 
 ## Providing hints with posix_fadvise
 
-The `posix_fadvise()` system call gives the Linux kernel hints about expected file access patterns to optimize I/O. The function takes the following arguments. 
+The `posix_fadvise()` function is a wrapper around the `fadvise64` linux system call (syscall). This syscall gives the Linux kernel hints about expected file access patterns to optimize I/O, for example preemptively reading ahead for sequential file access. The function takes the following arguments. 
 - `fd`: file descriptor of the file,  
 - `offset`: where the advice starts (0 = beginning),  
 - `len`: how many bytes the advice applies to (0 = to the end),  
@@ -58,7 +58,6 @@ int main() {
     return 0;
 }
 
-
 ```
 
 Compile with the following command.
@@ -83,10 +82,14 @@ sudo perf stat -e cache-references,cache-misses,minor-faults,major-faults -r 9 .
 
 ```
 
+{{% notice Tip%}}
+If you are using `posix_fadvise()` with your own application and you want to observe which system calls are issued. Consider using the system call tracer, `strace` with a command such as `strace -ttT -e trace=<syscall of interest,fadvise64> ./<your workload>` to observe what is causing fewer cache misses.
+{{% /notice %}}
+
 ### Results
 
 Here we observe that on this run with a single line of code we are able to reduce the cache miss rate from ~4.8% to ~3.8%. This can translate to more efficient and performant software, especially if your program is synchronous and has to wait for disk accesses. 
 
 {{% notice Please Note%}}
-Since this is only a hint to the operating system and it depends on other factors such as memory pressure, memory usage, other processes etc. the behaviour on your system may be different
+Since this is advise to the operating system, the operating may not do anything with this. Real-world impact depends on other factors such as memory pressure, memory usage etc. As such, the behaviour on your own system may be different.
 {{% /notice %}}

content/learning-paths/cross-platform/filesystem-cache-hit/without_hint.md

@@ -8,7 +8,7 @@ layout: learningpathall
 
 ## Setup
 
-For this demonstration, I have connected to an Arm-based AWS `c7g.xlarge` instance running Ubuntu 24.04. Results may vary depending on which instance and kernel version you are using. At the time of writing, I was using the `6.8.0-1024-aws` kernel version. 
+For this demonstration, connect to an Arm-based AWS `c7g.xlarge` instance running Ubuntu 24.04. Results may vary depending on which instance and kernel version you are using. At the time of writing, kernel version `6.8.0-1024-aws` was used. 
 
 First, you need to install the linux performance measure tool, `perf`. Please follow the [installation guide](https://learn.arm.com/install-guides/perf/) for your system. 
 
@@ -33,7 +33,7 @@ L2 cache:                             4 MiB (4 instances)
 L3 cache:                             32 MiB (1 instance)
 ```
 
-This information will be useful as we want to ensure our working set size cannot all fit within on-CPU cache. 
+This information will be useful to ensure our working set size cannot all fit within on-CPU cache. 
 
 Next, check the current memory usage of an idle system with the `free -h` command.