docs/developer-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 Developer-Guide
   5 ===============
   6
   7 .. contents::
   8    :depth: 3
   9    :local:
  10
  11 Introduction
  12 ------------
  13
  14 This document provides information required to work on O-DU High code-base.
  15
  16 Coding Style
  17 ------------
  18
  19 O-DU High uses C languages. The coding guidelines followed are:
  20
  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.
  26
  27 .. figure:: LicHeader.jpg
  28   :width: 600
  29   :alt: Figure 17 License Header and Footer
  30
  31   Figure 17 : License Header and Footer
  32
  33 O-DU High code
  34 ---------------
  35
  36 Refer to O-DU High code-base at: https://gerrit.o-ran-sc.org/r/gitweb?p=o-du/l2.git;a=tree
  37
  38 Technical Details
  39 -----------------
  40
  41 Below section references coding specifics of O-DU High components.
  42
  43 Thread Management
  44 ^^^^^^^^^^^^^^^^^
  45
  46 Creation of Thread:
  47 +++++++++++++++++++
  48
  49 In O-DU High, multiple threads are created using below macro
  50
  51    ODU_CREATE_TASK (priority, stskId)
  52
  53       a. Creates a thread by declaring a thread id
  54       b. Inputs
  55
  56          - priority - Priority of the task
  57          - stskId - Thread Id
  58
  59 Setting a core affinity:
  60 ++++++++++++++++++++++++
  61
  62    ODU_SET_THREAD_AFFINITY (tskId, mode, coreId, tskAssociatedTskId)
  63
  64       a. Sets the processor/core affinity for a thread based on the mode supplied by the caller.
  65       b. Inputs
  66
  67          - tskId - thread Id
  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
  71
  72       c. Returns ROK on success and RFAILED on failure
  73
  74 Registering Entities:
  75 +++++++++++++++++++++++
  76
  77 All logical entities in O-DU High must be registered into the database.
  78
  79    ODU_REG_TTSK (ent, inst, ttype, prior, initTsk, actvTsk)
  80
  81       a. Inputs
  82
  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
  90
  91 Attaching Entity to Thread:
  92 +++++++++++++++++++++++++++
  93
  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.
  96
  97    ODU_ATTACH_TTSK (ent, inst, stskId)
  98
  99       a. Inputs
 100
 101          - ent - Entity Id of the task
 102          - inst -  Instance Id of the task
 103          - stskId - Thread Id to use
 104
 105 Memory Management
 106 ^^^^^^^^^^^^^^^^^
 107
 108 Configuration
 109 +++++++++++++
 110
 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.
 114
 115 Region and pool used by each layer is identified by following macros:
 116
 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
 122
 123 Static Memory
 124 +++++++++++++
 125
 126 Macros are defined at each layer for static memory allocation/deallocation from that layer's region and pool.
 127
 128    XX_ALLOC(bufPtr, size)
 129
 130       a. Allocates static buffer
 131       b. Inputs:
 132
 133          - bufPtr - pointer to store address of the memory allocated
 134          - size   - size of memory to be allocated
 135
 136       c. Result:
 137
 138          - If allocation is sucessful, butPtr stores memory address
 139          - If allocation fails, bufPtr is NULL.
 140
 141    XX_FREE(bufPtr, size)
 142
 143       a. Frees static buffer
 144       b. Inputs:
 145
 146          - bufPtr - pointer to memory to be freed
 147          - size   - size of memory to be freed
 148
 149 Here, XX stands for various ODU-High entity i.e.
 150
 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
 155
 156 Sharable Memory
 157 +++++++++++++++
 158
 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.
 162
 163    XX_ALLOC_SHRABL_BUF(bufPtr, size)
 164
 165       a. Allocates sharable buffer
 166       b. Inputs:
 167
 168          - bufPtr - pointer to store address of the memory allocated
 169          - size   - size of memory to be allocated
 170
 171       c. Result:
 172
 173          - If allocation is sucessful, butPtr stores memory address
 174          - If allocation fails, bufPtr is NULL.
 175
 176    XX_FREE_SHRABL_BUF(region, pool, bufPtr, size)
 177
 178       a. Frees sharabale buffer
 179       b. Inputs:
 180
 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
 185
 186 Here, XX stands for various ODU-High entities i.e.
 187
 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
 192
 193 Message Buffer
 194 ++++++++++++++
 195
 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.
 198
 199    ODU_GET_MSG_BUF(region, pool, mBuf)
 200
 201       a. Allocates memory for message buffer
 202       b. Inputs:
 203
 204          - region - region of sending layer
 205          - pool   - pool of sending layer
 206          - mBuf   - pointer to message buffer
 207
 208    ODU_PUT_MSG_BUF(mBuf)
 209
 210       a. Frees memory for message
 211       b. Inputs:
 212
 213          - mBuf - message pointer
 214
 215 WLS Memory
 216 ++++++++++
 217
 218 WLS memory is allocated for message exchanges between O-DU High and O-DU Low.
 219
 220    LWR_MAC_ALLOC(ptr, size)
 221
 222       a. Allocates WLS memory block
 223       b. Inputs:
 224
 225          - ptr  - pointer to store address of the memory allocated
 226          - size - size of memory to be allocated
 227
 228       c. Result:
 229
 230          - If allocation is sucessful, ptr stores memory address
 231          - If allocation fails, ptr is NULL.
 232
 233    LWR_MAC_FREE(ptr, size)
 234
 235       a. Frees WLS block
 236       b. Inputs:
 237
 238          - bufPtr - pointer to memory to be freed
 239          - size   - size of memory to be freed
 240
 241 Intra O-DU High Communication
 242 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 243
 244 O-DU high entities communicate with each other through one of the following:
 245
 246 Types of Communication
 247 ++++++++++++++++++++++
 248
 249 Direct API Call
 250 ###############
 251
 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.
 254
 255    Macro to select this communication mode : ODU_SELECTOR_TC
 256
 257 Serialization
 258 #############
 259
 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:
 263
 264    a. Pack/Unpack data
 265
 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
 268
 269    b. Pack/Unpack pointer
 270
 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
 273
 274 Below figure depicts the mode of communication between various entities registered in O-DU High.
 275 Here,
 276
 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
 280
 281 .. figure:: ModeofCommunication.jpg
 282    :width: 600
 283    :alt: Figure 18 Mode of communication between O-DU High entities
 284
 285    Figure 18: Mode of communication between O-DU High entities
 286
 287 Steps of Communication
 288 ++++++++++++++++++++++
 289
 290 1. Fill Post Structure
 291
 292    Information needed by system services to route API to the destination layer is stored in post structure.
 293
 294    | typedef struct pst
 295    | {
 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 \*/
 309    | } Pst;
 310
 311 2. Pack API into message
 312
 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.
 315
 316    a. If pst->selector is LC, each parameter is packed/unpacked one by one using one of the below.
 317
 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
 324
 325       The sequence in which the parameters are unpacked must be reverse of the packing sequence.
 326
 327    b. If pst->selector is LWLC, pointer to the interface structure is packed/unpacked.
 328
 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
 331
 332 3. Post the message
 333
 334    Once the post information is filled and API is packed into a message, it is posted to destination using:
 335
 336       ODU_POST_TASK(pst, mBuf)
 337
 338          a. Inputs
 339
 340             - pst  - post structure mentioned above
 341             - mBuf - message
 342
 343 Below figure summarized the above steps of intra O-DU High communication
 344
 345 .. figure:: StepsOfCommunication.jpg
 346    :width: 600
 347    :alt: Figure 19 Communication between entities
 348
 349    Figure 19: Steps of Communication between O-DU High entities
 350
 351
 352 Communication with Intel O-DU Low
 353 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 354
 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.
 357
 358 1. **WLS_Open**
 359
 360    *void\* WLS_Open(const char \*ifacename, unsigned int mode, uint64_t \*nWlsMacMemorySize, uint64_t \*nWlsPhyMemorySize)*
 361
 362       a. Description
 363
 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.
 366
 367       b. Inputs:
 368
 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.
 371          - nWlsMacMemorySize - returns the value of WLS MAC memory Size as O-DU High acts as MASTER
 372          - nWlsPhyMemorySize - returns the value of WLS PHY memory Size as O-DU High acts as MASTER
 373
 374       c. Returns pointer handle to WLS interface for future use by WLS functions
 375
 376 2. **WLS_Ready**
 377
 378    *int WLS_Ready(void \*h)*
 379
 380       a. Description
 381
 382          - Checks the state of remote peer of WLS interface
 383
 384       b. Inputs - handle of WLS interface
 385       c. Returns 0 if peer is available i.e. one to one connection is established
 386
 387 3. **WLS_Close**
 388
 389    *int WLS_Close(void \*h)*
 390
 391       a. Description
 392
 393          - Closes the WLS interface and de-registers as instance in the kernel space driver
 394          - Control section of shared memory is unmapped form user space application
 395
 396       b. Input - handle of WLS interface to be closed
 397       c. Returns 0 if operation is successful
 398
 399 4. **WLS_Alloc**
 400
 401    *void\* WLS_Alloc(void\* h, unsigned int size)*
 402
 403       a. Description
 404
 405          - Allocates memory block for data exchange shared memory. Memory block is backed by huge pages.
 406          - Memory is allocated only once for L2, and divided into various regions.
 407
 408       b. Input
 409
 410          - h   - handle of WLS interface
 411          - size - size of memory block to allocate
 412
 413       c. Returns
 414
 415          - Pointer to allocated memory block
 416          - NULL on memory allocation failure
 417
 418 5. **WLS_Free**
 419
 420    *int WLS_Free(void\* h, void\* pMsg)*
 421
 422       a. Description
 423
 424          - Frees memory block for data exchanged on shared memory.
 425
 426       b. Input
 427
 428          - h    - handle of WLS interface
 429          - pMsg - pointer to WLS memory
 430
 431       c. Returns 0 if operation is sucessful
 432
 433 6. **WLS_Put**
 434
 435    *int WLS_Put(void\* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short
 436    Flags)*
 437
 438       a. Description
 439
 440          - Puts memory block (or group of blocks) allocated from WLS memory into the interface to transfer to remote peer
 441
 442       b. Input
 443
 444          - h    - handle of WLS interface
 445          - pMsg - pointer to memory block (physical address) with data to be transfered to remote peer
 446          - MsgSize - size of memory block to send (should be less than 2 MB)
 447          - MsgTypeID - application specific identifier of message type
 448          - Flags - Scatter/Gather flag if memory block has multiple chunks
 449
 450       c. Returns 0 if operation is successful
 451
 452 7. **WLS_Check**
 453
 454    *int WLS_Check(void\* h)*
 455
 456       a. Description
 457
 458          - Checks if there are memory blocks with data from remote peer
 459
 460       b. Input - handle of WLS interface
 461       c. Returns number of blocks available for "get" operation
 462
 463 8. **WLS_Wait**
 464
 465    *int WLS_Wait(void\* h)*
 466
 467       a. Description
 468
 469          - Waits for new memory block from remote peer
 470          - Blocking call
 471
 472       b. Input - the handle of WLS interface
 473       c. Returns number of blocks available for "get" operation
 474
 475 9. **WLS_Get**
 476
 477    *unsigned long long WLS_Get(void\* h, unsigned int \*MsgSize, unsigned short \*MsgTypeID, unsigned short \*Flags)*
 478
 479       a. Description
 480
 481          - Gets memory block from interface received from remote peer.
 482          - Non-blocking operation
 483
 484       b. Input
 485
 486          - h    - handle of WLS interface
 487          - MsgSize - pointer to set size of memory block
 488          - MsgTypeID - pointer to application specific identifier of message type
 489          - Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
 490
 491       c. Returns
 492
 493          - Pointer to memory block (physical address) with data received from remote peer
 494          - NULL if error or no blocks available
 495
 496 10. **WLS_WGet**
 497
 498     *unsigned long long WLS_WGet(void\* h, unsigned int \*MsgSize, unsigned short \*MsgTypeID, unsigned short \*Flags)*
 499
 500        a. Description
 501
 502           - Gets memory block from interface received from remote peer
 503           - It is a blocking operation and waits for next memory block from remote peer
 504
 505        b. Input
 506
 507           - h    - handle of WLS interface
 508           - MsgSize - pointer to set size of memory block
 509           - MsgTypeID - pointer to application specific identifier of message type
 510           - Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
 511
 512        c. Returns
 513
 514           - Pointer to memory block (physical address) with data received from remote peer
 515           - NULL if error or no blocks available
 516
 517 11. **WLS_WakeUp**
 518
 519     *int WLS_WakeUp(void\* h)*
 520
 521        a. Description
 522
 523           - Performs "wakeup" notification to remote peer to unblock "wait" operations pending
 524
 525        b. Input - handle of WLS interface
 526        c. Returns 0 if operation is successful
 527
 528 12. **WLS_VA2PA**
 529
 530     *unsigned long long WLS_VA2PA(void\* h, void\* pMsg)*
 531
 532        a. Description
 533
 534           - Converts virtual address (VA) to physical address (PA)
 535
 536        b. Input
 537
 538           - h    - handle of WLS interface
 539           - pMsg - virtual address of WLS memory block
 540
 541        c. Returns
 542
 543           - Physical address of WLS memory block
 544           - NULL, if error
 545
 546 13. **WLS_PA2VA**
 547
 548     *void\* WLS_PA2VA(void\* h, unsigned long long pMsg)*
 549
 550        a. Description
 551
 552           - Converts physical address (PA) to virtual address (VA)
 553
 554        b. Input
 555
 556           - h    - handle of WLS interface
 557           - pMsg - physical address of WLS memory block
 558
 559        c. Returns
 560
 561           - Virtual address of WLS memory block
 562           - NULL, if error
 563
 564 14. **WLS_EnqueueBlock**
 565
 566     *int WLS_EnqueueBlock(void\* h, unsigned long long pMsg)*
 567
 568        a. Description
 569
 570           - Used by the Master to provide memory blocks to slave for next slave-to-master data transfer
 571
 572        b. Input
 573
 574           - h    - handle of WLS interface
 575           - pMsg - physical address of WLS memory block
 576
 577        c. Returns 0 if opertaion is successful
 578
 579 15. **WLS_DequeueBlock**
 580
 581     *unsigned long long WLS_DequeueBlock(void\* h)*
 582
 583       a. Description
 584
 585          - Used by the Master and Slave to get block from master-to-slave queue of available memory blocks
 586
 587       b. Input - handle of WLS interface
 588       c. Returns
 589
 590          - Physical address of WLS memory block
 591          - NULL, if error
 592
 593 16. **WLS_NumBlocks**
 594
 595     *int WLS_NumBlocks(void\* h)*
 596
 597        a. Description
 598
 599           - Returns number of current available block provided by the Master for new transfer of data from slave
 600
 601        b. Input - handle of WLS interface
 602        c. Returns number of available blocks in slave to master queue
 603
 604 Scheduler Framework with plug-in support
 605 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 606
 607 5G NR SCH module is encapsulated within 5G NR MAC of ODU-High. Any communication to/from SCH will happen only through MAC.
 608 The scheduler framework in ODU-High provides support to plug-in multiple scheduling algorithms easily.
 609
 610 Design
 611 +++++++
 612
 613 .. figure:: 5G_NR_SCH_Design.PNG
 614    :width: 600
 615    :alt: 5G NR Scheduler Framework Design
 616
 617    Figure 20: 5G NR Scheduler Framework Design
 618
 619 - The code for scheduler has been divided into 2 parts i.e. the common APIs and scheduler-specific APIs.
 620 - Any code (structure/API) which is specific to a scheduling algorithm must be within scheduler-specific files such as sch_rr.c and sch_rr.h for round-roubin scheduler.
 621 - Function pointers are used to identify and call APIs belonging to the scheduling algorithm in use at any given point in time.
 622 - All supported scheduling algorithm are listed in SchType enum in sch.h file.
 623 - All function pointers are declared in SchAllApis structure in sch.h
 624 - For each scheduling algorithm, function pointers must be initialised to scheduler-specific APIs during scheduler initialisation.
 625
 626 Call Flow
 627 +++++++++
 628
 629 - In any call flow, a common API calls the scheduler-specific API using function pointer and its output is returned back to the common API, which will be further processed and communicated to MAC.
 630
 631 .. figure:: Multi_Scheduling_Algorithm_Call_Flow.PNG
 632    :width: 600
 633    :alt: Call flow example of Multi-Scheduling Algorithm framework
 634
 635    Figure 21: Example of a call flow in multi-scheduling algorithm framework
 636
 637 Additional Utility Functions
 638 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 639
 640 1. ODU_START_TASK(startTime, taskId)
 641
 642       a. Gives current time through input parameter
 643       b. Input
 644
 645          - startTime - stores current time to be returned
 646          - taskId - task id of calling entity
 647
 648 2. ODU_STOP_TASK(startTime, taskId)
 649
 650       a. Calculates difference of start time and current time.
 651       b. Input
 652
 653          - startTime - start time of this task
 654          - taskId - taskId of calling entity
 655
 656 3. ODU_SET_PROC_ID(procId)
 657
 658       a. Processors are identified by processor identifiers (ProcId) that are globally unique.
 659          It sets the procId for the local processor. In O-DU High, procId is 0 (DU_PROC)
 660       b. Inputs
 661
 662          - procId - process id to be set
 663
 664 4. ODU_GET_PROCID()
 665
 666       a. Finds and returns the local processor id on which the calling task is running
 667       b. Inputs
 668
 669          - void
 670
 671 5. ODU_CAT_MSG(mbuf1, mbuf2, order)
 672
 673       a. Concatenates the given two message.
 674       b. Inputs
 675
 676          - mbuf1 - pointer to message buffer 1
 677          - mbuf2 - pointer to message buffer 2
 678          - order - order in which the messages are concatenated
 679
 680 6. ODU_GET_MSG_LEN(mBuf, lngPtr)
 681
 682       a. Determines length of the data contents of a message
 683       b. Inputs
 684
 685          - mBuf - pointer to the message buffer
 686          - lngPtr - pointer to store length value
 687
 688 7. ODU_EXIT_TASK()
 689
 690       a. Gracefully exits the process
 691       b. Inputs
 692
 693          - void
 694
 695 8. ODU_PRINT_MSG(mBuf, src, dst)
 696
 697       a. Prints information about message buffer.
 698       b. Inputs
 699
 700          - mBuf - pointer to the message buffer
 701          - src  - source Id
 702          - dest - destination Id
 703
 704 9. ODU_REM_PRE_MSG(dataPtr, mBuf)
 705
 706       a. Removes one byte of data from the beginning of a message
 707       b. Inputs
 708
 709          - dataPtr - pointer to the location where one byte of data is placed
 710          - mBuf - pointer to the message buffer
 711
 712 10. ODU_REM_PRE_MSG_MULT(dst, cnt, mBuf)
 713
 714       a. Removes the specified number of bytes of data from the beginning of a message
 715       b. Inputs
 716
 717          - dst - pointer to the location where the data bytes are placed.
 718          - cnt - number of bytes to be removed from the message.
 719          - mBuf- pointer to the message.
 720
 721 11. ODU_REG_TMR_MT(ent, inst, period, func)
 722
 723       a. Registers timer function of an entity with system services
 724       b. Inputs
 725
 726          - ent - entity ID of task registering the timer.
 727          - inst - instance of task registering the timer.
 728          - period - period in system ticks between system service sccessive scheduling
 729            of the timer function in the entity
 730          - func - timer function.
 731
 732 12. ODU_SEGMENT_MSG(mBuf1, idx, mBuf2)
 733
 734       a. Segments a message into two messages at the specified index.
 735       b. Inputs
 736
 737          - mBuf1 - Message 1, original message to be segmented
 738          - idx - index in message 1 from which message 2 is created.
 739          - mBuf2 - pointer to message buffer 2 (new message).
 740
 741 13. ODU_ADD_PRE_MSG_MULT(src, cnt, dst)
 742
 743        a. Copies consecutive bytes of data to the beginning of a message
 744        b. Inputs
 745
 746           - src - source buffer
 747           - cnt - number of bytes
 748           - dst - destination message
 749
 750 14. ODU_ADD_PRE_MSG_MULT_IN_ORDER(src, cnt, dst)
 751
 752        a. Copies consecutive bytes of data to the beginning of a message and keeps the bytes order preserved
 753        b. Inputs
 754
 755           - src - source buffer
 756           - cnt - number of bytes
 757           - dst - destination message
 758
 759 15. ODU_ADD_POST_MSG_MULT(src, cnt, dst)
 760
 761        a. Copies consecutive bytes of data to the end of a message
 762        b. Inputs
 763
 764           - src - source buffer
 765           - cnt - number of bytes
 766           - dst - destination message
 767
 768 16. ODU_COPY_MSG_TO_FIX_BUF(src, srcIdx, cnt, dst, ccnt)
 769
 770        a. Copies data from a message buffer into a fixed buffer
 771        b. Inputs
 772
 773           - src - source message
 774           - srcIdx - start index of source buffer to be copied
 775           - cnt - number of bytes to be copied
 776           - dst - destination buffer
 777           - ccnt - number of bytes copied
 778
 779 17. ODU_COPY_FIX_BUF_TO_MSG(src, dst, dstIdx, cnt, ccnt)
 780
 781        a. Copies data from a fixed buffer to a message buffer
 782        b. Inputs
 783
 784           - src - source buffer
 785           - dst - destination message
 786           - dstIdx - index in destination message to starting copying bytes from
 787           - cnt - number of bytes to be copied
 788           - ccnt - number of bytes copied
 789
 790 O1 Module
 791 ----------
 792
 793 Coding Style
 794 ^^^^^^^^^^^^
 795
 796 O1 uses GNU C++ language.
 797
 798 ODU - O1 Communication
 799 ^^^^^^^^^^^^^^^^^^^^^^
 800
 801 O1 module runs as a thread in O-DU High.
 802
 803 Alarm communication between the threads happen on a Unix socket.
 804
 805 O-DU High sends alarm messages in the following structure using Alarm Interface APIs.
 806
 807
 808 Alarm Structure
 809    |   typedef struct
 810    |   {
 811    |        MsgHeader msgHeader;                           /\* Alarm action raise/clear \*/
 812    |        EventType eventType;                           /\* Alarm event type \*/
 813    |        char objectClassObjectInstance[OBJ_INST_SIZE]; /\* Name of object that raise/clear an alarm \*/
 814    |        char alarmId[ALRM_ID_SIZE];                    /\* Alarm Id \*/
 815    |        char alarmRaiseTime[DATE_TIME_SIZE];           /\* Time when alarm is raised \*/
 816    |        char alarmChangeTime[DATE_TIME_SIZE];          /\* Time when alarm is updated \*/
 817    |        char alarmClearTime[DATE_TIME_SIZE];           /\* Time when alarm is cleared \*/
 818    |        char probableCause[TEXT_SIZE];                 /\* Probable cause of alarm \*/
 819    |        SeverityLevel perceivedSeverity;               /\* Severity level of alarm \*/
 820    |        char rootCauseIndicator[TEXT_SIZE];            /\* Root cause of alarm \*/
 821    |        char additionalText[TEXT_SIZE];                /\* Additional text describing alarm \*/
 822    |        char additionalInfo[TEXT_SIZE];                /\* Any additional information \*/
 823    |        char specificProblem[TEXT_SIZE];               /\* Any specific problem related to alarm \*/
 824    |   }AlarmRecord;
 825
 826
 827 O1 - Netconf Communication
 828 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 829
 830 O1 communicates with the Netconf server using sysrepo and libyang APIs