Merge remote-tracking branch 'origin/iqplayer_doc' into integration_2023_w16

doc/README.md

@@ -88,7 +88,7 @@ Some directories under `radio` contain READMEs:
 - [RFsimulator](../radio/rfsimulator/README.md)
 - [USRP](../radio/USRP/README.md)
 - [BladeRF](../radio/BLADERF/README)
-- [IQPlayer](../radio/iqplayer/DOC/iqrecordplayer_usage.md)
+- [IQPlayer](../radio/iqplayer/DOC/iqrecordplayer_usage.md), and [general documentation](./iqrecordplayer_usage.md)
 
 The other SDRs (AW2S, LimeSDR, ...) have no READMEs.
 

doc/iqrecordplayer_usage.md

+# I/Q record-replay
+## using the iq record-replay
+
+This feature provides I/Q record-replay as initially presented in the 4th OAI workshop for LTE
+(https://www.openairinterface.org/docs/workshop/4_OAI_Workshop_20171107/Talks/MONGAZON_Nokia-Bell-Labs-OAI-IQ.pdf)
+The current implementation has been temporarily disrupted for LTE and only works for 5G SA
+nr-uesoftmodem executable.
+
+The I/Q record-replay feature is briefly described hereafter, it allows you to:
+* record slots received by the USRP board in a file while the system is operating.
+  For example you can record a full nrUE connection/traffic/disconnection sequence.
+  Today the OAI USRP device is the only one supporting the recording feature. 
+* replay slots from a previously recorded file to operate the system,
+  possibly in multiple loops if the recorded sequence is convenient from the logical point of view. 
+
+The record-replay features are activated and configured using OAI configuration parameters
+
+### Record mode
+options for record mode are:
+* `subframes-record` Activate record mode
+* `subframes-file`   Path of the file used for slots recording (default is `/tmp/iqfile`)
+* `subframes-max`    Maximum count of slots to be recorded in a file (default is 120000)
+
+Note that the value of `--subframes-max` parameter needs to be tuned according to your RAM capabilities.
+The default value is 120000, which allows for 120 seconds of record-replay but will require ~20GB of RAM and disk space. 
+If RAM does not allow for the parameter value, an error message will be displayed and the run will be aborted.
+In record mode, to minimize performance impacts of operating software, slots are always saved into memory and
+written to disk when the process terminates.
+When you estimate the recorded sequence is achieved, you can terminate the nr-uesoftmodem by typing `CTRL-C`.
+At that time, up to the value of `--subframes-max` slots will be written on disk.
+The nr-uesoftmodem will indicate the exact count of slots written to disk, which may be less (but not higher)
+than the value of `--subframes-max` parameter.
+
+>Recording session example:
+```bash
+./nr-uesoftmodem -O /home/oaitests/mediatek_sim.conf --sa --nokrnmod 1 --numerology 1 -r 106 -C 3649440000 --band 78 -E --ue-fo-compensation --device.recplay.subframes-record 1 --device.recplay.subframes-file /home/iqs/oai-nrUE-17042023.dat --device.recplay.use-mmap 1 --device.recplay.subframes-max 30000
+............................................
+............................................
+............................................
+^C
+[HW]   Writing file header to /home/iqs/oai-nrUE-17042023.dat 
+[HW]   Writing 4565 subframes to /home/iqs/oai-nrUE-17042023.dat 
+[HW]   File /home/iqs/oai-nrUE-17042023.dat closed
+[HW]   releasing USRP
+
+### Replay mode
+Replaying I/Q works only for nr-uesoftmodem at 40MHz bandwidth 3/4 sampling.
+Mismatch between file content and run time parameters might lead to unpredictable results.
+options for replay mode are:
+* `subframes-replay` Activate replay mode
+* `subframes-file`   Path of the file used for slots replay (default is `/tmp/iqfile`)
+* `subframes-loops`  Number of iterations to replay the entire slots file (default is 5)
+* `use-mmap`         Boolean, set to 1 (true) by default, iq file is map to memory if true, otherwise iq's are read from file. 
+
+>Replay mode session example:
+```bash
+./nr-uesoftmodem -O /home/oaitests/mediatek_sim.conf --sa --nokrnmod 1 --numerology 1 -r 106 -C 3649440000 --band 78 -E --ue-fo-compensation --device.recplay.subframes-replay 1 --device.recplay.subframes-file /home/iqs/oai-nrUE-17042023.dat --device.recplay.use-mmap 1 --device.recplay.subframes-loops 1
+..................................
+..................................
+[HW]   Replay iqs from USRP B200 device, bandwidth 4.000000e+07
+[HW]   Loaded 4565 subframes.
+[HW]   iqplayer device initialized, replay /home/iqs/oai-nrUE-17042023.dat for 1 iteration(s)
+..................................
+..................................
+
+[OAI Wikis home](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/home)

radio/iqplayer/DOC/iqrecordplayer_usage.md

@@ -75,7 +75,7 @@ U[HW]I ru thread Writing file header to /tmp/iqfile
 ```
 
 ### Playback/replay mode
-When replaying iq's received by eNB or gNB The option works only for 5MHz bandwidth because the information stored in the iq's file header regarding bandwidth is not yet properly processed.  
+When replaying iq's received by eNB or gNB The option works only for 40MHz bandwidth 3/4 sampling because the information stored in the iq's file header regarding bandwidth is not yet properly processed. In addition the current implementation has only been validated with nr-uesoftmodem in 5G SA configuration.  
  In this version,  mismatch between file content and run time parameters might lead to unpredictable results. In addition a file recorded on a AVX2-capable processor cannot be replayed on a non-AVX2-capable processor (this is to be further investigated).
 options for replay mode are:
 * `subframes-replay` Activate replay mode
@@ -159,6 +159,6 @@ The replay feature is implemented as a oai device.
 * s device is automatically, dynamicaly loaded when the player feature is activated at runtime when the boolean  `device.recplay.subframes-replay` option is set.
 
 ### iq's file format
-The recorder adds a header containing the device type, the bandwith and a format identifier. Using these information when replaying a file has not yet been implemented, so the player only supports USRP B2xx device and 5MHz bandwith. 
+The recorder adds a header containing the device type, the bandwith and a format identifier. Using these information when replaying a file has not yet been implemented, so the player only supports USRP B2xx device and 40MHz bandwith 3/4 sampling. 
 
 [oai Wikis home](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/home)