From: Stefan Jumarea <stefanjumarea02@gmail.com>
Date: Mon, 27 Nov 2023 13:45:13 +0000 (+0200)
Subject: lib/posix-sysinfo: Add README.md file
X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=e7ab4f5e4df8f3bf29a0338a180695135c117cfd;p=unikraft%2Funikraft.git

lib/posix-sysinfo: Add README.md file

Add a minimal README that includes basic information abot the library,
as well as a simple application example.

Signed-off-by: Stefan Jumarea <stefanjumarea02@gmail.com>
---

diff --git a/lib/posix-sysinfo/README.md b/lib/posix-sysinfo/README.md
new file mode 100644
index 000000000..091377330
--- /dev/null
+++ b/lib/posix-sysinfo/README.md
@@ -0,0 +1,65 @@
+# `posix-sysinfo`: Unikraft's System Information Internal Library
+
+`posix-sysinfo` is an internal library of Unikraft that provides a similar interface to the Linux system information related syscalls (`sysinfo`, `uname`, etc.).
+
+The `struct sysinfo` and `struct utsname` structures follow the Linux conventions.
+The Unikraft `sysinfo` library will not fill all the items in the `struct sysinfo` structure, some of them will be set to 0 (such as `uptime`, `loads`, `*swap`, `*high`).
+For memory-related fields to be populated (`*ram`, `mem_unit`), the `Virtual memory API` config option must be selected from the `Platform Configuration -> Platform Interface Options` configuration screen.
+
+## Configuring applications to use `posix-sysinfo`
+
+You can select `posix-sysinfo` under the `Library Configuration` screen of the `make menuconfig` command.
+After that, you can use the functions eposed by the internal library just like you would for a Linux system,
+
+An example of a simple application that uses the `posix-sysinfo` library is the following:
+
+```c
+#include <stdio.h>
+#include <sys/sysinfo.h>
+#include <sys/utsname.h>
+
+int main(int argc, char *argv[])
+{
+        struct sysinfo info;
+        struct utsname utsn;
+
+        sysinfo(&info);
+        uname(&utsn);
+
+        printf("Nr proc: %hu\n", info.procs);
+        printf("Kernel release: %s\n", utsn.release);
+
+        return 0;
+}
+```
+
+To configure, build and run the application, follow the steps below:
+
+1. Enter the configuration interface:
+
+```console
+make menuconfig
+```
+
+1. Enter the `Library Configuration` menu and select `posix-sysinfo`
+1. Build the application using `make`
+1. Run the application using `qemu-system`.
+   If the application was built for `x86_64`, run using the following command:
+
+```console
+qemu-system-x86_64 -kernel <path-to-application-image> -nographic
+```
+
+This should print an output similar to:
+
+```text
+Booting from ROM..Powered by
+o.   .o       _ _               __ _
+Oo   Oo  ___ (_) | __ __  __ _ ' _) :_
+oO   oO ' _ `| | |/ /  _)' _` | |_|  _)
+oOo oOO| | | | |   (| | | (_) |  _) :_
+ OoOoO ._, ._:_:_,\_._,  .__,_:_, \___)
+                Pandora 0.15.0~423d8933
+Nr proc: 1
+Kernel release: 5-Pandora
+```