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) release is:
40 │ │ ├── app_io_fh_xran.c
42 │ │ ├── app_io_fh_xran.h
44 │ │ ├── app_profile_xran.c
46 │ │ ├── app_profile_xran.h
60 │ │ └── xran_mlog_task_id.h
78 │ │ ├── xran_compression.h
80 │ │ ├── xran_compression.hpp
84 │ │ ├── xran_fh_o_du.h
86 │ │ ├── xran_lib_mlog_tasks_id.h
88 │ │ ├── xran_mlog_lnx.h
96 │ │ ├── xran_sync_api.h
100 │ │ ├── xran_transport.h
102 │ │ └── xran_up_api.h
118 │ ├── xran_app_frag.c
120 │ ├── xran_app_frag.h
122 │ ├── xran_bfp_byte_packing_utils.hpp
124 │ ├── xran_bfp_cplane8.cpp
126 │ ├── xran_bfp_cplane8_snc.cpp
128 │ ├── xran_bfp_cplane16.cpp
130 ├── xran_bfp_cplane16_snc.cpp
132 │ ├── xran_bfp_cplane32.cpp
134 │ ├── xran_bfp_cplane32_snc.cpp
136 │ ├── xran_bfp_cplane64.cpp
138 │ ├── xran_bfp_cplane64_snc.cpp
140 │ ├── xran_bfp_cplane8.cpp
142 │ ├── xran_bfp_ref.cpp
144 │ ├── xran_bfp_uplane.cpp
146 │ ├── xran_bfp_uplane_9b16rb.cpp
148 │ ├── xran_bfp_uplane_snc.cpp
150 │ ├── xran_bfp_utils.hpp
160 │ ├── xran_compression.cpp
162 │ ├── xran_compression_snc.cpp
170 │ ├── xran_delay_measurement.c
176 │ ├── xran_ecpri_owd_measurements.h
178 │ ├── xran_frame_struct.c
180 │ ├── xran_frame_struct.h
190 │ ├── xran_mod_compression.cpp
192 │ ├── xran_mod_compression.h
194 │ ├── xran_prach_cfg.h
202 │ ├── xran_sync_api.c
206 │ ├── xran_transport.c
212 │ ├── xran_ul_tables.c
228 │ ├── common_typedef_xran.h
232 │ ├── MIT_License.txt
234 │ ├── xranlib_unit_test_main.cc
236 │ └── xran_lib_wrap.hpp
246 ├── compander_functional.cc
252 ├── init_sys_functional.cc
256 ├── prach_functional.cc
258 ├── prach_performance.cc
262 └── u_plane_functional.cc
268 The O-RAN Library functionality is broken down into two main sections:
270 - O-RAN specific packet handling (src)
272 - Ethernet and supporting functionality (Ethernet)
274 External functions and structures are available via set of header files
277 This library depends on DPDK primitives to perform Ethernet networking
278 in userspace, including initialization and control of Ethernet ports.
279 Ethernet ports are expected to be SRIOV virtual functions (VF) but also
280 can be physical functions (PF) as well.
282 This library is expected to be included in the project via
283 xran_fh_o_du.h, statically compiled and linked with the L1 application
284 as well as DPDK libraries. The O-RAN packet processing-specific
285 functionality is encapsulated into this library and not exposed to the
286 rest of the 5G NR pipeline.
288 This way, O-RAN specific changes are decoupled from the 5G NR L1
289 pipeline. As a result, the design and implementation of the 5G L1
290 pipeline code and O-RAN library can be done in parallel, provided the
291 defined interface is not modified.
293 Ethernet consists of two modules:
295 - Ethernet implements O-RAN specific HW Ethernet initialization, close,
298 - ethdi provides Ethernet level software primitives to handle O-RAN
301 The O-RAN layer implements the next set of functionalities:
303 - Common code specific for both C-plane and U-plane as well as TX and
306 - Implementation of C-plane API available within the library and
309 - The primary function where general library initialization and
310 configuration performed
312 - Module to provide the status of PTP synchronization
314 - Timing module where system time is polled
316 - eCPRI specific transport layer functions
318 - APIs to handle U-plane packets
320 - A set of utility modules for debugging (printf) and data tables are
323 .. image:: images/Illustration-of-xRAN-Sublayers.jpg
325 :alt: Figure 25. Illustration of O-RAN Sublayers
327 Figure 25. Illustration of O-RAN Sublayers
329 A detailed description of functions and input/output arguments, as well
330 as key data structures, can be found in the Doxygen file for the FlexRAN
331 5G NR release. In this document supplemental information is provided
332 with respect to the overall design and implementation assumptions.
334 Initialization and Close
335 ------------------------
337 An example of the initialization sequence can be found in the sample
338 application code. It consists of the following steps:
340 1.Setup structure struct xran_fh_init according to configuration.
342 2.Call xran_init() to instantiate the O-RAN lib memory model and
343 threads. The function returns a pointer to O-RAN handle which is used
344 for consecutive configuration functions.
346 3.Initialize memory buffers used for L1 and O-RAN exchange of
349 4.Assign callback functions for (one) TTI event and for the reception
350 of half of the slot of symbols (7 symbols) and Full slot of symbols
353 5.Call xran_open() to initialize PRACH configuration, initialize DPDK,
354 and launch O-RAN timing thread.
356 6.Call xran_start() to start processing O-RAN packets for DL and UL.
358 After this is complete 5G L1 runs with O-RAN Front haul interface. During
359 run time for every TTI event, the corresponding call back is called. For
360 packet reception on UL direction, the corresponding call back is called.
361 OTA time information such as frame id, subframe id and slot id can be
362 obtained as result synchronization of the L1 pipeline to GPS time is
365 To stop and close the interface, perform this sequence of steps:
367 7.Call xran_stop() to stop the processing of DL and UL.
369 8.Call xran_close() to remove usage of O-RAN resources.
371 9.Call xran_mm_destroy() to destroy memory management subsystem.
373 After this session is complete, a restart of the full L1 application is
374 required. The current version of the library does not support multiple
375 sessions without a restart of the full L1 application.
380 The O-RAN library configuration is provided in the set of structures, such as struct xran_fh_init and struct xran_fh_config.
381 The sample application gives an example of a test configuration used for LTE and 5GNR mmWave and Sub 6. Sample application
382 folder /app/usecase/ contains set of examples for different Radio Access technology (LTE|5G NR), different category (A|B)
383 and list of numerologies (0,1,3) and list of bandwidths (5,10,20,100Mhz).
385 Some configuration options are not used in the Bronze Release and are reserved
388 The following options are available:
390 **Structure** struct xran_fh_init\ **:**
392 - Number of CC and corresponding settings for each
394 - Core allocation for O-RAN
396 - Ethernet port allocation
398 - O-DU and RU Ethernet Mac address
400 - Timing constraints of O-DU and 0-RU
404 **Structure** struct xran_fh_config\ **:**
408 - TTI Callback function and parameters
410 - PRACH 5G NR specific settings
412 - TDD frame configuration
414 - BBU specific configuration
416 - RU specific configuration
418 **From an implementation perspective:**
420 xran_init() performs init of the O-RAN library and interface according to
421 struct xran_fh_init information as per the start of application
424 - Init DPDK with corresponding networking ports and core assignment
428 - Init DPDK timers and DPDK rings for internal packet processing
430 - Instantiate ORAN FH thread doing
432 - Timing processing (xran_timing_source_thread())
434 - ETH PMD (process_dpdk_io())
436 - IO O-RAN-PHY exchange (ring_processing_func())
438 **xran_open()** performs additional configuration as per run scenario:
440 - PRACH configuration
442 - C-plane initialization
444 The Function **xran_close()** performs free of resources and allows potential
445 restart of front haul interface with a different scenario.
450 The Functions **xran_start()/xran_stop()** enable/disable packet processing for
451 both DL and UL. This triggers execution of callbacks into the L1
457 Exchange of IQ samples, as well as C-plane specific information, is
458 performed using a set of buffers allocated by O-RAN library from DPDK
459 memory and shared with the l1 application. Buffers are allocated as a
460 standard mbuf structure and DPDK pools are used to manage the allocation
461 and free resources. Shared buffers are allocated at the init stage and
462 are expected to be reused within 80 TTIs (10 ms).
464 The O-RAN protocol requires U-plane IQ data to be transferred in network
465 byte order, and the L1 application handles IQ sample data in CPU byte
466 order, requiring a swap. The PHY BBU pooling tasks perform copy and byte
467 order swap during packet processing.
469 C-plane Information Settings
470 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
472 The interface between the O-RAN library and PHY is defined via struct
473 xran_prb_map and similar to the data plane. The same mbuf memory is used
474 to allocate memory map of PRBs for each TTI.::
476 /*\* Beamforming waights for single stream for each PRBs given number of
478 struct xran_cp_bf_weight{
480 int16_t nAntElmTRx; /**< num TRX for this allocation \*/
482 int16_t ext_section_sz; /**< extType section size \*/
484 int8_t\* p_ext_start; /**< pointer to start of buffer for full C-plane
487 int8_t\* p_ext_section; /**< pointer to form extType \*/
491 uint8_t bfwCompMeth; /\* Compression Method for BFW \*/
493 uint8_t bfwIqWidth; /\* Bitwidth of BFW \*/
495 uint8_t numSetBFWs; /\* Total number of beam forming weights set (L) \*/
497 uint8_t numBundPrb; /\* The number of bundled PRBs, 0 means to use ext1
504 int16_t maxExtBufSize; /\* Maximum space of external buffer \*/
506 struct xran_ext11_bfw_info bfw[XRAN_MAX_SET_BFWS]
510 /*\* PRB element structure \*/
512 struct xran_prb_elm {
514 int16_t nRBStart; /**< start RB of RB allocation \*/
516 int16_t nRBSize; /**< number of RBs used \*/
518 int16_t nStartSymb; /**< start symbol ID \*/
520 int16_t numSymb; /**< number of symbols \*/
522 int16_t nBeamIndex; /**< beam index for given PRB \*/
524 int16_t bf_weight_update; /*\* need to update beam weights or not \*/
526 int16_t compMethod; /**< compression index for given PRB \*/
528 int16_t iqWidth; /**< compression bit width for given PRB \*/
530 uint16_t ScaleFactor; /**< scale factor for modulation compression \*/
532 int16_t reMask; /**< 12-bit RE Mask for modulation compression \*/
534 int16_t BeamFormingType; /**< index based, weights based or attribute
537 int16_t nSecDesc[XRAN_NUM_OF_SYMBOL_PER_SLOT]; /**< number of section
538 descriptors per symbol \*/
540 struct xran_section_desc \*
541 p_sec_desc[XRAN_NUM_OF_SYMBOL_PER_SLOT][XRAN_MAX_FRAGMENT]; /**< section
542 desctiptors to U-plane data given RBs \*/
544 struct xran_cp_bf_weight bf_weight; /**< beam forming information
545 relevant for given RBs \*/
549 struct xran_cp_bf_attribute bf_attribute;
551 struct xran_cp_bf_precoding bf_precoding;
557 /*\* PRB map structure \*/
559 struct xran_prb_map {
561 uint8_t dir; /**< DL or UL direction \*/
563 uint8_t xran_port; /**< O-RAN id of given RU [0-(XRAN_PORTS_NUM-1)] \*/
565 uint16_t band_id; /**< O-RAN band id \*/
567 uint16_t cc_id; /**< component carrier id [0 - (XRAN_MAX_SECTOR_NR-1)]
570 uint16_t ru_port_id; /**< RU device antenna port id [0 -
571 (XRAN_MAX_ANTENNA_NR-1) \*/
573 uint16_t tti_id; /**< O-RAN slot id [0 - (max tti-1)] \*/
575 uint8_t start_sym_id; /**< start symbol Id [0-13] \*/
577 uint32_t nPrbElm; /**< total number of PRB elements for given map [0-
578 (XRAN_MAX_SECTIONS_PER_SLOT-1)] \*/
580 struct xran_prb_elm prbMap[XRAN_MAX_SECTIONS_PER_SLOT];
585 For the Bronze release C-plane sections are expected to be provided by L1
586 pipeline. If 100% of RBs always allocated single element of RB map
587 is expected to be allocated across all symbols. Dynamic RB allocation is
588 performed base on C-plane configuration.
590 The O-RAN library will require that the content of the PRB map should be
591 sorted in increasing order of PRB first and then symbols.
596 Memory used for the exchange of IQ data as well as control information,
597 is controlled by the O-RAN library. L1 application at the init stage
600 - init memory management subsystem
602 - init buffer management subsystem (via DPDK pools)
604 - allocate buffers (mbuf) for each CC, antenna, symbol, and direction \
605 (DL, UL, PRACH) for XRAN_N_FE_BUF_LEN TTIs.
607 - buffers are reused for every XRAN_N_FE_BUF_LEN TTIs
609 After the session is completed, the application can free buffers and
610 destroy the memory management subsystem.
612 From an implementation perspective, the O-RAN library uses a standard
613 mbuf primitive and allocates a pool of buffers for each sector. This
614 function is performed using rte_pktmbuf_pool_create(),
615 rte_pktmbuf_alloc(), rte_pktmbuf_append() to allocate one buffer per
616 symbol for the mmWave case. More information on mbuf and DPDK pools can
617 be found in the DPDK documentation.
619 In the current implementation, mbuf, the number of buffers shared with
620 the L1 application is the same number of buffers used to send to and
621 receive from the Ethernet port. Memory copy operations are not required
622 if the packet size is smaller than or equal to MTU. Future versions of
623 the O-RAN library are required to remove the memory copy requirement for
624 packets where the size larger than MTU.
626 External Interface Memory
627 ~~~~~~~~~~~~~~~~~~~~~~~~~
629 The O-RAN library header file defines a set of structures to simplify
630 access to memory buffers used for IQ data.:::
632 struct xran_flat_buffer {
634 uint32_t nElementLenInBytes;
636 uint32_t nNumberOfElements;
638 uint32_t nOffsetInBytes;
648 struct xran_buffer_list {
650 uint32_t nNumBuffers;
652 struct xran_flat_buffer \*pBuffers;
656 void \*pPrivateMetaData;
660 struct xran_io_buf_ctrl {
662 /\* -1-this subframe is not used in current frame format
664 0-this subframe can be transmitted, i.e., data is ready
666 1-this subframe is waiting transmission, i.e., data is not ready
668 10 - DL transmission missing deadline. When FE needs this subframe data
669 but bValid is still 1,
675 int32_t bValid ; // when UL rx, it is subframe index.
679 int32_t nSegGenerated; // how many date segment are generated by DL LTE
680 processing or received from FE
682 // -1 means that DL packet to be transmitted is not ready in BS
684 int32_t nSegTransferred; // number of data segments has been transmitted
687 struct rte_mbuf \*pData[N_MAX_BUFFER_SEGMENT]; // point to DPDK
688 allocated memory pool
690 struct xran_buffer_list sBufferList;
694 There is no explicit requirement for user to organize a set of buffers
695 in this particular way. From a compatibility |br|
696 perspective it is useful to
697 follow the existing design of the 5G NR l1app used for Front Haul FPGA
698 and define structures shared between l1 and O-RAN lib as shown: ::
700 struct bbu_xran_io_if {
702 void\* nInstanceHandle[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR]; /**<
703 instance per O-RAN port per CC \*/
706 nBufPoolIndex[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR][MAX_SW_XRAN_INTERFACE_NUM];
707 /**< unique buffer pool \*/
709 uint16_t nInstanceNum[XRAN_PORTS_NUM]; /**< instance is equivalent to CC
712 uint16_t DynamicSectionEna;
714 uint32_t nPhaseCompFlag;
718 int32_t num_cc_per_port[XRAN_PORTS_NUM];
720 int32_t map_cell_id2port[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
722 struct xran_io_shared_ctrl ioCtrl[XRAN_PORTS_NUM]; /**< for each O-RU
725 struct xran_cb_tag RxCbTag[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
727 struct xran_cb_tag PrachCbTag[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
729 struct xran_cb_tag SrsCbTag[XRAN_PORTS_NUM][XRAN_MAX_SECTOR_NR];
733 struct xran_io_shared_ctrl {
737 struct xran_io_buf_ctrl
738 sFrontHaulTxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
740 struct xran_io_buf_ctrl
741 sFrontHaulTxPrbMapBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
743 struct xran_io_buf_ctrl
744 sFrontHaulRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
746 struct xran_io_buf_ctrl
747 sFrontHaulRxPrbMapBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
749 struct xran_io_buf_ctrl
750 sFHPrachRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
754 struct xran_io_buf_ctrl
755 sFHSrsRxBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR];
757 struct xran_io_buf_ctrl
758 sFHSrsRxPrbMapBbuIoBufCtrl[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR];
760 /\* buffers lists \*/
762 struct xran_flat_buffer
763 sFrontHaulTxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
765 struct xran_flat_buffer
766 sFrontHaulTxPrbMapBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
768 struct xran_flat_buffer
769 sFrontHaulRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
771 struct xran_flat_buffer
772 sFrontHaulRxPrbMapBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR];
774 struct xran_flat_buffer
775 sFHPrachRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANTENNA_NR][XRAN_NUM_OF_SYMBOL_PER_SLOT];
777 /\* Cat B SRS buffers \*/
779 struct xran_flat_buffer
780 sFHSrsRxBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR][XRAN_MAX_NUM_OF_SRS_SYMBOL_PER_SLOT];
782 struct xran_flat_buffer
783 sFHSrsRxPrbMapBuffers[XRAN_N_FE_BUF_LEN][XRAN_MAX_SECTOR_NR][XRAN_MAX_ANT_ARRAY_ELM_NR];
787 Doxygen file and xran_fh_o_du.h provide more details on the definition
788 and usage of these structures.
790 O-RAN Specific Functionality
791 ----------------------------
793 Front haul interface implementation in the general case is abstracted
794 away using the interface defined in xran_fh_o_du.h
796 The L1 application is not required to access O-RAN protocol primitives
797 (eCPRI header, application header, and others) directly. It is
798 recommended to use the interface to remove dependencies between
799 different software modules such as the l1 pipeline and O-RAN library.
804 The U-plane and C-plane APIs can be used directly from the application
805 if such an option is required. The set of header files can be exported
806 and called directly.::
808 xran_fh_o_du.h – O-RAN main header file for O-DU scenario
810 xran_cp_api.h – Control plane functions
812 xran_pkt_cp.h – O-RAN control plane packet definition
814 xran_pkt.h – O-RAN packet definition
816 xran_pkt_up.h – O-RAN User plane packet definition
818 xran_sync_api.h – api functions to check PTP status
820 xran_timer.h – API for timing
822 xran_transport.h – eCPRI transport layer definition and api
824 xran_up_api.h – user plane functions and definitions
826 xran_compression.h – interface to compression/decompression functions
828 Doxygen files provide detailed information on functions and structures
836 Implementation of the C-plane set of functions is defined in
837 xran_cp_api.c and is used to prepare the content of C-plane packets
838 according to the given configuration. Users can enable/disable
839 generation of C-plane messages using enableCP field in struct
840 xran_fh_init structure during init of ORAN front haul. The time of
841 generation of C-plane message for DL and UL is done “Slot-based,” and
842 timing can be controlled using O-DU settings according to Table 4.
844 The C-plane module contains:
846 - initialization of C-plane database to keep track of allocation of
849 - code to prepare C-plane packet for TX (O-DU)
851 - append radio application header
852 - append control section header
853 - append control section
855 - parser of C-plane packet for RX (O-RU emulation)
857 - parses and checks Section 1 and Section 3 packet content
859 Sending and receiving packets is performed using O-RAN ethdi sublayer
862 Creating a C-Plane Packet
863 ^^^^^^^^^^^^^^^^^^^^^^^^^
865 API and Data Structures
866 '''''''''''''''''''''''
868 A C-Plane message can be composed using the following API:::
870 int xran_prepare_ctrl_pkt(struct rte_mbuf \*mbuf,
872 struct xran_cp_gen_params \*params,
874 uint8_t CC_ID, uint8_t Ant_ID, uint8_t seq_id);
876 mbuf is the pointer of a DPDK packet buffer, which is allocated from the
879 params are the pointer of the structure which has the parameters to
882 CC_ID is the parameter to specify component carrier index, Ant_ID is the
883 parameters to specify the antenna port index (RU port index).
885 seq_id is the sequence index for the message.
887 params, the parameters to create a C-Plane message are defined as the
888 structure of xran_cp_gen_params with an |br|
889 example given below:::
891 struct xran_cp_gen_params {
897 uint16_t numSections;
899 struct xran_cp_header_params hdr;
901 struct xran_section_gen_info \*sections;
905 dir is the direction of the C-Plane message to be generated. Available
906 parameters are defined as XRAN_DIR_UL and XRAN_DIR_DL.
908 sectionType is the section type for C-Plane message to generate, as O-RAN
909 specification defines all sections in a C-Plane message shall have the
910 same section type. If different section types are required, they shall
911 be sent with separate C-Plane messages. Available types of sections are
912 defined as XRAN_CP_SECTIONTYPE_x. Please refer to the Table 5-2 Section
913 Types in chapter 5.4 of ORAN specification.
915 numSections is the total number of sections to generate, i.e., the
916 number of the array in sections (struct xran_section_gen_info).
918 hdr is the structure to hold the information to generate the radio
919 application and section header in the C-Plane message. It is defined as
920 the structure of xran_cp_header_params. Not all parameters in this
921 structure are used for the generation, and the required parameters are
922 slightly different by the type of section, as described in Table 10.
924 Table 10. struct xran_cp_header_params – Common Radio Application Header
926 +------------+---------------------------------------------+---------+
927 | | Description | Remarks |
928 +============+=============================================+=========+
929 | filterIdx | Filter Index. Available values are defined | 5.4.4.3 |
930 | | as XRAN_FILTERINDEX_xxxxx. | |
931 +------------+---------------------------------------------+---------+
932 | frameId | Frame Index. It is modulo 256 of frame | 5.4.4.4 |
934 +------------+---------------------------------------------+---------+
935 | subframeId | Sub-frame Index. | 5.4.4.5 |
936 +------------+---------------------------------------------+---------+
937 | slotId | Slot Index. The maximum number is 15, as | 5.4.4.6 |
938 | | defined in the specification. | |
939 +------------+---------------------------------------------+---------+
940 | startSymId | Start Symbol Index. | 5.4.4.7 |
941 +------------+---------------------------------------------+---------+
943 Table 11. struct xran_cp_header_params – Section Specific Parameters
945 +----------+----------+----------+---------+---+---+---+---+----------+
946 | | Des\ | Section | Remarks | | | | | |
947 | | cription | Type | | | | | | |
948 | | | ap\ | | | | | | |
949 | | | plicable | | | | | | |
950 +==========+==========+==========+=========+===+===+===+===+==========+
951 | | | 0 | 1 | 3 | 5 | 6 | 7 | |
952 +----------+----------+----------+---------+---+---+---+---+----------+
953 | fftSize | FFT size | X | | X | | | | 5.4.4.13 |
954 | | in frame | | | | | | | |
955 | | st\ | | | | | | | |
956 | | ructure. | | | | | | | |
957 | | A\ | | | | | | | |
958 | | vailable | | | | | | | |
959 | | values | | | | | | | |
960 | | are | | | | | | | |
961 | | defined | | | | | | | |
962 | | as | | | | | | | |
963 | | X\ | | | | | | | |
964 | | RAN_FFTS\| | | | | | | |
965 | | IZE_xxxx | | | | | | | |
966 +----------+----------+----------+---------+---+---+---+---+----------+
967 | Scs | Su\ | X | | X | | | | 5.4.4.13 |
968 | | bcarrier | | | | | | | |
969 | | Spacing | | | | | | | |
970 | | in the | | | | | | | |
971 | | frame | | | | | | | |
972 | | st\ | | | | | | | |
973 | | ructure. | | | | | | | |
974 | | A\ | | | | | | | |
975 | | vailable | | | | | | | |
976 | | values | | | | | | | |
977 | | are | | | | | | | |
978 | | defined | | | | | | | |
979 | | as | | | | | | | |
980 | | XRAN_SCS\| | | | | | | |
981 | | _xxxx | | | | | | | |
982 +----------+----------+----------+---------+---+---+---+---+----------+
983 | iqWidth | I/Q bit | | X | X | X | | | 5.4.4.10 |
984 | | width in | | | | | | | |
985 | | user | | | | | | | 6.3.3.13 |
986 | | data | | | | | | | |
987 | | com\ | | | | | | | |
988 | | pression | | | | | | | |
989 | | header. | | | | | | | |
990 | | Should | | | | | | | |
991 | | be set | | | | | | | |
992 | | by zero | | | | | | | |
993 | | for | | | | | | | |
994 | | 16bits | | | | | | | |
995 +----------+----------+----------+---------+---+---+---+---+----------+
996 | compMeth | Com\ | | X | X | X | | | 5.4.4.10 |
997 | | pression | | | | | | | |
998 | | Method | | | | | | | 6.3.3.13 |
999 | | in user | | | | | | | |
1000 | | data | | | | | | | |
1001 | | com\ | | | | | | | |
1002 | | pression | | | | | | | |
1003 | | header. | | | | | | | |
1004 | | A\ | | | | | | | |
1005 | | vailable | | | | | | | |
1006 | | values | | | | | | | |
1007 | | are | | | | | | | |
1008 | | defined | | | | | | | |
1009 | | as | | | | | | | |
1010 | | O-RAN\ | | | | | | | |
1011 | | _COMPMET\| | | | | | | |
1012 | | HOD_xxxx | | | | | | | |
1013 +----------+----------+----------+---------+---+---+---+---+----------+
1014 | numUEs | Number | | | | | X | | 5.4.4.11 |
1015 | | of UEs. | | | | | | | |
1016 | | Applies | | | | | | | |
1017 | | to | | | | | | | |
1018 | | section | | | | | | | |
1019 | | type 6 | | | | | | | |
1020 | | and not | | | | | | | |
1021 | | s\ | | | | | | | |
1022 | | upported | | | | | | | |
1023 | | in this | | | | | | | |
1024 | | release. | | | | | | | |
1025 +----------+----------+----------+---------+---+---+---+---+----------+
1026 | ti\ | Time | X | | X | | | | 5.4.4.12 |
1027 | meOffset | Offset. | | | | | | | |
1028 | | Time | | | | | | | |
1029 | | offset | | | | | | | |
1030 | | from the | | | | | | | |
1031 | | start of | | | | | | | |
1032 | | the slot | | | | | | | |
1033 | | to start | | | | | | | |
1034 | | of | | | | | | | |
1035 | | Cyclic | | | | | | | |
1036 | | Prefix. | | | | | | | |
1037 +----------+----------+----------+---------+---+---+---+---+----------+
1038 | cpLength | Cyclic | X | | X | | | | 5.4.4.14 |
1039 | | Prefix | | | | | | | |
1040 | | Length. | | | | | | | |
1041 +----------+----------+----------+---------+---+---+---+---+----------+
1043 **Only sections types 1 and 3 are supported in the current release.**
1045 Sections are the pointer to the array of structure which has the
1046 parameters for section(s) and it is defined as below:::
1048 struct xran_section_gen_info {
1050 struct xran_section_info info;
1052 uint32_t exDataSize;
1062 } exData[XRAN_MAX_NUM_EXTENSIONS];
1066 info is the structure to hold the information to generate section and it
1067 is defined as the structure of xran_section_info. Like
1068 xran_cp_header_params, all parameters are not required to generate
1069 section and Table 12 describes which |br|
1070 parameters are required for each
1073 Table 12. Parameters for Sections
1075 +-------+-------+-------+-------+-------+-------+-------+-------+
1076 | | D\ | Se\ | Re\ | | | | |
1077 | | escri\| ction | marks | | | | |
1078 | | ption | Type | | | | | |
1079 | | | appli\| | | | | |
1080 | | | cable | | | | | |
1081 +=======+=======+=======+=======+=======+=======+=======+=======+
1082 | | | 0 | 1 | 3 | 5 | 6 | |
1083 +-------+-------+-------+-------+-------+-------+-------+-------+
1084 | Id | Se\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
1085 | | ction | | | | | | 4.5.1 |
1086 | | I\ | | | | | | |
1087 | | denti\| | | | | | |
1088 | | fier. | | | | | | |
1089 +-------+-------+-------+-------+-------+-------+-------+-------+
1090 | Rb | Res\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
1091 | | ource | | | | | | 4.5.2 |
1092 | | Block\| | | | | | |
1093 | | Indic\| | | | | | |
1094 | | ator. | | | | | | |
1095 | | Avai\ | | | | | | |
1096 | | lable | | | | | | |
1097 | | v\ | | | | | | |
1098 | | alues | | | | | | |
1099 | | are | | | | | | |
1100 | | de\ | | | | | | |
1101 | | fined | | | | | | |
1102 | | as | | | | | | |
1103 | | O-RAN\| | | | | | |
1104 | | _\ | | | | | | |
1105 | | RBI\ | | | | | | |
1106 | | ND_xx\| | | | | | |
1107 | | xx. | | | | | | |
1108 +-------+-------+-------+-------+-------+-------+-------+-------+
1109 | s\ | S\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
1110 | ymInc | ymbol | | | | | | 4.5.3 |
1111 | | n\ | | | | | | |
1112 | | umber | | | | | | |
1113 | | Incr\ | | | | | | |
1114 | | ement | | | | | | |
1115 | | com\ | | | | | | |
1116 | | mand. | | | | | | |
1117 | | Avai\ | | | | | | |
1118 | | lable | | | | | | |
1119 | | v\ | | | | | | |
1120 | | alues | | | | | | |
1121 | | are | | | | | | |
1122 | | de\ | | | | | | |
1123 | | fined | | | | | | |
1124 | | as | | | | | | |
1125 | | XRA\ | | | | | | |
1126 | | N_SYM\| | | | | | |
1127 | | BOL\ | | | | | | |
1128 | | NUMBE\| | | | | | |
1129 | | R_xx\ | | | | | | |
1130 | | xx. | | | | | | |
1131 +-------+-------+-------+-------+-------+-------+-------+-------+
1132 | star\ | Sta\ | **X** | **X** | **X** | **X** | **X** | 5.\ |
1133 | tPrbc | rting\| | | | | | 4.5.4 |
1134 | | PRB | | | | | | |
1135 | | of | | | | | | |
1136 | | data | | | | | | |
1137 | | se\ | | | | | | |
1138 | | ction | | | | | | |
1139 | | de\ | | | | | | |
1140 | | scrip\| | | | | | |
1141 | | tion. | | | | | | |
1142 +-------+-------+-------+-------+-------+-------+-------+-------+
1143 | nu | The | **X** | **X** | **X** | **X** | **X** | 5.\ |
1144 | mPrbc | n\ | | | | | | 4.5.6 |
1145 | | umber | | | | | | |
1146 | | of | | | | | | |
1147 | | conti\| | | | | | |
1148 | | guous | | | | | | |
1149 | | PRBs | | | | | | |
1150 | | per | | | | | | |
1151 | | data | | | | | | |
1152 | | se\ | | | | | | |
1153 | | ction | | | | | | |
1154 | | de\ | | | | | | |
1155 | | scrip\| | | | | | |
1156 | | tion. | | | | | | |
1157 | | When | | | | | | |
1158 | | nu\ | | | | | | |
1159 | | mPrbc | | | | | | |
1160 | | is | | | | | | |
1161 | | gr\ | | | | | | |
1162 | | eater | | | | | | |
1163 | | than | | | | | | |
1164 | | 255, | | | | | | |
1165 | | it | | | | | | |
1166 | | will | | | | | | |
1167 | | be | | | | | | |
1168 | | conv\ | | | | | | |
1169 | | erted | | | | | | |
1170 | | to | | | | | | |
1171 | | zero | | | | | | |
1172 | | by | | | | | | |
1173 | | the | | | | | | |
1174 | | macro | | | | | | |
1175 | | (XR\ | | | | | | |
1176 | | AN_CO\| | | | | | |
1177 | | NVERT\| | | | | | |
1178 | | _NUMP\| | | | | | |
1179 | | RBC). | | | | | | |
1180 +-------+-------+-------+-------+-------+-------+-------+-------+
1181 | r\ | Res\ | **X** | **X** | **X** | **X** | | 5.\ |
1182 | eMask | ource\| | | | | | 4.5.5 |
1183 | | El\ | | | | | | |
1184 | | ement\| | | | | | |
1185 | | Mask. | | | | | | |
1186 +-------+-------+-------+-------+-------+-------+-------+-------+
1187 | numS\ | N\ | **X** | **X** | **X** | **X** | | 5.\ |
1188 | ymbol | umber | | | | | | 4.5.7 |
1189 | | of | | | | | | |
1190 | | Sym\ | | | | | | |
1191 | | bols. | | | | | | |
1192 +-------+-------+-------+-------+-------+-------+-------+-------+
1193 | b\ | Beam\ | | **X** | **X** | | | 5.\ |
1194 | eamId | I\ | | | | | | 4.5.9 |
1195 | | denti\| | | | | | |
1196 | | fier. | | | | | | |
1197 +-------+-------+-------+-------+-------+-------+-------+-------+
1198 | freqO\| Freq\ | | | **X** | | | 5.4\ |
1199 | ffset | uency\| | | | | | .5.11 |
1200 | | Of\ | | | | | | |
1201 | | fset. | | | | | | |
1202 +-------+-------+-------+-------+-------+-------+-------+-------+
1203 | ueId | UE\ | | | | **X** | **X** | 5.4\ |
1204 | | i\ | | | | | | .5.10 |
1205 | | denti\| | | | | | |
1206 | | fier. | | | | | | |
1207 | | Not | | | | | | |
1208 | | supp\ | | | | | | |
1209 | | orted | | | | | | |
1210 | | in | | | | | | |
1211 | | this | | | | | | |
1212 | | rel\ | | | | | | |
1213 | | ease. | | | | | | |
1214 +-------+-------+-------+-------+-------+-------+-------+-------+
1215 | regF\ | Regu\ | | | | | **X** | 5.4\ |
1216 | actor | lariz\| | | | | | .5.12 |
1217 | | ation | | | | | | |
1218 | | Fa\ | | | | | | |
1219 | | ctor. | | | | | | |
1220 | | Not | | | | | | |
1221 | | supp\ | | | | | | |
1222 | | orted | | | | | | |
1223 | | in | | | | | | |
1224 | | this | | | | | | |
1225 | | re\ | | | | | | |
1226 | | lease | | | | | | |
1227 +-------+-------+-------+-------+-------+-------+-------+-------+
1228 | Ef | Exte\ | | **X** | **X** | **X** | **X** | 5.\ |
1229 | | nsion | | | | | | 4.5.8 |
1230 | | Flag. | | | | | | |
1231 | | Not | | | | | | |
1232 | | supp\ | | | | | | |
1233 | | orted | | | | | | |
1234 | | in | | | | | | |
1235 | | this | | | | | | |
1236 | | rel\ | | | | | | |
1237 | | ease. | | | | | | |
1238 +-------+-------+-------+-------+-------+-------+-------+-------+
1240 **Only sections types 1 and 3 are supported in the current release.**
1242 **The xran_section_info has more parameters – type, startSymId, iqWidth,
1243 compMeth. These are the same parameters as those of radio application
1244 or section header but need to be copied into this structure again for
1245 the section data base.**
1247 exDataSize and exData are used to add section extensions for the
1250 exDataSize is the number of elements in the exData array. The maximum
1251 number of elements is defined as XRAN_MAX_NUM_EXTENSIONS and it is
1252 defined by four in this release with the assumption that four different
1253 types of section extensions can be added to a section (section extension
1254 type 3 is excluded since it is not supported). exData.type is the type
1255 of section extension and exData.len is the length of structure of
1256 section extension parameter in exData.data. exData.data is the pointer
1257 to the structure of section extensions and different structures are used
1258 by the type of section extensions like below.::
1260 struct xran_sectionext1_info {
1262 uint16_t rbNumber; /* number RBs to ext1 chain \*/
1264 uint16_t bfwNumber; /* number of bf weights in this section \*/
1268 uint8_t bfwCompMeth;
1270 int16_t \*p_bfwIQ; /* pointer to formed section extention \*/
1272 int16_t bfwIQ_sz; /* size of buffer with section extention information
1279 uint8_t blockScaler;
1281 uint8_t compBitWidthShift;
1283 uint8_t activeBeamspaceCoeffMask[XRAN_MAX_BFW_N]; /\* ceil(N/8)*8,
1284 should be multiple of 8 \*/
1290 For section extension type 1, the structure of xran_sectionext1_info is
1291 used. Please note that the O-RAN library will use bfwIQ (beamforming
1292 weight) as-is, i.e., O-RAN library will not perform the compression, so
1293 the user should provide proper data to bfwIQ.::
1295 struct xran_sectionext2_info {
1297 uint8_t bfAzPtWidth;
1301 uint8_t bfZePtWidth;
1305 uint8_t bfAz3ddWidth;
1309 uint8_t bfZe3ddWidth;
1319 For section extension type 2, the structure of xran_sectionext2_info is
1320 used. Each parameter will be packed as specified bit width.::
1322 struct xran_sectionext4_info {
1328 uint16_t modCompScaler;
1332 For section extension type 4, the structure of xran_sectionext4_info is
1335 struct xran_sectionext5_info {
1343 uint16_t mcScaleReMask;
1345 uint16_t mcScaleOffset;
1347 } mc[XRAN_MAX_MODCOMP_ADDPARMS];
1351 For section extension type 5, the structure of xran_sectionext5_info is
1352 used. Please note that current implementation supports maximum two sets
1353 of additional parameters.::
1355 struct xran_sectionext6_info {
1361 uint16_t symbolMask;
1367 For section extension type 6, the structure of xran_sectionext6_info is
1370 struct xran_sectionext10_info {
1374 uint8_t beamGrpType;
1376 uint16_t beamID[XRAN_MAX_NUMPORTC_EXT10];
1380 For section extension type 10, the structure of xran_sectionext10_info
1383 struct xran_sectionext11_info {
1387 uint8_t disableBFWs;
1391 uint8_t numSetBFWs; /\* Total number of beam forming weights set (L) \*/
1393 uint8_t bfwCompMeth;
1399 int maxExtBufSize; /\* Maximum space of external buffer \*/
1401 uint8_t \*pExtBuf; /\* pointer to start of external buffer \*/
1403 void \*pExtBufShinfo; /\* Pointer to rte_mbuf_ext_shared_info \*/
1407 For section extension type 11, the structure of xran_sectionext11_info
1410 To minimize memory copy for beamforming weights, when section extension
1411 11 is required to send beamforming weights(BFWs), external flat buffer
1412 is being used in current release. If extension 11 is used, it will be
1413 used instead of mbufs that pre-allocated external buffers which BFWs
1414 have been prepared already. BFW can be prepared by
1415 xran_cp_prepare_ext11_bfws() and the example usage can be found from
1416 app_init_xran_iq_content() from sample-app.c.
1418 Detail Procedures in API
1419 ''''''''''''''''''''''''
1421 xran_prepare_ctrl_pkt() has several procedures to compose a C-Plane
1424 1. Append transport header
1426 - Reserve eCPRI header space in the packet buffer
1428 - eCPRI version is fixed by XRAN_ECPRI_VER (0x0001)
1430 - Concatenation and transport layer fragmentation is not supported.
1432 ecpri_concat=0, ecpri_seq_id.sub_seq_id=0 and ecpri_seq_id.e_bit=1
1434 - The caller needs to provide a component carrier index, antenna index,
1435 and message identifier through function arguments.
1437 CC_ID, Ant_ID and seq_id
1439 - ecpriRtcid (ecpri_xtc_id) is composed with CC_ID and Ant_ID by
1442 - DU port ID and band sector ID are fixed by zero in this release.
1444 - The output of xran_compose_cid is stored in network byte order.
1446 - The length of the payload is initialized by zero.
1448 2. Append radio application header:
1450 - xran_append_radioapp_header() checks the type of section through
1451 params->sectionType and determines proper function to append
1452 remaining header components.
1454 - Only section type 1 and 3 are supported, returns
1455 XRAN_STATUS_INVALID_PARAM for other types.
1457 - Each section uses a different function to compose the remaining
1458 header and size to calculate the total length in the transport
1461 For section type 1, xran_prepare_section1_hdr() and sizeof(struct
1462 xran_cp_radioapp_section1_header)
1464 For section type 3, xran_prepare_section3_hdr() and sizeof(struct
1465 xran_cp_radioapp_section3_header)
1467 - Reserves the space of common radio application header and composes
1468 header by xran_prepare_radioapp_common_header().
1470 - The header is stored in network byte order.
1472 - Appends remaining header components by the selected function above
1474 - The header is stored in network byte order
1476 3. Append section header and section
1478 - xran_append_control_section() determines proper size and function to
1479 append section header and contents.
1481 - For section type 1, xran_prepare_section1() and sizeof(struct
1482 xran_cp_radioapp_section1)
1484 - For section type 3, xran_prepare_section3() and sizeof(struct
1485 xran_cp_radioapp_section3)
1487 - Appends section header and section(s) by selected function above.
1489 - If multiple sections are configured, then those will be added.
1491 - Since fragmentation is not considered in this implementation, the
1492 total length of a single C-Plane message shall not exceed MTU
1495 - The header and section(s) are stored in network byte order.
1497 - Appends section extensions if it is set (ef=1)
1499 - xran_append_section_extensions() adds all configured extensions by
1502 - xran_prepare_sectionext_x() (x = 1,2,4,5) will be called by the
1503 type from xran_append_section_extensions() and these functions
1504 will create extension field.
1506 Example Usage of API
1507 ''''''''''''''''''''
1509 There are two reference usages of API to generate C-Plane messages:
1511 - xran_cp_create_and_send_section() in xran_main.c
1513 - generate_cpmsg_prach() in xran_common.c
1515 The xran_cp_create_and_send_section() is to generate the C-Plane message
1516 with section type 1 for DL or UL symbol data scheduling.
1518 This function has hardcoded values for some parameters such as:
1520 - The filter index is fixed to XRAN_FILTERINDEX_STANDARD.
1522 - RB indicator is fixed to XRAN_RBIND_EVERY.
1524 - Symbol increment is not used (XRAN_SYMBOLNUMBER_NOTINC)
1526 - Resource Element Mask is fixed to 0xfff
1528 If section extensions include extension 1 or 11, direct mbuf will not be
1529 allocated/used and pre-allocated flat buffer will be attached to
1530 indirect mbuf. This external buffer will be used to compose C-Plane
1531 message and should have BFWs already by xran_cp_populate_section_ext_1()
1532 or xran_cp_prepare_ext11_bfws().
1534 Since current implementation uses single section single C-Plane message,
1535 if multi sections are present, this function will generate same amount
1536 of C-Plane messages with the number of sections.
1538 After C-Plane message generation, it will send generated packet to TX
1539 ring after adding an Ethernet header and also will add section
1540 information of generated C-Plane packet to section database, to generate
1541 U-plane message by C-Plane configuration.
1543 The generate_cpmsg_prach()is to generate the C-Plane message with
1544 section type 3 for PRACH scheduling.
1546 This functions also has some hardcoded values for the following
1549 - RB indicator is fixed to XRAN_RBIND_EVERY.
1551 - Symbol increment is not used (XRAN_SYMBOLNUMBER_NOTINC).
1553 - Resource Element Mask is fixed to 0xfff.
1555 This function does not send generated packet, send_cpmsg() should be
1556 called after this function call. The example can be found from
1557 tx_cp_ul_cb() in xran_main.c. Checking and parsing received PRACH symbol
1558 data by section information from the C-Plane are not implemented in this
1561 Example Configuration of C-Plane Messages
1562 '''''''''''''''''''''''''''''''''''''''''
1564 C-Plane messages can be composed through API, and the sample application
1565 shows several reference usages of the configuration for different
1568 Below are the examples of C-Plane message configuration with a sample
1569 application for mmWave – numerology 3, 100 MHz bandwidth, TDD (DDDS)
1571 **C-Plane Message – downlink symbol data for a downlink slot**
1573 - Single CP message with the single section of section type 1
1575 - Configures single CP message for all consecutive downlink symbols
1577 - Configures whole RBs (66) for a symbol
1579 - Compression and beamforming are not used
1581 Common Header Fields::
1583 - dataDirection = XRAN_DIR_DL
1584 - payloadVersion = XRAN_PAYLOAD_VER
1585 - filterIndex = XRAN_FILTERINDEX_STANDARD
1587 - subframeId = [0..9]
1590 - numberOfsections = 1
1591 - sectionType = XRAN_CP_SECTIONTYPE_1
1592 - udCompHdr.idIqWidth = 0
1593 - udCompHdr.udCompMeth = XRAN_COMPMETHOD_NONE
1598 - sectionId = [0..4095]
1599 - rb = XRAN_RBIND_EVERY
1600 - symInc = XRAN_SYMBOLNUMBER_NOTINC
1609 **C-Plane Message – uplink symbol data for uplink slot**
1611 - Single CP message with the single section of section type 1
1613 - Configures single CP message for all consecutive uplink symbols (UL
1614 symbol starts from 3)
1616 - Configures whole RBs (66) for a symbol
1618 - Compression and beamforming are not used
1620 Common Header Fields::
1622 - dataDirection = XRAN_DIR_UL
1623 - payloadVersion = XRAN_PAYLOAD_VER
1624 - filterIndex = XRAN_FILTERINDEX_STANDARD
1626 - subframeId = [0..9]
1629 - numberOfsections = 1
1630 - sectionType = XRAN_CP_SECTIONTYPE_1
1631 - udCompHdr.idIqWidth = 0
1632 - udCompHdr.udCompMeth = XRAN_COMPMETHOD_NONE
1637 - sectionId = [0..4095]
1638 - rb = XRAN_RBIND_EVERY
1639 - symInc = XRAN_SYMBOLNUMBER_NOTINC
1648 **C-Plane Message – PRACH**
1650 - Single CP message with the single section of section type 3 including
1653 - Configures PRACH format A3, config index 81, and detail parameters
1660 - Time offset : 2026
1664 - Subcarrier spacing : 120KHz
1666 - Start symbol index : 7
1668 - Number of symbols : 6
1670 - Number of PRBCs : 12
1672 - Frequency offset : -792
1674 - Compression and beamforming are not used
1676 Common Header Fields::
1678 - dataDirection = XRAN_DIR_UL
1679 - payloadVersion = XRAN_PAYLOAD_VER
1680 - filterIndex = XRAN_FILTERINDEPRACH_ABC
1682 - subframeId = [0,3]
1685 - numberOfSections = 1
1686 - sectionType = XRAN_CP_SECTIONTYPE_3
1688 - frameStructure.FFTSize = XRAN_FFTSIZE_1024
1689 - frameStructure.u = XRAN_SCS_120KHZ
1691 - udCompHdr.idIqWidth = 0
1692 - udCompHdr.udCompMeth = XRAN_COMPMETHOD_NONE
1696 - sectionId = [0..4095]
1697 - rb = XRAN_RBIND_EVERY
1698 - symInc = XRAN_SYMBOLNUMBER_NOTINC
1705 - frequencyOffset = -792
1709 Functions to Store/Retrieve Section Information
1710 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1712 There are several functions to store/retrieve section information of
1713 C-Plane messages. Since U-plane messages must be generated by the
1714 information in the sections of a C-Plane message, it is required to
1715 store and retrieve section information.
1717 **APIs and Data Structure**
1718 '''''''''''''''''''''''''''
1720 APIs for initialization and release storage are:
1722 - int xran_cp_init_sectiondb(void \*pHandle);
1724 - int xran_cp_free_sectiondb(void \*pHandle);
1726 APIs to store and retrieve section information are:
1728 - int xran_cp_add_section_info(void \*pHandle, uint8_t dir, uint8_t
1729 cc_id, uint8_t ruport_id, uint8_t ctx_id, struct xran_section_info
1732 - int xran_cp_add_multisection_info(void \*pHandle, uint8_t cc_id,
1733 uint8_t ruport_id, uint8_t ctx_id, struct xran_cp_gen_params
1736 - struct xran_section_info \*xran_cp_find_section_info(void \*pHandle,
1737 uint8_t dir, uint8_t cc_id, uint8_t ruport_id, uint8_t ctx_id,
1738 uint16_t section_id);
1740 - struct xran_section_info \*xran_cp_iterate_section_info(void
1741 \*pHandle, uint8_t dir, uint8_t cc_id, uint8_t ruport_id, uint8_t
1742 ctx_id, uint32_t \*next);
1744 - int xran_cp_getsize_section_info(void \*pHandle, uint8_t dir, uint8_t
1745 cc_id, uint8_t ruport_id, uint8_t ctx_id);
1747 APIs to reset the storage for a new slot are:
1749 - int xran_cp_reset_section_info(void \*pHandle, uint8_t dir, uint8_t
1750 cc_id, uint8_t ruport_id, uint8_t ctx_id);
1752 The structure of xran_section_info is used to store/retrieve
1753 information. This is the same structure used to generate a C-Plane
1754 message. Please refer to Section 5.4.2.1.1 for more details.
1756 The storage for section information is declared as a multi-dimensional
1757 array and declared as a local static variable to limit direct access.
1758 Each item is defined as the structure of xran_sectioninfo_db, and it has
1759 the number of stored section information items (cur_index) and the array
1760 of the information (list), as shown below.
1764 \* This structure to store the section information of C-Plane
1766 \* in order to generate and parse corresponding U-Plane \*/
1768 struct xran_sectioninfo_db {
1770 uint32_t cur_index; /* Current index to store for this eAXC \*/
1772 struct xran_section_info list[XRAN_MAX_NUM_SECTIONS]; /* The array of
1773 section information \*/
1777 static struct xran_sectioninfo_db
1778 sectiondb[XRAN_MAX_SECTIONDB_CTX][XRAN_DIR_MAX][XRAN_COMPONENT_CARRIERS_MAX][XRAN_MAX_ANTENNA_NR*2
1779 + XRAN_MAX_ANT_ARRAY_ELM_NR];
1781 The maximum size of the array can be adjusted if required by system
1782 configuration. Since transmission and reception window of U-Plane can be
1783 overlapped with the start of new C-Plane for next slot, functions have
1784 context index to identify and protect the information. Currently the
1785 maximum number of context is defined by two and it can be adjusted if
1788 Note. Since the context index is not managed by the library and APIs are
1789 expecting it from the caller as a parameter, the caller shall
1790 consider a proper method to manage it to avoid corruption. The
1791 current reference implementation uses a slot and subframe index to
1792 calculate the context index.
1794 **Example Usage of APIs**
1795 '''''''''''''''''''''''''
1797 There are references to show the usage of APIs as below.
1799 - Initialization and release:
1801 - xran_cp_init_sectiondb(): xran_open() in lib/src/xran_main.c
1803 - xran_cp_free_sectiondb(): xran_close() in lib/src/xran_main.c
1805 - Store section information:
1807 - xran_cp_add_section_info(): send_cpmsg_dlul() and
1808 send_cpmsg_prach()in lib/src/xran_main.c
1810 - Retrieve section information:
1812 - xran_cp_iterate_section_info(): xran_process_tx_sym() in
1815 - xran_cp_getsize_section_info(): xran_process_tx_sym() in
1818 - Reset the storage for a new slot:
1820 - xran_cp_reset_section_info(): tx_cp_dl_cb() and tx_cp_ul_cb() in
1823 **Function for RU emulation and Debug**
1824 '''''''''''''''''''''''''''''''''''''''
1826 xran_parse_cp_pkt() is a function which can be utilized for RU emulation
1827 or debug. It is defined below:
1829 int xran_parse_cp_pkt(struct rte_mbuf \*mbuf,
1831 struct xran_cp_gen_params \*result,
1833 struct xran_recv_packet_info \*pkt_info);
1835 It parses a received C-Plane packet and retrieves the information from
1836 its headers and sections.
1838 The retrieved information is stored in the structures:
1840 struct xran_cp_gen_params: section information from received C-Plane
1843 struct xran_recv_packet_info: transport layer header information (eCPRI
1846 These functions can be utilized to debug or RU emulation purposes.
1853 Single Section is the default mode of O-RAN packet creation. It assumes
1854 that there is only one section per packet, and all IQ samples are
1855 attached to it. Compression is not supported.
1857 A message is built in mbuf space given as a parameter. The library
1858 builds eCPRI header filling structure fields by taking the IQ sample
1859 size and populating a particular packet length and sequence number.
1861 With compression, supported IQ bit widths are 8,9,10,12,14.
1863 Implementation of a U-plane set of functions is defined in xran_up_api.c
1864 and is used to prepare U-plane packet content according to the given
1867 The following list of functions is implemented for U-plane:
1869 - Build eCPRI header
1871 - Build application header
1873 - Build section header
1875 - Append IQ samples to packet
1877 - Prepare full symbol of O-RAN data for single eAxC
1879 - Process RX packet per symbol.
1881 The time of generation of a U-plane message for DL and UL is
1882 “symbol-based” and can be controlled using O-DU settings (O-RU),
1883 according to Table 4.
1888 The O-RAN library has a set of functions used to assist in packet
1889 processing and data exchange not directly used for O-RAN packet
1895 The sense of time for the O-RAN protocol is obtained from system time,
1896 where the system timer is synchronized to GPS time via PTP protocol
1897 using the Linux PHP package. On the software side, a simple polling loop
1898 is utilized to get time up to nanosecond precision and particular packet
1899 processing jobs are scheduled via the DPDK timer.
1901 long poll_next_tick(int interval)
1905 struct timespec start_time;
1907 struct timespec cur_time;
1913 clock_gettime(CLOCK_REALTIME, &start_time);
1915 target_time = (start_time.tv_sec \* NSEC_PER_SEC + start_time.tv_nsec +
1916 interval \* NSEC_PER_USEC) / (interval \* NSEC_PER_USEC) \* interval;
1922 clock_gettime(CLOCK_REALTIME, &cur_time);
1924 delta = (cur_time.tv_sec \* NSEC_PER_SEC + cur_time.tv_nsec) -
1925 target_time \* NSEC_PER_USEC;
1927 if(delta > 0 \|\| (delta < 0 && abs(delta) < THRESHOLD))
1941 Polling is used to achieve the required precision of symbol time. For
1942 example, in the mmWave scenario, the symbol time is 125µs/14=~8.9µs.
1943 Small deterministic tasks can be executed within the polling interval
1944 provided. It’s smaller than the symbol interval time.
1949 DPDK provides sets of primitives (struct rte_rimer) and functions
1950 (rte_timer_reset_sync() rte_timer_manage()) to |br|
1951 schedule processing of
1952 function as timer. The timer is based on the TSC clock and is not
1953 synchronized to PTP time. As a |br|
1954 result, this timer cannot be used as a
1955 periodic timer because the TSC clock can drift substantially relative to
1956 the system timer which in turn is synchronized to PTP (GPS)
1958 Only single-shot timers are used to schedule processing based on
1959 events such as symbol time. The packet |br|
1961 calls rte_timer_manage() in the loop, and the resulting execution of
1962 timer function happens right |br|
1963 after the timer was “armed”.
1968 xran_init_port() function performs initialization of DPDK ETH port.
1969 Standard port configuration is used as per reference example from DPDK.
1971 Jumbo Frames are used by default. Mbufs size is extended to support 9600
1974 Mac address and VLAN tag are expected to be configured by Infrastructure
1975 software. See Appendix A.4.
1977 From an implementation perspective, modules provide functions to handle:
1983 - Send and Receive mbuf.
1988 Ethdi provides functionality to work with the content of an Ethernet
1989 packet and dispatch processing to/from the O-RAN layer. Ethdi
1990 instantiates a main PMD driver thread and dispatches packets between the
1991 ring and RX/TX using rte_eth_rx_burst() and rte_eth_tx_burst() DPDK
1994 For received packets, it maintains a set of handlers for ethertype
1995 handlers and O-RAN layer register one O-RAN ethtype |br|
1996 0xAEFE, resulting in
1997 packets with this ethertype being routed to the O-RAN processing
1998 function. This function checks the message type of the eCPRI header and
1999 dispatches packet to either C-plane processing or U-plane processing.
2001 Initialization of memory pools, allocation and freeing of mbuf for
2002 Ethernet packets occur in this layer.
2005 O-RAN One Way Delay Measurements
2006 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2008 The support for the eCPRI one- way delay measurements which are specified by
2009 the O-RAN to be used with the Measured Transport support per Section 2.3.3.3
2010 of the O-RAN-WG4.CUS.0-v4.00 specification and section 3.2.4.6 of the eCPRI_v2.0
2011 specification is implemented in the file xran_delay_measurement.c. Structure
2012 definitions used by the owd measurement functions are in the file xran_fh_o_du.h
2013 for common data and port specific variables and parameters.
2015 The implementation of this feature has been done under the assumption that the requestor
2016 is the O-DU and the recipient is the O-RU. All of the action_types per the eCPRI 2.0 have
2017 been implemented. In the current version the timestamps are obtained using the linux
2018 function clock_gettime using CLOCK_REALTIME as the clock_id argument.
2020 The implementation supports both the O-RU and the O-DU side in order to do the unit test
2023 The one-delay measurements are enabled at configuration time and run right after the
2024 xran_start() function is executed. The total number of consecutive measurements per port
2025 should be a power of 2 and in order to minimize the system startup it is advisable that
2026 the number is 16 or below.
2028 The following functions can be found in the xran_delay_measurement.c:
2030 xran_ecpri_one_way_delay_measurement_transmitter() which is invoked from the
2031 process_dpdk_io()function if the one-way delay measurements are enabled. This is
2032 the main function for the owd transmitter.
2034 xran_generate_delay_meas() is a general function used by the transmitter to send the appropriate
2035 messages based on actionType and filling up all the details for the ethernet and ecpri layers.
2037 Process_delay_meas() this function is invoked from the handle_ecpri_ethertype() function when
2038 the ecpri message type is ECPRI_DELAY_MEASUREMENT. This is the main owd receiver function.
2040 From the Process_delay_meas() and depending on the message received we can execute one
2041 of the following functions
2043 xran_process_delmeas_request() If we received a request message.
2045 xran_process_delmeas_request_w_fup() If we received a request with follow up message.
2047 xran_process_delmeas_response() If we received a response message.
2049 xran_process_delmeas_rem_request() If we received a remote request message
2052 xran_delmeas_rem_request_w_fup() If we received a remote request with follow up message.
2054 All of the receiver functions also can generate the appropriate send message by using
2055 the DPDK function rte_eth_tx_burst() to minimize the response delay.
2057 Additional utility functions used by the owd implementation for managing of timestamps
2058 and time measurements are:
2060 xran_ptp_ts_to_ns() that takes a TimeStamp argument from a received owd ecpri packet and
2061 places it in host order and returns the value in nanoseconds.
2063 xran_timespec_to_ns() that takes an argument in timespec format like the return value from the
2064 linux function clock_gettime() and returns a value in nanoseconds.
2066 xran_ns_to_timespec() that takes an argument in nanoseconds and returns a value by
2067 reference in timespec format.
2069 xran_compute_and_report_delay_estimate() This function takes an average of the computed one way
2070 delay measurements and prints out the average value to the console expressed in nanoseconds.
2071 Currently we exclude the first 2 measurements from the average.
2073 Utility functions in support of the owd ecpri packet formulation are:
2075 xran_build_owd_meas_ecpri_hdr() Builds the ecpri header with message type ECPRI_DELAY_MEASUREMENT
2076 and writes the payload size in network order.
2078 xran_add_at_and_measId_to_header() This function is used to write the action Type and
2079 MeasurementID to the eCPRI owd header.
2081 The current implementation of the one way delay measurements only supports a fixed
2082 message size. The message is defined in the xran_pkt.h in the structure xran_ecpri_delay_meas_pl.
2084 The one-way delay measurements have been tested with the sample-app for the Front Haul Interface
2085 Library and have not yet been integrated with the L1 Layer functions.