1 .. Copyright (c) 2019-2022 Intel
3 .. Licensed under the Apache License, Version 2.0 (the "License");
4 .. you may not use this file except in compliance with the License.
5 .. You may obtain a copy of the License at
7 .. http://www.apache.org/licenses/LICENSE-2.0
9 .. Unless required by applicable law or agreed to in writing, software
10 .. distributed under the License is distributed on an "AS IS" BASIS,
11 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 .. See the License for the specific language governing permissions and
13 .. limitations under the License.
26 The O-RAN Library consists of multiple modules where different
27 functionality is encapsulated. The complete list of all \*.c and \*.h
28 files, as well as Makefile for O-RAN (aka FHI Lib)f release is:
46 │ │ ├── app_bbu_main.c
48 │ │ ├── app_bbu_pool.c
50 │ │ ├── app_bbu_pool.h
52 │ │ ├── app_dl_bbu_pool_tasks.c
54 │ │ ├── app_io_fh_xran.c
56 │ │ ├── app_io_fh_xran.h
58 │ │ ├── app_profile_xran.c
60 │ │ ├── app_profile_xran.h
62 │ │ ├── app_ul_bbu_pool_tasks.c
78 │ │ ├── ebbu_pool_cfg.c
80 │ │ ├── ebbu_pool_cfg.h
84 │ │ └── xran_mlog_task_id.h
104 │ │ ├── xran_compression.h
106 │ │ ├── xran_compression.hpp
108 │ │ ├── xran_cp_api.h
110 │ │ ├── xran_ecpri_owd_measurements.h
112 │ │ ├── xran_fh_o_du.h
114 │ │ ├── xran_fh_o_ru.h
116 │ │ ├── xran_lib_mlog_tasks_id.h
118 │ │ ├── xran_mlog_lnx.h
120 │ │ ├── xran_pkt_cp.h
124 │ │ ├── xran_pkt_up.h
126 │ │ ├── xran_sync_api.h
130 │ │ ├── xran_transport.h
132 │ │ └── xran_up_api.h
148 │ ├── xran_bfp_byte_packing_utils.hpp
150 │ ├── xran_bfp_cplane8.cpp
152 │ ├── xran_bfp_cplane8_snc.cpp
154 │ ├── xran_bfp_cplane16.cpp
156 │ ├── xran_bfp_cplane16_snc.cpp
158 │ ├── xran_bfp_cplane32.cpp
160 │ ├── xran_bfp_cplane32_snc.cpp
162 │ ├── xran_bfp_cplane64.cpp
164 │ ├── xran_bfp_cplane64_snc.cpp
166 │ ├── xran_bfp_ref.cpp
168 │ ├── xran_bfp_uplane.cpp
170 │ ├── xran_bfp_uplane_9b16rb.cpp
172 │ ├── xran_bfp_uplane_snc.cpp
174 │ ├── xran_bfp_utils.hpp
184 │ ├── xran_compression.cpp
186 │ ├── xran_compression_snc.cpp
194 │ ├── xran_delay_measurement.c
200 │ ├── xran_frame_struct.c
202 │ ├── xran_frame_struct.h
212 │ ├── xran_mod_compression.cpp
214 │ ├── xran_mod_compression.h
216 │ ├── xran_prach_cfg.h
224 │ ├── xran_sync_api.c
228 │ ├── xran_transport.c
234 │ ├── xran_ul_tables.c
246 │ ├── common_typedef_xran.h
250 │ ├── MIT_License.txt
252 │ ├── xranlib_unit_test_main.cc
254 │ └── xran_lib_wrap.hpp
266 ├── compander_functional.cc
270 ├── init_sys_functional.cc
274 ├── mod_compression_unit_test.cc
276 ├── prach_functional.cc
278 ├── prach_performance.cc
282 └── u_plane_functional.cc
284 ├── u_plane_performance.cc
290 The O-RAN FHI Library functionality is broken down into two main sections:
292 - O-RAN specific packet handling (src)
294 - Ethernet and supporting functionality (ethernet)
296 External functions and structures are available via a set of header
297 files in the API folder.
299 This library depends on DPDK primitives to perform Ethernet networking
300 in user space, including initialization and control of Ethernet ports.
301 Ethernet ports are expected to be SRIOV virtual functions (VF) but also
302 can be physical functions (PF) as well
304 This library is expected to be included in the project via
305 xran_fh_o_du.h, statically compiled and linked with the L1 application
306 as well as DPDK libraries. The O-RAN packet processing-specific
307 functionality is encapsulated into this library and not exposed to the
308 rest of the 5G NR pipeline.
310 This way, O-RAN specific changes are decoupled from the L1 pipeline. As a
311 result, the design and implementation of the 5G L1 pipeline code and
312 O-RAN FHI library can be done in parallel, provided the defined interface is
315 Ethernet consists of two modules:
317 - Ethernet implements O-RAN specific HW Ethernet initialization, close,
320 - ethdi provides Ethernet level software primitives to handle O-RAN
323 The O-RAN layer implements the next set of functionalities:
325 - Common code specific for both C-plane and U-plane as well as TX and
328 - Implementation of C-plane API available within the library and
331 - The primary function where general library initialization and
332 configuration performed
334 - Module to provide the status of PTP synchronization
336 - Timing module where system time is polled
338 - eCPRI specific transport layer functions
340 - APIs to handle U-plane packets
342 - A set of utility modules for debugging (printf) and data tables are
345 .. image:: images/Illustration-of-xRAN-Sublayers.jpg
347 :alt: Figure 25. Illustration of O-RAN Sublayers
349 Figure 25. Illustration of O-RAN Sublayers
351 A detailed description of functions and input/output arguments, as well
352 as key data structures, can be found in the Doxygen file for the FlexRAN
353 5G NR release, Refer to Table 2. In this document, supplemental
354 information is provided for the overall design and implementation
355 assumptions.(Available only outside of the Community Version)
357 Initialization and Close
358 ------------------------
360 An example of the initialization sequence can be found in the sample
361 application code. It consists of the following steps:
363 1.Setup structure struct xran_fh_init according to configuration.
365 2.Call xran_init() to instantiate the O-RAN lib memory model and
366 threads. The function returns a pointer to O-RAN handle which is used
367 for consecutive configuration functions.
369 3.Initialize memory buffers used for L1 and O-RAN exchange of
372 4.Assign callback functions for (one) TTI event and for the reception
373 of half of the slot of symbols (7 symbols) and Full slot of symbols
376 5.Call xran_open() to initialize PRACH configuration, initialize DPDK,
377 and launch xRAN timing thread,
379 6.Call xran_start() to start processing O-RAN packets for DL and UL.
381 After this is complete 5G L1 runs with O-RAN Front haul interface. During
382 run time for every TTI event, the corresponding call back is called. For
383 packet reception on UL direction, the corresponding call back is called.
384 OTA time information such as frame id, subframe id, and slot id can be
385 obtained as result synchronization of the L1 pipeline to GPS time is
388 To stop and close the interface, perform this sequence of steps:
390 1.Call xran_stop() to stop the processing of DL and UL
392 2.Call xran_close() to remove usage of xRAN resources
394 3.Call xran_mm_destroy() to destroy memory management subsystem
396 After this session is complete, a restart of the full L1 application is
397 required. The current version of the library does not support multiple
398 sessions without a restart of the full L1 application.
403 The O-RAN library configuration is provided in the set of structures, such as struct xran_fh_init and struct xran_fh_config.
404 The sample application gives an example of a test configuration used for LTE and 5GNR mmWave and Sub 6. Sample application
405 folder /app/usecase/ contains set of examples for different Radio Access technology (LTE|5G NR), different category (A|B)
406 and list of numerologies (0,1,3) and list of bandwidths (5,10,20,100Mhz).
408 Note: Some configuration options are not used in the f release and are reserved
411 The following options are available:
413 **Structure** struct xran_fh_init\ **:**
415 - Number of CC and corresponding settings for each
417 - Core allocation for O-RAN
419 - Ethernet port allocation
421 - O-DU and RU Ethernet Mac address
423 - Timing constraints of O-DU and 0-RU
427 **Structure** struct xran_fh_config\ **:**
431 - TTI Callback function and parameters
433 - PRACH 5G NR specific settings
435 - TDD frame configuration
437 - BBU specific configuration
439 - RU specific configuration
441 **From an implementation perspective:**
443 The xran_init() performs init of the O-RAN FHI library and interface
444 according to struct xran_fh_init information as per the start of
445 application configuration:
447 - Init DPDK with corresponding networking ports and core assignment
451 - Init DPDK timers and DPDK rings for internal packet processing
453 - Instantiates ORAH FH thread doing
455 - Timing processing (xran_timing_source_thread())
457 - ETH PMD (process_dpdk_io())
459 - IO XRAN-PHY exchange (ring_processing_func())
461 **xran_open()** performs additional configuration as per run scenario:
463 - PRACH configuration
465 - C-plane initialization
467 The Function **xran_close()** performs free of resources and allows potential
468 restart of front haul interface with a different scenario.
473 The Functions **xran_start()/xran_stop()** enable/disable packet processing for
474 both DL and UL. This triggers execution of callbacks into the L1
480 Exchange of IQ samples, as well as C-plane specific information, is
481 performed using a set of buffers allocated by xRAN library from DPDK
482 memory and shared with the l1 application. Buffers are allocated as a
483 standard mbuf structure, and DPDK pools are used to manage the
484 allocation and free resources. Shared buffers are allocated at the init
485 stage and are expected to be reused within 80 TTIs (10 ms).
487 The O-RAN protocol requires U-plane IQ data to be transferred in network
488 byte order, and the L1 application handles IQ sample data in CPU byte
489 order, requiring a swap. The PHY BBU pooling tasks perform copy and byte
490 order swap during packet processing.
492 C-plane Information Settings
493 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
495 The interface between the O-RAN library and PHY is defined via struct
496 xran_prb_map and similar to the data plane. The same mbuf memory is used
497 to allocate memory map of PRBs for each TTI.::
499 /*\* Beamforming waights for single stream for each PRBs given number of
501 struct xran_cp_bf_weight{
503 int16_t nAntElmTRx; /**< num TRX for this allocation \*/
505 int16_t ext_section_sz; /**< extType section size \*/
507 int8_t\* p_ext_start; /**< pointer to start of buffer for full C-plane
510 int8_t\* p_ext_section; /**< pointer to form extType \*/
514 uint8_t bfwCompMeth; /\* Compression Method for BFW \*/
516 uint8_t bfwIqWidth; /\* Bitwidth of BFW \*/
518 uint8_t numSetBFWs; /\* Total number of beam forming weights set (L) \*/
520 uint8_t numBundPrb; /\* The number of bundled PRBs, 0 means to use ext1
527 int16_t maxExtBufSize; /\* Maximum space of external buffer \*/
529 struct xran_ext11_bfw_info bfw[XRAN_MAX_SET_BFWS]
533 /*\* PRB element structure \*/
535 struct xran_prb_elm {
537 int16_t nRBStart; /**< start RB of RB allocation \*/
539 int16_t nRBSize; /**< number of RBs used \*/
541 int16_t nStartSymb; /**< start symbol ID \*/
543 int16_t numSymb; /**< number of symbols \*/
545 int16_t nBeamIndex; /**< beam index for given PRB \*/
547 int16_t bf_weight_update; /*\* need to update beam weights or not \*/
549 int16_t compMethod; /**< compression index for given PRB \*/
551 int16_t iqWidth; /**< compression bit width for given PRB \*/
553 uint16_t ScaleFactor; /**< scale factor for modulation compression \*/
555 int16_t reMask; /**< 12-bit RE Mask for modulation compression \*/
557 int16_t BeamFormingType; /**< index based, weights based or attribute
560 int16_t nSecDesc[XRAN_NUM_OF_SYMBOL_PER_SLOT]; /**< number of section
561 descriptors per symbol \*/
563 struct xran_section_desc \*
564 p_sec_desc[XRAN_NUM_OF_SYMBOL_PER_SLOT][XRAN_MAX_FRAGMENT]; /**< section
565 desctiptors to U-plane data given RBs \*/
567 struct xran_cp_bf_weight bf_weight; /**< beam forming information
568 relevant for given RBs \*/
572 struct xran_cp_bf_attribute bf_attribute;
574 struct xran_cp_bf_precoding bf_precoding;
580 /*\* PRB map structure \*/
582 struct xran_prb_map {
584 uint8_t dir; /**< DL or UL direction \*/
586 uint8_t xran_port; /**< O-RAN id of given RU [0-(XRAN_PORTS_NUM-1)] \*/
588 uint16_t band_id; /**< O-RAN band id \*/
590 uint16_t cc_id; /**< component carrier id [0 - (XRAN_MAX_SECTOR_NR-1)]
593 uint16_t ru_port_id; /**< RU device antenna port id [0 -
594 (XRAN_MAX_ANTENNA_NR-1) \*/
596 uint16_t tti_id; /**< O-RAN slot id [0 - (max tti-1)] \*/
598 uint8_t start_sym_id; /**< start symbol Id [0-13] \*/
600 uint32_t nPrbElm; /**< total number of PRB elements for given map [0-
601 (XRAN_MAX_SECTIONS_PER_SLOT-1)] \*/
603 struct xran_prb_elm prbMap[XRAN_MAX_SECTIONS_PER_SLOT];
608 C-plane sections are expected to be provided by the L1
609 pipeline. If 100% of the RBs are used they are always allocated as a single element RB map, that
610 is expected to be allocated across all symbols. Dynamic RB allocation is
611 performed based on C-plane configuration.
613 The O-RAN library will require that the content of the PRB map should be
614 sorted in increasing order of PRB first and then symbols.
619 Memory used for the exchange of IQ data as well as control information,
620 is controlled by the O-RAN library. L1 application at the init stage
623 - init memory management subsystem
625 - init buffer management subsystem (via DPDK pools)
627 - allocate buffers (mbuf) for each CC, antenna, symbol, and direction \
628 (DL, UL, PRACH) for XRAN_N_FE_BUF_LEN TTIs.
630 - buffers are reused for every XRAN_N_FE_BUF_LEN TTIs
632 After the session is completed, the application can free buffers and
633 destroy the memory management subsystem.
635 From an implementation perspective, the O-RAN library uses a standard
636 mbuf primitive and allocates a pool of buffers for each sector. This
637 function is performed using rte_pktmbuf_pool_create(),
638 rte_pktmbuf_alloc(), and rte_pktmbuf_append() to allocate one buffer per
639 symbol for the mmWave case. More information on mbuf and DPDK pools can
640 be found in the DPDK documentation.
642 In the current implementation, mbuf, the number of buffers shared with
643 the L1 application is the same number of buffers used to send to and
644 receive from the Ethernet port. Memory copy operations are not required
645 if the packet size is smaller than or equal to MTU. Future versions of
646 the O-RAN library are required to remove the memory copy requirement for
647 packets where the size larger than MTU.
649 External Interface Memory
650 ~~~~~~~~~~~~~~~~~~~~~~~~~
652 The O-RAN library header file defines a set of structures to simplify
653 access to memory buffers used for IQ data.:::
655 struct xran_flat_buffer {
657 uint32_t nElementLenInBytes;
659 uint32_t nNumberOfElements;
661 uint32_t nOffsetInBytes;
671 struct xran_buffer_list {
673 uint32_t nNumBuffers;
675 struct xran_flat_buffer \*pBuffers;
679 void \*pPrivateMetaData;
683 struct xran_io_buf_ctrl {
685 /\* -1-this subframe is not used in current frame format
687 0-this subframe can be transmitted, i.e., data is ready
689 1-this subframe is waiting transmission, i.e., data is not ready
691 10 - DL transmission missing deadline. When FE needs this subframe data
692 but bValid is still 1,
698 int32_t bValid ; // when UL rx, it is subframe index.
702 int32_t nSegGenerated; // how many date segment are generated by DL LTE
703 processing or received from FE
705 // -1 means that DL packet to be transmitted is not ready in BS
707 int32_t nSegTransferred; // number of data segments has been transmitted
710 struct rte_mbuf \*pData[N_MAX_BUFFER_SEGMENT]; // point to DPDK
711 allocated memory pool
713 struct xran_buffer_list sBufferList;
717 There is no explicit requirement for user to organize a set of buffers
718 in this particular way. From a compatibility |br|
719 perspective it is useful to
720 follow the existing design of the 5G NR l1app used for Front Haul FPGA
721 and define structures shared between l1 and O-RAN lib as shown: ::
723 struct bbu_xran_io_if {
725 void\* nInstanceHandle[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR]; /**<
726 instance per O-RAN port per CC \*/
729 nBufPoolIndex[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR][MAX_SW_XRAN_INTERFACE_NUM];
730 /**< unique buffer pool \*/
732 uint16_t nInstanceNum[XRAN_PORTS_NUM]; /**< instance is equivalent to CC
735 uint16_t DynamicSectionEna;
737 uint32_t nPhaseCompFlag;
741 int32_t num_cc_per_port[XRAN_PORTS_NUM];
743 int32_t map_cell_id2port[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
745 struct xran_io_shared_ctrl ioCtrl[XRAN_PORTS_NUM]; /**< for each O-RU
748 struct xran_cb_tag RxCbTag[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
750 struct xran_cb_tag PrachCbTag[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
752 struct xran_cb_tag SrsCbTag[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
756 struct xran_io_shared_ctrl {
760 struct xran_io_buf_ctrl
761 sFrontHaulTxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
763 struct xran_io_buf_ctrl
764 sFrontHaulTxPrbMapBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
766 struct xran_io_buf_ctrl
767 sFrontHaulRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
769 struct xran_io_buf_ctrl
770 sFrontHaulRxPrbMapBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
772 struct xran_io_buf_ctrl
773 sFHPrachRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
777 struct xran_io_buf_ctrl
778 sFHSrsRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR];
780 struct xran_io_buf_ctrl
781 sFHSrsRxPrbMapBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR];
783 /\* buffers lists \*/
785 struct xran_flat_buffer
786 sFrontHaulTxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
788 struct xran_flat_buffer
789 sFrontHaulTxPrbMapBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
791 struct xran_flat_buffer
792 sFrontHaulRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
794 struct xran_flat_buffer
795 sFrontHaulRxPrbMapBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
797 struct xran_flat_buffer
798 sFHPrachRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
800 /\* Cat B SRS buffers \*/
802 struct xran_flat_buffer
803 sFHSrsRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR][XRAN_MAX_NUM_OF_SRS_SYMBOL_PER_SLOT];
805 struct xran_flat_buffer
806 sFHSrsRxPrbMapBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR];
810 The Doxygen file and xran_fh_o_du.h provides more details on the
811 definition and usage of these structures. Refer to *Table 2*, for
812 FlexRAN 5G NR Reference Solution RefPHY (Doxygen).(Not available in
813 the community version).
815 O-RAN Specific Functionality
816 ----------------------------
818 Front haul interface implementation in the general case is abstracted
819 away using the interface defined in xran_fh_o_du.h
821 The L1 application is not required to access O-RAN protocol primitives
822 (eCPRI header, application header, and others) directly. It is
823 recommended to use the interface to remove dependencies between
824 different software modules such as the l1 pipeline and O-RAN library.
829 The U-plane and C-plane APIs can be used directly from the application
830 if such an option is required. The set of header files can be exported
831 and called directly.::
833 xran_fh_o_du.h – O-RAN main header file for O-DU scenario
835 xran_cp_api.h – Control plane functions
837 xran_pkt_cp.h – O-RAN control plane packet definition
839 xran_pkt.h – O-RAN packet definition
841 xran_pkt_up.h – O-RAN User plane packet definition
843 xran_sync_api.h – api functions to check PTP status
845 xran_timer.h – API for timing
847 xran_transport.h – eCPRI transport layer definition and api
849 xran_up_api.h – user plane functions and definitions
851 xran_compression.h – interface to compression/decompression functions
853 Source code comments can provide more details on functions and
854 structures available.
861 Implementation of the C-plane set of functions is defined in
862 xran_cp_api.c and is used to prepare the content of C-plane packets
863 according to the given configuration. Users can enable/disable
864 generation of C-plane messages using enableCP field in struct
865 xran_fh_init structure during the initialization of O-RAN front haul.
866 The time of generation of C-plane message for DL and UL is done
867 “Slot-based,” and timing can be controlled using O-DU settings according
870 The C-plane module contains:
872 - initialization of C-plane database to keep track of allocation of
875 - Code to prepare C-plane packet for TX (O-DU)
877 - append radio application header
878 - append control section header
879 - append control section
881 - Parser of C-plane packet for RX (O-RU emulation)
883 - parses and checks Section 1 and Section 3 packet content
885 Sending and receiving packets is performed using O-RAN ethdi sublayer
888 More information on function arguments and parameters can be found in
889 the comments for the corresponding source code.
891 Creating a C-Plane Packet
892 ^^^^^^^^^^^^^^^^^^^^^^^^^
894 1. API and Data Structures
896 A C-Plane message can be composed using the following API:::
898 int xran_prepare_ctrl_pkt(struct rte_mbuf \*mbuf,
900 struct xran_cp_gen_params \*params,
902 uint8_t CC_ID, uint8_t Ant_ID, uint8_t seq_id);
904 mbuf is the pointer of a DPDK packet buffer, which is allocated from the
907 params are the pointer of the structure which has the parameters to
910 CC_ID is the parameter to specify component carrier index, Ant_ID is the
911 parameters to specify the antenna port index (RU port index).
913 seq_id is the sequence index for the message.
915 params, the parameters to create a C-Plane message are defined as the
916 structure of xran_cp_gen_params with an |br|
917 example given below:::
919 struct xran_cp_gen_params {
925 uint16_t numSections;
927 struct xran_cp_header_params hdr;
929 struct xran_section_gen_info \*sections;
933 dir is the direction of the C-Plane message to be generated. Available
934 parameters are defined as XRAN_DIR_UL and XRAN_DIR_DL.
936 sectionType is the section type for C-Plane message to generate, as
937 O-RAN specification defines all sections in a C-Plane message shall have
938 the same section type. If different section types are required, they
939 shall be sent with separate C-Plane messages. Available types of
940 sections are defined as XRAN_CP_SECTIONTYPE_x. Refer to *Table* 2,
941 *O-RAN Specification*, Table 5-2 Section Types.
943 numSections is the total number of sections to generate, i.e., the
944 number of the array in sections (struct xran_section_gen_info).
946 hdr is the structure to hold the information to generate the radio
947 application and section header in the C-Plane message. It is defined as
948 the structure of xran_cp_header_params. Not all parameters in this
949 structure are used for the generation, and the required parameters are
950 slightly different by the type of section, as described in Table 10 and
951 References in the remarks column are corresponding Chapter numbers in
952 the O-RAN *FrontHaul Working Group Control, User, and Synchronization
953 Plane Specification* in *Table 2*.
955 Table 10. struct xran_cp_header_params – Common Radio Application Header
957 +------------+---------------------------------------------+---------+
958 | | Description | Remarks |
959 +============+=============================================+=========+
960 | filterIdx | Filter Index. Available values are defined | 5.4.4.3 |
961 | | as XRAN_FILTERINDEX_xxxxx. | |
962 +------------+---------------------------------------------+---------+
963 | frameId | Frame Index. It is modulo 256 of frame | 5.4.4.4 |
965 +------------+---------------------------------------------+---------+
966 | subframeId | Sub-frame Index. | 5.4.4.5 |
967 +------------+---------------------------------------------+---------+
968 | slotId | Slot Index. The maximum number is 15, as | 5.4.4.6 |
969 | | defined in the specification. | |
970 +------------+---------------------------------------------+---------+
971 | startSymId | Start Symbol Index. | 5.4.4.7 |
972 +------------+---------------------------------------------+---------+
974 Table 11. struct xran_cp_header_params – Section Specific Parameters
976 +----------+-----------+------------------------------------+----------+
977 | | Des\ | Section Type applicable | Remarks |
979 +==========+===========+==========+=========+===+===+===+===+==========+
980 | | | 0 | 1 | 3 | 5 | 6 | 7 | |
981 +----------+-----------+----------+---------+---+---+---+---+----------+
982 | fftSize || FFT size | X | | X | | | | 5.4.4.13 |
983 | || in frame | | | | | | | |
984 | || st\ | | | | | | | |
985 | | ructure. | | | | | | | |
986 | || A\ | | | | | | | |
987 | | vailable | | | | | | | |
988 | || values | | | | | | | |
989 | || are | | | | | | | |
990 | || defined | | | | | | | |
991 | || as | | | | | | | |
992 | || X\ | | | | | | | |
993 | | RAN_FFT\ | | | | | | | |
994 | || SIZE_xxxx| | | | | | | |
995 +----------+-----------+----------+---------+---+---+---+---+----------+
996 | Scs || Su\ | X | | X | | | | 5.4.4.13 |
997 | | bcarrier | | | | | | | |
998 | || Spacing | | | | | | | |
999 | || in the | | | | | | | |
1000 | || frame | | | | | | | |
1001 | || st\ | | | | | | | |
1002 | | ructure. | | | | | | | |
1003 | || A\ | | | | | | | |
1004 | | vailable | | | | | | | |
1005 | || values | | | | | | | |
1006 | || are | | | | | | | |
1007 | || defined | | | | | | | |
1008 | || as | | | | | | | |
1009 | || XRAN_SCS\| | | | | | | |
1010 | | _xxxx | | | | | | | |
1011 +----------+-----------+----------+---------+---+---+---+---+----------+
1012 | iqWidth || I/Q bit | | X | X | X | | | 5.4.4.10 |
1013 | || width in | | | | | | | |
1014 | || user | | | | | | | 6.3.3.13 |
1015 | || data | | | | | | | |
1016 | || com\ | | | | | | | |
1017 | | pression | | | | | | | |
1018 | || header. | | | | | | | |
1019 | || Should | | | | | | | |
1020 | || be set | | | | | | | |
1021 | || by zero | | | | | | | |
1022 | || for | | | | | | | |
1023 | || 16bits | | | | | | | |
1024 +----------+-----------+----------+---------+---+---+---+---+----------+
1025 | compMeth || Com\ | | X | X | X | | | 5.4.4.10 |
1026 | | pression | | | | | | | |
1027 | || Method | | | | | | | 6.3.3.13 |
1028 | || in user | | | | | | | |
1029 | || data | | | | | | | |
1030 | || com\ | | | | | | | |
1031 | | pression | | | | | | | |
1032 | || header. | | | | | | | |
1033 | || A\ | | | | | | | |
1034 | | vailable | | | | | | | |
1035 | || values | | | | | | | |
1036 | || are | | | | | | | |
1037 | || defined | | | | | | | |
1038 | || as | | | | | | | |
1039 | || X-RAN\ | | | | | | | |
1040 | | _COMP | | | | | | | |
1041 | || METHOD_x\| | | | | | | |
1042 | || xxx | | | | | | | |
1043 +----------+-----------+----------+---------+---+---+---+---+----------+
1044 | numUEs || Number | | | | | X | | 5.4.4.11 |
1045 | || of UEs. | | | | | | | |
1046 | || Applies | | | | | | | |
1047 | || to | | | | | | | |
1048 | || section | | | | | | | |
1049 | || type 6 | | | | | | | |
1050 | || and not | | | | | | | |
1051 | || s\ | | | | | | | |
1052 | | upported | | | | | | | |
1053 | || in this | | | | | | | |
1054 | || release. | | | | | | | |
1055 +----------+-----------+----------+---------+---+---+---+---+----------+
1056 | ti\ || Time | X | | X | | | | 5.4.4.12 |
1057 | meOffset || Offset. | | | | | | | |
1058 | || Time | | | | | | | |
1059 | || offset | | | | | | | |
1060 | || from the | | | | | | | |
1061 | || start of | | | | | | | |
1062 | || the slot | | | | | | | |
1063 | || to start | | | | | | | |
1064 | || of | | | | | | | |
1065 | || Cyclic | | | | | | | |
1066 | || Prefix. | | | | | | | |
1067 +----------+-----------+----------+---------+---+---+---+---+----------+
1068 | cpLength || Cyclic | X | | X | | | | 5.4.4.14 |
1069 | || Prefix | | | | | | | |
1070 | || Length. | | | | | | | |
1071 +----------+-----------+----------+---------+---+---+---+---+----------+
1075 1.Only sections types 1 and 3 are supported in the current release.
1077 2.References in the remarks column are corresponding Chapter numbers in
1078 the *O-RAN Fronthaul Working Group Control, User, and
1079 Synchronization Plane Specification* in *Table 2*.
1081 Sections are the pointer to the array of structure which has the
1082 parameters for section(s) and it is defined as below:::
1084 struct xran_section_gen_info {
1086 struct xran_section_info info;
1088 uint32_t exDataSize;
1098 } exData[XRAN_MAX_NUM_EXTENSIONS];
1102 info is the structure to hold the information to generate section and it
1103 is defined as the structure of xran_section_info. Like
1104 xran_cp_header_params, all parameters are not required to generate
1105 section and *Table 12* describes which parameters are required for each
1108 Table 12. Parameters for Sections
1110 +-------+-------+---------------------------------------+-------+
1111 | | Descr\| Section Type applicable | Remar\|
1113 +=======+=======+=======+=======+=======+=======+=======+=======+
1114 | | | 0 | 1 | 3 | 5 | 6 | |
1115 +-------+-------+-------+-------+-------+-------+-------+-------+
1116 | Id || Se\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
1117 | | ction | | | | | | 4.5.1 |
1118 | || I\ | | | | | | |
1119 | | denti\| | | | | | |
1120 | | fier. | | | | | | |
1121 +-------+-------+-------+-------+-------+-------+-------+-------+
1122 | Rb || Res\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
1123 | || ource| | | | | | 4.5.2 |
1124 | || Block| | | | | | |
1125 | || Indi\| | | | | | |
1126 | | cator.| | | | | | |
1127 | || Avai\| | | | | | |
1128 | | lable | | | | | | |
1129 | || v\ | | | | | | |
1130 | | alues | | | | | | |
1131 | || are | | | | | | |
1132 | || de\ | | | | | | |
1133 | | fined | | | | | | |
1134 | || as | | | | | | |
1135 | || X-RA\| | | | | | |
1136 | | N\ | | | | | | |
1137 | || _RBI\| | | | | | |
1138 | | ND\ | | | | | | |
1139 | || _xxxx| | | | | | |
1140 +-------+-------+-------+-------+-------+-------+-------+-------+
1141 | s\ || S\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
1142 | ymInc | ymbol | | | | | | 4.5.3 |
1143 | || n\ | | | | | | |
1144 | | umber | | | | | | |
1145 | || Incr\| | | | | | |
1146 | | ement | | | | | | |
1147 | || com\ | | | | | | |
1148 | | mand. | | | | | | |
1149 | || Avai\| | | | | | |
1150 | | lable | | | | | | |
1151 | || v\ | | | | | | |
1152 | | alues | | | | | | |
1153 | || are | | | | | | |
1154 | || de\ | | | | | | |
1155 | | fined | | | | | | |
1156 | || as | | | | | | |
1157 | || XRA\ | | | | | | |
1158 | | N_SYM\| | | | | | |
1159 | || BOL\ | | | | | | |
1160 | || NUMB\| | | | | | |
1161 | | ER | | | | | | |
1162 | || _xxxx| | | | | | |
1163 +-------+-------+-------+-------+-------+-------+-------+-------+
1164 || star\|| Sta\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
1165 | tPrbc | rting\| | | | | | 4.5.4 |
1166 | || PRB | | | | | | |
1167 | | of | | | | | | |
1168 | | data | | | | | | |
1169 | || se\ | | | | | | |
1170 | | ction | | | | | | |
1171 | || de\ | | | | | | |
1172 | | scrip\| | | | | | |
1173 | | tion. | | | | | | |
1174 +-------+-------+-------+-------+-------+-------+-------+-------+
1175 || num\ || The | **X** | **X** | **X** | **X** | **X** | 5.\ |
1176 | Prbc | n\ | | | | | | 4.5.6 |
1177 | | umber | | | | | | |
1178 | || of | | | | | | |
1179 | || cont\| | | | | | |
1180 | | iguous| | | | | | |
1181 | || PRBs | | | | | | |
1182 | || per | | | | | | |
1183 | || data | | | | | | |
1184 | || se\ | | | | | | |
1185 | | ction | | | | | | |
1186 | || de\ | | | | | | |
1187 | | scrip\| | | | | | |
1188 | | tion. | | | | | | |
1189 | || When | | | | | | |
1190 | || nu\ | | | | | | |
1191 | | mPrbc | | | | | | |
1192 | || is | | | | | | |
1193 | || gr\ | | | | | | |
1194 | | eater | | | | | | |
1195 | || than | | | | | | |
1196 | | 255, | | | | | | |
1197 | || it | | | | | | |
1198 | | will | | | | | | |
1199 | | be | | | | | | |
1200 | || conv\| | | | | | |
1201 | | erted | | | | | | |
1202 | || to | | | | | | |
1203 | | zero | | | | | | |
1204 | || by | | | | | | |
1205 | | the | | | | | | |
1206 | | macro | | | | | | |
1207 | || (XRA\| | | | | | |
1208 | | N_CO\| | | | | | |
1209 | | NVERT| | | | | | |
1210 | || _NUM\| | | | | | |
1211 | || PRBC)| | | | | | |
1212 +-------+-------+-------+-------+-------+-------+-------+-------+
1213 | r\ | Res\ | **X** | **X** | **X** | **X** | | 5.\ |
1214 | eMask | ource\| | | | | | 4.5.5 |
1215 | | El\ | | | | | | |
1216 | | ement\| | | | | | |
1217 | | Mask. | | | | | | |
1218 +-------+-------+-------+-------+-------+-------+-------+-------+
1219 | numS\ | N\ | **X** | **X** | **X** | **X** | | 5.\ |
1220 | ymbol | umber | | | | | | 4.5.7 |
1221 | | of | | | | | | |
1222 | | Sym\ | | | | | | |
1223 | | bols. | | | | | | |
1224 +-------+-------+-------+-------+-------+-------+-------+-------+
1225 | b\ | Beam\ | | **X** | **X** | | | 5.\ |
1226 | eamId | I\ | | | | | | 4.5.9 |
1227 | | denti\| | | | | | |
1228 | | fier. | | | | | | |
1229 +-------+-------+-------+-------+-------+-------+-------+-------+
1230 | freqO\| Freq\ | | | **X** | | | 5.4\ |
1231 | ffset | uency\| | | | | | .5.11 |
1232 | | Of\ | | | | | | |
1233 | | fset. | | | | | | |
1234 +-------+-------+-------+-------+-------+-------+-------+-------+
1235 | ueId || UE\ | | | | **X** | **X** | 5.4\ |
1236 | | i\ | | | | | | .5.10 |
1237 | | denti\| | | | | | |
1238 | | fier. | | | | | | |
1239 | || Not | | | | | | |
1240 | || supp\| | | | | | |
1241 | | orted | | | | | | |
1242 | || in | | | | | | |
1243 | | this | | | | | | |
1244 | || rel\ | | | | | | |
1245 | | ease. | | | | | | |
1246 +-------+-------+-------+-------+-------+-------+-------+-------+
1247 | regF\ || Regu\| | | | | **X** | 5.4\ |
1248 | actor | lariz\| | | | | | .5.12 |
1249 | | ation | | | | | | |
1250 | || Fa\ | | | | | | |
1251 | | ctor. | | | | | | |
1252 | || Not | | | | | | |
1253 | || supp\| | | | | | |
1254 | | orted | | | | | | |
1255 | || in | | | | | | |
1256 | | this | | | | | | |
1257 | | re\ | | | | | | |
1258 | | lease | | | | | | |
1259 +-------+-------+-------+-------+-------+-------+-------+-------+
1260 | Ef || Exte\| | **X** | **X** | **X** | **X** | 5.\ |
1261 | | nsion | | | | | | 4.5.8 |
1262 | | Flag. | | | | | | |
1263 | || Not | | | | | | |
1264 | || supp\| | | | | | |
1265 | | orted | | | | | | |
1266 | || in | | | | | | |
1267 | | this | | | | | | |
1268 | | rel\ | | | | | | |
1269 | | ease. | | | | | | |
1270 +-------+-------+-------+-------+-------+-------+-------+-------+
1274 1.Only sections types 1 and 3 are supported in the current release.
1276 2.References in the remarks column are corresponding Chapter numbers in
1277 the *O-RAN FrontHaul Working Group Control, User, and
1278 Synchronization Plane Specification* in *Table 2*.
1280 Note: xran_section_info has more parameters – type, startSymId, iqWidth,
1281 compMeth. These are the same parameters as those of radio application
1282 or section header but need to be copied into this structure again for
1283 the section data base.
1285 exDataSize and exData are used to add section extensions for the
1288 exDataSize is the number of elements in the exData array. The maximum
1289 number of elements is defined as XRAN_MAX_NUM_EXTENSIONS and it is
1290 defined by four in this release with the assumption that four different
1291 types of section extensions can be added to a section (section extension
1292 type 3 is excluded since it is not supported). exData.type is the type
1293 of section extension and exData.len is the length of structure of
1294 section extension parameter in exData.data. exData.data is the pointer
1295 to the structure of section extensions and different structures are used
1296 by the type of section extensions like below.::
1298 struct xran_sectionext1_info {
1300 uint16_t rbNumber; /* number RBs to ext1 chain \*/
1302 uint16_t bfwNumber; /* number of bf weights in this section \*/
1306 uint8_t bfwCompMeth;
1308 int16_t \*p_bfwIQ; /* pointer to formed section extention \*/
1310 int16_t bfwIQ_sz; /* size of buffer with section extention information
1317 uint8_t blockScaler;
1319 uint8_t compBitWidthShift;
1321 uint8_t activeBeamspaceCoeffMask[XRAN_MAX_BFW_N]; /\* ceil(N/8)*8,
1322 should be multiple of 8 \*/
1328 For section extension type 1, the structure of xran_sectionext1_info is
1331 Note: The O-RAN library will use beamforming weight (bfwIQ) as-is, i.e.,
1332 O-RAN library will not perform the compression, so the user should provide
1333 proper data to bfwIQ.::
1335 struct xran_sectionext2_info {
1337 uint8_t bfAzPtWidth;
1341 uint8_t bfZePtWidth;
1345 uint8_t bfAz3ddWidth;
1349 uint8_t bfZe3ddWidth;
1359 For section extension type 2, the structure of xran_sectionext2_info is
1360 used. Each parameter will be packed as specified bit width.::
1362 struct xran_sectionext3_info {
1364 uint8_t codebookIdx;
1378 uint16_t numAntPort;
1388 For section extension type 3, the structure of xran_sectionext3_info is
1391 struct xran_sectionext4_info {
1397 uint16_t modCompScaler;
1401 For section extension type 4, the structure of xran_sectionext4_info is
1404 struct xran_sectionext5_info {
1412 uint16_t mcScaleReMask;
1414 uint16_t mcScaleOffset;
1416 } mc[XRAN_MAX_MODCOMP_ADDPARMS];
1420 For section extension type 5, the structure of xran_sectionext5_info is
1423 Note: Current implementation supports maximum two sets of additional parameters.::
1425 struct xran_sectionext6_info {
1431 uint16_t symbolMask;
1437 For section extension type 6, the structure of xran_sectionext6_info is
1440 struct xran_sectionext10_info {
1444 uint8_t beamGrpType;
1446 uint16_t beamID[XRAN_MAX_NUMPORTC_EXT10];
1450 For section extension type 10, the structure of xran_sectionext10_info
1453 struct xran_sectionext11_info {
1457 uint8_t disableBFWs;
1461 uint8_t numSetBFWs; /\* Total number of beam forming weights set (L) \*/
1463 uint8_t bfwCompMeth;
1469 int maxExtBufSize; /\* Maximum space of external buffer \*/
1471 uint8_t \*pExtBuf; /\* pointer to start of external buffer \*/
1473 void \*pExtBufShinfo; /\* Pointer to rte_mbuf_ext_shared_info \*/
1477 For section extension type 11, the structure of xran_sectionext11_info
1480 To minimize memory copy for beamforming weights, when section extension
1481 11 is required to send beamforming weights(BFWs), external flat buffer
1482 is being used in current release. If extension 11 is used, it will be
1483 used instead of mbufs that pre-allocated external buffers which BFWs
1484 have been prepared already. BFW can be prepared by
1485 xran_cp_prepare_ext11_bfws() and the example usage can be found from
1486 app_init_xran_iq_content() from sample-app.c.
1488 Detail Procedures in API
1489 ''''''''''''''''''''''''
1491 The xran_prepare_ctrl_pkt() has several procedures to compose a C-Plane
1494 1. Append transport header:
1496 - Reserve eCPRI header space in the packet buffer
1498 - eCPRI version is fixed by XRAN_ECPRI_VER (0x0001)
1500 - Concatenation and transport layer fragmentation is not supported.
1502 ecpri_concat=0, ecpri_seq_id.sub_seq_id=0 and ecpri_seq_id.e_bit=1
1504 - The caller needs to provide a component carrier index, antenna index,
1505 and message identifier through function arguments.
1507 CC_ID, Ant_ID and seq_id
1509 - ecpriRtcid (ecpri_xtc_id) is composed with CC_ID and Ant_ID by
1512 - DU port ID and band sector ID are fixed by zero in this release.
1514 - The output of xran_compose_cid is stored in network byte order.
1516 - The length of the payload is initialized by zero.
1518 2. Append radio application header:
1520 - The xran_append_radioapp_header() checks the type of section through params->sectionType and determines proper function to append remaining header components.
1522 - Only section type 1 and 3 are supported, returns
1523 XRAN_STATUS_INVALID_PARAM for other types.
1525 - Each section uses a different function to compose the remaining
1526 header and size to calculate the total length in the transport
1529 - For section type 1, xran_prepare_section1_hdr() and sizeof(struct xran_cp_radioapp_section1_header)
1531 - For section type 3, xran_prepare_section3_hdr() and sizeof(struct xran_cp_radioapp_section3_header)
1533 - Reserves the space of common radio application header and composes header by xran_prepare_radioapp_common_header().
1535 The header is stored in network byte order.
1537 - Appends remaining header components by the selected function above
1539 The header is stored in network byte order
1541 3. Append section header and section:
1543 - The xran_append_control_section() determines proper size and function to append section header and contents.
1545 - For section type 1, xran_prepare_section1() and sizeof(struct
1546 xran_cp_radioapp_section1)
1548 - For section type 3, xran_prepare_section3() and sizeof(struct
1549 xran_cp_radioapp_section3)
1551 - Appends section header and section(s) by selected function above.
1553 - If multiple sections are configured, then those will be added.
1555 - Since fragmentation is not considered in this implementation, the
1556 total length of a single C-Plane message shall not exceed MTU
1559 - The header and section(s) are stored in network byte order.
1561 - Appends section extensions if it is set (ef=1)
1563 - The xran_append_section_extensions() adds all configured extensions by its type.
1565 - The xran_prepare_sectionext_x() (x = 1,2,4,5) will be called by the type from and these functions will create extension field.
1567 Example Usage of API
1568 ''''''''''''''''''''
1570 There are two reference usages of API to generate C-Plane messages:
1572 - xran_cp_create_and_send_section() in xran_main.c
1574 - generate_cpmsg_prach() in xran_common.c
1576 The xran_cp_create_and_send_section() is to generate the C-Plane message
1577 with section type 1 for DL or UL symbol data scheduling.
1579 This function has hardcoded values for some parameters such as:
1581 - The filter index is fixed to XRAN_FILTERINDEX_STANDARD.
1583 - RB indicator is fixed to XRAN_RBIND_EVERY.
1585 - Symbol increment is not used (XRAN_SYMBOLNUMBER_NOTINC)
1587 - Resource Element Mask is fixed to 0xfff
1589 If section extensions include extension 1 or 11, direct mbuf will not be
1590 allocated/used and pre-allocated flat buffer will be attached to
1591 indirect mbuf. This external buffer will be used to compose C-Plane
1592 message and should have BFWs already by xran_cp_populate_section_ext_1()
1593 or xran_cp_prepare_ext11_bfws().
1595 Since current implementation uses single section single C-Plane message,
1596 if multi sections are present, this function will generate same amount
1597 of C-Plane messages with the number of sections.
1599 After C-Plane message generation, it will send generated packet to TX
1600 ring after adding an Ethernet header and also will add section
1601 information of generated C-Plane packet to section database, to generate
1602 U-plane message by C-Plane configuration.
1604 The generate_cpmsg_prach()is to generate the C-Plane message with
1605 section type 3 for PRACH scheduling.
1607 This functions also has some hardcoded values for the following
1610 - RB indicator is fixed to XRAN_RBIND_EVERY.
1612 - Symbol increment is not used (XRAN_SYMBOLNUMBER_NOTINC).
1614 - Resource Element Mask is fixed to 0xfff.
1616 This function does not send generated packet, send_cpmsg() should be
1617 called after this function call. The example can be found from
1618 tx_cp_ul_cb() in xran_main.c. Checking and parsing received PRACH symbol
1619 data by section information from the C-Plane are not implemented in this
1622 Example Configuration of C-Plane Messages
1623 '''''''''''''''''''''''''''''''''''''''''
1625 C-Plane messages can be composed through API, and the sample application
1626 shows several reference usages of the configuration for different
1629 Below are the examples of C-Plane message configuration with a sample
1630 application for mmWave – numerology 3, 100 MHz bandwidth, TDD (DDDS)
1632 **C-Plane Message – downlink symbol data for a downlink slot**
1634 - Single CP message with the single section of section type 1
1636 - Configures single CP message for all consecutive downlink symbols
1638 - Configures whole RBs (66) for a symbol
1640 - Compression and beamforming are not used
1642 Common Header Fields::
1644 - dataDirection = XRAN_DIR_DL
1645 - payloadVersion = XRAN_PAYLOAD_VER
1646 - filterIndex = XRAN_FILTERINDEX_STANDARD
1648 - subframeId = [0..9]
1651 - numberOfsections = 1
1652 - sectionType = XRAN_CP_SECTIONTYPE_1
1653 - udCompHdr.idIqWidth = 0
1654 - udCompHdr.udCompMeth = XRAN_COMPMETHOD_NONE
1659 - sectionId = [0..4095]
1660 - rb = XRAN_RBIND_EVERY
1661 - symInc = XRAN_SYMBOLNUMBER_NOTINC
1670 **C-Plane Message – uplink symbol data for uplink slot**
1672 - Single CP message with the single section of section type 1
1674 - Configures single CP message for all consecutive uplink symbols (UL
1675 symbol starts from 3)
1677 - Configures whole RBs (66) for a symbol
1679 - Compression and beamforming are not used
1681 Common Header Fields::
1683 - dataDirection = XRAN_DIR_UL
1684 - payloadVersion = XRAN_PAYLOAD_VER
1685 - filterIndex = XRAN_FILTERINDEX_STANDARD
1687 - subframeId = [0..9]
1690 - numberOfsections = 1
1691 - sectionType = XRAN_CP_SECTIONTYPE_1
1692 - udCompHdr.idIqWidth = 0
1693 - udCompHdr.udCompMeth = XRAN_COMPMETHOD_NONE
1698 - sectionId = [0..4095]
1699 - rb = XRAN_RBIND_EVERY
1700 - symInc = XRAN_SYMBOLNUMBER_NOTINC
1709 **C-Plane Message – PRACH**
1711 - Single CP message with the single section of section type 3 including
1714 - Configures PRACH format A3, config index 81, and detail parameters
1721 - Time offset : 2026
1725 - Subcarrier spacing : 120KHz
1727 - Start symbol index : 7
1729 - Number of symbols : 6
1731 - Number of PRBCs : 12
1733 - Frequency offset : -792
1735 - Compression and beamforming are not used
1737 Common Header Fields::
1739 - dataDirection = XRAN_DIR_UL
1740 - payloadVersion = XRAN_PAYLOAD_VER
1741 - filterIndex = XRAN_FILTERINDEPRACH_ABC
1743 - subframeId = [0,3]
1746 - numberOfSections = 1
1747 - sectionType = XRAN_CP_SECTIONTYPE_3
1749 - frameStructure.FFTSize = XRAN_FFTSIZE_1024
1750 - frameStructure.u = XRAN_SCS_120KHZ
1752 - udCompHdr.idIqWidth = 0
1753 - udCompHdr.udCompMeth = XRAN_COMPMETHOD_NONE
1757 - sectionId = [0..4095]
1758 - rb = XRAN_RBIND_EVERY
1759 - symInc = XRAN_SYMBOLNUMBER_NOTINC
1766 - frequencyOffset = -792
1770 Functions to Store/Retrieve Section Information
1771 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1773 There are several functions to store/retrieve section information of
1774 C-Plane messages. Since U-plane messages must be generated by the
1775 information in the sections of a C-Plane message, it is required to
1776 store and retrieve section information.
1778 **APIs and Data Structure**
1779 '''''''''''''''''''''''''''
1781 APIs for initialization and release storage are:
1783 - int xran_cp_init_sectiondb(void \*pHandle);
1785 - int xran_cp_free_sectiondb(void \*pHandle);
1787 APIs to store and retrieve section information are:
1789 - int xran_cp_add_section_info(void \*pHandle, uint8_t dir, uint8_t
1790 cc_id, uint8_t ruport_id, uint8_t ctx_id, struct xran_section_info
1793 - int xran_cp_add_multisection_info(void \*pHandle, uint8_t cc_id,
1794 uint8_t ruport_id, uint8_t ctx_id, struct xran_cp_gen_params
1797 - struct xran_section_info \*xran_cp_find_section_info(void \*pHandle,
1798 uint8_t dir, uint8_t cc_id, uint8_t ruport_id, uint8_t ctx_id,
1799 uint16_t section_id);
1801 - struct xran_section_info \*xran_cp_iterate_section_info(void
1802 \*pHandle, uint8_t dir, uint8_t cc_id, uint8_t ruport_id, uint8_t
1803 ctx_id, uint32_t \*next);
1805 - int xran_cp_getsize_section_info(void \*pHandle, uint8_t dir, uint8_t
1806 cc_id, uint8_t ruport_id, uint8_t ctx_id);
1808 APIs to reset the storage for a new slot are:
1810 - int xran_cp_reset_section_info(void \*pHandle, uint8_t dir, uint8_t
1811 cc_id, uint8_t ruport_id, uint8_t ctx_id);
1813 The structure of xran_section_info is used to store/retrieve
1814 information. This is the same structure used to generate a C-Plane
1815 message. Refer to Section *1, API and Data Structures* for more details.
1817 The storage for section information is declared as a multi-dimensional
1818 array and declared as a local static variable to limit direct access.
1819 Each item is defined as the structure of xran_sectioninfo_db, and it has
1820 the number of stored section information items (cur_index) and the array
1821 of the information (list), as shown below.
1824 \* This structure to store the section information of C-Plane
1825 \* in order to generate and parse corresponding U-Plane \*/
1827 struct xran_sectioninfo_db {
1828 uint32_t cur_index; /* Current index to store for this eAXC*/\
1829 struct xran_section_info list[XRAN_MAX_NUM_SECTIONS]; /* The array of
1830 section information \*/
1834 static struct xran_sectioninfo_db
1835 sectiondb[XRAN_MAX_SECTIONDB_CTX][XRAN_DIR_MAX][XRAN_COMPONENT_CARRIERS_MAX][XRAN_MAX_ANTENNA_NR*2
1836 + XRAN_MAX_ANT_ARRAY_ELM_NR];
1838 The maximum size of the array can be adjusted if required by system
1839 configuration. Since transmission and reception window of U-Plane can be
1840 overlapped with the start of new C-Plane for next slot, functions have
1841 context index to identify and protect the information. Currently the
1842 maximum number of context is defined by two and it can be adjusted if
1845 Note. Since the context index is not managed by the library and APIs are
1846 expecting it from the caller as a parameter, the caller shall
1847 consider a proper method to manage it to avoid corruption. The
1848 current reference implementation uses a slot and subframe index to
1849 calculate the context index.
1851 **Example Usage of APIs**
1852 '''''''''''''''''''''''''
1854 There are references to show the usage of APIs as below.
1856 - Initialization and release::
1858 xran_cp_init_sectiondb(): xran_open() in lib/src/xran_main.c
1860 xran_cp_free_sectiondb(): xran_close() in lib/src/xran_main.c
1862 - Store section information::
1864 xran_cp_add_section_info(): send_cpmsg_dlul() and
1865 send_cpmsg_prach()in lib/src/xran_main.c
1867 - Retrieve section information::
1869 xran_cp_iterate_section_info(): xran_process_tx_sym() in
1872 xran_cp_getsize_section_info(): xran_process_tx_sym() in
1875 - Reset the storage for a new slot::
1877 xran_cp_reset_section_info(): tx_cp_dl_cb() and tx_cp_ul_cb() in
1880 **Function for RU emulation and Debug**
1881 '''''''''''''''''''''''''''''''''''''''
1883 xran_parse_cp_pkt() is a function which can be utilized for RU emulation
1884 or debug. It is defined below::
1886 int xran_parse_cp_pkt(struct rte_mbuf \*mbuf,
1887 struct xran_cp_recv_params \*result,
1888 struct xran_recv_packet_info \*pkt_info);
1890 It parses a received C-Plane packet and retrieves the information from
1891 its headers and sections.
1893 The retrieved information is stored in the structures:
1895 struct xran_cp_recv_params: section information from received C-Plane
1898 struct xran_recv_packet_info: transport layer header information
1901 These functions can be utilized to debug or RU emulation purposes.
1908 Single Section is the default mode of O-RAN packet creation. It assumes
1909 that there is only one section per packet, and all IQ samples are
1910 attached to it. Compression is not supported.
1912 A message is built in the mbuf space given as a parameter. The library
1913 builds eCPRI header filling structure fields by taking the IQ sample
1914 size and populating a particular packet length and sequence number.
1916 With block floating point compression, supported IQ bit widths are
1917 8,9,10,12,14. With modulation compression, supported IQ bit widths are
1918 defined according to modulation order as in section A.5 of O-RAN spec..
1920 Implementation of a U-plane set of functions is defined in xran_up_api.c
1921 and is used to prepare U-plane packet content according to the given
1924 The following list of functions is implemented for U-plane:
1926 - Build eCPRI header
1928 - Build application header
1930 - Build section header
1932 - Append IQ samples to packet
1934 - Prepare full symbol of O-RAN data for single eAxC
1936 - Process RX packet per symbol.
1938 The time of generation of a U-plane message for DL and UL is
1939 “symbol-based” and can be controlled using O-DU settings (O-RU),
1940 according to *Table 4*.
1942 For more information on function arguments and parameters refer to
1943 corresponding source cod*\ e.
1948 The O-RAN library has a set of functions used to assist in packet
1949 processing and data exchange not directly used for O-RAN packet
1955 The sense of time for the O-RAN protocol is obtained from system time,
1956 where the system timer is synchronized to GPS time via PTP protocol
1957 using the Linux PHP package. On the software side, a simple polling loop
1958 is utilized to get time up to nanosecond precision and particular packet
1959 processing jobs are scheduled via the DPDK timer.:::
1961 long poll_next_tick(int interval)
1965 struct timespec start_time;
1967 struct timespec cur_time;
1973 clock_gettime(CLOCK_REALTIME, &start_time);
1975 target_time = (start_time.tv_sec \* NSEC_PER_SEC + start_time.tv_nsec +
1976 interval \* NSEC_PER_USEC) / (interval \* NSEC_PER_USEC) \* interval;
1982 clock_gettime(CLOCK_REALTIME, &cur_time);
1984 delta = (cur_time.tv_sec \* NSEC_PER_SEC + cur_time.tv_nsec) -
1985 target_time \* NSEC_PER_USEC;
1987 if(delta > 0 \|\| (delta < 0 && abs(delta) < THRESHOLD))
2001 Polling is used to achieve the required precision of symbol time. For
2002 example, in the mmWave scenario, the symbol time is 125µs/14=~8.9µs.
2003 Small deterministic tasks can be executed within the polling interval
2004 provided. It’s smaller than the symbol interval time.
2006 Current O-RAN library supports multiple O-RU of multiple numerologies,
2007 thus the sense of timing is based on the O-RU with highest numerology
2008 (smallest symbol time). It is required to configure the O-RU0 with
2009 highest numerology in the O-RAN configuration.
2014 DPDK provides sets of primitives (struct rte_rimer) and functions
2015 (rte_timer_reset_sync() rte_timer_manage()) to |br|
2016 schedule processing of
2017 function as timer. The timer is based on the TSC clock and is not
2018 synchronized to PTP time. As a |br|
2019 result, this timer cannot be used as a
2020 periodic timer because the TSC clock can drift substantially relative to
2021 the system timer which in turn is synchronized to PTP (GPS)
2023 Only single-shot timers are used to schedule processing based on
2024 events such as symbol time. The packet |br|
2026 calls rte_timer_manage() in the loop, and the resulting execution of
2027 timer function happens right |br|
2028 after the timer was “armed”.
2033 xran_init_port() function performs initialization of DPDK ETH port.
2034 Standard port configuration is used as per reference example from DPDK.
2036 Jumbo Frames are used by default. Mbufs size is extended to support 9600
2039 Configurable MTU size is supported starting from E release.
2041 MAC address and VLAN tag are expected to be configured by Infrastructure
2042 software. Refer to *A.4, Install and Configure Sample Application*.
2044 From an implementation perspective, modules provide functions to handle:
2050 - Send and Receive mbuf.
2055 Ethdi provides functionality to work with the content of an Ethernet
2056 packet and dispatch processing to/from the xRAN layer. Ethdi
2057 instantiates a main PMD driver thread and dispatches packets between the
2058 ring and RX/TX using rte_eth_rx_burst() and rte_eth_tx_burst() DPDK
2061 For received packets, it maintains a set of handlers for ethertype
2062 handlers and xRAN layer register one O-RAN ethtype |br|
2063 0xAEFE, resulting in
2064 packets with this ethertype being routed to the xRAN processing
2065 function. This function checks the message type of the eCPRI header and
2066 dispatches packet to either C-plane processing or U-plane processing.
2068 Initialization of memory pools, allocation, and freeing of the mbuf for
2069 Ethernet packets occur in this layer.
2072 O-RAN One Way Delay Measurements
2073 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2075 The support for the eCPRI one- way delay measurements which are
2076 specified by the O-RAN to be used with the Measured Transport support
2077 per Section 2.3.3.3 of the O-RAN-WG4.CUS.0-v4.00 specification and
2078 section 3.2.4.6 of the eCPRI_v2.0 specification is implemented in the
2079 file xran_delay_measurement.c. Structure definitions used by the owd
2080 measurement functions are in the file xran_fh_o_du.h for common data and
2081 port specific variables and parameters.
2083 The implementation of this feature has been done under the assumption
2084 that the requestor is the O-DU and the recipient is the O-RU. All of the
2085 action_types per the eCPRI 2.0 have been implemented. In the current
2086 version the timestamps are obtained using the linux function
2087 clock_gettime using CLOCK_REALTIME as the clock_id argument.
2089 The implementation supports both the O-RU and the O-DU side in order to
2090 do the unit test in loopback mode.
2092 The one-delay measurements are enabled at configuration time and run
2093 right after the xran_start() function is executed. The total number of
2094 consecutive measurements per port should be a power of 2 and in order to
2095 minimize the system startup it is advisable that the number is 16 or
2098 The following functions can be found in the xran_delay_measurement.c:
2100 xran_ecpri_one_way_delay_measurement_transmitter() which is invoked from
2101 the process_dpdk_io() function if the one-way delay measurements are
2102 enabled. This is the main function for the owd transmitter.
2104 xran_generate_delay_meas() is a general function used by the transmitter
2105 to send the appropriate messages based on actionType and filling up all
2106 the details for the ethernet and ecpri layers.
2108 Process_delay_meas() this function is invoked from the
2109 handle_ecpri_ethertype() function when the ecpri message type is
2110 ECPRI_DELAY_MEASUREMENT. This is the main owd receiver function.
2112 From the Process_delay_meas() and depending on the message received we
2113 can execute one of the following functions
2115 xran_process_delmeas_request() If we received a request message.
2117 xran_process_delmeas_request_w_fup() If we received a request with follow up message.
2119 xran_process_delmeas_response() If we received a response message.
2121 xran_process_delmeas_rem_request() If we received a remote request message
2124 xran_delmeas_rem_request_w_fup() If we received a remote request with follow up message.
2126 All of the receiver functions also can generate the appropriate send message by using
2127 the DPDK function rte_eth_tx_burst() to minimize the response delay.
2129 Additional utility functions used by the owd implementation for managing of timestamps
2130 and time measurements are:
2132 xran_ptp_ts_to_ns() that takes a TimeStamp argument from a received owd ecpri packet and
2133 places it in host order and returns the value in nanoseconds.
2135 xran_timespec_to_ns() that takes an argument in timespec format like the return value from the
2136 linux function clock_gettime() and returns a value in nanoseconds.
2138 xran_ns_to_timespec() that takes an argument in nanoseconds and returns a value by
2139 reference in timespec format.
2141 xran_compute_and_report_delay_estimate() This function takes an average of the computed one way
2142 delay measurements and prints out the average value to the console expressed in nanoseconds.
2143 Currently we exclude the first 2 measurements from the average.
2145 Utility functions in support of the owd ecpri packet formulation are:
2147 xran_build_owd_meas_ecpri_hdr() Builds the ecpri header with message type ECPRI_DELAY_MEASUREMENT
2148 and writes the payload size in network order.
2150 xran_add_at_and_measId_to_header() This function is used to write the action Type and
2151 MeasurementID to the eCPRI owd header.
2153 The current implementation of the one way delay measurements only supports a fixed
2154 message size. The message is defined in the xran_pkt.h in the structure xran_ecpri_delay_meas_pl.
2156 The one-way delay measurements have been tested with the sample-app for the Front Haul Interface
2157 Library and have not yet been integrated with the L1 Layer functions.