1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
14 This document provides information required to work on O-DU High code-base.
19 O-DU High uses C languages. The coding guidelines followed are:
21 a. A new file should have License Header and Footer with exception of auto-generated files like files generated by
22 ASN tool. Refer to the diagram below for License header.
23 b. Every block must be indented by 3 spaces.
24 c. Any header file must be included only in .c file, not in other header files.
25 d. The line width should not exceed more than 120 characters.
27 .. figure:: LicHeader.jpg
29 :alt: Figure 8 License Header and Footer
31 Figure 8 : License Header and Footer
36 Refer to O-DU High code-base at: https://gerrit.o-ran-sc.org/r/gitweb?p=o-du/l2.git;a=tree
41 Below section references coding specifics of O-DU High components.
49 In O-DU High, multiple threads are created using below macro
51 ODU_CREATE_TASK (priority, stskId)
53 a. Creates a thread by declaring a thread id
56 - priority - Priority of the task
59 Setting a core affinity:
60 ++++++++++++++++++++++++
62 ODU_SET_THREAD_AFFINITY (tskId, mode, coreId, tskAssociatedTskId)
64 a. Sets the processor/core affinity for a thread based on the mode supplied by the caller.
68 - mode - mode according to which the affinity is set
69 - coreId - coreId to which the affinity has to be set
70 - tskAssociatedTskId - thread Id of the associated layer
72 c. Returns ROK on success and RFAILED on failure
75 +++++++++++++++++++++++
77 All logical entities in O-DU High must be registered into the database.
79 ODU_REG_TTSK (ent, inst, ttype, prior, initTsk, actvTsk)
83 - ent - Id of the entity to activate. Example: ENTDUAPP, ENTSCTP, ENTEGTP etc
84 - Inst - Instance of the entity to activate. It distinguishes between multiple instances of the same entity on a
85 given processor. Example: RLC_UL_INST (Instance id 0) and RLC_DL_INST (Instance id 1) belong to the same entity id, ENTRLC.
86 - ttype - Type of entity
87 - prior - Priority, ranges from 0(Highest) to 3(Lowest).
88 - initTsk - Initialization function(xxActvInit) of the entity being registered gets invoked. Example: duActvInit initializes DU APP
89 - actvTsk - This function(xxActvTsk) is responsible to receive any incoming message to that entity. Example: duActvTsk is triggerred when a message comes to DU APP
91 Attaching Entity to Thread:
92 +++++++++++++++++++++++++++
94 Every entity must be attached to a thread to schedule its activation based on priority and incoming events. Any number
95 of entities can be attached to a system task.
97 ODU_ATTACH_TTSK (ent, inst, stskId)
101 - ent - Entity Id of the task
102 - inst - Instance Id of the task
103 - stskId - Thread Id to use
111 Memory is divided into multiple regions(identified by region id) and each region is divided into multiple pools(identified by pool id).
112 The configurations are present in mt_ss.h and mt_ss.c at <rsys_directory>/l2/src/mt.
113 Currently, the number of regions configured are 6 and each region has 5 pools.
115 Region and pool used by each layer is identified by following macros:
117 - MAC - MAC_MEM_REGION and MAC_POOL
118 - SCH - SCH_MEM_REGION and SCH_POOL
119 - RLC UL - RLC_MEM_REGION_UL and RLC_POOL
120 - RLC_DL - RLC_MEM_REGION_DL and RLC_POOL
121 - DU APP - DU_APP_MEM_REGION and DU_POOL
126 Macros are defined at each layer for static memory allocation/deallocation from that layer's region and pool.
128 XX_ALLOC(bufPtr, size)
130 a. Allocates static buffer
133 - bufPtr - pointer to store address of the memory allocated
134 - size - size of memory to be allocated
138 - If allocation is sucessful, butPtr stores memory address
139 - If allocation fails, bufPtr is NULL.
141 XX_FREE(bufPtr, size)
143 a. Frees static buffer
146 - bufPtr - pointer to memory to be freed
147 - size - size of memory to be freed
149 Here, XX stands for various ODU-High entity i.e.
151 - MAC - MAC_ALLOC & MAC_FREE
152 - SCH - SCH_ALLOC & SCH_FREE
153 - RLC - RLC_ALLOC & RLC_FREE
154 - DU APP - DU_ALLOC & DU_FREE
159 One of the methods of communication between layers is through sharabale memory.
160 The sender will allocate sharable buffer from its own region and pool.
161 This memory will be freed by receiving layer and returned back to sender's region and pool.
163 XX_ALLOC_SHRABL_BUF(bufPtr, size)
165 a. Allocates sharable buffer
168 - bufPtr - pointer to store address of the memory allocated
169 - size - size of memory to be allocated
173 - If allocation is sucessful, butPtr stores memory address
174 - If allocation fails, bufPtr is NULL.
176 XX_FREE_SHRABL_BUF(region, pool, bufPtr, size)
178 a. Frees sharabale buffer
181 - region - region where this buffer is allocated from
182 - pool - pool where this buffer is allocated from
183 - bufPtr - pointer to memory to be freed
184 - size - size of memory to be freed
186 Here, XX stands for various ODU-High entities i.e.
188 - MAC - MAC_ALLOC_SHRABL_BUF & MAC_FREE_SHRABL_BUF
189 - SCH - Since scheduler communicates only with MAC and is tightly coupled, sharable buffers are not needed.
190 - RLC - RLC_ALLOC_SHRABL_BUF & RLC_FREE_SHRABL_BUF
191 - DU APP - DU_ALLOC_SHRABL_BUF & DU_FREE_SHRABL_BUF
196 A message is an ordered sequence of bytes. It stores both the control information and the data being communicated.
197 Message buffers are allocated from dynamic memory.
199 ODU_GET_MSG_BUF(region, pool, mBuf)
201 a. Allocates memory for message buffer
204 - region - region of sending layer
205 - pool - pool of sending layer
206 - mBuf - pointer to message buffer
208 ODU_PUT_MSG_BUF(mBuf)
210 a. Frees memory for message
213 - mBuf - message pointer
218 WLS memory is allocated for message exchanges between O-DU High and O-DU Low.
220 LWR_MAC_ALLOC(ptr, size)
222 a. Allocates WLS memory block
225 - ptr - pointer to store address of the memory allocated
226 - size - size of memory to be allocated
230 - If allocation is sucessful, ptr stores memory address
231 - If allocation fails, ptr is NULL.
233 LWR_MAC_FREE(ptr, size)
238 - bufPtr - pointer to memory to be freed
239 - size - size of memory to be freed
241 Intra O-DU High Communication
242 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
244 O-DU high entities communicate with each other through one of the following:
246 Types of Communication
247 ++++++++++++++++++++++
252 Interface APIs invoked from one entity translate into direct function calls into the destination entity.
253 Control returns to the calling entity after the called entity has completed processing the called function.
255 Macro to select this communication mode : ODU_SELECTOR_TC
260 Interface API invoked from one entity is packed into a message and then sent to destination entity through system services.
261 Control returns to the caller immediately after the message is posted, before the destination has seen or processed it.
262 There are two serialization methods supported:
266 - The interface data is packed into the message. Receiver will unpack this, parameter by parameter.
267 - Macro to select this communication mode : ODU_SELECTOR_LC
269 b. Pack/Unpack pointer
271 - The pointer to data is packed and sent. Receiver will unpack the pointer and directly access data at this address.
272 - Macro to select this communication mode : ODU_SELECTOR_LWLC
274 Below figure depicts the mode of communication between various entities registered in O-DU High.
277 - TC stands for Direct API call
278 - LC stands for Serialization by packing/unpacking of data
279 - LWLC stands for Serialization by packing/unpacking of pointers
281 .. figure:: ModeofCommunication.jpg
283 :alt: Figure 9 Mode of communication between O-DU High entities
285 Figure 9: Mode of communication between O-DU High entities
287 Steps of Communication
288 ++++++++++++++++++++++
290 1. Fill Post Structure
292 Information needed by system services to route API to the destination layer is stored in post structure.
296 | ProcId dstProcId; /\* destination processor ID \*/
297 | ProcId srcProcId; /\* source processor ID \*/
298 | Ent dstEnt; /\* destination entity \*/
299 | Inst dstInst; /\* destination instance \*/
300 | Ent srcEnt; /\* source entity \*/
301 | Inst srcInst; /\* source instance \*/
302 | Prior prior; /\* priority \*/
303 | Route route; /\* route \*/
304 | Event event; /\* event \*/
305 | Region region; /\* region \*/
306 | Pool pool; /\* pool \*/
307 | Selector selector; /\* selector \*/
308 | uint16_t spare1; /\* spare for alignment \*/
311 2. Pack API into message
313 At sender, API is packed i.e. the data is stored into a message in ordered sequence of bytes.
314 At receiver, the data is unpacked from the message and its corresponding handler is invoked.
316 a. If pst->selector is LC, each parameter is packed/unpacked one by one using one of the below.
318 - oduPackUInt8(val, mBuf) - Packs 8-bits value(val) into message(mBuf)
319 - oduUnpakcUInt8(val, mBuf) - Unpacks 8-bits from message(mBuf) and stores in val
320 - oduPackUInt16(val, mBuf) - Packs 16-bits value(val) into message(mBuf)
321 - oduUnpakcUInt16(val, mBuf) - Unpacks 16-bits from message(mBuf) and stores in val
322 - oduPackUInt32(val, mBuf) - Packs 32-bits value(val) into message(mBuf)
323 - oduUnpakcUInt32(val, mBuf) - Unpacks 16-bits from message(mBuf) and stores in val
325 The sequence in which the parameters are unpacked must be reverse of the packing sequence.
327 b. If pst->selector is LWLC, pointer to the interface structure is packed/unpacked.
329 - oduPackPointer(ptr, mBuf) - Packs pointer value(ptr) into message(mBuf)
330 - oduUnpackPointer(ptr, mBuf) - Unpacks pointer value from message(mBuf) and stores in ptr
334 Once the post information is filled and API is packed into a message, it is posted to destination using:
336 ODU_POST_TASK(pst, mBuf)
340 - pst - post structure mentioned above
343 Below figure summarized the above steps of intra O-DU High communication
345 .. figure:: StepsOfCommunication.jpg
347 :alt: Figure 10 Communication between entities
349 Figure 10: Steps of Communication between O-DU High entities
352 Communication with Intel O-DU Low
353 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
355 Intel O-DU Low communicates with O-DU High over WLS interface. Hence, Intel's "wls_lib.h" library is required for using
356 the following APIs for communication.
360 *void\* WLS_Open(const char \*ifacename, unsigned int mode, unsigned long long nWlsMemorySize)*
364 - Opens the WLS interface and registers as instance in the kernel space driver.
365 - Control section of shared memory is mapped to application memory.
369 - ifacename - pointer to string with device driver name (/dev/wls)
370 - mode - mode of operation (Master or Slave). Here, O-DU High acts as MASTER.
372 c. Returns pointer handle to WLS interface for future use by WLS functions
376 *int WLS_Ready(void \*h)*
380 - Checks the state of remote peer of WLS interface
382 b. Inputs - handle of WLS interface
383 c. Returns 0 if peer is available i.e. one to one connection is established
387 *int WLS_Close(void \*h)*
391 - Closes the WLS interface and de-registers as instance in the kernel space driver
392 - Control section of shared memory is unmapped form user space application
394 b. Input - handle of WLS interface to be closed
395 c. Returns 0 if operation is successful
399 *void\* WLS_Alloc(void\* h, unsigned int size)*
403 - Allocates memory block for data exchange shared memory. Memory block is backed by huge pages.
404 - Memory is allocated only once for L2, and divided into various regions.
408 - h - handle of WLS interface
409 - size - size of memory block to allocate
413 - Pointer to allocated memory block
414 - NULL on memory allocation failure
418 *int WLS_Free(void\* h, void\* pMsg)*
422 - Frees memory block for data exchanged on shared memory.
426 - h - handle of WLS interface
427 - pMsg - pointer to WLS memory
429 c. Returns 0 if operation is sucessful
433 *int WLS_Put(void\* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short
438 - Puts memory block (or group of blocks) allocated from WLS memory into the interface to transfer to remote peer
442 - h - handle of WLS interface
443 - pMsg - pointer to memory block (physical address) with data to be transfered to remote peer
444 - MsgSize - size of memory block to send (should be less than 2 MB)
445 - MsgTypeID - application specific identifier of message type
446 - Flags - Scatter/Gather flag if memory block has multiple chunks
448 c. Returns 0 if operation is successful
452 *int WLS_Check(void\* h)*
456 - Checks if there are memory blocks with data from remote peer
458 b. Input - handle of WLS interface
459 c. Returns number of blocks available for "get" operation
463 *int WLS_Wait(void\* h)*
467 - Waits for new memory block from remote peer
470 b. Input - the handle of WLS interface
471 c. Returns number of blocks available for "get" operation
475 *unsigned long long WLS_Get(void\* h, unsigned int \*MsgSize, unsigned short \*MsgTypeID, unsigned short \*Flags)*
479 - Gets memory block from interface received from remote peer.
480 - Non-blocking operation
484 - h - handle of WLS interface
485 - MsgSize - pointer to set size of memory block
486 - MsgTypeID - pointer to application specific identifier of message type
487 - Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
491 - Pointer to memory block (physical address) with data received from remote peer
492 - NULL if error or no blocks available
496 *unsigned long long WLS_WGet(void\* h, unsigned int \*MsgSize, unsigned short \*MsgTypeID, unsigned short \*Flags)*
500 - Gets memory block from interface received from remote peer
501 - It is a blocking operation and waits for next memory block from remote peer
505 - h - handle of WLS interface
506 - MsgSize - pointer to set size of memory block
507 - MsgTypeID - pointer to application specific identifier of message type
508 - Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
512 - Pointer to memory block (physical address) with data received from remote peer
513 - NULL if error or no blocks available
517 *int WLS_WakeUp(void\* h)*
521 - Performs "wakeup" notification to remote peer to unblock "wait" operations pending
523 b. Input - handle of WLS interface
524 c. Returns 0 if operation is successful
528 *unsigned long long WLS_VA2PA(void\* h, void\* pMsg)*
532 - Converts virtual address (VA) to physical address (PA)
536 - h - handle of WLS interface
537 - pMsg - virtual address of WLS memory block
541 - Physical address of WLS memory block
546 *void\* WLS_PA2VA(void\* h, unsigned long long pMsg)*
550 - Converts physical address (PA) to virtual address (VA)
554 - h - handle of WLS interface
555 - pMsg - physical address of WLS memory block
559 - Virtual address of WLS memory block
562 14. **WLS_EnqueueBlock**
564 *int WLS_EnqueueBlock(void\* h, unsigned long long pMsg)*
568 - Used by the Master to provide memory blocks to slave for next slave-to-master data transfer
572 - h - handle of WLS interface
573 - pMsg - physical address of WLS memory block
575 c. Returns 0 if opertaion is successful
577 15. **WLS_DequeueBlock**
579 *unsigned long long WLS_DequeueBlock(void\* h)*
583 - Used by the Master and Slave to get block from master-to-slave queue of available memory blocks
585 b. Input - handle of WLS interface
588 - Physical address of WLS memory block
591 16. **WLS_NumBlocks**
593 *int WLS_NumBlocks(void\* h)*
597 - Returns number of current available block provided by the Master for new transfer of data from slave
599 b. Input - handle of WLS interface
600 c. Returns number of available blocks in slave to master queue
602 Additional Utility Functions
603 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
605 1. ODU_START_TASK(startTime, taskId)
607 a. Gives current time through input parameter
610 - startTime - stores current time to be returned
611 - taskId - task id of calling entity
613 2. ODU_STOP_TASK(startTime, taskId)
615 a. Calculates difference of start time and current time.
618 - startTime - start time of this task
619 - taskId - taskId of calling entity
621 3. ODU_SET_PROC_ID(procId)
623 a. Processors are identified by processor identifiers (ProcId) that are globally unique.
624 It sets the procId for the local processor. In O-DU High, procId is 0 (DU_PROC)
627 - procId - process id to be set
631 a. Finds and returns the local processor id on which the calling task is running
636 5. ODU_CAT_MSG(mbuf1, mbuf2, order)
638 a. Concatenates the given two message.
641 - mbuf1 - pointer to message buffer 1
642 - mbuf2 - pointer to message buffer 2
643 - order - order in which the messages are concatenated
645 6. ODU_GET_MSG_LEN(mBuf, lngPtr)
647 a. Determines length of the data contents of a message
650 - mBuf - pointer to the message buffer
651 - lngPtr - pointer to store length value
655 a. Gracefully exits the process
660 8. ODU_PRINT_MSG(mBuf, src, dst)
662 a. Prints information about message buffer.
665 - mBuf - pointer to the message buffer
667 - dest - destination Id
669 9. ODU_REM_PRE_MSG(dataPtr, mBuf)
671 a. Removes one byte of data from the beginning of a message
674 - dataPtr - pointer to the location where one byte of data is placed
675 - mBuf - pointer to the message buffer
677 10. ODU_REM_PRE_MSG_MULT(dst, cnt, mBuf)
679 a. Removes the specified number of bytes of data from the beginning of a message
682 - dst - pointer to the location where the data bytes are placed.
683 - cnt - number of bytes to be removed from the message.
684 - mBuf- pointer to the message.
686 11. ODU_REG_TMR_MT(ent, inst, period, func)
688 a. Registers timer function of an entity with system services
691 - ent - entity ID of task registering the timer.
692 - inst - instance of task registering the timer.
693 - period - period in system ticks between system service sccessive scheduling
694 of the timer function in the entity
695 - func - timer function.
697 12. ODU_SEGMENT_MSG(mBuf1, idx, mBuf2)
699 a. Segments a message into two messages at the specified index.
702 - mBuf1 - Message 1, original message to be segmented
703 - idx - index in message 1 from which message 2 is created.
704 - mBuf2 - pointer to message buffer 2 (new message).
706 13. ODU_ADD_PRE_MSG_MULT(src, cnt, dst)
708 a. Copies consecutive bytes of data to the beginning of a message
711 - src - source buffer
712 - cnt - number of bytes
713 - dst - destination message
715 14. ODU_ADD_PRE_MSG_MULT_IN_ORDER(src, cnt, dst)
717 a. Copies consecutive bytes of data to the beginning of a message and keeps the bytes order preserved
720 - src - source buffer
721 - cnt - number of bytes
722 - dst - destination message
724 15. ODU_ADD_POST_MSG_MULT(src, cnt, dst)
726 a. Copies consecutive bytes of data to the end of a message
729 - src - source buffer
730 - cnt - number of bytes
731 - dst - destination message
733 16. ODU_COPY_MSG_TO_FIX_BUF(src, srcIdx, cnt, dst, ccnt)
735 a. Copies data from a message buffer into a fixed buffer
738 - src - source message
739 - srcIdx - start index of source buffer to be copied
740 - cnt - number of bytes to be copied
741 - dst - destination buffer
742 - ccnt - number of bytes copied
744 17. ODU_COPY_FIX_BUF_TO_MSG(src, dst, dstIdx, cnt, ccnt)
746 a. Copies data from a fixed buffer to a message buffer
749 - src - source buffer
750 - dst - destination message
751 - dstIdx - index in destination message to starting copying bytes from
752 - cnt - number of bytes to be copied
753 - ccnt - number of bytes copied
761 O1 uses GNU C++ language.
763 ODU - O1 Communication
764 ^^^^^^^^^^^^^^^^^^^^^^
766 O1 module runs as a thread in O-DU High.
768 Alarm communication between the threads happen on a Unix socket.
770 O-DU High sends alarm messages in the following structure using Alarm Interface APIs.
776 | MsgHeader msgHeader; /\* Alarm action raise/clear \*/
777 | EventType eventType; /\* Alarm event type \*/
778 | char objectClassObjectInstance[OBJ_INST_SIZE]; /\* Name of object that raise/clear an alarm \*/
779 | char alarmId[ALRM_ID_SIZE]; /\* Alarm Id \*/
780 | char alarmRaiseTime[DATE_TIME_SIZE]; /\* Time when alarm is raised \*/
781 | char alarmChangeTime[DATE_TIME_SIZE]; /\* Time when alarm is updated \*/
782 | char alarmClearTime[DATE_TIME_SIZE]; /\* Time when alarm is cleared \*/
783 | char probableCause[TEXT_SIZE]; /\* Probable cause of alarm \*/
784 | SeverityLevel perceivedSeverity; /\* Severity level of alarm \*/
785 | char rootCauseIndicator[TEXT_SIZE]; /\* Root cause of alarm \*/
786 | char additionalText[TEXT_SIZE]; /\* Additional text describing alarm \*/
787 | char additionalInfo[TEXT_SIZE]; /\* Any additional information \*/
788 | char specificProblem[TEXT_SIZE]; /\* Any specific problem related to alarm \*/
792 O1 - Netconf Communication
793 ^^^^^^^^^^^^^^^^^^^^^^^^^^
795 O1 communicates with the Netconf server using sysrepo and libyang APIs