From fc6e205c890a412a2b456d2933c5f9eb70dd5583 Mon Sep 17 00:00:00 2001
From: vijay chadachan <vijay.chadachan@firecell.io>
Date: Wed, 9 Oct 2024 15:49:44 +0200
Subject: [PATCH] Add documentation on TDD configuration

Co-authored-by: Robert Schmidt <robert.schmidt@openairinterface.org>
---
 doc/FEATURE_SET.md              |   4 +-
 doc/MAC/TDD_Frame_Structure.png | Bin 0 -> 4135 bytes
 doc/MAC/mac-usage.md            | 112 ++++++++++++++++++++++++++++++++
 3 files changed, 115 insertions(+), 1 deletion(-)
 create mode 100644 doc/MAC/TDD_Frame_Structure.png

diff --git a/doc/FEATURE_SET.md b/doc/FEATURE_SET.md
index 454faf1a1e..567187ac60 100644
--- a/doc/FEATURE_SET.md
+++ b/doc/FEATURE_SET.md
@@ -24,7 +24,9 @@
 
 The following features are valid for the gNB and the 5G-NR UE.
 
-*  Static TDD, FDD
+*  Static TDD
+   - Multi TDD pattern supported refer [TDD Configuration](NR_SA_Multi_TDD_Pattern.md)
+*  Static FDD
 *  Normal CP
 *  Subcarrier spacings: 15 and 30kHz (FR1), 120kHz (FR2)
 *  Bandwidths: 10, 20, 40, 60, 80, 100MHz
diff --git a/doc/MAC/TDD_Frame_Structure.png b/doc/MAC/TDD_Frame_Structure.png
new file mode 100644
index 0000000000000000000000000000000000000000..611be183d7c377480f624a5d35ef921d24899505
GIT binary patch
literal 4135
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

literal 0
HcmV?d00001

diff --git a/doc/MAC/mac-usage.md b/doc/MAC/mac-usage.md
index c3dbd6f199..f96f94d522 100644
--- a/doc/MAC/mac-usage.md
+++ b/doc/MAC/mac-usage.md
@@ -240,3 +240,115 @@ here, *also they pertain to the DU*, i.e., the scheduler.
   options are 2, 4, 6, 8, 10, 12, 32; **32 is a Rel-17 features**)
 * `num_ulharq` (default 16): as `num_dlharq` for UL (other valid option is 32;
   **32 is i Rel-17 feature**)
