From 4b93939b714c828e4bc5f98d07d21add30ae9331 Mon Sep 17 00:00:00 2001
From: Alex Kotov <kotovalexarian@gmail.com>
Date: Tue, 14 Dec 2021 04:56:31 +0500
Subject: [PATCH] Add example for PFA

---
 .gitignore     |  1 +
 Makefile.am    |  8 +++++++-
 examples/pfa.c | 43 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100644 examples/pfa.c

diff --git a/.gitignore b/.gitignore
index f391b9a..0cc67fb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -35,6 +35,7 @@
 /tests/test*.trs
 
 /examples/cmdline
+/examples/pfa
 /examples/printf
 /examples/printf_va
 /examples/units_human
diff --git a/Makefile.am b/Makefile.am
index 05ad93a..fad6c7d 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -62,7 +62,9 @@ endif
 
 if ENABLE_PFA
 libkernaux_a_SOURCES += src/pfa.c
-TESTS += tests/test_pfa
+TESTS += \
+	examples/pfa \
+	tests/test_pfa
 endif
 
 if ENABLE_UNITS
@@ -76,6 +78,10 @@ examples_cmdline_SOURCES = \
 	$(libkernaux_a_SOURCES) \
 	examples/cmdline.c
 
+examples_pfa_SOURCES = \
+	$(libkernaux_a_SOURCES) \
+	examples/pfa.c
+
 examples_printf_SOURCES = \
 	$(libkernaux_a_SOURCES) \
 	examples/printf.c
diff --git a/examples/pfa.c b/examples/pfa.c
new file mode 100644
index 0000000..2189690
--- /dev/null
+++ b/examples/pfa.c
@@ -0,0 +1,43 @@
+#include <kernaux/pfa.h>
+
+#include <assert.h>
+
+// Create PFA in some static memory area because typically you don't have memory
+// management in kernel before PFA is even used.
+struct KernAux_PFA pfa;
+
+int main()
+{
+    // In the earliest stage of kernel initialization mark all pages as
+    // unavailable because you don't have memory map yet.
+    KernAux_PFA_initialize(&pfa);
+
+    // Let's assume that you have the following memory map now:
+    // * [0 B; 64 KiB)
+    // * [1 MiB; 4 MiB)
+    // * [6 MiB; 128 MiB)
+    // Mark these pages as available. Note that page is identified by any
+    // address inside it. This is why you can subtract 1, not only
+    // KERNAUX_PFA_PAGE_SIZE.
+    KernAux_PFA_mark_available(&pfa, 0,               1024        * 64  - 1);
+    KernAux_PFA_mark_available(&pfa, 1024 * 1024,     1024 * 1024 * 4   - 1);
+    KernAux_PFA_mark_available(&pfa, 1024 * 1024 * 6, 1024 * 1024 * 128 - 1);
+
+    // You can test page availability.
+    assert(KernAux_PFA_is_available(&pfa,  1024 * 32));      // 32 KiB
+    assert(!KernAux_PFA_is_available(&pfa, 1024 * 64));      // 64 KiB
+    assert(KernAux_PFA_is_available(&pfa,  1024 * 1024));    // 1 MiB
+    assert(!KernAux_PFA_is_available(&pfa, 1024 * 1024 * 6   // 6 MiB - 4 KiB
+                                           - KERNAUX_PFA_PAGE_SIZE));
+    assert(KernAux_PFA_is_available(&pfa,  1024 * 1024 * 128 // 128 MiB - 4 KiB
+                                           - KERNAUX_PFA_PAGE_SIZE));
+    assert(!KernAux_PFA_is_available(&pfa, 1024 * 1024 * 128)); // 128 MiB
+
+    // When you have configured PFA, you can use it to allocate and free pages.
+    const size_t page_addr = KernAux_PFA_alloc_page(&pfa);
+    assert(!KernAux_PFA_is_available(&pfa, page_addr));
+    KernAux_PFA_free_page(&pfa, page_addr);
+    assert(KernAux_PFA_is_available(&pfa, page_addr));
+
+    return 0;
+}