-.. Copyright (c) 2019 Intel
+.. Copyright (c) 2019-2022 Intel
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
<br />
-xRAN Library Design
-===================
+O-RAN Library Design
+====================
.. contents::
:depth: 3
:local:
-The xRAN Library consists of multiple modules where different
+The O-RAN Library consists of multiple modules where different
functionality is encapsulated. The complete list of all \*.c and \*.h
-files as well as Makefile for xRAN (aka FHI Lib Bronze Release) release is:
+files, as well as Makefile for O-RAN (aka FHI Lib)f release is:
-├──fhi_lib
+├── app
-│ ├── lib
+│ ├── dpdk.sh
-│ │ ├── api
+│ ├── gen_test.m
-│ │ │ ├── xran_compression.h
+│ ├── Makefile
-│ │ │ ├── xran_compression.hpp
+│ ├── ifft_in.txt
-│ │ │ ├── xran_cp_api.h
+│ ├── run_o_du.sh
-│ │ │ ├── xran_fh_o_du.h
+│ ├── run_o_ru.sh
-│ │ │ ├── xran_mlog_lnx.h
+│ ├── src
-│ │ │ ├── xran_pkt_cp.h
+│ │ ├── app_bbu_main.c
-│ │ │ ├── xran_pkt.h
+│ │ ├── app_bbu_pool.c
-│ │ │ ├── xran_pkt_up.h
+│ │ ├── app_bbu_pool.h
-│ │ │ ├── xran_sync_api.h
+│ │ ├── app_dl_bbu_pool_tasks.c
-│ │ │ ├── xran_timer.h
+│ │ ├── app_io_fh_xran.c
-│ │ │ ├── xran_transport.h
+│ │ ├── app_io_fh_xran.h
-│ │ │ └── xran_up_api.h
+│ │ ├── app_profile_xran.c
-│ │ ├── ethernet
+│ │ ├── app_profile_xran.h
-│ │ │ ├── ethdi.c
+│ │ ├── app_ul_bbu_pool_tasks.c
-│ │ │ ├── ethdi.h
+│ │ ├── aux_line.c
-│ │ │ ├── ethernet.c
+│ │ ├── aux_line.h
-│ │ │ └── ethernet.h
+│ │ ├── common.c
-│ │ ├── Makefile
+│ │ ├── common.h
-│ │ └── src
+│ │ ├── config.c
-│ │ │ ├── xran_app_frag.c
+│ │ ├── config.h
-│ │ │ ├── xran_app_frag.h
+│ │ ├── debug.h
-│ │ │ ├── xran_common.c
+│ │ ├── ebbu_pool_cfg.c
-│ │ │ ├── xran_common.h
+│ │ ├── ebbu_pool_cfg.h
-│ │ │ ├── xran_compression.cpp
+│ │ ├── sample-app.c
-│ │ │ ├── xran_cp_api.c
+│ │ └── xran_mlog_task_id.h
-│ │ │ ├── xran_frame_struct.c
+│ └── usecase
-│ │ │ ├── xran_frame_struct.h
+│ ├── cat_a
-│ │ │ ├── xran_lib_mlog_tasks_id.h
+│ ├── cat_b
-│ │ │ ├── xran_main.c
+│ ├── dss
-│ │ │ ├── xran_printf.h
+│ ├── lte_a
-│ │ │ ├── xran_sync_api.c
+│ ├── lte_b
-â\94\82Â Â â\94\82Â Â â\94\82Â Â â\94\9câ\94\80â\94\80 xran_timer.c
+â\94\9câ\94\80â\94\80 build.sh
-â\94\82Â Â â\94\82Â Â â\94\82Â Â â\94\9câ\94\80â\94\80 xran_transport.c
+â\94\9câ\94\80â\94\80 lib
-│ │ │ ├── xran_ul_tables.c
+│ ├── api
-│ │ │ └── xran_up_api.c
+│ │ ├── xran_compression.h
-│ ├── readme.txt
+│ │ ├── xran_compression.hpp
-│ ├── Licenses.txt
+│ │ ├── xran_cp_api.h
-│ ├── build.sh
+│ │ ├── xran_ecpri_owd_measurements.h
-│ └── test
+│ │ ├── xran_fh_o_du.h
-│ │ ├── common
+│ │ ├── xran_fh_o_ru.h
-│ │ │ ├── common.cpp
+│ │ ├── xran_lib_mlog_tasks_id.h
-│ │ │ ├── common.hpp
+│ │ ├── xran_mlog_lnx.h
-│ │ │ ├── common_typedef_xran.h
+│ │ ├── xran_pkt_cp.h
-│ │ ├── xranlib_unit_test_main.cc
+│ │ ├── xran_pkt.h
-│ │ └── xran_lib_wrap.hpp
+│ │ ├── xran_pkt_up.h
-│ │ ├── master.py
+│ │ ├── xran_sync_api.h
-│ │ ├── readme.txt
+│ │ ├── xran_timer.h
-│ │ └── test_xran
+│ │ ├── xran_transport.h
-│ │ │ ├── chain_tests.cc
+│ │ └── xran_up_api.h
-│ │ │ ├── compander_functional.cc
+│ ├── ethernet
-│ │ │ ├── conf.json
+│ │ ├── ethdi.c
-│ │ │ ├── c_plane_tests.cc
+│ │ ├── ethdi.h
-│ │ │ ├── init_sys_functional.cc
+│ │ ├── ethernet.c
-│ │ │ ├── Makefile
+│ │ └── ethernet.h
-│ │ │ ├── prach_functional.cc
+│ ├── Makefile
-│ │ │ ├── prach_performance.cc
+│ └── src
-│ │ │ ├── unittests.cc
+│ ├── xran_bfp_byte_packing_utils.hpp
+
+│ ├── xran_bfp_cplane8.cpp
+
+│ ├── xran_bfp_cplane8_snc.cpp
+
+│ ├── xran_bfp_cplane16.cpp
+
+│ ├── xran_bfp_cplane16_snc.cpp
+
+│ ├── xran_bfp_cplane32.cpp
+
+│ ├── xran_bfp_cplane32_snc.cpp
+
+│ ├── xran_bfp_cplane64.cpp
+
+│ ├── xran_bfp_cplane64_snc.cpp
+
+│ ├── xran_bfp_ref.cpp
+
+│ ├── xran_bfp_uplane.cpp
+
+│ ├── xran_bfp_uplane_9b16rb.cpp
+
+│ ├── xran_bfp_uplane_snc.cpp
+
+│ ├── xran_bfp_utils.hpp
+
+│ ├── xran_cb_proc.c
+
+│ ├── xran_cb_proc.h
+
+│ ├── xran_common.c
+
+│ ├── xran_common.h
+
+│ ├── xran_compression.cpp
+
+│ ├── xran_compression_snc.cpp
+
+│ ├── xran_cp_api.c
+
+│ ├── xran_cp_proc.c
+
+│ ├── xran_cp_proc.h
+
+│ ├── xran_delay_measurement.c
+
+│ ├── xran_dev.c
+
+│ ├── xran_dev.h
+
+│ ├── xran_frame_struct.c
+
+│ ├── xran_frame_struct.h
+
+│ ├── xran_main.c
+
+│ ├── xran_main.h
+
+│ ├── xran_mem_mgr.c
+
+│ ├── xran_mem_mgr.h
+
+│ ├── xran_mod_compression.cpp
+
+│ ├── xran_mod_compression.h
+
+│ ├── xran_prach_cfg.h
+
+│ ├── xran_printf.h
+
+│ ├── xran_rx_proc.c
+
+│ ├── xran_rx_proc.h
+
+│ ├── xran_sync_api.c
+
+│ ├── xran_timer.c
+
+│ ├── xran_transport.c
+
+│ ├── xran_tx_proc.c
+
+│ ├── xran_tx_proc.h
+
+│ ├── xran_ul_tables.c
+
+│ └── xran_up_api.c
+
+└── test
+
+ ├── common
+
+ │ ├── common.cpp
+
+ │ ├── common.hpp
+
+ │ ├── common_typedef_xran.h
+
+ │ ├── json.hpp
+
+ │ ├── MIT_License.txt
+
+ │ ├── xranlib_unit_test_main.cc
+
+ │ └── xran_lib_wrap.hpp
+
+ ├── master.py
+
+ ├── readme.txt
+
+ └── test_xran
+
+ ├── c_plane_tests.cc
+
+ ├── chain_tests.cc
+
+ ├── compander_functional.cc
+
+ ├── conf.json
+
+ ├── init_sys_functional.cc
+
+ ├── Makefile
+
+ ├── mod_compression_unit_test.cc
+
+ ├── prach_functional.cc
+
+ ├── prach_performance.cc
+
+ ├── unittests.cc
+
+ └── u_plane_functional.cc
+
+ ├── u_plane_performance.cc
-│ │ │ ├── u_plane_functional.cc
General Introduction
--------------------
-The xRAN Library functionality is broken down into two main sections:
+The O-RAN FHI Library functionality is broken down into two main sections:
-- XRAN specific packet handling (src)
+- O-RAN specific packet handling (src)
-- Ethernet and supporting functionality (Ethernet)
+- Ethernet and supporting functionality (ethernet)
-External functions and structures are available via set of header files
-in the API folder.
+External functions and structures are available via a set of header
+files in the API folder.
This library depends on DPDK primitives to perform Ethernet networking
-in userspace, including initialization and control of Ethernet ports.
+in user space, including initialization and control of Ethernet ports.
Ethernet ports are expected to be SRIOV virtual functions (VF) but also
can be physical functions (PF) as well
This library is expected to be included in the project via
xran_fh_o_du.h, statically compiled and linked with the L1 application
-as well as DPDK libraries. The xRAN packet processing-specific
+as well as DPDK libraries. The O-RAN packet processing-specific
functionality is encapsulated into this library and not exposed to the
-rest of the 5G NR pipeline. An abstract interface similar to the mmWave
-front haul interface is defined in xran_fh_o_du.h to be available for
-usage.
+rest of the 5G NR pipeline.
-This way, xRAN specific changes are decoupled from the 5G NR L1
-pipeline. As a result, the design and implementation of the 5G L1
-pipeline code and xRAN library can be done in parallel, provided the
-defined interface is not modified.
+This way, O-RAN specific changes are decoupled from the L1 pipeline. As a
+result, the design and implementation of the 5G L1 pipeline code and
+O-RAN FHI library can be done in parallel, provided the defined interface is
+not modified.
Ethernet consists of two modules:
-- Ethernet implements xRAN specific HW Ethernet initialization, close,
+- Ethernet implements O-RAN specific HW Ethernet initialization, close,
send and receive
-- ethdi provides Ethernet level software primitives to handle xRAN
+- ethdi provides Ethernet level software primitives to handle O-RAN
packet exchange
-The xRAN layer implements the next set of functionalities:
+The O-RAN layer implements the next set of functionalities:
- Common code specific for both C-plane and U-plane as well as TX and
RX
.. image:: images/Illustration-of-xRAN-Sublayers.jpg
:width: 600
- :alt: Figure 24. Illustration of xRAN Sublayers
+ :alt: Figure 25. Illustration of O-RAN Sublayers
-Figure 24. Illustration of xRAN Sublayers
+Figure 25. Illustration of O-RAN Sublayers
A detailed description of functions and input/output arguments, as well
as key data structures, can be found in the Doxygen file for the FlexRAN
-5G NR release. In this document supplemental information is provided
-with respect to the overall design and implementation assumptions.
+5G NR release, Refer to Table 2. In this document, supplemental
+information is provided for the overall design and implementation
+assumptions.(Available only outside of the Community Version)
Initialization and Close
------------------------
1.Setup structure struct xran_fh_init according to configuration.
-2.Call xran_init() to instantiate the xRAN lib memory model and
-threads. The function returns a pointer to xRAN handle which is used
+2.Call xran_init() to instantiate the O-RAN lib memory model and
+threads. The function returns a pointer to O-RAN handle which is used
for consecutive configuration functions.
-3.Initialize memory buffers used for L1 and xRAN exchange of
+3.Initialize memory buffers used for L1 and O-RAN exchange of
information.
4.Assign callback functions for (one) TTI event and for the reception
14 symbols).
5.Call xran_open() to initialize PRACH configuration, initialize DPDK,
-and launch xRAN timing thread.
+and launch xRAN timing thread,
-6.Call xran_start() to start processing xRAN packets for DL and UL.
+6.Call xran_start() to start processing O-RAN packets for DL and UL.
-After this is complete 5G L1 runs with xRAN Front haul interface. During
+After this is complete 5G L1 runs with O-RAN Front haul interface. During
run time for every TTI event, the corresponding call back is called. For
packet reception on UL direction, the corresponding call back is called.
-OTA time information such as frame id, subframe id and slot id can be
+OTA time information such as frame id, subframe id, and slot id can be
obtained as result synchronization of the L1 pipeline to GPS time is
performed.
To stop and close the interface, perform this sequence of steps:
-7.Call xran_stop() to stop the processing of DL and UL.
+1.Call xran_stop() to stop the processing of DL and UL
-8.Call xran_close() to remove usage of xRAN resources.
+2.Call xran_close() to remove usage of xRAN resources
-9.Call xran_mm_destroy() to destroy memory management subsystem.
+3.Call xran_mm_destroy() to destroy memory management subsystem
After this session is complete, a restart of the full L1 application is
required. The current version of the library does not support multiple
sessions without a restart of the full L1 application.
-
+Configuration
~~~~~~~~~~~~~
-The xRAN library configuration is provided in the set of structures,
-such as struct xran_fh_init and struct xran_fh_config. The sample
-application gives an example of a test configuration used for mmWave.
+The O-RAN library configuration is provided in the set of structures, such as struct xran_fh_init and struct xran_fh_config.
+The sample application gives an example of a test configuration used for LTE and 5GNR mmWave and Sub 6. Sample application
+folder /app/usecase/ contains set of examples for different Radio Access technology (LTE|5G NR), different category (A|B)
+and list of numerologies (0,1,3) and list of bandwidths (5,10,20,100Mhz).
-Some configuration options are not used in the Bronze Release and are reserved
+Note: Some configuration options are not used in the f release and are reserved
for future use.
The following options are available:
- Number of CC and corresponding settings for each
-- Core allocation for xRAN
+- Core allocation for O-RAN
- Ethernet port allocation
**From an implementation perspective:**
-xran_init() performs init of the xRAN library and interface according to
-struct xran_fh_init information as per the start of application
-configuration.:
+The xran_init() performs init of the O-RAN FHI library and interface
+according to struct xran_fh_init information as per the start of
+application configuration:
- Init DPDK with corresponding networking ports and core assignment
- Init DPDK timers and DPDK rings for internal packet processing
-- Instantiate ORAH FH thread doing
+- Instantiates ORAH FH thread doing
-- Timing processing (xran_timing_source_thread())
+ - Timing processing (xran_timing_source_thread())
-- ETH PMD (process_dpdk_io())
+ - ETH PMD (process_dpdk_io())
-- IO XRAN-PHY exchange (ring_processing_func())
+ - IO XRAN-PHY exchange (ring_processing_func())
**xran_open()** performs additional configuration as per run scenario:
~~~~~~~~~~~~~
Exchange of IQ samples, as well as C-plane specific information, is
-performed using a set of buffers allocated by xRAN |br|
-library from DPDK
+performed using a set of buffers allocated by xRAN library from DPDK
memory and shared with the l1 application. Buffers are allocated as a
-standard mbuf structure and DPDK pools are used to manage the allocation
-and free resources. Shared buffers are allocated at the init stage and
-are expected to be reused within 80 TTIs (10 ms).
+standard mbuf structure, and DPDK pools are used to manage the
+allocation and free resources. Shared buffers are allocated at the init
+stage and are expected to be reused within 80 TTIs (10 ms).
-The xRAN protocol requires U-plane IQ data to be transferred in network
+The O-RAN protocol requires U-plane IQ data to be transferred in network
byte order, and the L1 application handles IQ sample data in CPU byte
order, requiring a swap. The PHY BBU pooling tasks perform copy and byte
order swap during packet processing.
C-plane Information Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The interface between the xRAN library and PHY is defined via struct
+The interface between the O-RAN library and PHY is defined via struct
xran_prb_map and similar to the data plane. The same mbuf memory is used
-to allocate memory map of PRBs for each TTI.
+to allocate memory map of PRBs for each TTI.::
-/\* Beamforming weights for single stream for each PRBs given number of
-Antenna elements \*/
+ /*\* Beamforming waights for single stream for each PRBs given number of
+ Antenna elements \*/
+ struct xran_cp_bf_weight{
-struct xran_cp_bf_weight{
+ int16_t nAntElmTRx; /**< num TRX for this allocation \*/
-int16_t nAntElmTRx; /* num TRX for this allocation \*/
+ int16_t ext_section_sz; /**< extType section size \*/
-int8_t\* p_ext_section; /* pointer to form extType \*/
+ int8_t\* p_ext_start; /**< pointer to start of buffer for full C-plane
+ packet \*/
-int16_t ext_section_sz; /* extType section size \*/
+ int8_t\* p_ext_section; /**< pointer to form extType \*/
-};
-
-struct xran_cp_bf_attribute{
+ /\* For ext 11 \*/
-int16_t weight[4];
+ uint8_t bfwCompMeth; /\* Compression Method for BFW \*/
-};
+ uint8_t bfwIqWidth; /\* Bitwidth of BFW \*/
-struct xran_cp_bf_precoding{
+ uint8_t numSetBFWs; /\* Total number of beam forming weights set (L) \*/
-int16_t weight[4];
+ uint8_t numBundPrb; /\* The number of bundled PRBs, 0 means to use ext1
+ \*/
-};
+ uint8_t RAD;
-/\* section descriptor for given number of PRBs used on U-plane packet
-creation \*/
+ uint8_t disableBFWs;
-struct xran_section_desc {
+ int16_t maxExtBufSize; /\* Maximum space of external buffer \*/
-uint16_t section_id; /* section id used for this element \*/
+ struct xran_ext11_bfw_info bfw[XRAN_MAX_SET_BFWS]
-int16_t iq_buffer_offset; /* Offset in bytes for the content of IQs
-with in main symb buffer \*/
+ };
-int16_t iq_buffer_len; /* Length in bytes for the content of IQs with
-in main symb buffer \*/
+ /*\* PRB element structure \*/
-uint8_t \*pData; /* optional pointer to data buffer \*/
+ struct xran_prb_elm {
-void \*pCtrl; /* optional poitner to mbuf \*/
+ int16_t nRBStart; /**< start RB of RB allocation \*/
-};
+ int16_t nRBSize; /**< number of RBs used \*/
-/* PRB element structure \*/
+ int16_t nStartSymb; /**< start symbol ID \*/
-struct xran_prb_elm {
+ int16_t numSymb; /**< number of symbols \*/
-int16_t nRBStart; /* start RB of RB allocation \*/
+ int16_t nBeamIndex; /**< beam index for given PRB \*/
-int16_t nRBSize; /* number of RBs used \*/
+ int16_t bf_weight_update; /*\* need to update beam weights or not \*/
-int16_t nStartSymb; /* start symbol ID \*/
+ int16_t compMethod; /**< compression index for given PRB \*/
-int16_t numSymb; /* number of symbols \*/
+ int16_t iqWidth; /**< compression bit width for given PRB \*/
-int16_t nBeamIndex; /* beam index for given PRB \*/
+ uint16_t ScaleFactor; /**< scale factor for modulation compression \*/
-int16_t bf_weight_update; /* need to update beam weights or not \*/
+ int16_t reMask; /**< 12-bit RE Mask for modulation compression \*/
-int16_t compMethod; /* compression index for given PRB \*/
+ int16_t BeamFormingType; /**< index based, weights based or attribute
+ based beam forming*/
-int16_t iqWidth; /* compression bit width for given PRB \*/
+ int16_t nSecDesc[XRAN_NUM_OF_SYMBOL_PER_SLOT]; /**< number of section
+ descriptors per symbol \*/
-int16_t BeamFormingType; /* index based, weights based or
-attribute-based beam forming*/
+ struct xran_section_desc \*
+ p_sec_desc[XRAN_NUM_OF_SYMBOL_PER_SLOT][XRAN_MAX_FRAGMENT]; /**< section
+ desctiptors to U-plane data given RBs \*/
-struct xran_section_desc \* p_sec_desc[XRAN_NUM_OF_SYMBOL_PER_SLOT];
-/* section desctiptors to U-plane data given RBs \*/
+ struct xran_cp_bf_weight bf_weight; /**< beam forming information
+ relevant for given RBs \*/
-struct xran_cp_bf_weight bf_weight; /* beam forming information
-relevant for given RBs \*/
+ union {
-union {
+ struct xran_cp_bf_attribute bf_attribute;
-struct xran_cp_bf_attribute bf_attribute;
+ struct xran_cp_bf_precoding bf_precoding;
-struct xran_cp_bf_precoding bf_precoding;
+ };
-};
+ };
-};
+ /*\* PRB map structure \*/
-/* PRB map structure \*/
+ struct xran_prb_map {
-struct xran_prb_map {
+ uint8_t dir; /**< DL or UL direction \*/
-uint8_t dir; /* DL or UL direction \*/
+ uint8_t xran_port; /**< O-RAN id of given RU [0-(XRAN_PORTS_NUM-1)] \*/
-uint8_t xran_port; /* xran id of given RU [0-(XRAN_PORTS_NUM-1)] \*/
+ uint16_t band_id; /**< O-RAN band id \*/
-uint16_t band_id; /* xran band id \*/
+ uint16_t cc_id; /**< component carrier id [0 - (XRAN_MAX_SECTOR_NR-1)]
+ \*/
-uint16_t cc_id; /* componnent carrier id [0 - (XRAN_MAX_SECTOR_NR-1)]
-\*/
+ uint16_t ru_port_id; /**< RU device antenna port id [0 -
+ (XRAN_MAX_ANTENNA_NR-1) \*/
-uint16_t ru_port_id; /* RU device antenna portid [0 -
-(XRAN_MAX_ANTENNA_NR-1)*/
+ uint16_t tti_id; /**< O-RAN slot id [0 - (max tti-1)] \*/
-uint16_t tti_id; /* xRAN slot id [0 - (max tti-1)] \*/
+ uint8_t start_sym_id; /**< start symbol Id [0-13] \*/
-uint8_t start_sym_id; /* start symbol Id [0-13] \*/
+ uint32_t nPrbElm; /**< total number of PRB elements for given map [0-
+ (XRAN_MAX_SECTIONS_PER_SLOT-1)] \*/
-uint32_t nPrbElm; /* total number of PRB elements for given map [0-
-(XRAN_MAX_PRBS-1)] \*/
+ struct xran_prb_elm prbMap[XRAN_MAX_SECTIONS_PER_SLOT];
-struct xran_prb_elm prbMap[XRAN_MAX_PRBS];
+ };
-};
-For the Bronze release C-plane sections are expected to be provided by L1
-pipeline. If 100% of RBs allocated at all times single element of RB map
+C-plane sections are expected to be provided by the L1
+pipeline. If 100% of the RBs are used they are always allocated as a single element RB map, that
is expected to be allocated across all symbols. Dynamic RB allocation is
-performed base on C-plane configuration.
+performed based on C-plane configuration.
-The xRAN library will require that the content of the PRB map should be
+The O-RAN library will require that the content of the PRB map should be
sorted in increasing order of PRB first and then symbols.
Memory Management
-----------------
Memory used for the exchange of IQ data as well as control information,
-is controlled by the xRAN library. L1 application at the init stage
+is controlled by the O-RAN library. L1 application at the init stage
performs:
- init memory management subsystem
After the session is completed, the application can free buffers and
destroy the memory management subsystem.
-From an implementation perspective, the xRAN library uses a standard
+From an implementation perspective, the O-RAN library uses a standard
mbuf primitive and allocates a pool of buffers for each sector. This
function is performed using rte_pktmbuf_pool_create(),
-rte_pktmbuf_alloc(), rte_pktmbuf_append() to allocate one buffer per
+rte_pktmbuf_alloc(), and rte_pktmbuf_append() to allocate one buffer per
symbol for the mmWave case. More information on mbuf and DPDK pools can
be found in the DPDK documentation.
the L1 application is the same number of buffers used to send to and
receive from the Ethernet port. Memory copy operations are not required
if the packet size is smaller than or equal to MTU. Future versions of
-the xRAN library are required to remove the memory copy requirement for
+the O-RAN library are required to remove the memory copy requirement for
packets where the size larger than MTU.
External Interface Memory
~~~~~~~~~~~~~~~~~~~~~~~~~
-The xRAN library header file defines a set of structures to simplify
-access to memory buffers used for IQ data.
+The O-RAN library header file defines a set of structures to simplify
+access to memory buffers used for IQ data.:::
-struct xran_flat_buffer {
+ struct xran_flat_buffer {
-uint32_t nElementLenInBytes;
+ uint32_t nElementLenInBytes;
-uint32_t nNumberOfElements;
+ uint32_t nNumberOfElements;
-uint32_t nOffsetInBytes;
+ uint32_t nOffsetInBytes;
-uint32_t nIsPhyAddr;
+ uint32_t nIsPhyAddr;
-uint8_t \*pData;
+ uint8_t \*pData;
-void \*pCtrl;
+ void \*pCtrl;
-};
+ };
-struct xran_buffer_list {
+ struct xran_buffer_list {
-uint32_t nNumBuffers;
+ uint32_t nNumBuffers;
-struct xran_flat_buffer \*pBuffers;
+ struct xran_flat_buffer \*pBuffers;
-void \*pUserData;
+ void \*pUserData;
-void \*pPrivateMetaData;
+ void \*pPrivateMetaData;
-};
+ };
+
+ struct xran_io_buf_ctrl {
+
+ /\* -1-this subframe is not used in current frame format
-typedef struct {
+ 0-this subframe can be transmitted, i.e., data is ready
-int32_t bValid ;
+ 1-this subframe is waiting transmission, i.e., data is not ready
-int32_t nSegToBeGen;
+ 10 - DL transmission missing deadline. When FE needs this subframe data
+ but bValid is still 1,
-int32_t nSegGenerated;
+ set bValid to 10.
-int32_t nSegTransferred;
+ \*/
-struct rte_mbuf \*pData[N_MAX_BUFFER_SEGMENT];
+ int32_t bValid ; // when UL rx, it is subframe index.
-struct xran_buffer_list sBufferList;
+ int32_t nSegToBeGen;
-} BbuIoBufCtrlStruct;
+ int32_t nSegGenerated; // how many date segment are generated by DL LTE
+ processing or received from FE
+
+ // -1 means that DL packet to be transmitted is not ready in BS
+
+ int32_t nSegTransferred; // number of data segments has been transmitted
+ or received
+
+ struct rte_mbuf \*pData[N_MAX_BUFFER_SEGMENT]; // point to DPDK
+ allocated memory pool
+
+ struct xran_buffer_list sBufferList;
+
+ };
There is no explicit requirement for user to organize a set of buffers
in this particular way. From a compatibility |br|
perspective it is useful to
follow the existing design of the 5G NR l1app used for Front Haul FPGA
-and define structures shared between l1 and xRAN lib as shown:
+and define structures shared between l1 and O-RAN lib as shown: ::
+
+ struct bbu_xran_io_if {
+
+ void\* nInstanceHandle[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR]; /**<
+ instance per O-RAN port per CC \*/
+
+ uint32_t
+ nBufPoolIndex[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR][MAX_SW_XRAN_INTERFACE_NUM];
+ /**< unique buffer pool \*/
+
+ uint16_t nInstanceNum[XRAN_PORTS_NUM]; /**< instance is equivalent to CC
+ \*/
+
+ uint16_t DynamicSectionEna;
+
+ uint32_t nPhaseCompFlag;
-/\* io struct \*/
+ int32_t num_o_ru;
-BbuIoBufCtrlStruct
-sFrontHaulTxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR]\
-[XRAN_MAX_ANTENNA_NR];
+ int32_t num_cc_per_port[XRAN_PORTS_NUM];
-BbuIoBufCtrlStruct
-sFrontHaulTxPrbMapBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
+ int32_t map_cell_id2port[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
-BbuIoBufCtrlStruct
-sFrontHaulRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
+ struct xran_io_shared_ctrl ioCtrl[XRAN_PORTS_NUM]; /**< for each O-RU
+ port \*/
-BbuIoBufCtrlStruct
-sFrontHaulRxPrbMapBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
+ struct xran_cb_tag RxCbTag[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
-BbuIoBufCtrlStruct
-sFHPrachRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
+ struct xran_cb_tag PrachCbTag[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
-/\* Cat B \*/
+ struct xran_cb_tag SrsCbTag[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
-BbuIoBufCtrlStruct
-sFHSrsRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR];
+ };
-/\* buffers list \*/
+ struct xran_io_shared_ctrl {
-struct xran_flat_buffer
-sFrontHaulTxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
+ /\* io struct \*/
-struct xran_flat_buffer
-sFrontHaulTxPrbMapBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
+ struct xran_io_buf_ctrl
+ sFrontHaulTxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
-struct xran_flat_buffer
-sFrontHaulRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
+ struct xran_io_buf_ctrl
+ sFrontHaulTxPrbMapBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
-struct xran_flat_buffer
-sFrontHaulRxPrbMapBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
+ struct xran_io_buf_ctrl
+ sFrontHaulRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
-struct xran_flat_buffer
-sFHPrachRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
+ struct xran_io_buf_ctrl
+ sFrontHaulRxPrbMapBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
-/\* Cat B SRS buffers \*/
+ struct xran_io_buf_ctrl
+ sFHPrachRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
-struct xran_flat_buffer
-sFHSrsRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR][XRAN_MAX_NUM_OF_SRS_SYMBOL_PER_SLOT];
+ /\* Cat B \*/
-Doxygen file and xran_fh_o_du.h provide more details on the definition
-and usage of these structures.
+ struct xran_io_buf_ctrl
+ sFHSrsRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR];
-xRAN Specific Functionality
----------------------------
+ struct xran_io_buf_ctrl
+ sFHSrsRxPrbMapBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR];
+
+ /\* buffers lists \*/
+
+ struct xran_flat_buffer
+ sFrontHaulTxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
+
+ struct xran_flat_buffer
+ sFrontHaulTxPrbMapBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
+
+ struct xran_flat_buffer
+ sFrontHaulRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
+
+ struct xran_flat_buffer
+ sFrontHaulRxPrbMapBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
+
+ struct xran_flat_buffer
+ sFHPrachRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
+
+ /\* Cat B SRS buffers \*/
+
+ struct xran_flat_buffer
+ sFHSrsRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR][XRAN_MAX_NUM_OF_SRS_SYMBOL_PER_SLOT];
+
+ struct xran_flat_buffer
+ sFHSrsRxPrbMapBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR];
+
+ };
+
+The Doxygen file and xran_fh_o_du.h provides more details on the
+definition and usage of these structures. Refer to *Table 2*, for
+FlexRAN 5G NR Reference Solution RefPHY (Doxygen).(Not available in
+the community version).
+
+O-RAN Specific Functionality
+----------------------------
Front haul interface implementation in the general case is abstracted
away using the interface defined in xran_fh_o_du.h
-The L1 application is not required to access xRAN protocol primitives
+The L1 application is not required to access O-RAN protocol primitives
(eCPRI header, application header, and others) directly. It is
recommended to use the interface to remove dependencies between
-different software modules such as the l1 pipeline and xRAN library.
+different software modules such as the l1 pipeline and O-RAN library.
External API
~~~~~~~~~~~~
The U-plane and C-plane APIs can be used directly from the application
if such an option is required. The set of header files can be exported
-and called directly.
+and called directly.::
-xran_fh_o_du.h – xRAN main header file for O-DU scenario
+ xran_fh_o_du.h – O-RAN main header file for O-DU scenario
-xran_cp_api.h – Control plane functions
+ xran_cp_api.h – Control plane functions
-xran_pkt_cp.h – xRAN control plane packet definition
+ xran_pkt_cp.h – O-RAN control plane packet definition
-xran_pkt.h – xRAN packet definition
+ xran_pkt.h – O-RAN packet definition
-xran_pkt_up.h – xRAN User plane packet definition
+ xran_pkt_up.h – O-RAN User plane packet definition
-xran_sync_api.h – api functions to check PTP status
+ xran_sync_api.h – api functions to check PTP status
-xran_timer.h – API for timing
+ xran_timer.h – API for timing
-xran_transport.h – eCPRI transport layer definition and api
+ xran_transport.h – eCPRI transport layer definition and api
-xran_up_api.h – user plane functions and definitions
+ xran_up_api.h – user plane functions and definitions
-xran_compression.h – interface to compression/decompression functions
+ xran_compression.h – interface to compression/decompression functions
-Doxygen files provide detailed information on functions and structures
-available.
+Source code comments can provide more details on functions and
+structures available.
.. _c-plane-1:
xran_cp_api.c and is used to prepare the content of C-plane packets
according to the given configuration. Users can enable/disable
generation of C-plane messages using enableCP field in struct
-xran_fh_init structure during init of ORAN front haul. The time of
-generation of C-plane message for DL and UL is done “Slot-based,” and
-timing can be controlled using O-DU settings according to Table 4.
+xran_fh_init structure during the initialization of O-RAN front haul.
+The time of generation of C-plane message for DL and UL is done
+“Slot-based,” and timing can be controlled using O-DU settings according
+to *Table 4*.
The C-plane module contains:
- initialization of C-plane database to keep track of allocation of
resources
-- code to prepare C-plane packet for TX (O-DU)
+- Code to prepare C-plane packet for TX (O-DU)
+ - eCPRI header
+ - append radio application header
+ - append control section header
+ - append control section
-- eCPRI header
-
-- append radio application header
-
-- append control section header
-
-- append control section
-
-- parser of C-plane packet for RX (O-RU emulation)
+- Parser of C-plane packet for RX (O-RU emulation)
- parses and checks Section 1 and Section 3 packet content
-Sending and receiving packets is performed using xRAN ethdi sublayer
+Sending and receiving packets is performed using O-RAN ethdi sublayer
functions.
+More information on function arguments and parameters can be found in
+the comments for the corresponding source code.
+
Creating a C-Plane Packet
^^^^^^^^^^^^^^^^^^^^^^^^^
-API and Data Structures
-'''''''''''''''''''''''
+1. API and Data Structures
-A C-Plane message can be composed using the following API:
+A C-Plane message can be composed using the following API:::
-int xran_prepare_ctrl_pkt(struct rte_mbuf \*mbuf,
+ int xran_prepare_ctrl_pkt(struct rte_mbuf \*mbuf,
-struct xran_cp_gen_params \*params,
+ struct xran_cp_gen_params \*params,
-uint8_t CC_ID, uint8_t Ant_ID, uint8_t seq_id);
+ uint8_t CC_ID, uint8_t Ant_ID, uint8_t seq_id);
mbuf is the pointer of a DPDK packet buffer, which is allocated from the
caller.
params, the parameters to create a C-Plane message are defined as the
structure of xran_cp_gen_params with an |br|
-example given below:
+example given below:::
-struct xran_cp_gen_params {
+ struct xran_cp_gen_params {
-uint8_t dir;
+ uint8_t dir;
-uint8_t sectionType;
+ uint8_t sectionType;
-uint16_t numSections;
+ uint16_t numSections;
-struct xran_cp_header_params hdr;
+ struct xran_cp_header_params hdr;
-struct xran_section_gen_info \*sections;
+ struct xran_section_gen_info \*sections;
-};
+ };
dir is the direction of the C-Plane message to be generated. Available
parameters are defined as XRAN_DIR_UL and XRAN_DIR_DL.
-sectionType is the section type for C-Plane message to generate, as ORAN
-specification defines all sections in a C-Plane message shall have the
-same section type. If different section types are required, they shall
-be sent with separate C-Plane messages. Available types of sections are
-defined as XRAN_CP_SECTIONTYPE_x. Please refer to the Table 5-2 Section
-Types in chapter 5.4 of ORAN specification.
+sectionType is the section type for C-Plane message to generate, as
+O-RAN specification defines all sections in a C-Plane message shall have
+the same section type. If different section types are required, they
+shall be sent with separate C-Plane messages. Available types of
+sections are defined as XRAN_CP_SECTIONTYPE_x. Refer to *Table* 2,
+*O-RAN Specification*, Table 5-2 Section Types.
numSections is the total number of sections to generate, i.e., the
number of the array in sections (struct xran_section_gen_info).
the structure of xran_cp_header_params. Not all parameters in this
structure are used for the generation, and the required parameters are
slightly different by the type of section, as described in Table 10 and
-Table 11.
+References in the remarks column are corresponding Chapter numbers in
+the O-RAN *FrontHaul Working Group Control, User, and Synchronization
+Plane Specification* in *Table 2*.
Table 10. struct xran_cp_header_params – Common Radio Application Header
Table 11. struct xran_cp_header_params – Section Specific Parameters
-+----------+----------+----------+---------+---+---+---+---+----------+
-| | Des\ | Section | Remarks | | | | | |
-| | cription | Type | | | | | | |
-| | | ap\ | | | | | | |
-| | | plicable | | | | | | |
-+==========+==========+==========+=========+===+===+===+===+==========+
-| | | 0 | 1 | 3 | 5 | 6 | 7 | |
-+----------+----------+----------+---------+---+---+---+---+----------+
-| fftSize | FFT size | X | | X | | | | 5.4.4.13 |
-| | in frame | | | | | | | |
-| | st\ | | | | | | | |
-| | ructure. | | | | | | | |
-| | A\ | | | | | | | |
-| | vailable | | | | | | | |
-| | values | | | | | | | |
-| | are | | | | | | | |
-| | defined | | | | | | | |
-| | as | | | | | | | |
-| | X\ | | | | | | | |
-| | RAN_FFTS\| | | | | | | |
-| | IZE_xxxx | | | | | | | |
-+----------+----------+----------+---------+---+---+---+---+----------+
-| Scs | Su\ | X | | X | | | | 5.4.4.13 |
-| | bcarrier | | | | | | | |
-| | Spacing | | | | | | | |
-| | in the | | | | | | | |
-| | frame | | | | | | | |
-| | st\ | | | | | | | |
-| | ructure. | | | | | | | |
-| | A\ | | | | | | | |
-| | vailable | | | | | | | |
-| | values | | | | | | | |
-| | are | | | | | | | |
-| | defined | | | | | | | |
-| | as | | | | | | | |
-| | XRAN_SCS\| | | | | | | |
-| | _xxxx | | | | | | | |
-+----------+----------+----------+---------+---+---+---+---+----------+
-| iqWidth | I/Q bit | | X | X | X | | | 5.4.4.10 |
-| | width in | | | | | | | |
-| | user | | | | | | | 6.3.3.13 |
-| | data | | | | | | | |
-| | com\ | | | | | | | |
-| | pression | | | | | | | |
-| | header. | | | | | | | |
-| | Should | | | | | | | |
-| | be set | | | | | | | |
-| | by zero | | | | | | | |
-| | for | | | | | | | |
-| | 16bits | | | | | | | |
-+----------+----------+----------+---------+---+---+---+---+----------+
-| compMeth | Com\ | | X | X | X | | | 5.4.4.10 |
-| | pression | | | | | | | |
-| | Method | | | | | | | 6.3.3.13 |
-| | in user | | | | | | | |
-| | data | | | | | | | |
-| | com\ | | | | | | | |
-| | pression | | | | | | | |
-| | header. | | | | | | | |
-| | A\ | | | | | | | |
-| | vailable | | | | | | | |
-| | values | | | | | | | |
-| | are | | | | | | | |
-| | defined | | | | | | | |
-| | as | | | | | | | |
-| | XRAN\ | | | | | | | |
-| | _COMPMET\| | | | | | | |
-| | HOD_xxxx | | | | | | | |
-+----------+----------+----------+---------+---+---+---+---+----------+
-| numUEs | Number | | | | | X | | 5.4.4.11 |
-| | of UEs. | | | | | | | |
-| | Applies | | | | | | | |
-| | to | | | | | | | |
-| | section | | | | | | | |
-| | type 6 | | | | | | | |
-| | and not | | | | | | | |
-| | s\ | | | | | | | |
-| | upported | | | | | | | |
-| | in this | | | | | | | |
-| | release. | | | | | | | |
-+----------+----------+----------+---------+---+---+---+---+----------+
-| ti\ | Time | X | | X | | | | 5.4.4.12 |
-| meOffset | Offset. | | | | | | | |
-| | Time | | | | | | | |
-| | offset | | | | | | | |
-| | from the | | | | | | | |
-| | start of | | | | | | | |
-| | the slot | | | | | | | |
-| | to start | | | | | | | |
-| | of | | | | | | | |
-| | Cyclic | | | | | | | |
-| | Prefix. | | | | | | | |
-+----------+----------+----------+---------+---+---+---+---+----------+
-| cpLength | Cyclic | X | | X | | | | 5.4.4.14 |
-| | Prefix | | | | | | | |
-| | Length. | | | | | | | |
-+----------+----------+----------+---------+---+---+---+---+----------+
-
-**Only sections types 1 and 3 are supported in the current release.**
++----------+-----------+------------------------------------+----------+
+| | Des\ | Section Type applicable | Remarks |
+| | cription | | |
++==========+===========+==========+=========+===+===+===+===+==========+
+| | | 0 | 1 | 3 | 5 | 6 | 7 | |
++----------+-----------+----------+---------+---+---+---+---+----------+
+| fftSize || FFT size | X | | X | | | | 5.4.4.13 |
+| || in frame | | | | | | | |
+| || st\ | | | | | | | |
+| | ructure. | | | | | | | |
+| || A\ | | | | | | | |
+| | vailable | | | | | | | |
+| || values | | | | | | | |
+| || are | | | | | | | |
+| || defined | | | | | | | |
+| || as | | | | | | | |
+| || X\ | | | | | | | |
+| | RAN_FFT\ | | | | | | | |
+| || SIZE_xxxx| | | | | | | |
++----------+-----------+----------+---------+---+---+---+---+----------+
+| Scs || Su\ | X | | X | | | | 5.4.4.13 |
+| | bcarrier | | | | | | | |
+| || Spacing | | | | | | | |
+| || in the | | | | | | | |
+| || frame | | | | | | | |
+| || st\ | | | | | | | |
+| | ructure. | | | | | | | |
+| || A\ | | | | | | | |
+| | vailable | | | | | | | |
+| || values | | | | | | | |
+| || are | | | | | | | |
+| || defined | | | | | | | |
+| || as | | | | | | | |
+| || XRAN_SCS\| | | | | | | |
+| | _xxxx | | | | | | | |
++----------+-----------+----------+---------+---+---+---+---+----------+
+| iqWidth || I/Q bit | | X | X | X | | | 5.4.4.10 |
+| || width in | | | | | | | |
+| || user | | | | | | | 6.3.3.13 |
+| || data | | | | | | | |
+| || com\ | | | | | | | |
+| | pression | | | | | | | |
+| || header. | | | | | | | |
+| || Should | | | | | | | |
+| || be set | | | | | | | |
+| || by zero | | | | | | | |
+| || for | | | | | | | |
+| || 16bits | | | | | | | |
++----------+-----------+----------+---------+---+---+---+---+----------+
+| compMeth || Com\ | | X | X | X | | | 5.4.4.10 |
+| | pression | | | | | | | |
+| || Method | | | | | | | 6.3.3.13 |
+| || in user | | | | | | | |
+| || data | | | | | | | |
+| || com\ | | | | | | | |
+| | pression | | | | | | | |
+| || header. | | | | | | | |
+| || A\ | | | | | | | |
+| | vailable | | | | | | | |
+| || values | | | | | | | |
+| || are | | | | | | | |
+| || defined | | | | | | | |
+| || as | | | | | | | |
+| || X-RAN\ | | | | | | | |
+| | _COMP | | | | | | | |
+| || METHOD_x\| | | | | | | |
+| || xxx | | | | | | | |
++----------+-----------+----------+---------+---+---+---+---+----------+
+| numUEs || Number | | | | | X | | 5.4.4.11 |
+| || of UEs. | | | | | | | |
+| || Applies | | | | | | | |
+| || to | | | | | | | |
+| || section | | | | | | | |
+| || type 6 | | | | | | | |
+| || and not | | | | | | | |
+| || s\ | | | | | | | |
+| | upported | | | | | | | |
+| || in this | | | | | | | |
+| || release. | | | | | | | |
++----------+-----------+----------+---------+---+---+---+---+----------+
+| ti\ || Time | X | | X | | | | 5.4.4.12 |
+| meOffset || Offset. | | | | | | | |
+| || Time | | | | | | | |
+| || offset | | | | | | | |
+| || from the | | | | | | | |
+| || start of | | | | | | | |
+| || the slot | | | | | | | |
+| || to start | | | | | | | |
+| || of | | | | | | | |
+| || Cyclic | | | | | | | |
+| || Prefix. | | | | | | | |
++----------+-----------+----------+---------+---+---+---+---+----------+
+| cpLength || Cyclic | X | | X | | | | 5.4.4.14 |
+| || Prefix | | | | | | | |
+| || Length. | | | | | | | |
++----------+-----------+----------+---------+---+---+---+---+----------+
+
+**Note:**
+
+1.Only sections types 1 and 3 are supported in the current release.
+
+2.References in the remarks column are corresponding Chapter numbers in
+the *O-RAN Fronthaul Working Group Control, User, and
+Synchronization Plane Specification* in *Table 2*.
Sections are the pointer to the array of structure which has the
-parameters for section(s) and it is defined as below:
+parameters for section(s) and it is defined as below:::
-struct xran_section_gen_info {
+ struct xran_section_gen_info {
-struct xran_section_info info;
+ struct xran_section_info info;
-uint32_t exDataSize;
+ uint32_t exDataSize;
-struct {
+ struct {
-uint16_t type;
+ uint16_t type;
-uint16_t len;
+ uint16_t len;
-void \*data;
+ void \*data;
-} exData[XRAN_MAX_NUM_EXTENSIONS];
+ } exData[XRAN_MAX_NUM_EXTENSIONS];
-};
+ };
info is the structure to hold the information to generate section and it
is defined as the structure of xran_section_info. Like
xran_cp_header_params, all parameters are not required to generate
-section and Table 12 describes which |br|
-parameters are required for each
+section and *Table 12* describes which parameters are required for each
section.
Table 12. Parameters for Sections
-+-------+-------+-------+-------+-------+-------+-------+-------+
-| | D\ | Se\ | Re\ | | | | |
-| | escri\| ction | marks | | | | |
-| | ption | Type | | | | | |
-| | | appli\| | | | | |
-| | | cable | | | | | |
++-------+-------+---------------------------------------+-------+
+| | Descr\| Section Type applicable | Remar\|
+| | iption| | ks |
+=======+=======+=======+=======+=======+=======+=======+=======+
| | | 0 | 1 | 3 | 5 | 6 | |
+-------+-------+-------+-------+-------+-------+-------+-------+
-| Id | Se\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
+| Id || Se\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
| | ction | | | | | | 4.5.1 |
-| | I\ | | | | | | |
+| || I\ | | | | | | |
| | denti\| | | | | | |
| | fier. | | | | | | |
+-------+-------+-------+-------+-------+-------+-------+-------+
-| Rb | Res\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
-| | ource | | | | | | 4.5.2 |
-| | Block\| | | | | | |
-| | Indic\| | | | | | |
-| | ator. | | | | | | |
-| | Avai\ | | | | | | |
+| Rb || Res\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
+| || ource| | | | | | 4.5.2 |
+| || Block| | | | | | |
+| || Indi\| | | | | | |
+| | cator.| | | | | | |
+| || Avai\| | | | | | |
| | lable | | | | | | |
-| | v\ | | | | | | |
+| || v\ | | | | | | |
| | alues | | | | | | |
-| | are | | | | | | |
-| | de\ | | | | | | |
+| || are | | | | | | |
+| || de\ | | | | | | |
| | fined | | | | | | |
-| | as | | | | | | |
-| | XRAN\ | | | | | | |
-| | _\ | | | | | | |
-| | RBI\ | | | | | | |
-| | ND_xx\| | | | | | |
-| | xx. | | | | | | |
+| || as | | | | | | |
+| || X-RA\| | | | | | |
+| | N\ | | | | | | |
+| || _RBI\| | | | | | |
+| | ND\ | | | | | | |
+| || _xxxx| | | | | | |
+-------+-------+-------+-------+-------+-------+-------+-------+
-| s\ | S\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
+| s\ || S\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
| ymInc | ymbol | | | | | | 4.5.3 |
-| | n\ | | | | | | |
+| || n\ | | | | | | |
| | umber | | | | | | |
-| | Incr\ | | | | | | |
+| || Incr\| | | | | | |
| | ement | | | | | | |
-| | com\ | | | | | | |
+| || com\ | | | | | | |
| | mand. | | | | | | |
-| | Avai\ | | | | | | |
+| || Avai\| | | | | | |
| | lable | | | | | | |
-| | v\ | | | | | | |
+| || v\ | | | | | | |
| | alues | | | | | | |
-| | are | | | | | | |
-| | de\ | | | | | | |
+| || are | | | | | | |
+| || de\ | | | | | | |
| | fined | | | | | | |
-| | as | | | | | | |
-| | XRA\ | | | | | | |
+| || as | | | | | | |
+| || XRA\ | | | | | | |
| | N_SYM\| | | | | | |
-| | BOL\ | | | | | | |
-| | NUMBE\| | | | | | |
-| | R_xx\ | | | | | | |
-| | xx. | | | | | | |
+| || BOL\ | | | | | | |
+| || NUMB\| | | | | | |
+| | ER | | | | | | |
+| || _xxxx| | | | | | |
+-------+-------+-------+-------+-------+-------+-------+-------+
-| star\ | Sta\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
+|| star\|| Sta\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
| tPrbc | rting\| | | | | | 4.5.4 |
-| | PRB | | | | | | |
+| || PRB | | | | | | |
| | of | | | | | | |
| | data | | | | | | |
-| | se\ | | | | | | |
+| || se\ | | | | | | |
| | ction | | | | | | |
-| | de\ | | | | | | |
+| || de\ | | | | | | |
| | scrip\| | | | | | |
| | tion. | | | | | | |
+-------+-------+-------+-------+-------+-------+-------+-------+
-| nu | The | **X** | **X** | **X** | **X** | **X** | 5.\ |
-| mPrbc | n\ | | | | | | 4.5.6 |
+|| num\ || The | **X** | **X** | **X** | **X** | **X** | 5.\ |
+| Prbc | n\ | | | | | | 4.5.6 |
| | umber | | | | | | |
-| | of | | | | | | |
-| | conti\| | | | | | |
-| | guous | | | | | | |
-| | PRBs | | | | | | |
-| | per | | | | | | |
-| | data | | | | | | |
-| | se\ | | | | | | |
+| || of | | | | | | |
+| || cont\| | | | | | |
+| | iguous| | | | | | |
+| || PRBs | | | | | | |
+| || per | | | | | | |
+| || data | | | | | | |
+| || se\ | | | | | | |
| | ction | | | | | | |
-| | de\ | | | | | | |
+| || de\ | | | | | | |
| | scrip\| | | | | | |
| | tion. | | | | | | |
-| | When | | | | | | |
-| | nu\ | | | | | | |
+| || When | | | | | | |
+| || nu\ | | | | | | |
| | mPrbc | | | | | | |
-| | is | | | | | | |
-| | gr\ | | | | | | |
+| || is | | | | | | |
+| || gr\ | | | | | | |
| | eater | | | | | | |
-| | than | | | | | | |
+| || than | | | | | | |
| | 255, | | | | | | |
-| | it | | | | | | |
+| || it | | | | | | |
| | will | | | | | | |
| | be | | | | | | |
-| | conv\ | | | | | | |
+| || conv\| | | | | | |
| | erted | | | | | | |
-| | to | | | | | | |
+| || to | | | | | | |
| | zero | | | | | | |
-| | by | | | | | | |
+| || by | | | | | | |
| | the | | | | | | |
| | macro | | | | | | |
-| | (XR\ | | | | | | |
-| | AN_CO\| | | | | | |
-| | NVERT\| | | | | | |
-| | _NUMP\| | | | | | |
-| | RBC). | | | | | | |
+| || (XRA\| | | | | | |
+| | N_CO\| | | | | | |
+| | NVERT| | | | | | |
+| || _NUM\| | | | | | |
+| || PRBC)| | | | | | |
+-------+-------+-------+-------+-------+-------+-------+-------+
| r\ | Res\ | **X** | **X** | **X** | **X** | | 5.\ |
| eMask | ource\| | | | | | 4.5.5 |
| | Of\ | | | | | | |
| | fset. | | | | | | |
+-------+-------+-------+-------+-------+-------+-------+-------+
-| ueId | UE\ | | | | **X** | **X** | 5.4\ |
+| ueId || UE\ | | | | **X** | **X** | 5.4\ |
| | i\ | | | | | | .5.10 |
| | denti\| | | | | | |
| | fier. | | | | | | |
-| | Not | | | | | | |
-| | supp\ | | | | | | |
+| || Not | | | | | | |
+| || supp\| | | | | | |
| | orted | | | | | | |
-| | in | | | | | | |
+| || in | | | | | | |
| | this | | | | | | |
-| | rel\ | | | | | | |
+| || rel\ | | | | | | |
| | ease. | | | | | | |
+-------+-------+-------+-------+-------+-------+-------+-------+
-| regF\ | Regu\ | | | | | **X** | 5.4\ |
+| regF\ || Regu\| | | | | **X** | 5.4\ |
| actor | lariz\| | | | | | .5.12 |
| | ation | | | | | | |
-| | Fa\ | | | | | | |
+| || Fa\ | | | | | | |
| | ctor. | | | | | | |
-| | Not | | | | | | |
-| | supp\ | | | | | | |
+| || Not | | | | | | |
+| || supp\| | | | | | |
| | orted | | | | | | |
-| | in | | | | | | |
+| || in | | | | | | |
| | this | | | | | | |
| | re\ | | | | | | |
| | lease | | | | | | |
+-------+-------+-------+-------+-------+-------+-------+-------+
-| Ef | Exte\ | | **X** | **X** | **X** | **X** | 5.\ |
+| Ef || Exte\| | **X** | **X** | **X** | **X** | 5.\ |
| | nsion | | | | | | 4.5.8 |
| | Flag. | | | | | | |
-| | Not | | | | | | |
-| | supp\ | | | | | | |
+| || Not | | | | | | |
+| || supp\| | | | | | |
| | orted | | | | | | |
-| | in | | | | | | |
+| || in | | | | | | |
| | this | | | | | | |
| | rel\ | | | | | | |
| | ease. | | | | | | |
+-------+-------+-------+-------+-------+-------+-------+-------+
-**Only sections types 1 and 3 are supported in the current release.**
+Note:
-**The xran_section_info has more parameters – type, startSymId, iqWidth,
+1.Only sections types 1 and 3 are supported in the current release.
+
+2.References in the remarks column are corresponding Chapter numbers in
+the *O-RAN FrontHaul Working Group Control, User, and
+Synchronization Plane Specification* in *Table 2*.
+
+Note: xran_section_info has more parameters – type, startSymId, iqWidth,
compMeth. These are the same parameters as those of radio application
or section header but need to be copied into this structure again for
-the section data base.**
+the section data base.
exDataSize and exData are used to add section extensions for the
section.
of section extension and exData.len is the length of structure of
section extension parameter in exData.data. exData.data is the pointer
to the structure of section extensions and different structures are used
-by the type of section extensions like below.
+by the type of section extensions like below.::
-struct xran_sectionext1_info {
+ struct xran_sectionext1_info {
-uint16_t rbNumber; /* number RBs to ext1 chain \*/
+ uint16_t rbNumber; /* number RBs to ext1 chain \*/
-uint16_t bfwNumber; /* number of bf weights in this section \*/
+ uint16_t bfwNumber; /* number of bf weights in this section \*/
-uint8_t bfwiqWidth;
+ uint8_t bfwiqWidth;
-uint8_t bfwCompMeth;
+ uint8_t bfwCompMeth;
-int16_t \*p_bfwIQ; /* pointer to formed section extention \*/
+ int16_t \*p_bfwIQ; /* pointer to formed section extention \*/
-int16_t bfwIQ_sz; /* size of buffer with section extention information
-\*/
+ int16_t bfwIQ_sz; /* size of buffer with section extention information
+ \*/
-union {
+ union {
-uint8_t exponent;
+ uint8_t exponent;
-uint8_t blockScaler;
+ uint8_t blockScaler;
-uint8_t compBitWidthShift;
+ uint8_t compBitWidthShift;
-uint8_t activeBeamspaceCoeffMask[XRAN_MAX_BFW_N]; /\* ceil(N/8)*8,
-should be multiple of 8 \*/
+ uint8_t activeBeamspaceCoeffMask[XRAN_MAX_BFW_N]; /\* ceil(N/8)*8,
+ should be multiple of 8 \*/
-} bfwCompParam;
+ } bfwCompParam;
-};
+ };
For section extension type 1, the structure of xran_sectionext1_info is
-used. Please note that the xRAN library will use bfwIQ (beamforming
-weight) as-is, i.e., xRAN library will not perform the compression, so
-the user should provide proper data to bfwIQ.
+used.
-struct xran_sectionext2_info {
+Note: The O-RAN library will use beamforming weight (bfwIQ) as-is, i.e.,
+O-RAN library will not perform the compression, so the user should provide
+proper data to bfwIQ.::
-uint8_t bfAzPtWidth;
+ struct xran_sectionext2_info {
-uint8_t bfAzPt;
+ uint8_t bfAzPtWidth;
-uint8_t bfZePtWidth;
+ uint8_t bfAzPt;
-uint8_t bfZePt;
+ uint8_t bfZePtWidth;
-uint8_t bfAz3ddWidth;
+ uint8_t bfZePt;
-uint8_t bfAz3dd;
+ uint8_t bfAz3ddWidth;
-uint8_t bfZe3ddWidth;
+ uint8_t bfAz3dd;
-uint8_t bfZe3dd;
+ uint8_t bfZe3ddWidth;
-uint8_t bfAzSI;
+ uint8_t bfZe3dd;
-uint8_t bfZeSI;
+ uint8_t bfAzSI;
-};
+ uint8_t bfZeSI;
+
+ };
For section extension type 2, the structure of xran_sectionext2_info is
-used. Each parameter will be packed as specified bit width.
+used. Each parameter will be packed as specified bit width.::
-struct xran_sectionext4_info {
+ struct xran_sectionext3_info {
-uint8_t csf;
+ uint8_t codebookIdx;
-uint8_t pad0;
+ uint8_t layerId;
-uint16_t modCompScaler;
+ uint8_t numLayers;
-};
+ uint8_t txScheme;
+
+ uint16_t crsReMask;
+
+ uint8_t crsShift;
+
+ uint8_t crsSymNum;
+
+ uint16_t numAntPort;
+
+ uint16_t beamIdAP1;
+
+ uint16_t beamIdAP2;
+
+ uint16_t beamIdAP3;
+
+ };
+
+For section extension type 3, the structure of xran_sectionext3_info is
+used.::
+
+ struct xran_sectionext4_info {
+
+ uint8_t csf;
+
+ uint8_t pad0;
+
+ uint16_t modCompScaler;
+
+ };
For section extension type 4, the structure of xran_sectionext4_info is
-used.
+used.::
-struct xran_sectionext5_info {
+ struct xran_sectionext5_info {
-uint8_t num_sets;
+ uint8_t num_sets;
-struct {
+ struct {
-uint16_t csf;
+ uint16_t csf;
-uint16_t mcScaleReMask;
+ uint16_t mcScaleReMask;
-uint16_t mcScaleOffset;
+ uint16_t mcScaleOffset;
-} mc[XRAN_MAX_MODCOMP_ADDPARMS];
+ } mc[XRAN_MAX_MODCOMP_ADDPARMS];
-};
+ };
For section extension type 5, the structure of xran_sectionext5_info is
-used. Please note that current implementation supports maximum two sets
-of additional parameters.
+used.
+
+Note: Current implementation supports maximum two sets of additional parameters.::
+
+ struct xran_sectionext6_info {
+
+ uint8_t rbgSize;
+
+ uint8_t pad;
+
+ uint16_t symbolMask;
+
+ uint32_t rbgMask;
+
+ };
+
+For section extension type 6, the structure of xran_sectionext6_info is
+used.::
+
+ struct xran_sectionext10_info {
+
+ uint8_t numPortc;
+
+ uint8_t beamGrpType;
+
+ uint16_t beamID[XRAN_MAX_NUMPORTC_EXT10];
+
+ };
+
+For section extension type 10, the structure of xran_sectionext10_info
+is used.::
+
+ struct xran_sectionext11_info {
+
+ uint8_t RAD;
+
+ uint8_t disableBFWs;
+
+ uint8_t numBundPrb;
+
+ uint8_t numSetBFWs; /\* Total number of beam forming weights set (L) \*/
+
+ uint8_t bfwCompMeth;
+
+ uint8_t bfwIqWidth;
+
+ int totalBfwIQLen;
+
+ int maxExtBufSize; /\* Maximum space of external buffer \*/
-**Section extensions type 3 is not supported since it is LTE specific.**
+ uint8_t \*pExtBuf; /\* pointer to start of external buffer \*/
-Section Extensions are not fully verified in this release.
+ void \*pExtBufShinfo; /\* Pointer to rte_mbuf_ext_shared_info \*/
+
+ };
+
+For section extension type 11, the structure of xran_sectionext11_info
+is used.
+
+To minimize memory copy for beamforming weights, when section extension
+11 is required to send beamforming weights(BFWs), external flat buffer
+is being used in current release. If extension 11 is used, it will be
+used instead of mbufs that pre-allocated external buffers which BFWs
+have been prepared already. BFW can be prepared by
+xran_cp_prepare_ext11_bfws() and the example usage can be found from
+app_init_xran_iq_content() from sample-app.c.
Detail Procedures in API
''''''''''''''''''''''''
-xran_prepare_ctrl_pkt() has several procedures to compose a C-Plane
+The xran_prepare_ctrl_pkt() has several procedures to compose a C-Plane
packet.
-1. Append transport header
+1. Append transport header:
- Reserve eCPRI header space in the packet buffer
2. Append radio application header:
-- xran_append_radioapp_header() checks the type of section through
- params->sectionType and determines proper function to append
- remaining header components.
+- The xran_append_radioapp_header() checks the type of section through params->sectionType and determines proper function to append remaining header components.
- Only section type 1 and 3 are supported, returns
XRAN_STATUS_INVALID_PARAM for other types.
header and size to calculate the total length in the transport
header.
-For section type 1, xran_prepare_section1_hdr() and sizeof(struct
-xran_cp_radioapp_section1_header)
+- For section type 1, xran_prepare_section1_hdr() and sizeof(struct xran_cp_radioapp_section1_header)
-For section type 3, xran_prepare_section3_hdr() and sizeof(struct
-xran_cp_radioapp_section3_header)
+- For section type 3, xran_prepare_section3_hdr() and sizeof(struct xran_cp_radioapp_section3_header)
-- Reserves the space of common radio application header and composes
- header by xran_prepare_radioapp_common_header().
+- Reserves the space of common radio application header and composes header by xran_prepare_radioapp_common_header().
-- The header is stored in network byte order.
+ The header is stored in network byte order.
- Appends remaining header components by the selected function above
-- The header is stored in network byte order
+ The header is stored in network byte order
-3. Append section header and section
+3. Append section header and section:
-- xran_append_control_section() determines proper size and function to
- append section header and contents.
+- The xran_append_control_section() determines proper size and function to append section header and contents.
- For section type 1, xran_prepare_section1() and sizeof(struct
xran_cp_radioapp_section1)
- Appends section extensions if it is set (ef=1)
-- xran_append_section_extensions() adds all configured extensions by
- its type.
+- The xran_append_section_extensions() adds all configured extensions by its type.
-- xran_prepare_sectionext_x() (x = 1,2,4,5) will be called by the
- type from xran_append_section_extensions() and these functions
- will create extension field.
+- The xran_prepare_sectionext_x() (x = 1,2,4,5) will be called by the type from and these functions will create extension field.
-**Example Usage of API**
-''''''''''''''''''''''''
+Example Usage of API
+''''''''''''''''''''
-There are two reference usages of API to generate C-Plane message in
-lib/src/xran_common.c
+There are two reference usages of API to generate C-Plane messages:
-- generate_cpmsg_dlul()
+- xran_cp_create_and_send_section() in xran_main.c
-- generate_cpmsg_prach()
+- generate_cpmsg_prach() in xran_common.c
-generate_cpmsg_dlul() is to generate the C-Plane message with section
-type 1 for DL or UL symbol data scheduling.
+The xran_cp_create_and_send_section() is to generate the C-Plane message
+with section type 1 for DL or UL symbol data scheduling.
This function has hardcoded values for some parameters such as:
- Resource Element Mask is fixed to 0xfff
-The extension is not used.
-
-After C-Plane message generation, API send_cpmsg() is called. This
-function also includes the implementation for these capabilities:
+If section extensions include extension 1 or 11, direct mbuf will not be
+allocated/used and pre-allocated flat buffer will be attached to
+indirect mbuf. This external buffer will be used to compose C-Plane
+message and should have BFWs already by xran_cp_populate_section_ext_1()
+or xran_cp_prepare_ext11_bfws().
-- Send the generated packet to the TX ring after adding an Ethernet
- header.
+Since current implementation uses single section single C-Plane message,
+if multi sections are present, this function will generate same amount
+of C-Plane messages with the number of sections.
-- Add section information of generated C-Plane packet to section
- database, to generate U-plane message by C-Plane configuration
+After C-Plane message generation, it will send generated packet to TX
+ring after adding an Ethernet header and also will add section
+information of generated C-Plane packet to section database, to generate
+U-plane message by C-Plane configuration.
-send_cpmsg_prach() is to generate the C-Plane message with section type
-3 for PRACH scheduling.
+The generate_cpmsg_prach()is to generate the C-Plane message with
+section type 3 for PRACH scheduling.
This functions also has some hardcoded values for the following
parameters:
- Resource Element Mask is fixed to 0xfff.
-And similar to generate_cpmsg_dlul(), after this function generates the
-message, send_cpmsg() sends the generated packet to the TX ring and adds
-section information of the packet to the section database. Checking and
-parsing received PRACH symbol data by section information from the
-C-Plane are not implemented in this release.
+This function does not send generated packet, send_cpmsg() should be
+called after this function call. The example can be found from
+tx_cp_ul_cb() in xran_main.c. Checking and parsing received PRACH symbol
+data by section information from the C-Plane are not implemented in this
+release.
Example Configuration of C-Plane Messages
'''''''''''''''''''''''''''''''''''''''''
- Compression and beamforming are not used
+Common Header Fields::
+
+- dataDirection = XRAN_DIR_DL
+- payloadVersion = XRAN_PAYLOAD_VER
+- filterIndex = XRAN_FILTERINDEX_STANDARD
+- frameId = [0..99]
+- subframeId = [0..9]
+- slotID = [0..9]
+- startSymbolid = 0
+- numberOfsections = 1
+- sectionType = XRAN_CP_SECTIONTYPE_1
+- udCompHdr.idIqWidth = 0
+- udCompHdr.udCompMeth = XRAN_COMPMETHOD_NONE
+- reserved = 0
+
+Section Fields::
+
+- sectionId = [0..4095]
+- rb = XRAN_RBIND_EVERY
+- symInc = XRAN_SYMBOLNUMBER_NOTINC
+- startPrbc = 0
+- numPrbc = 66
+- reMask = 0xfff
+- numSymbol = 14
+- ef = 0
+- beamId = 0
+
+
**C-Plane Message – uplink symbol data for uplink slot**
- Single CP message with the single section of section type 1
- Compression and beamforming are not used
+Common Header Fields::
+
+- dataDirection = XRAN_DIR_UL
+- payloadVersion = XRAN_PAYLOAD_VER
+- filterIndex = XRAN_FILTERINDEX_STANDARD
+- frameId = [0..99]
+- subframeId = [0..9]
+- slotID = [0..9]
+- startSymbolid = 3
+- numberOfsections = 1
+- sectionType = XRAN_CP_SECTIONTYPE_1
+- udCompHdr.idIqWidth = 0
+- udCompHdr.udCompMeth = XRAN_COMPMETHOD_NONE
+- reserved = 0
+
+Section Fields::
+
+- sectionId = [0..4095]
+- rb = XRAN_RBIND_EVERY
+- symInc = XRAN_SYMBOLNUMBER_NOTINC
+- startPrbc = 0
+- numPrbc = 66
+- reMask = 0xfff
+- numSymbol = 11
+- ef = 0
+- beamId = 0
+
+
**C-Plane Message – PRACH**
- Single CP message with the single section of section type 3 including
- Compression and beamforming are not used
+Common Header Fields::
+
+- dataDirection = XRAN_DIR_UL
+- payloadVersion = XRAN_PAYLOAD_VER
+- filterIndex = XRAN_FILTERINDEPRACH_ABC
+- frameId = [0,99]
+- subframeId = [0,3]
+- slotID = 3 or 7
+- startSymbolid = 7
+- numberOfSections = 1
+- sectionType = XRAN_CP_SECTIONTYPE_3
+- timeOffset = 2026
+- frameStructure.FFTSize = XRAN_FFTSIZE_1024
+- frameStructure.u = XRAN_SCS_120KHZ
+- cpLength = 0
+- udCompHdr.idIqWidth = 0
+- udCompHdr.udCompMeth = XRAN_COMPMETHOD_NONE
+
+Section Fields::
+
+- sectionId = [0..4095]
+- rb = XRAN_RBIND_EVERY
+- symInc = XRAN_SYMBOLNUMBER_NOTINC
+- startPrbc = 0
+- numPrbc = 12
+- reMask = 0xfff
+- numSymbol = 6
+- ef = 0
+- beamId = 0
+- frequencyOffset = -792
+- reserved
+
+
Functions to Store/Retrieve Section Information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are several functions to store/retrieve section information of
C-Plane messages. Since U-plane messages must be generated by the
information in the sections of a C-Plane message, it is required to
-store and retrieve section |br|
-information.
+store and retrieve section information.
**APIs and Data Structure**
'''''''''''''''''''''''''''
The structure of xran_section_info is used to store/retrieve
information. This is the same structure used to generate a C-Plane
-message. Please refer to Section 5.4.2.1.1 for more details.
+message. Refer to Section *1, API and Data Structures* for more details.
The storage for section information is declared as a multi-dimensional
array and declared as a local static variable to limit direct access.
of the information (list), as shown below.
/*
-
\* This structure to store the section information of C-Plane
-
\* in order to generate and parse corresponding U-Plane \*/
struct xran_sectioninfo_db {
-
-uint32_t cur_index; /* Current index to store for this eAXC \*/
-
+uint32_t cur_index; /* Current index to store for this eAXC*/\
struct xran_section_info list[XRAN_MAX_NUM_SECTIONS]; /* The array of
section information \*/
maximum number of context is defined by two and it can be adjusted if
needed.
-8. Since the context index is not managed by the library and APIs are
+Note. Since the context index is not managed by the library and APIs are
expecting it from the caller as a parameter, the caller shall
consider a proper method to manage it to avoid corruption. The
current reference implementation uses a slot and subframe index to
There are references to show the usage of APIs as below.
-- Initialization and release:
+- Initialization and release::
-- xran_cp_init_sectiondb(): xran_open() in lib/src/xran_main.c
+ xran_cp_init_sectiondb(): xran_open() in lib/src/xran_main.c
-- xran_cp_free_sectiondb(): xran_close() in lib/src/xran_main.c
+ xran_cp_free_sectiondb(): xran_close() in lib/src/xran_main.c
-- Store section information:
+- Store section information::
-- xran_cp_add_section_info(): send_cpmsg_dlul() and
- send_cpmsg_prach()in lib/src/xran_main.c
+ xran_cp_add_section_info(): send_cpmsg_dlul() and
+ send_cpmsg_prach()in lib/src/xran_main.c
-- Retrieve section information:
+- Retrieve section information::
-- xran_cp_iterate_section_info(): xran_process_tx_sym() in
- lib/src/xran_main.c
+ xran_cp_iterate_section_info(): xran_process_tx_sym() in
+ lib/src/xran_main.c
-- xran_cp_getsize_section_info(): xran_process_tx_sym() in
- lib/src/xran_main.c
+ xran_cp_getsize_section_info(): xran_process_tx_sym() in
+ lib/src/xran_main.c
-- Reset the storage for a new slot:
+- Reset the storage for a new slot::
-- xran_cp_reset_section_info(): tx_cp_dl_cb() and tx_cp_ul_cb() in
- lib/src/xran_main.c
+ xran_cp_reset_section_info(): tx_cp_dl_cb() and tx_cp_ul_cb() in
+ lib/src/xran_main.c
**Function for RU emulation and Debug**
'''''''''''''''''''''''''''''''''''''''
xran_parse_cp_pkt() is a function which can be utilized for RU emulation
-or debug. It is defined below:
-
-int xran_parse_cp_pkt(struct rte_mbuf \*mbuf,
+or debug. It is defined below::
-struct xran_cp_gen_params \*result,
-
-struct xran_recv_packet_info \*pkt_info);
+ int xran_parse_cp_pkt(struct rte_mbuf \*mbuf,
+ struct xran_cp_recv_params \*result,
+ struct xran_recv_packet_info \*pkt_info);
It parses a received C-Plane packet and retrieves the information from
its headers and sections.
The retrieved information is stored in the structures:
-struct xran_cp_gen_params: section information from received C-Plane
+struct xran_cp_recv_params: section information from received C-Plane
packet
-struct xran_recv_packet_info: transport layer header information (eCPRI
-header)
+struct xran_recv_packet_info: transport layer header information
+(eCPRI header)
These functions can be utilized to debug or RU emulation purposes.
U-plane
~~~~~~~
-Single Section is the default mode of xRAN packet creation. It assumes
+Single Section is the default mode of O-RAN packet creation. It assumes
that there is only one section per packet, and all IQ samples are
attached to it. Compression is not supported.
-A message is built in mbuf space given as a parameter. The library
+A message is built in the mbuf space given as a parameter. The library
builds eCPRI header filling structure fields by taking the IQ sample
size and populating a particular packet length and sequence number.
-Currently, the supported IQ bit width is 16.
+With block floating point compression, supported IQ bit widths are
+8,9,10,12,14. With modulation compression, supported IQ bit widths are
+defined according to modulation order as in section A.5 of O-RAN spec..
Implementation of a U-plane set of functions is defined in xran_up_api.c
and is used to prepare U-plane packet content according to the given
- Append IQ samples to packet
-- Prepare full symbol of xRAN data for single eAxC
+- Prepare full symbol of O-RAN data for single eAxC
- Process RX packet per symbol.
The time of generation of a U-plane message for DL and UL is
“symbol-based” and can be controlled using O-DU settings (O-RU),
-according to Table 4.
+according to *Table 4*.
+
+For more information on function arguments and parameters refer to
+corresponding source cod*\ e.
Supporting Code
---------------
-The xRAN library has a set of functions used to assist in packet
-processing and data exchange not directly used for xRAN packet
+The O-RAN library has a set of functions used to assist in packet
+processing and data exchange not directly used for O-RAN packet
processing.
Timing
~~~~~~
-The sense of time for the xRAN protocol is obtained from system time,
+The sense of time for the O-RAN protocol is obtained from system time,
where the system timer is synchronized to GPS time via PTP protocol
using the Linux PHP package. On the software side, a simple polling loop
is utilized to get time up to nanosecond precision and particular packet
-processing jobs are scheduled via the DPDK timer.
+processing jobs are scheduled via the DPDK timer.:::
-long poll_next_tick(int interval)
+ long poll_next_tick(int interval)
-{
+ {
-struct timespec start_time;
+ struct timespec start_time;
-struct timespec cur_time;
+ struct timespec cur_time;
-long target_time;
+ long target_time;
-long delta;
+ long delta;
-clock_gettime(CLOCK_REALTIME, &start_time);
+ clock_gettime(CLOCK_REALTIME, &start_time);
-target_time = (start_time.tv_sec \* NSEC_PER_SEC + start_time.tv_nsec +
-interval \* NSEC_PER_USEC) / (interval \* NSEC_PER_USEC) \* interval;
+ target_time = (start_time.tv_sec \* NSEC_PER_SEC + start_time.tv_nsec +
+ interval \* NSEC_PER_USEC) / (interval \* NSEC_PER_USEC) \* interval;
-while(1)
+ while(1)
-{
+ {
-clock_gettime(CLOCK_REALTIME, &cur_time);
+ clock_gettime(CLOCK_REALTIME, &cur_time);
-delta = (cur_time.tv_sec \* NSEC_PER_SEC + cur_time.tv_nsec) -
-target_time \* NSEC_PER_USEC;
+ delta = (cur_time.tv_sec \* NSEC_PER_SEC + cur_time.tv_nsec) -
+ target_time \* NSEC_PER_USEC;
-if(delta > 0 \|\| (delta < 0 && abs(delta) < THRESHOLD))
+ if(delta > 0 \|\| (delta < 0 && abs(delta) < THRESHOLD))
-{
+ {
-break;
+ break;
-}
+ }
-}
+ }
-return delta;
+ return delta;
-}
+ }
Polling is used to achieve the required precision of symbol time. For
example, in the mmWave scenario, the symbol time is 125µs/14=~8.9µs.
Small deterministic tasks can be executed within the polling interval
provided. It’s smaller than the symbol interval time.
+Current O-RAN library supports multiple O-RU of multiple numerologies,
+thus the sense of timing is based on the O-RU with highest numerology
+(smallest symbol time). It is required to configure the O-RU0 with
+highest numerology in the O-RAN configuration.
+
DPDK Timers
~~~~~~~~~~~
the system timer which in turn is synchronized to PTP (GPS)
Only single-shot timers are used to schedule processing based on
-particular events such as symbol time. The packet |br|
+events such as symbol time. The packet |br|
processing function
calls rte_timer_manage() in the loop, and the resulting execution of
timer function happens right |br|
after the timer was “armed”.
-xRAN Ethernet
-~~~~~~~~~~~~~
+O-RAN Ethernet
+~~~~~~~~~~~~~~
xran_init_port() function performs initialization of DPDK ETH port.
Standard port configuration is used as per reference example from DPDK.
Jumbo Frames are used by default. Mbufs size is extended to support 9600
bytes packets.
-Mac address and VLAN tag are expected to be configured by Infrastructure
-software. See Appendix A.4.
+Configurable MTU size is supported starting from E release.
+
+MAC address and VLAN tag are expected to be configured by Infrastructure
+software. Refer to *A.4, Install and Configure Sample Application*.
From an implementation perspective, modules provide functions to handle:
functions.
For received packets, it maintains a set of handlers for ethertype
-handlers and xRAN layer register one xRAN ethtype |br|
+handlers and xRAN layer register one O-RAN ethtype |br|
0xAEFE, resulting in
packets with this ethertype being routed to the xRAN processing
function. This function checks the message type of the eCPRI header and
dispatches packet to either C-plane processing or U-plane processing.
-Initialization of memory pools, allocation and freeing of mbuf for
+Initialization of memory pools, allocation, and freeing of the mbuf for
Ethernet packets occur in this layer.
+O-RAN One Way Delay Measurements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The support for the eCPRI one- way delay measurements which are
+specified by the O-RAN to be used with the Measured Transport support
+per Section 2.3.3.3 of the O-RAN-WG4.CUS.0-v4.00 specification and
+section 3.2.4.6 of the eCPRI_v2.0 specification is implemented in the
+file xran_delay_measurement.c. Structure definitions used by the owd
+measurement functions are in the file xran_fh_o_du.h for common data and
+port specific variables and parameters.
+
+The implementation of this feature has been done under the assumption
+that the requestor is the O-DU and the recipient is the O-RU. All of the
+action_types per the eCPRI 2.0 have been implemented. In the current
+version the timestamps are obtained using the linux function
+clock_gettime using CLOCK_REALTIME as the clock_id argument.
+
+The implementation supports both the O-RU and the O-DU side in order to
+do the unit test in loopback mode.
+
+The one-delay measurements are enabled at configuration time and run
+right after the xran_start() function is executed. The total number of
+consecutive measurements per port should be a power of 2 and in order to
+minimize the system startup it is advisable that the number is 16 or
+below.
+
+The following functions can be found in the xran_delay_measurement.c:
+
+xran_ecpri_one_way_delay_measurement_transmitter() which is invoked from
+the process_dpdk_io() function if the one-way delay measurements are
+enabled. This is the main function for the owd transmitter.
+
+xran_generate_delay_meas() is a general function used by the transmitter
+to send the appropriate messages based on actionType and filling up all
+the details for the ethernet and ecpri layers.
+
+Process_delay_meas() this function is invoked from the
+handle_ecpri_ethertype() function when the ecpri message type is
+ECPRI_DELAY_MEASUREMENT. This is the main owd receiver function.
+
+From the Process_delay_meas() and depending on the message received we
+can execute one of the following functions
+
+xran_process_delmeas_request() If we received a request message.
+
+xran_process_delmeas_request_w_fup() If we received a request with follow up message.
+
+xran_process_delmeas_response() If we received a response message.
+
+xran_process_delmeas_rem_request() If we received a remote request message
+
+
+xran_delmeas_rem_request_w_fup() If we received a remote request with follow up message.
+
+All of the receiver functions also can generate the appropriate send message by using
+the DPDK function rte_eth_tx_burst() to minimize the response delay.
+
+Additional utility functions used by the owd implementation for managing of timestamps
+and time measurements are:
+
+xran_ptp_ts_to_ns() that takes a TimeStamp argument from a received owd ecpri packet and
+places it in host order and returns the value in nanoseconds.
+
+xran_timespec_to_ns() that takes an argument in timespec format like the return value from the
+linux function clock_gettime() and returns a value in nanoseconds.
+
+xran_ns_to_timespec() that takes an argument in nanoseconds and returns a value by
+reference in timespec format.
+
+xran_compute_and_report_delay_estimate() This function takes an average of the computed one way
+delay measurements and prints out the average value to the console expressed in nanoseconds.
+Currently we exclude the first 2 measurements from the average.
+
+Utility functions in support of the owd ecpri packet formulation are:
+
+xran_build_owd_meas_ecpri_hdr() Builds the ecpri header with message type ECPRI_DELAY_MEASUREMENT
+and writes the payload size in network order.
+xran_add_at_and_measId_to_header() This function is used to write the action Type and
+MeasurementID to the eCPRI owd header.
+The current implementation of the one way delay measurements only supports a fixed
+message size. The message is defined in the xran_pkt.h in the structure xran_ecpri_delay_meas_pl.
+The one-way delay measurements have been tested with the sample-app for the Front Haul Interface
+Library and have not yet been integrated with the L1 Layer functions.
\ No newline at end of file
Code Review / o-du / phy.git / blobdiff