From 14270ad7b3f7fb86296ffabc0e048deedf644c52 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ciro=20Santilli=20=E5=85=AD=E5=9B=9B=E4=BA=8B=E4=BB=B6=20?=
 =?UTF-8?q?=E6=B3=95=E8=BD=AE=E5=8A=9F?= <ciro.santilli@gmail.com>
Date: Sun, 5 May 2019 00:00:00 +0000
Subject: [PATCH] userland: document path_properties

---
 README.adoc        | 33 ++++++++++++++++++++++++++++++++-
 path_properties.py |  5 ++++-
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/README.adoc b/README.adoc
index 701236f..e301b51 100644
--- a/README.adoc
+++ b/README.adoc
@@ -3824,7 +3824,7 @@ First we build Dhrystone manually statically since dynamic linking is broken in
 gem5 user mode:
 
 ....
-./build-buildroot --config 'BR2_PACKAGE_DHRYSTONE=y' --arch arm
+./build-buildroot --arch arm --config 'BR2_PACKAGE_DHRYSTONE=y'
 make \
   -B \
   -C "$(./getvar --arch arm buildroot_build_build_dir)/dhrystone-2" \
@@ -3921,6 +3921,37 @@ Error while loading /path/to/linux-kernel-module-cheat/out/userland/default/x86_
 
 Tested in de77c62c091f6418e73b64e8a0a19639c587a103 + 1.
 
+=== User mode simulation path_properties
+
+In order to build and run each example properly, we need some file metadata which is stored in link:path_properties.py[] at `path_properties_tuples`.
+
+Maybe we should embed it magically into source files directories? But this was easier to implement so we started like this.
+
+The format is as follows:
+
+....
+'path_component': (
+    {'property': value},
+    {
+        'child_path_component':
+        {
+            {'child_property': },
+            {}
+        }
+    }
+)
+....
+
+and as a shortcut, paths that don't have any children can be written directly as:
+
+.....
+'path_component': {'property': value}
+.....
+
+Properties of parent directories apply to all children.
+
+Lists coming from parent directories are extended instead of overwritten by children, this is especially useful for C compiler flags.
+
 == Kernel module utilities
 
 === insmod
diff --git a/path_properties.py b/path_properties.py
index 108b618..f8ba3c6 100644
--- a/path_properties.py
+++ b/path_properties.py
@@ -144,6 +144,7 @@ freestanding_properties = {
     ],
     'extra_objs_userland_asm': False,
 }
+# See: https://github.com/cirosantilli/linux-kernel-module-cheat#user-mode-simulation-path_properties
 path_properties_tuples = (
     {
         'allowed_archs': None,
@@ -276,7 +277,9 @@ path_properties_tuples = (
                         'libdrm': {'sudo': True},
                     }
                 ),
-                'linux': {**gnu_extension_properties, **{'skip_run_unclassified': True}},
+                'linux': (
+                    {**gnu_extension_properties, **{'skip_run_unclassified': True}},
+                )
                 'posix': (
                     {},
                     {