Commit 2c357401 authored by frtabu's avatar frtabu
Browse files

telnet server and iq record player documentation update

parent f8037ab6
# telnet server principles
The oai telnet server is implemented in a shared library to be loaded by the [oai shared library loader](loader). The implementation includes a `telnetsrv_autoinit` function which is automatically called at load time, starts the telnet server and registers a first set of commands, which are delivered with the server (telnet, softmodem, loader).
The oai telnet server is implemented in shared libraries to be loaded by the [oai shared library loader](loader). `libtelnetsrv.so ` contains the code common to all oai softmodem executables, where `libtelnetsrv_<app>.so` contains the code specific to the executable identified by `app`.
| `<app>` | executable |
| :-----: | :---------------: |
| enb | `lte-softmodem` |
| gnb | `nr-softmodem` |
| 4Gue | `lte-uesoftmodem` |
| 5Gue | `nr-uesoftmodem` |
The implementation includes a `telnetsrv_autoinit` function which is automatically called at load time, starts the telnet server and registers a first set of commands, which are delivered with the server (telnet, softmodem, loader). it also uses the `get_softmodem_function` call to retrieve the running executable id and possibly loads the corresponding `libtelnetsrv_<app>.so`library.
Currently the telnet server only supports one user connection. The same dedicated thread is used to wait for a user connection and process the input received from this connection.
......@@ -12,10 +21,11 @@ The telnet server provides an API which can be used by any oai component to add
telnet server source files are located in [common/utils/telnetsrv](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/telnetsrv)
1. [telnetsrv.c](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/telnetsrv/telnetsrv.c) contains the telnet server implementation, including the implementation of the telnet CLI command.
1. [telnetsrv.c](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/telnetsrv/telnetsrv.c) contains the telnet server implementation, including the implementation of the `telnet` CLI command. This implementation is compatible with all softmodem executables and is in charge of loading any additional `libtelnetsrv_<app> .so` containing code specific to the running executables.
1. [telnetsrv.h](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/telnetsrv/telnetsrv.h) is the telnet server include file containing both private and public data type definitions. It also contains API prototypes for functions that are used to register a new command in the server.
1. `telnetsrv\_\<XXX\>.c`: implementation of \<XXX\> CLI command which are delivered with the telnet server.
1. `telnetsrv\_\<XXX\>.h`: include file for the implementation of XXX CLI command. Usually included only in the corresponding `.c`file
1. `telnetsrv_<XXX\>.c`: implementation of \<XXX\> CLI command which are delivered with the telnet server and are common to all softmodem executables.
1. `telnetsrv_<XXX\>.h`: include file for the implementation of XXX CLI command. Usually included only in the corresponding `.c`file
1. `telnetsrv_<app>_<XXX>.c`: implementation of \<XXX\> CLI command specific to the executable identified by \<app\>.These sources are used to create `libtelnetsrv_<app>.so` at build time.
1. [telnetsrv_CMakeLists.txt](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/telnetsrv/telnetsrv_CMakeLists.txt): CMakelists file containing the cmake instructions to build the telnet server. this file is included in the [global oai CMakelists](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/cmake_targets/CMakeLists.txt).
[oai telnet server home](telnetsrv.md)
......@@ -8,7 +8,7 @@ By default the embedded telnet server, which is implemented in a shared library,
./build_oai --build-lib telnetsrv
```
This will create the `libtelnetsrv.so` file in the `targets/bin` and `cmake_targets/ran_build/build` sub directories of the oai repository.
This will create the `libtelnetsrv.so` and `libtelnetsrv_<app> file in the `targets/bin` and `cmake_targets/ran_build/build` sub directories of the oai repository. <app> can be "enb", "gnb", "4GUE" or "5GUE", each library containing functions specific to a given executable.
When starting the softmodem, you must specify the **_\-\-telnetsrv_** option to load and start the telnet server. The telnet server is loaded via the [oai shared library loader](loader).
......
#I/Q record-playback
## using the iq recorder or iq player
This feature provides I/Q record-playback as presented in the 4th OAI workshop. Tests have only been performed with a eNB, but the implementation should allow any softmodem executable to use the iq's record/player.
The I/Q record/playback feature is briefly described hereafter, it allows you to:
* record subframes received by the USRP board in a file while the system is operating (for example you can record a full UE connection/traffic/ disconnection sequence). Today the oai USRP device is the only one supporting the recording feature.
* replay subframes from a file to operate the system (possibly in multiple loops if the recorded sequence is convenient from the logical point of view).
The record/replay 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 subframes recording (default is `/tmp/iqfile`)
* `subframes-max` Maximum count of subframes to be recorded in subframe 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 ~3.6GB 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, subframes are copied in specific memory records not to disrupt regular behavior. When you estimate the recorded sequence is achieved, you should terminate the eNB/RRU by typing `CTRL-C`. At that time, up to the value of --subframes-max parameter will be written on disk. The eNB/RRU will indicate the exact count of subframes written to disk, which may be less (but not higher) that the value of --subframes-max parameter (120000 by default). The number of subframes written to disk is rounded to an integral number of frames. When replaying a file you should always specify the exact number of subframes, and thus use the exact number of subframes written during recording. You might experiment unexpected behavior if the number of subframes to be replayed does not match the number of subframes recorded. This might be improved in the future.
Although it is possible to perform recording with a fronthaul setup, it is suggested to perform recording in full eNB mode and then replay in either full or split eNB.
The option can be used while operating full eNB or RCC/RRU linked by NGFI IF5/IF4p5 fronthaul techniques. One of the advantage of the record/replay technique is that you can replay on a fronthauling setup a file that has been recorded in full eNB mode. This can easily asserts that the fronthauling underlying set up or technique is correct.
>recording session example:
```bash
./lte-softmodem -O libconfig:/usr/local/oai/conf/enb.band7.tm1.20PRB.usrpb210.conf:dbgl5 --log_config.global_log_options level,thread --device.recplay.subframes-record 1
............................................
............................................
[CONFIG] device.recplay.subframes-file set to default value "/tmp/iqfile"
[CONFIG] subframes-record: 0
[CONFIG] device.recplay.subframes-record set to default value
[CONFIG] subframes-replay: 0
[CONFIG] device.recplay.subframes-replay set to default value
[CONFIG] subframes-max: 120000
[CONFIG] device.recplay.subframes-max set to default value
[CONFIG] subframes-loops: 5
[CONFIG] device.recplay.subframes-loops set to default value
[CONFIG] subframes-read-delay: 700
[CONFIG] device.recplay.subframes-read-delay set to default value
[CONFIG] subframes-write-delay: 15
[CONFIG] device.recplay.subframes-write-delay set to default value
[LIBCONFIG] device.recplay: 7/7 parameters successfully set, (7 to default value)
[CONFIG] subframes-record: 1
[CONFIG] device.recplay 1 options set from command line
[CONFIG] loader.oai_device.shlibversion set to default value ""
[LIBCONFIG] loader.oai_device: 2/2 parameters successfully set, (1 to default value)
[CONFIG] loader.oai_device 0 options set from command line
[LOADER] library liboai_device.so successfully loaded
USRP device initialized in subframes record mode
[HW]I lte-softmodem UHD version 3.14.1.1-release (3.14.1)
...................................................
...................................................
[PHY]I lte-softmodem prach_I0 = 0.0 dB
[PHY]I ru thread max_I0 18, min_I0 12
^C
Run time: 0h 26s
Time executing user inst.: 1s 865251us
Time executing system inst.: 2s 805162us
Max. Phy. memory usage: 4068328kB
Page fault number (no io): 1008741
Page fault number (requiring io): 15
Number of file system read: 97672
Number of filesystem write: 0
Number of context switch (process origin, io...): 562871
Number of context switch (os origin, priority...): 112
Linux signal Interrupt...
/usr/local/oai/develop/openairinterface5g/executables/softmodem-common.c:188 signal_handler() Exiting OAI softmodem: softmodem starting exit procedure
Exiting ru_thread
U[HW]I ru thread Writing file header to /tmp/iqfile
[HW]I lte-softmodem Writing file header to /tmp/iqfile
[HW]I ru thread Writing 19730 subframes to /tmp/iqfile
[HW]I lte-softmodem Writing 19730 subframes to /tmp/iqfile
[HW]I lte-softmodem File /tmp/iqfile closed
[HW]I ru thread File /tmp/iqfile closed
[PHY]I ru thread RU 0 rf device stopped
```
###Playback/replay mode
The option works only for 5MHz bandwidth because the information stored in the iq's file header regarding bandwidth is not yet properly processed.
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
* `subframes-file` Path of the file used for subframes replay (default is `/tmp/iqfile`)
* `subframes-loops` Number of iterations to replay the entire subframes file (default is 5)
* `subframes-read-delay` Delay in microseconds to read a subframe in replay mode (default 200)
* `subframes-write-delay` Delay in milliseconds to write a subframe in replay mode (default 15)
>iq player session example:
```bash
./lte-softmodem -O libconfig:/usr/local/oai/conf/enb.nbiot.band7.tm1.50PRB.usrpb210.conf:dbgl5 --T_stdout 1 --log_config.global_log_options level,thread --eNBs.[0].component_carriers.[0].N_RB_DL 25 --device.recplay.subframes-replay 1
[CONFIG] get parameters from libconfig /usr/local/oai/conf/enb.nbiot.band7.tm1.50PRB.usrpb210.conf , debug flags: 0x00000005
................................
..................................
[PHY]I lte-softmodem rxdataF[0] 0x55f52df52f40 for RU 0
[CONFIG] device.recplay.subframes-file set to default value "/tmp/iqfile"
[CONFIG] subframes-record: 0
[CONFIG] device.recplay.subframes-record set to default value
[CONFIG] subframes-replay: 0
[CONFIG] device.recplay.subframes-replay set to default value
[CONFIG] subframes-max: 120000
[CONFIG] device.recplay.subframes-max set to default value
[CONFIG] subframes-loops: 5
[CONFIG] device.recplay.subframes-loops set to default value
[CONFIG] subframes-read-delay: 700
[CONFIG] device.recplay.subframes-read-delay set to default value
[CONFIG] subframes-write-delay: 15
[CONFIG] device.recplay.subframes-write-delay set to default value
[LIBCONFIG] device.recplay: 7/7 parameters successfully set, (7 to default value)
[CONFIG] subframes-replay: 1
[CONFIG] device.recplay 1 options set from command line
[CONFIG] loader.oai_iqplayer.shlibversion set to default value ""
[LIBCONFIG] loader.oai_iqplayer: 2/2 parameters successfully set, (1 to default value)
[CONFIG] loader.oai_iqplayer 0 options set from command line
[LOADER] library liboai_iqplayer.so successfully loaded
[HW]I lte-softmodem Loading subframes using mmap() from /tmp/iqfile size=324433632 bytes ...
[HW]I lte-softmodem Replay iqs from USRP B200 device, bandwidth 5.000000e+06
[HW]I lte-softmodem Loaded 10550 subframes.
[HW]I lte-softmodem iqplayer device initialized, replay /tmp/iqfile for 5 iterations[HW]I lte-softmodem [RAU] has loaded USRP B200 device.
.............................................
.............................................
[PHY]I ru thread max_I0 18, min_I0 12
[PHY]I lte-softmodem prach_I0 = 0.0 dB
[PHY]I ru thread max_I0 18, min_I0 0
[HW]I ru thread starting subframes file with wrap_count=1 wrap_ts=81024000 ts=107616555
[PHY]I lte-softmodem prach_I0 = 0.0 dB
[PHY]I ru thread max_I0 18, min_I0 12
[HW]I ru thread starting subframes file with wrap_count=2 wrap_ts=162048000 ts=188640555
[PHY]I lte-softmodem prach_I0 = 0.0 dB
[PHY]I ru thread max_I0 18, min_I0 0
[HW]I ru thread starting subframes file with wrap_count=3 wrap_ts=243072000 ts=269664555
[PHY]I lte-softmodem prach_I0 = 0.0 dB
[PHY]I ru thread max_I0 19, min_I0 12
[HW]I ru thread starting subframes file with wrap_count=4 wrap_ts=324096000 ts=350688555
[PHY]I lte-softmodem prach_I0 = 0.0 dB
[PHY]I ru thread max_I0 18, min_I0 12
[HW]W ru thread iqplayer device terminating subframes replay after 5 iteration
/usr/local/oai/develop/openairinterface5g/targets/ARCH/iqplayer/iqplayer_lib.c:222 trx_iqplayer_read() Exiting OAI softmodem: replay ended, triggering process termination
```
## iq recorder and iq player implementation overview
###configuration
The iq's record/player is using the [configuration module](../../../../common/config/DOC/config.md). Configuration parameters supported by the record player are defined in the [record_player.h](../../COMMON/record_player.h) include file.
There are no specific sections for the recorder or the replayer, parameters are defined under the `device.recplay`section and the `read_recplayconfig` function is common to both the recorder and the player. `device.recplay` configuration section is read from oai code common to all devices:
Implemented in [record_player.c](../../COMMON/record_player.c), the `read_recplayconfig` function is called from `load_lib` and reads the configuration parameters, saving them in a `recplay_conf_t` sub-structure of the oai device. It also allocates a `recplay_state_t` structure which will save the recorder or player data.
3GPP authentication algorithm doesn't allow session establishment via replaying iq's. When using the replayer, a softmodem parameter is set (`SOFTMODEM_RECPLAY_BIT` in the `optmask` bitmask of the `softmodem_params_t` structure. It allows bypassing or activating specific code in the softmodem to allow session establishment replay. This mechanism only works if in parallel specific code is also activated in the EPC, which is supported by the NOKIA LTE box.
An easiest scenario is to use the record player in parallel with the noS1 mode, as described [here](../../../../doc/RUNMODEM.md)
### iq recorder
most of the implementation is now located in the oai device common code:
* The`load_lib` function in [common-lib.c](../../COMMON/common_lib.c) reads the record player parameters.
* Recorder specific functions are implemented in `iqrecorder_end` saves the cached iq's to disk, it has to be called by the oai device in it's end function.
* When recording is enabled, the device must implement iq's caching in it's read function. It also has to call the `iqrecorder_end ` function when terminating to write iqs to a file on disk. Look at the USRP device ( [../usrp_lib.cpp](../../USRP/USERSPACE/LIB/usrp_lib.cpp) ) for details.
### iq player
The replay feature is implemented as a oai device.
* The`load_lib` function in [common-lib.c](../../COMMON/common_lib.c) reads the record player parameters, this code is common with the recorder.
* The player device is implemented in [iqplayer_lib.c](../iqplayer_lib.c) which at build time creates the `liboai_iqplayer.so` shared library. Thi
* 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.
[oai Wikis home](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/home)
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment