ntsimulator/deploy/o-ran-ru-fh/yang/o-ran-antenna-calibration@2020-12-10.yang

   1 module o-ran-antenna-calibration {
   2   yang-version 1.1;
   3   namespace "urn:o-ran:antcal:1.0";
   4   prefix "o-ran-antcal";
   5
   6   organization "O-RAN Alliance";
   7
   8   contact
   9     "www.o-ran.org";
  10
  11   description
  12     "This module defines the configuration required for supporting the optional
  13     antenna calibration functionality.
  14
  15      Copyright 2019 the O-RAN Alliance.
  16
  17      THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS'
  18      AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19      IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20      ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  21      LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22      CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23      SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24      INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25      CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26      ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27      POSSIBILITY OF SUCH DAMAGE.
  28
  29      Redistribution and use in source and binary forms, with or without
  30      modification, are permitted provided that the following conditions are met:
  31
  32      * Redistributions of source code must retain the above copyright notice,
  33      this list of conditions and the above disclaimer.
  34      * Redistributions in binary form must reproduce the above copyright notice,
  35      this list of conditions and the above disclaimer in the documentation
  36      and/or other materials provided with the distribution.
  37      * Neither the Members of the O-RAN Alliance nor the names of its
  38      contributors may be used to endorse or promote products derived from
  39      this software without specific prior written permission.";
  40
  41   revision 2020-12-10 {
  42     description
  43       "version 5.0.0
  44
  45        1) O-RU-COORDINATED-ANT-CAL is added as optional feature
  46        to provide the antenna calibration without RPC
  47        on the condition that coordinated-calibration-support is true
  48        and coordinated-calibration-allowed is true.";
  49
  50     reference "ORAN-WG4.MP-v05.00";
  51   }
  52
  53   revision 2019-07-03 {
  54     description
  55       "version 1.0.0
  56
  57        1) Newly introduced model for supporting optional
  58        antenna calibration functionality";
  59
  60     reference "ORAN-WG4.MP-v02.00";
  61   }
  62
  63   feature O-RU-COORDINATED-ANT-CAL {
  64     description
  65       "Indicates that the O-RU needs user traffic to be coordinated from O-DU for antenna calibration.";
  66   }
  67
  68   grouping antenna-calibration-capabilities {
  69     description "container for collection of leafs for antenna calibration";
  70
  71     leaf self-calibration-support {
  72       type boolean;
  73       default false;
  74       description
  75         "Indicates whether O-RU supports self-calibration or not.
  76
  77         When true, indicates O-RU can initiate calibration without receiving an
  78         rpc and/or impacting simultaneous CU-plane operation";
  79     }
  80     leaf coordinated-calibration-support {
  81       if-feature O-RU-COORDINATED-ANT-CAL;
  82       type boolean;
  83       default false;
  84       description
  85         "True means the O-RU is able to determine priori the time-frequency
  86          resources required for self-calibration and indicate those to the O-DU
  87          in the antenna-calibration-coordination notification.";
  88     }
  89     leaf number-of-calibration-symbols-per-block-dl {
  90       type uint8 {
  91         range "1..max";
  92       }
  93       units symbols;
  94       mandatory true;
  95       description
  96         "Indicates how many consecutive symbols are required for DL antenna
  97         calibration operation";
  98     }
  99     leaf number-of-calibration-symbols-per-block-ul {
 100       type uint8 {
 101         range "1..max";
 102       }
 103       units symbols;
 104       mandatory true;
 105       description
 106         "Indicates how many consecutive symbols are required for UL antenna
 107         calibration operation";
 108     }
 109     leaf interval-between-calibration-blocks {
 110       type uint8;
 111       units symbols;
 112       description
 113         "if time interval is required between consecutive antenna calibration
 114         operation, defines this time value as unit of symbols.
 115
 116         A common value is used here for the intervals
 117         between DL-DL blocks, UL-UL blocks, DL-UL blocks and UL-DL blocks,
 118         which is the largest minimum interval required between any two adjacent
 119         calibration blocks.";
 120     }
 121     leaf number-of-calibration-blocks-per-step-dl {
 122       type uint8 {
 123         range "1..max";
 124       }
 125       mandatory true;
 126       description
 127         "Indicates how many blocks are required for one step of DL antenna
 128         calibration operation";
 129     }
 130     leaf number-of-calibration-blocks-per-step-ul {
 131       type uint8 {
 132         range "1..max";
 133       }
 134       mandatory true;
 135       description
 136         "Indicates how many blocks are required for one step of UL antenna
 137         calibration operation";
 138     }
 139     leaf interval-between-calibration-steps {
 140       type uint8;
 141       units radio-frames;
 142       description
 143         "If time interval is required between consecutive step of antenna
 144         calibration operation, defines this time value as unit of radio frames";
 145     }
 146     leaf number-of-calibration-steps {
 147       type uint8 {
 148         range "1..max";
 149       }
 150       mandatory true;
 151       description
 152         "Indicates how many steps are required for whole DL/UL antenna
 153         calibration operation";
 154     }
 155     leaf calibration-period {
 156        if-feature O-RU-COORDINATED-ANT-CAL;
 157        type uint16;
 158        units minutes;
 159        description "peiodical interval between antenna calibrations in the case of support of feature O-RU-COORDINATED-ANT-CAL";
 160     }
 161   }
 162
 163   grouping antenna-calibration {
 164     container antenna-calibration-capabilities {
 165       config false;
 166       description
 167         "Describes the antenna calibration capabilities";
 168       uses antenna-calibration-capabilities;
 169     }
 170     container self-calibration-policy {
 171       leaf self-calibration-allowed {
 172         type boolean;
 173         default false;
 174         description
 175           "whether the self-calibration is allowed by operator.
 176           Note, self-calibration-alllowed and coordinated-calibration-allowed cannot both be set to true";
 177       }
 178       leaf coordinated-calibration-allowed {
 179         if-feature O-RU-COORDINATED-ANT-CAL;
 180         type boolean;
 181         must "../self-calibration-allowed = 'false'";
 182         default false;
 183         description
 184           "whether the coordinated-calibration is allowed by operator.
 185
 186           True means that O-DU may beneficially use the indicated time-frequency resources
 187           to adapt its operation during the antenna calibration operation,
 188           e.g., consider the time-frequency resources as reserved for calibration.
 189           Both calibrations (self-calibration-alllowed and coordinated-calibration-support) disallowed
 190           or one of them allowed only";
 191       }
 192       description
 193         "Describes the self calibration policy of the operator";
 194     }
 195     description
 196       "Describe the grouping set of antenna calibration";
 197   }
 198
 199   container antenna-calibration {
 200     uses antenna-calibration;
 201     description
 202       "Describes the antenna calibration top node";
 203   }
 204
 205   rpc start-antenna-calibration {
 206     description
 207       "The antenna calibration operation can start when NETCONF client sends a
 208       calibration start command with resource allocation parameters.
 209       These parameters indicate how the O-RU can perform the antenna
 210       calibration operation; at which Symbol, Slot, and Frame.
 211       This scheduling information can be generated by O-RU itself.
 212       However, in a dynamic TDD environment, the DL and UL configuration
 213       is only determined and known by O-DU. Consequently, only O-DU (NETCONF
 214       client ) can determine and configure the scheduling and resource
 215       allocation permitted for use by the antenna calibration operation";
 216     input  {
 217        uses antenna-calibration-data;
 218     }
 219     output  {
 220       leaf status {
 221         type enumeration {
 222           enum ACCEPTED {
 223             description
 224               "Status information to indicate that O-RU accepted RPC
 225               antenna calibration start request";
 226           }
 227           enum REJECTED {
 228             description
 229               "Status information to indicate that O-RU rejected RPC antenna
 230               calibration start request";
 231           }
 232         }
 233         mandatory true;
 234         description
 235           "Status of whether antenna calibration trigger by RPC is accepted
 236           by the O-RU";
 237       }
 238       leaf error-message {
 239         when "../status='REJECTED'";
 240           type string;
 241           description
 242             "Detailed error Message when the status is rejected, e.g.,
 243              because O-RU can not start antenna calibration
 244              such as already running antenna calibration,
 245              resource mask mismatch with O-RU antenna calibration capability,
 246                                overlapped DL and UL masks, insufficient memory, O-RU internal reason";
 247         }
 248       }
 249   }
 250
 251   grouping antenna-calibration-data {
 252      description "information set for the operation of antenna calibration";
 253
 254      leaf symbol-bitmask-dl {
 255         type string {
 256           length "14";
 257           pattern "[01]*";
 258         }
 259         mandatory true;
 260         description
 261           "Bitmask indicating DL calibration symbol within a calibration slot.
 262            First character in the string indicate first symbol,
 263            next character in the string indicate second symbol and so on.
 264            Value 1 indicates that the symbol may be used for calibration
 265            and 0 means the symbol shall not be used for calibration.";
 266       }
 267       leaf symbol-bitmask-ul {
 268         type string {
 269           length "14";
 270           pattern "[01]*";
 271         }
 272         mandatory true;
 273         description
 274           "Bitmask indicating UL calibration symbol within a calibration slot.
 275            First character in the string indicate first symbol,
 276            next character in the string indicate second symbol and so on.
 277            Value 1 indicates that the symbol may be used for calibration
 278            and 0 means the symbol shall not be used for calibration.";
 279       }
 280       leaf slot-bitmask-dl {
 281         type string {
 282           length "10..255";
 283           pattern "[01]*";
 284         }
 285         mandatory true;
 286         description
 287           "Bitmask indicating DL calibration slot within a calibration frame.
 288            First character in the string indicate first slot,
 289            next character in the string indicate second slot and so on.
 290            Value 1 indicates that the slot may be used for calibration
 291            and 0 means the slot shall not be used for calibration.";
 292         }
 293         leaf slot-bitmask-ul {
 294           type string {
 295             length "10..255";
 296             pattern "[01]*";
 297           }
 298           mandatory true;
 299           description
 300             "Bitmask indicating UL calibration slot within a calibration frame.
 301              First character in the string indicate first slot,
 302              next character in the string indicate second slot and so on.
 303              Value 1 indicates that the slot may be used for calibration
 304              and 0 means the slot shall not be used for calibration.";
 305         }
 306         leaf frame-bitmask-dl {
 307           type string {
 308             length "1..255";
 309             pattern "[01]*";
 310           }
 311           mandatory true;
 312           description
 313             "Bitmask indicating DL calibration frame within a calibration step.
 314              First character in the string indicate first radio frame equal to
 315              the start-SFN, next character in the string indicate the next frame
 316              and so on.
 317
 318              Value 1 indicates that the frame may be used for calibration
 319              and 0 means the frame shall not be used for calibration.";
 320         }
 321         leaf frame-bitmask-ul {
 322           type string {
 323             length "1..255";
 324             pattern "[01]*";
 325           }
 326           mandatory true;
 327           description
 328             "Bitmask indicating UL calibration frame within a calibration step.
 329              First character in the string indicate first radio frame equal to
 330              the start-SFN, next character in the string indicate the next frame
 331              and so on.
 332
 333              Value 1 indicates that the frame is may be used for calibration
 334              and 0 means the frame shall not be used for calibration.";
 335         }
 336         leaf calibration-step-size {
 337           type uint8;
 338           mandatory true;
 339           description " Number of frames within a calibration step";
 340         }
 341         leaf calibration-step-number {
 342           type uint8;
 343           mandatory true;
 344           description "Number of calibration steps";
 345         }
 346         leaf start-sfn {
 347           type uint16 {
 348             range "0..1023";
 349           }
 350           mandatory true;
 351           description "start SFN number of the first calibration step";
 352         }
 353   }
 354
 355   notification antenna-calibration-required {
 356     list dl-calibration-frequency-chunk {
 357       leaf start-calibration-frequency-dl {
 358         type uint64;
 359         description
 360           "lowest frequency value in Hz of the frequency range is required for
 361            DL antenna calibration operation.";
 362       }
 363       leaf end-calibration-frequency-dl {
 364         type uint64;
 365         description
 366           "highest frequency value in Hz of the frequency range is required for
 367            DL antenna calibration operation.";
 368       }
 369       description
 370          "min/max frequency of dl spectrum chunk affected by calibration process";
 371     }
 372     list ul-calibration-frequency-chunk {
 373       leaf start-calibration-frequency-ul {
 374         type uint64;
 375         description
 376           "lowest frequency value in Hz of the frequency range is required for
 377            UL antenna calibration operation.";
 378       }
 379       leaf end-calibration-frequency-ul {
 380         type uint64;
 381         description
 382           "highest frequency value in Hz of the frequency range is required for
 383            UL antenna calibration operation.";
 384       }
 385       description
 386         "min/max frequency of ul spectrum chunk affected by calibration process";
 387     }
 388
 389     description
 390       "this notification indicates that the antenna calibration is required in O-RU";
 391   }
 392
 393   notification antenna-calibration-coordinated {
 394     if-feature O-RU-COORDINATED-ANT-CAL;
 395     list dl-calibration-frequency-chunk {
 396       leaf start-calibration-frequency-dl {
 397         type uint64;
 398         description
 399           "lowest frequency value in Hz of the frequency range is required for
 400            DL antenna calibration operation.";
 401       }
 402       leaf end-calibration-frequency-dl {
 403         type uint64;
 404         description
 405           "highest frequency value in Hz of the frequency range is required for
 406            DL antenna calibration operation.";
 407       }
 408       description
 409          "min/max frequency of dl spectrum chunk affected by calibration process";
 410     }
 411     list ul-calibration-frequency-chunk {
 412       leaf start-calibration-frequency-ul {
 413         type uint64;
 414         description
 415           "lowest frequency value in Hz of the frequency range is required for
 416            UL antenna calibration operation.";
 417       }
 418       leaf end-calibration-frequency-ul {
 419         type uint64;
 420         description
 421           "highest frequency value in Hz of the frequency range is required for
 422            UL antenna calibration operation.";
 423       }
 424       description
 425         "min/max frequency of ul spectrum chunk affected by calibration process";
 426     }
 427     uses antenna-calibration-data {
 428       description
 429         "In the case of support of feature O-RU-COORDINATED-ANT-CAL,
 430          time-frequency resource determined by O-RU will be included";
 431     }
 432
 433     description
 434       "this notification indicates that coordinated antenna calibration is provided in O-RU.
 435        It indicate the time-frequency resources will be sent to a subscribed O-DU at least 60 seconds
 436        before the operation of the coordinated antenna calibration procedure.";
 437   }
 438
 439   notification antenna-calibration-result {
 440     leaf status {
 441       type enumeration {
 442         enum SUCCESS {
 443           description "O-RU has succeeded in calibrating its antenna";
 444         }
 445         enum FAILURE {
 446           description
 447             "O-RU attemted to calibrate its antenna, but the procedure failed.";
 448         }
 449       }
 450       mandatory true;
 451       description
 452         "Status of the antenna calibration procedure which has been triggered
 453         by accepting an start-antenna-calibration RPC.";
 454     }
 455     leaf detailed-reason {
 456       when "../status='FAILURE'";
 457       type string;
 458       description
 459         "Detailed reason when the status is FAILURE, e.g.,
 460         O-RU cannot complete the antenna calibration
 461         because of lack of memory, self-calibration failure, etc";
 462     }
 463     description
 464     "This notification indicates the antenna calibration result";
 465   }
 466 }