DOCUMENTATION: configs readme (#444)

closes #443

---------

Co-authored-by: Alexey Zharkov <62723911+Az3git@users.noreply.github.com>

Author: PaulRalnikov

configuration_examples/README.md

@@ -1,62 +1,99 @@
-# Datacenter Topology File Format
+# General configs information
 
-This document describes the structure of the YAML file used to define datacenter network topologies, including hosts,
-switches, and links between them.
+## Units data format
 
-## Structure Overview
+In all configs you may see fields that contains time, size and speed. All of them have same format: `<value><unit>` where `value` is an integer and `unit` is small string suffix. For each unit where are fixed list of available units that you may see below.
 
-The topology file is divided into multiple sections, each representing a different network topology. Each topology
-consists of:
+### Available time units:
 
-- `devices`: Defines devices: senders, receivers and switches.
+- `ns`: Nanosecond
+- `us`: Microsecond
+- `ms`: Millisecond
+- `s`: Second
 
-- `links`: Specifies connections between devices with network parameters.
+### Available size units:
 
-## Sections
+- `b`: bit
+- `B`: Byte
+- `Mb`: Megabit
+- `MB`: Megabyte
+- `Gb`: Gigabit
+- `GB`: Gigabyte
 
-### Devices
+### Available speed units:
 
-Each host entry represents a device:
+- `Mbps`: Megabits per second
+- `Gbps`: Gigabits per second
 
-```yaml
-devices:
-  device_name:
-    type: [ sender | receiver | switch ]
-```
+Examples:
+- Time: `1ns`, `2s`,
+- Size: `1Mb`, `5GB`
+- Speed: `2Gpbs`, `3Mbps`
 
-- `device_name`: Unique identifier for the device.
+## Presets
 
-- `type`: Defines device type.
-
-### Links
+For some config parts you may create presets - common set of fields for the objects. For example, in topology configs it may looks like
+```yaml
+presets:
+  links:
+    best-link:
+      latency: 1000ns
+      throughput: 10Gbps
+      ingress_buffer_size: 4096B
+      egress_buffer_size: 4096B
+  switches:
+    really-best-switch:
+      ecn:
+        min: 0.2
+        max: 0.4
+        probability: 0.8
+    bad-switch:
+      ecn:
+        min: 1.0
+        max: 1.0
+        probability: 0.0
+```
 
-Each link defines a connection between two devices:
+To use your preset, fill in `preset-name` field in concrete object description:
 
 ```yaml
+switches:
+  switch-1:
+    preset-name: really-best-switch
+  switch-2:
+    preset-name: bad-switch
 links:
-  link_id:
-    from: <source_device>
-    to: <destination_device>
-    latency: <value><unit>
-    throughput: <value><unit>
-    ingress_buffer_size: <value>B
-    egress_buffer_size: <value>B
+  link1-2:
+    preset-name:  best-link
+    from: switch-1
+    to: switch-2
+  link2-1:
+    preset-name: best-link
+    from: switch-2
+    to: switch-1
+    throughput: 10Gpps # overrides value from preset
 ```
 
-- `link_id`: Unique identifier for the link.
-
-- `from`: Source device name.
-
-- `to`: Destination device name.
+## Default preset
 
-- `latency`: Transmission delay (e.g., 5ns).
+To shorten the configs length, you may fill default preset that used for all objects in description of which `preset-name` does not set (or set to `default`):
 
-- `throughput`: Link bandwidth (e.g., 1Gbps).
-
-- `ingress_buffer_size`: Link ingress buffer size in bytes (e.g., 1024B)
-
-- `egress_buffer_size`: Link egress buffer size in bytes (e.g., 1024B)
-
-### Examples images
+```yaml
+presets:
+  links:
+    default:
+      latency: 1000ns
+      throughput: 10Gbps
+      ingress_buffer_size: 4096B
+      egress_buffer_size: 4096B
+links:
+   link-1:
+      from: device-1
+      to: device-2
+      # other fields takes from default preset
+    link-1:
+      preset-name: default # works similarly with link-1
+      from: device-2
+      to: device-1
 
-You may generate images of topologies using the [generator](../scripts/generate_image.py) script.
+```

configuration_examples/simulation_examples/README.md

@@ -0,0 +1,66 @@
+# Datacenter Topology Simulation Config Format
+
+This document describes the structure of the YAML file used to define datacenter simulation config format, including connections, flows other settings.
+
+## Structure Overview
+
+The topology file is divided into multiple sections:
+
+- `topology_config_path`: path (absolute or relative) to the topology config.
+
+- `simulation_time`: maximal time of simulation in [time format](../README.md); optional field
+
+- `connections` : Defines connections
+
+## Connections
+
+`connections` sections looks like:
+
+```yaml
+connections:
+  sender_id: <source_device>
+  receiver_id: <destination_device>
+  packet_to_send: <count_of_packets>
+  mpld: round_robin
+  flows:
+    # flows section; see it below
+```
+
+- `sender_id` and receiver_id should be the names of hosts  from topology config.
+- `packets_to_send` is an integer
+- `mplb` is multipath load ballansing type. The only availabe value is `round_robin`
+
+# Flows section
+
+Each flow describes flow from `source_id` to `receiver_id`:
+
+```yaml
+flows:
+  flow_id:
+    type: tcp
+      packet_size: <size>
+      cc:
+        # congestion control settings; see it below
+```
+
+- `flow_id` is an unique name of flow (names of flows from different connections may be equal)
+- `type` is a type of flow. The only avaliable value is tcp
+- `packet_size` is an number in [size format](../README.md)
+- `cc` describes congestion control module of flow. See more details below
+
+# `cc` section in tcp flow
+
+`cc` module looks like:
+
+```yaml
+cc:
+  type: basic|tahoe|swift
+  # rest values specific for given congestion control type
+```
+
+`type` describes type of congestion control:
+
+- `basic`: no congestion control; no specific values
+- `tahoe`: [tcp tahoe](https://www.geeksforgeeks.org/computer-networks/tcp-tahoe-and-tcp-reno/) congestion control; no specific values
+- `swift`: [swift](https://2022-cs244.github.io/papers/L5-swift.pdf) congestion control (especialle see pseudocode on page 516); one specific value:
+  + `target_delay`: value from paper above in [time format](../README.md)

configuration_examples/topology_examples/README.md

@@ -0,0 +1,88 @@
+# Datacenter Topology Config Format
+
+This document describes the structure of the YAML file used to define datacenter network topologies, including hosts,
+switches, and links between them.
+
+## Structure Overview
+
+The topology file is divided into multiple sections, each representing a different network topology. Each topology
+consists of:
+
+- `packet-spraying`: defines packet spraying type and its settings if needed
+
+- `hosts`: Defines hosts
+
+- `switches` : Defines switches
+
+- `links`: Specifies connections between devices (hosts and switches) with network parameters.
+
+## Sections
+
+### Packet spraying
+
+Structure:
+```yaml
+packet-spraying:
+  type: random|ecmp|salt|flowlet 
+```
+
+If type is flowlet, it needs to set field `threshold` in [time format](../README.md)
+
+### Hosts
+
+Each host entry represents a host:
+
+```yaml
+hosts:
+  host_name: 
+```
+
+`host_name` should be unique 
+
+### Switches
+
+Each switches entry represents a switch:
+
+```yaml
+switches:
+  switch_name:
+    ecn:
+      min:
+      max:
+      probability:
+```
+- `switch_name` is unique name of switch
+- `ecn` is optional and describes settings Explicit Congestion Notification settings. You can see more about it [here](https://man7.org/linux/man-pages/man8/tc-red.8.html)  
+
+### Links
+
+Each link defines a connection between two devices:
+
+```yaml
+links:
+  link_id:
+    from: <source_device>
+    to: <destination_device>
+    latency: <value>
+    throughput: <value>
+    ingress_buffer_size: <value>
+    egress_buffer_size: <value>
+```
+
+- `link_id`: Unique identifier for the link.
+
+- `from`: Source device name.
+
+- `to`: Destination device name.
+
+- `latency`: Transmission delay in [time format](../README.md)
+
+- `throughput`: Link bandwidth in [speed format](../README.md)
+
+- `ingress_buffer_size`: Link ingress buffer size in [size format](../README.md)
+
+- `egress_buffer_size`: Link egress buffer size in [size format](../README.md)
+
+### Examples images
+
+You may generate images of topologies using the [generator](../../scripts/generate_image.py) script.

scripts/check-md-links.py

@@ -35,21 +35,22 @@ def check_links_in_markdown(file_path : str):
             response = requests.head(link_url, allow_redirects=True)
             if response.status_code != 200:
                 raise requests.exceptions.ConnectionError(f"Can not access to {link_url}")
-            print(f"{link_url} is link to an avaliable site")
+            print(f"{link_url} is link to an available site")
         except requests.exceptions.RequestException:
+            print(f"{link_url} is not an available site; returned code {response.status_code}")
             incorrect_links.append(link_url)
     if len(incorrect_links) == 0:
         print()
         print("All links are correct!")
         return True
-    print("Found incorrect links. Each of them is neither the correct path to a file nor a link to an avaliable site:", file=sys.stderr)
+    print("Found incorrect links. Each of them is neither the correct path to a file nor a link to an available site:", file=sys.stderr)
     for link in incorrect_links:
         print(f"link: {link}", file=sys.stderr)
         print("====================", file=sys.stderr)
     return False
 def main():
     parser = argparse.ArgumentParser(
-        description="Check that all the links in given markdown file are correct pathes to some files or the links to the avaliable sites"
+        description="Check that all the links in given markdown file are correct pathes to some files or the links to the available sites"
     )
     parser.add_argument("-f", "--file", help="Path to the file to be checked", required=True)
     args = parser.parse_args()

source/parser/parse_utils.cpp

@@ -24,12 +24,12 @@ static std::pair<uint32_t, std::string> parse_value_unit(
 
 SpeedGbps parse_speed(const std::string &throughput) {
     auto [value, unit] = parse_value_unit(throughput);
-    if (unit == "Gbps") {
-        return SpeedGbps(value);
-    }
     if (unit == "Mbps") {
         return Speed<MBit, Second>(value);
     }
+    if (unit == "Gbps") {
+        return SpeedGbps(value);
+    }
     throw std::runtime_error("Unsupported throughput unit: " + unit);
 }
 
@@ -38,19 +38,43 @@ TimeNs parse_time(const std::string &time) {
     if (unit == "ns") {
         return TimeNs(value);
     }
+    if (unit == "us") {
+        return Time<Microsecond>(value);
+    }
+    if (unit == "ms") {
+        return Time<Millisecond>(value);
+    }
+    if (unit == "s") {
+        return Time<Second>(value);
+    }
     throw std::runtime_error("Unsupported time unit: " + unit);
 }
 
 SizeByte parse_size(const std::string &size) {
     auto [value, unit] = parse_value_unit(size);
+    if (unit == "b") {
+        return Size<Bit>(value);
+    }
     if (unit == "B") {
         return SizeByte(value);
     }
+    if (unit == "Kb") {
+        return Size<KBit>(value);
+    }
     if (unit == "KB") {
         return Size<KByte>(value);
     }
+    if (unit == "Mb") {
+        return Size<MBit>(value);
+    }
     if (unit == "MB") {
         return Size<MByte>(value);
     }
+    if (unit == "Gb") {
+        return Size<GBit>(value);
+    }
+    if (unit == "GB") {
+        return Size<GByte>(value);
+    }
     throw std::runtime_error("Unsupported buffer size unit: " + unit);
 }

source/units/time.hpp

@@ -15,7 +15,7 @@ struct Microsecond {
     static constexpr uint64_t to_nanoseconds_multiplier = 1'000;
 };
 
-struct Milisecond {
+struct Millisecond {
     static constexpr uint64_t to_nanoseconds_multiplier = 1'000'000;
 };