+
+## ServingCellConfigCommon parameters
+
+The `gNBs` configuration section has a big structure `servingCellConfigCommon`
+that has an influence on the overall behavior of MAC and L1. As the name says,
+this structure is a flat representation of the ServingCellConfigCommon
+structure, specified by 3GPP. Describing all of these parameters would be too
+exhaustive; more information about the individual fields can be found in 3GPP
+TS 38.331, section 6.3.2 "Radio resource control information elements".
+
+Below is a description of some of these parameters.
+
+### Frequency configuration
+
+There are many parameters, such as `absoluteFrequencySSB`, etc., that have an
+impact on the frequency used by the gNB. For more information, please check the
+[corresponding document](../gNB_frequency_setup.md).
+
+### TDD pattern configuration
+
+The TDD configuration parameters allow to use one or two TDD patterns.
+
+#### Single TDD pattern
+
+Configure the TDD pattern through these options:
+- `dl_UL_TransmissionPeriodicity`: Refers to the UL/DL slots periodicity for
+  the TDD pattern. See below for valid numbers.
+- `nrofDownlinkSlots`: Refers to the number of consecutive DL slots in the TDD
+  pattern. The number of DL slots depends on the TDD period.
+- `nrofDownlinkSymbols`: Indicates the number of consecutive DL symbols within
+  the special slot that follows the downlink slots in the TDD pattern. The
+  special slot is needed only to switch from DL to UL. The maximum number of
+  symbols in this slot is 14.
+- `nrofUplinkSlots`: Refers to the number of consecutive UL slots in the TDD
+  pattern, depending on the desired TDD period.
+- `nrofUplinkSymbols`: Indicates the number of consecutive UL symbols within
+  the special slot that follows the downlink slots in the TDD pattern. The sum
+  of downlink and uplink symbols should not exceed 14.
+- `prach_ConfigurationIndex`: index for PRACH according to tables 6.3.3.2-2 to
+  6.3.3.2-4 in TS 38.211.
+
+As an example, the below figure shows a single TDD pattern, consisting of 3 DL
+slots, 1 mixed slots (with 10 DL, 2 guard, 2 UL symbols), and 1 UL slot.
+
+![TDD Frame Structure](TDD_Frame_Structure.png)
+
+To configure this pattern in the configuration file, use
+
+```plaintext
+#dl_UL_TransmissionPeriodicity  0=ms0p5, 1=ms0p625, 2=ms1, 3=ms1p25, 4=ms2, 5=ms2p5, 6=ms5, 7=ms10, 8=ms3, 9=ms4
+
+dl_UL_TransmissionPeriodicity = 5;
+nrofDownlinkSlots             = 3;
+nrofDownlinkSymbols           = 10;
+nrofUplinkSlots               = 1;
+nrofUplinkSymbols             = 2;
+```
+
+The `dl_UL_TransmissionPeriodicity` is set to `5` (2.5ms). The above figure
+shows two TDD periods over 5ms. The 10 ms frame period must be strictly
+divisible by the sum of the TDD pattern periods.
+
+#### Two TDD patterns
+
+An optional `pattern2` structure is used to signal a TDD pattern 2.
+In this case, the TDD pattern may have two extended values of 3 ms and 4 ms.
+These values are standardized as `dl-UL-TransmissionPeriodicity-v1530`. For the
+sake of simplicity of the gNB configuration file, we have extended the set of
+`dl-UL-TransmissionPeriodicity` values to support the new TDD periods, as
+explained in the table below. However, these values will later be encoded as
+`dl-UL-TransmissionPeriodicity-v1530` to match the specifications.
+
+| `dl_UL_TransmissionPeriodicity` | TDD period |
+|---------------------------------|------------|
+| 0                               | 0.5 ms     |
+| 1                               | 0.625 ms   |
+| 2                               | 1 ms       |
+| 3                               | 1.25 ms    |
+| 4                               | 2 ms       |
+| 5                               | 2.5 ms     |
+| 6                               | 5 ms       |
+| 7                               | 10 ms      |
+| 8                               | 3 ms       |
+| 9                               | 4 ms       |
+
+The 10 ms frame period must be strictly divisible by the sum of the TDD pattern
+periods. For example, the 3 ms TDD pattern should be used with a second TDD
+pattern of 2 ms. Additionally, the 4 ms TDD pattern should be used with a
+second TDD pattern of 1 ms.
+
+As an example, this configuration might be used, where the first TDD pattern is
+followed by a second, consisting of 4 DL slots.
+```
+# pattern1
+# dl_UL_TransmissionPeriodicity
+# 0=ms0p5, 1=ms0p625, 2=ms1, 3=ms1p25, 4=ms2, 5=ms2p5, 6=ms5, 7=ms10
+# ext: 8=ms3, 9=ms4
+dl_UL_TransmissionPeriodicity  = 8;
+nrofDownlinkSlots              = 3;
+nrofDownlinkSymbols            = 6;
+nrofUplinkSlots                = 2;
+nrofUplinkSymbols              = 4;
+
+# pattern2
+pattern2: {
+    dl_UL_TransmissionPeriodicity2 = 4;
+    nrofDownlinkSlots2             = 4;
+    nrofDownlinkSymbols2           = 0;
+    nrofUplinkSlots2               = 0;
+    nrofUplinkSymbols2             = 0;
+};
+```