From 078c0845f8f8946f06ffd5d4ce3882fbee253500 Mon Sep 17 00:00:00 2001 From: Robert Schmidt Date: Sat, 1 Mar 2025 18:26:25 +0100 Subject: [PATCH] Add developer documentation for fhi_72 driver --- doc/README.md | 1 + radio/fhi_72/README.md | 46 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 radio/fhi_72/README.md diff --git a/doc/README.md b/doc/README.md index 13028479cd..4786458a66 100644 --- a/doc/README.md +++ b/doc/README.md @@ -117,6 +117,7 @@ Some directories under `radio` contain READMEs: - [USRP](../radio/USRP/README.md) - [BladeRF](../radio/BLADERF/README) - [IQPlayer](../radio/iqplayer/DOC/iqrecordplayer_usage.md), and [general documentation](./iqrecordplayer_usage.md) +- [fhi_72](../radio/fhi_72/README.md) The other SDRs (AW2S, LimeSDR, ...) have no READMEs. diff --git a/radio/fhi_72/README.md b/radio/fhi_72/README.md new file mode 100644 index 0000000000..2f72a9aa07 --- /dev/null +++ b/radio/fhi_72/README.md @@ -0,0 +1,46 @@ +This document describes the driver for the xran driver, implementing O-RAN FHI +7.2 interface. This is for developers; for user documentation, consider the +[O-RAN 7.2 tutorial instead](../../doc/ORAN_FHI7.2_Tutorial.md). + +The main source files and their purpose are as follows: + +- `oaioran.c`: definition of xran-specific callback functions. +- `oran-config.c`: reading of 7.2-specific configuration and preparing xran + configration. +- `oran-init.c`: initialization of xran. +- `oran_isolate.c`: main entry point and definition of function pointers for OAI + callbacks. + +The entry point for the driver library is `transport_init()` in `oran_isolate.c`. +This function is concerned with setting necessary function pointers for OAI +integration, and prepares xran configuration through `get_xran_config()`. This +function reads 7.2 specific configuration and deduces some of the parameters +(e.g., frequency) from OAI-provided radio configuration in `openair0_config_t`. + +Actual xran initialization happens in `oai_oran_initialize()` in `oran-init.c`. +It calls various helper function in the same file to set up DPDK memory buffer +(pools). Notably, these callbacks are installed: + +- `oai_xran_fh_rx_callback()` through `xran_5g_fronthault_config()`: callback + for PUSCH data; used to provide timing data. +- `oai_xran_fh_rx_prach_callback()` through `xran_5g_prach_req()`: callback for + PRACH data; not currently used and implemented in PUSCH data callback. +- `oai_physide_dl_tti_call_back()` through `xran_reg_physide_cb()`: only used + to unblock timing in `oai_xran_fh_rx_callback()` upon first xran call. + +More detailed information about the xran callbacks can be taken from the xran +documentation. + +During normal operation, OAI calls into the driver through functions +`oran_fh_if4p5_south_in()` for PUSCH/PRACH and `oran_fh_if4p5_south_out()` for +PDSCH. + +For PDSCH, `oran_fh_if4p5_south_out()` calls `xran_fh_tx_send_slot()` that +optionally compresses IQ data, then writes it into IQ buffers of xran. + +For PUSCH/PRACH, `oran_fh_if4p5_south_in()` calls `xran_fh_rx_read_slot()` that +blocks and waits for the next slot. This is done through either a message +queue, or through polling, which in both cases depends on xran calling the +callback `oai_xran_fh_rx_callback()` as installed during xran initialization. +Once unblocked, it reads first PRACH data, then PUSCH data, before returning to +OAI.