Add basic O1 telnet module

This adds a basic telnet module to support the O1 interface at the DU, to be used together with the oai/o1-adapter>. Concretely, this first version supports to - read/modify cell parameters - stop/start the L1
2024-12-16 16:18:11 +01:00
parent 68ae3ea11c
commit aba506e5e3
4 changed files with 575 additions and 1 deletions
@@ -0,0 +1,176 @@
+[[_TOC_]]
+
+The telnet O1 module (`telnetsrv_o1.c`) can be used to perform some O1-related
+actions (reading data, starting and stopping the nr-softmodem, reconfigurating
+frequency and bandwidth).
+
+# General usage
+
+The usage is similar to the general telnet usage, but in short:
+```
+./build_oai --ninja -c --gNB --nrUE --build-lib telnetsrv
+```
+to build everything including the telnet library.  Then, run the nr-softmodem
+by activating telnet and loading the `o1` module:
+```
+./nr-softmodem -O <config> --telnetsrv --telnetsrv.shrmod o1
+```
+
+Afterwards, it should be possible to connect via telnet on localhost, port
+9090. Use `help` to get help on the different command sections, and type e.g.
+`o1 stats` to get statistics (more information further below):
+
+```
+$ telnet 127.0.0.1 9090
+Trying 127.0.0.1...
+Connected to 127.0.0.1.
+Escape character is '^]'.
+
+softmodem_gnb> help
+[...]
+   module 4 = o1:
+      o1 stats
+      o1 config ?
+      o1 stop_modem
+      o1 start_modem
+[...]
+softmodem_gnb> o1 stats
+[...]
+softmodem_gnb> exit
+Connection closed by foreign host.
+```
+
+It also possible to send a command "directly from the command line", by piping
+the command into netcat:
+```
+echo o1 stats | nc -N 127.0.0.1 9090
+```
+
+Note that only one telnet client can be connected at a time.
+
+# Get statistics
+
+Use the `o1 stats` command. The output is in JSON format:
+```json
+{
+  "o1-config": {
+    "BWP": {
+      "dl": [
+        {
+          "bwp3gpp:isInitialBwp": true,
+          "bwp3gpp:numberOfRBs": 106,
+          "bwp3gpp:startRB": 0,
+          "bwp3gpp:subCarrierSpacing": 30
+        }
+      ],
+      "ul": [
+        {
+          "bwp3gpp:isInitialBwp": true,
+          "bwp3gpp:numberOfRBs": 106,
+          "bwp3gpp:startRB": 0,
+          "bwp3gpp:subCarrierSpacing": 30
+        }
+      ]
+    },
+    "NRCELLDU": {
+      "nrcelldu3gpp:ssbFrequency": 641280,
+      "nrcelldu3gpp:arfcnDL": 640008,
+      "nrcelldu3gpp:bSChannelBwDL": 40,
+      "nrcelldu3gpp:arfcnUL": 640008,
+      "nrcelldu3gpp:bSChannelBwUL": 40,
+      "nrcelldu3gpp:nRPCI": 0,
+      "nrcelldu3gpp:nRTAC": 1,
+      "nrcelldu3gpp:mcc": "208",
+      "nrcelldu3gpp:mnc": "95",
+      "nrcelldu3gpp:sd": 16777215,
+      "nrcelldu3gpp:sst": 1
+    },
+    "device": {
+      "gnbId": 1,
+      "gnbName": "gNB-Eurecom-5GNRBox",
+      "vendor": "OpenAirInterface"
+    }
+  },
+  "O1-Operational": {
+    "frame-type": "tdd",
+    "band-number": 78,
+    "num-ues": 1,
+    "ues": [
+      6876
+    ],
+    "load": 9,
+    "ues-thp": [
+      {
+        "rnti": 6876,
+        "dl": 3279,
+        "ul": 2725
+      }
+    ]
+  }
+}
+```
+
+Note that no actual JSON engine is used, so no actual verification is done; it
+is for convenience of the consumer. To verify, you can employ `jq`:
+```
+echo o1 stats | nc -N 127.0.0.1 9090 | awk '/^{$/, /^}$/' | jq .
+```
+(`awk`'s pattern matching makes that only everything between the first `{` and
+its corresponding `}` is printed).
+
+There are two sections:
+1. `.o1-config` show some stats that map directly to the O1 Netconf model. Note
+   that only one MCC/MNC/SD/SST (each) are supported right now. Also, note that
+   as per 3GPP specifications, SD of value `0xffffff` (16777215 in decimal)
+   means "no SD". `bSChannelBwDL/UL` is reported in MHz.
+2. `.O1-operational` output some statistics that do not map yet to any netconf
+   parameters, but that might be useful nevertheless for a consumer.
+
+# Write a new configuration
+
+Use `o1 config` to write a configuration:
+```
+echo o1 config nrcelldu3gpp:ssbFrequency 620736 nrcelldu3gpp:arfcnDL 620020 nrcelldu3gpp:bSChannelBwDL 51 bwp3gpp:numberOfRBs 51 bwp3gpp:startRB 0 | nc -N 127.0.0.1 9090
+```
+You have to pass the above parameters in exactly this order. The softmodem
+needs to be stopped; it will pick up the new configuration when starting the
+softmodem again.
+
+Note that you cannot switch three-quarter sampling for this as of now.
+
+For values of the configuration, refer to the next section.
+
+# Use hardcoded configuration
+
+Use `o1 bwconfig` to write a hard-coded configuration for 20 or 40 MHz cells:
+```
+echo o1 bwconfig 20 | nc -N 127.0.0.1 9090
+echo o1 bwconfig 40 | nc -N 127.0.0.1 9090
+```
+
+The softmodem needs to be stopped; it will pick up the new configuration when
+starting the softmodem again.
+
+Use `o1 stats` to see which configurations are set by these commands for the
+parameters `nrcelldu3gpp:ssbFrequency`, `nrcelldu3gpp:arfcnDL`,
+`nrcelldu3gpp:arfcnUL`, `nrcelldu3gpp:bSChannelBwDL`,
+`nrcelldu3gpp:bSChannelBwUL`, and `bwp3gpp:numberOfRBsbwp3gpp:startRB`.
+Furthermore, for 20MHz, it *disables* three-quarter sampling, whereas it
+*enables* three-quarter sampling for 40MHz.
+
+# Restart the softmodem
+
+Use `o1 stop_modem` to stop the `nr-softmodem`. To restart the softmodem, use
+`o1 start_modem`:
+```
+echo o1 stop_modem | nc -N 127.0.0.1 9090
+echo o1 start_modem | nc -N 127.0.0.1 9090
+```
+
+In fact, stopping terminates all L1 threads. It will be as if the softmodem
+"freezes", and no periodical output of statistics will occur (the O1 telnet
+interface will still work, though). Starting again will "defreeze" the
+softmodem.
+
+Upon restart, the DU sends a gNB-DU configuration update to the CU to inform it
+about the updated configuration. Therefore, this also works in F1.