cleanup(docs): edit libs page content for technical clarity

Signed-off-by: Melissa Kilby <[email protected]>

docs/index.md

@@ -1,10 +1,13 @@
 # Falcosecurity drivers
 
-## Falco drivers kernel testing matrixes
+## Falco Drivers Kernel Testing
 
-Here you can find kernel testing support matrixes for [Falco](https://falco.org/) drivers.  
-For more info, make sure to read the [driver kernel testing framework proposal](https://github.com/falcosecurity/libs/blob/master/proposals/20230530-driver-kernel-testing-framework.md).  
+This page gives you the latest updates on Falco's kernel driver testing. We test each driver (kmod, bpf, modern_bpf) on various kernels and distributions (which we call the kernel testing matrix). These tests ensure that each driver not only compiles correctly, but also functions and provides the right events to userspace. These tests are super important to make sure Falco keeps working well and adopters can update or change their kernels without any problems. Another positive result for the project maintainers is the increased confidence in releasing new versions of Falco.
 
-## Syscalls Report
+To learn more, check out the [Kernel Testing Framework Proposal](https://github.com/falcosecurity/libs/blob/master/proposals/20230530-driver-kernel-testing-framework.md) and visit the official Falco [website](https://falco.org/).
 
-You can also find the list of supported syscalls by our drivers, be it through specific filler or generic.
+Navigate to the Home of Falco Drivers Kernel Testing on the left, or click this [link](matrix.md).
+
+## Supported Syscalls Report
+
+Navigate to the Home of Falco Drivers Syscalls Report on the left, or click this [link](syscalls.md), or directly proceed to the supported syscalls [report](report.md).

docs/matrix.md

@@ -1,17 +1,23 @@
-# Home of Falco drivers kernel testing matrixes
+# Home of Falco Drivers Kernel Testing
 
-Basically, we use Ansible playbooks to spawn Firecracker microvms where we can test:  
+## Test Procedures
 
-* kmod and ebpf drivers build
-* scap-open run with {kmod,ebpf,modern-bpf}
+We use Ansible playbooks to spawn Firecracker microVMs where we can test:
 
-The modern-bpf driver-enabled scap-open is built using the exactly same process used by [Falco release pipeline](https://github.com/falcosecurity/falco/blob/master/.github/workflows/reusable_build_packages.yaml#L15):   
+* kmod and bpf driver builds.
+* `scap-open` runs with {kmod,bpf,modern_bpf}.
 
-* the modern bpf skeleton is built on a Fedora machine
-* scap-open with embedded modern-bpf skeleton is built on a centos7 machine to allow largest possible support (old glibc version)
-* scap-open binary is copied to each spawned vm
+Going into more detail, we list kmod and bpf builds separately because these drivers need to be compiled specifically for each kernel release. In the actual microVM, we perform these builds using the corresponding system compiler (gcc for kmod and clang for bpf). That way, we ensure the use of the most appropriate compiler version.
 
-## Supported Archs
+In contrast, modern BPF isn't tied to a particular kernel release. This is because of the CO-RE (Compile Once - Run Everywhere) feature of the modern BPF driver. As a result, we only compile the modern BPF skeleton once and then include it into `scap` during the linking process -- exactly how it's done in the official [Falco release pipeline](https://github.com/falcosecurity/falco/blob/master/.github/workflows/reusable_build_packages.yaml#L15). You can find even more details about modern BPF in the libs [README](https://github.com/falcosecurity/libs/tree/master#build).
+
+Here's some information about the steps in this regard:
+
+* modern BPF skeleton is built on a Fedora machine.
+* `scap-open` with embedded modern BPF skeleton is built on a centos7 machine to allow broad support (old GLIBC versions).
+* `scap-open` binary is copied to each spawned VM.
+
+## Supported Architectures
 
 For now, supported architectures are:  
 
@@ -20,6 +26,8 @@ For now, supported architectures are:
 
 ## Glossary
 
-* 🟢 -> means that the test was successful
-* 🟡 -> means that the test was skipped; you can click the symbol to reach the test section and checkout why the test was skipped.
-* ❌ -> means that the test failed; you can click the symbol to reach the test section and checkout why the test failed.
+* 🟢 → test was successful.
+* 🟡 → test was skipped; you can click the symbol to reach the test section and checkout why the test was skipped.
+* ❌ → test failed; you can click the symbol to reach the test section and checkout why the test failed.
+
+Navigate to the AMD64 and ARM64 links on the left to view the results of their respective test matrices.

docs/report.md

@@ -1,3 +1,15 @@
+
+## Glossary
+
+The Falco Projects' kernel drivers support monitoring a range of syscalls. For a subset of syscalls (indicated with 🟡), we only monitor when the syscalls occur (internally in libs, we refer to these as generic syscalls), but we do not extract the syscall arguments.
+
+On the other hand, syscalls indicated with 🟢 in the report are fully monitored. This means we read and parse each syscall argument. You can learn more about the specific syscall arguments for these syscalls by referring to the libs' [event_table](https://github.com/falcosecurity/libs/blob/master/driver/event_table.c) or the official Linux man pages.
+
+* 🟢 → syscall is implemented as dedicated libsinsp event type and each argument of the syscall is extracted and parsed.
+* 🟡 → syscall is implemented as a generic event; we only monitor when the syscall occurs.
+
+## Supported Syscalls
+
 |         SYSCALL         | SUPPORTED |
 |-------------------------|-----------|
 | _sysctl                 | 🟡        |

docs/syscalls.md

@@ -1,10 +1,7 @@
-# Home of Falco drivers syscalls report
+# Home of Falco Drivers Syscalls Report
 
-Thanks to our [syscalls-bumper](https://github.com/falcosecurity/syscalls-bumper) project, we are able to always support latest syscalls added to linux kernel.  
-Support for new syscalls is initially automatically added by the tool as generic events; when needed, a generic event can be made "specific",  
-by creating a whole new event to track it.
+Thanks to our [syscalls-bumper](https://github.com/falcosecurity/syscalls-bumper) project, we can consistently support the latest syscalls added to the Linux kernel.
 
-## Glossary
+Our automation adds new syscalls as generic events, meaning we don't extract the syscall arguments. Instead, we solely monitor when the syscall occurs. If necessary, developers can create new parsers to extract and make available each syscall argument. Internally, we refer to the extractors on the kernel side as "fillers". This process also involves the creation of a new event type in libsinsp.
 
-* 🟢 -> means that the syscall is implemented as a specific event
-* 🟡 -> means that the syscall is implemented as a generic event
+Navigate to the Report on the left, or click this [link](report.md).