Plugins & Data Acquisition

Data capture overview

Fig. 21Schematic overview of the data capture plugin for the 5G NR PHY layer. MIMO aspects omitted for simplicity.

The Sionna Research Kit uses the OpenAirInterface (OAI) plugin system[OAILib] to integrate custom code. This tutorial shows how to capture real-world 5G signals (IQ samples) using a plugin that replaces the demapper function. The captured dataset can be used for training in theIntegration of a Neural Demapper tutorial.

Quick Start: Data Capture Plugin

Let’s start with how to use the data capture plugin.The next section will then explain the technical background and how to create your own plugin.

Create log files:

mkdir-pplugins/data_acquisition/logscdplugins/data_acquisition/logstouchdemapper_in.txtdemapper_out.txtchmod666demapper_in.txtdemapper_out.txt

The plugin folder is automatically mounted to the gNB container.This allows you to read/write the log files from the host system and can also be used to pass configuration files or models to the plugin (seeIntegration of a Neural Demapper tutorial).

You can enable the plugin by setting the environment variable in the.env file (e.g.,config/b200/.env) or by passing the option to the executable:

GNB_EXTRA_OPTIONS="--loader.demapper.shlibversion _capture"

This loads thedemapper_capture.so shared library. The main benefit is that the plugin can be loaded and unloaded dynamically, which allows for a flexible integration of custom code in the OAI stack. For example, you can now also load theIntegration of a Neural Demapper plugin as alternative demapper without recompiling the gNB.

Start the gNB.

./scripts/start_system.shrfsim

The plugin will be loaded and the data will be captured.You should then see entries in the log filesdemapper_in.txt anddemapper_out.txt.

Data Format

Both files use a simple text format with a header followed by symbol data:

0.000000001         # Time source resolution1373853.185968662   # TimestampQPSK                # Modulation scheme96                  # Number of symbols177 -179            # Data values (2 columns for QPSK, 4 for 16-QAM, etc.)-179 176...

  • demapper_in.txt: Input symbols as (Real, Imag) pairs

  • demapper_out.txt: Output LLRs (2 per symbol for QPSK, 4 for 16-QAM, etc.)

See theIntegration of a Neural Demapper tutorial for an example of loading this data in Python.

Writing Your Own Plugin

The following section explains the technical details on how to create your own plugin and integrate it into the OAI stack.

Step 1: Define the Plugin Interface

Each plugin type needs an interface definition. The demapper interface is defined inplugins/data_acquisition/src/nr_demapper_extern.h:

The interface contains function pointers for:

  • init: Called once at startup

  • init_thread: Called for each worker thread in the thread pool

  • shutdown: Called at cleanup

  • compute_llr: The main function that replaces the original OAI demapper function

Step 2: Implement the Plugin Functions

Your plugin must export functions matching the above interface. Here’s the capture plugin’s initialization and shutdown functions fromplugins/data_acquisition/src/nr_demapper_capture.c:

The main processing function is implemented inplugins/data_acquisition/src/nr_demapper_capture.c:

For simplicity, we only implement the QPSK and 16-QAM demapper functions, but extensions are straightforward.

Step 3: Create the Plugin Loader

In order to load the plugin, we need to create a loader function that maps function names to symbols in your shared library. This is done inplugins/data_acquisition/src/nr_demapper_load.c:

Step 4: Register the Plugin

Add your plugin to the central plugin system inplugins/common/src/plugins.c:

Note that theGPU-Accelerated LDPC Decoding tutorial is not registered here as it is a separate OAI plugin that uses the existing OAI loader independently of the Sionna Research Kit.

Step 5: Hook into OAI Code

Finally, the OAI code must call your plugin instead of the original function. We patch the functionnr_ulsch_llr_computation.c in the OpenAirInterface codebase to add this hook:

If no plugin is loaded, the original implementation is used. This is the case when the--loader.demapper.shlibversion parameter is not set or when the plugin is not loaded. Note that we have therefore renamed the original function tonr_ulsch_compute_llr_default.

Step 6: Add CMake Build Rules

Each plugin needs aCMakeLists.txt that registers the loader with the build system, builds the plugin as a shared library, and adds it as a dependency of the gNB target. The following is an example for the data capture plugin:

# Register loader source with parent buildset(PLUGINS_SRC${PLUGINS_SRC}${CMAKE_CURRENT_SOURCE_DIR}/src/nr_demapper_load.cPARENT_SCOPE)# Build plugin as shared libraryadd_library(demapper_captureMODULE${OPENAIR1_DIR}/PHY/NR_TRANSPORT/nr_ulsch_llr_computation.csrc/nr_demapper_capture.c)target_link_libraries(demapper_capturePRIVATEpthread)# Build with gNBadd_dependencies(nr-softmodemdemapper_capture)

Then add your subdirectory toplugins/CMakeLists.txt:

add_subdirectory(data_acquisition)

Summary

After re-building the gNB, you can now use the plugin by setting the--loader.demapper.shlibversion parameter to_capture.

Though plugins add implementation overhead, the advantage is that they can be loaded dynamically, allowing you to rebuild the plugin without recompiling the entire gNB. This also makes it easier to compare different implementations.

TheIntegration of a Neural Demapper, the5G NR PUSCH Neural Receiver, and theGPU-Accelerated LDPC Decoding tutorials are implemented as plugins and can be used as a drop-in replacement for the original OAI functions.

References