Update README.md

README.md

@@ -7,6 +7,7 @@
 1. [How to compile](#how-to-compile)
 1. [Using cachix to build speed up](#using-cachix-to-build-speed-up)
 1. [How to modify or add new hardware](#how-to-modify-or-add-new-hardware)
+1. [Hardware description file structure](#hardware-description-file-structure)
 1. [How to add a new virtual machine for existing HW](#how-to-add-a-new-virtual-machine-for-existing-HW)
 1. [Ghaf documentation links](#ghaf-documentation-links)
 1. [Release notes](#release-notes)
@@ -90,7 +91,128 @@ total 36
 - If you wifh to modify existing hardware you can start from modifying any of other HW descriptions
 - HW description with `-public` suffix means that it can be built as open-source SW without any proprietary software included
 
+# Hardware description file structure
+Hardware description file is 100% valid nix file made to be as close to regular JSON file as possible to make it readable and modifyable to those who have never seen NIX before.
+
+Typical hardware description file structure is following:
+```nix
+{
+  # system and host description
+  sysconf = {
+    name = "example";
+    description = "example OS with 2 VMs";
+    systemPackages = [
+      "vim"
+      "tcpdump"
+    ]; # systemPackages
+
+    # VMs description
+    vms = {
+      # NetVM -- the network VM
+      netvm = {
+        enable = true;
+        name = "netvm";
+        macaddr = "02:00:00:01:01:01";
+        ipaddr = "192.168.101.1";
+        systemPackages = [
+          "vim"
+          "tcpdump"
+        ]; # systemPackages
+        extraModules = [
+        {
+          networking = {
+            nat.enable = true;
+          }; # networking
+
+          microvm.devices = [
+            {
+              bus = "pci";
+              # Add yours network device here
+              path = "0000:72:00.0";
+            }
+          ]; # microvm.devices
+
+          # For WLAN firmwares
+          hardware.enableRedistributableFirmware = true;
+        }]; # extraModules
+      }; # netvm
+
+      # Dummy VM
+      dummyvm = {
+        enable = true;
+        name = "dummyvm";
+        macaddr = "02:00:00:01:01:03";
+        ipaddr = "192.168.101.12";
+        defaultgw = "192.168.101.1";
+        extraModules = [
+        {
+         networking.firewall.enable = false;
+        }]; # extraModules
+      }; # dummyvm
+    }; # vms
+  }; # system
+}
+```
+System description starts from:
+```nix
+{
+  sysconf = {
+  };
+}
+```
+`sysconf` is dictionary which describes whole system configuration. Also all root fields in `sysconf` mainly describe system HOST configuration, except `vms` field which describes virtual machines configurations.
+
+For examlple to add system packages to HOST you may use following configuration:
+```nix
+{
+  # system and host description
+  sysconf = {
+...
+    systemPackages = [
+      "your_super_package_to_add"
+      "tcpdump"
+    ]; # systemPackages
+  };
+}
+```
+
+If you wish to modify or add some default nix services or even add yours own service to HOST you need to use root's `extraModules` list:
+```nix
+extraModules = [];
+```
+
+`vms` field contains Virtual Machines configurations dictionary. Every field in this dict describes dedicated Virtual Machine and follow the same rules as HOST description.
+
+
 # How to add a new virtual machine for existing HW
+- Open Hardware Description file you want to modify
+- Find `vms` section
+- Add a new VM to `vms` section:
+```nix
+{
+  sysconf = {
+    ...
+    vms = {
+      ....
+      # Dummy VM
+      dummyvm = {
+        enable = true;
+        name = "dummyvm";
+        macaddr = "02:00:00:01:01:03";
+        ipaddr = "192.168.101.12";
+        defaultgw = "192.168.101.1";
+        extraModules = [
+        {
+         networking.firewall.enable = false;
+        }]; # extraModules
+      }; # dummyvm
+    ...
+    }; # vms
+  }; # sysconf
+}
+```
+- `name`, `ipaddr`, `macaddr` - mandatory and should be uniq
+- `extraModules` can be used to add additional services to VM
 
 
 # Ghaf documentation links