data-model/yang/published/o-ran/ru-fh/o-ran-hardware@2022-12-05.yang

   1 module o-ran-hardware {
   2   yang-version 1.1;
   3   namespace "urn:o-ran:hardware:1.0";
   4   prefix "o-ran-hw";
   5
   6   import ietf-hardware {
   7     prefix hw;
   8   }
   9   import iana-hardware {
  10     prefix ianahw;
  11   }
  12   import ietf-yang-types {
  13     prefix yang;
  14   }
  15   import o-ran-wg4-features {
  16     prefix or-feat;
  17   }
  18
  19   organization "O-RAN Alliance";
  20
  21   contact
  22     "www.o-ran.org";
  23
  24   description
  25     "This module defines the YANG definitions for managing the O-RAN hardware.
  26
  27      Copyright 2021 the O-RAN Alliance.
  28
  29      THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS'
  30      AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  31      IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  32      ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  33      LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  34      CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  35      SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  36      INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  37      CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  38      ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  39      POSSIBILITY OF SUCH DAMAGE.
  40
  41      Redistribution and use in source and binary forms, with or without
  42      modification, are permitted provided that the following conditions are met:
  43
  44      * Redistributions of source code must retain the above copyright notice,
  45      this list of conditions and the above disclaimer.
  46      * Redistributions in binary form must reproduce the above copyright notice,
  47      this list of conditions and the above disclaimer in the documentation
  48      and/or other materials provided with the distribution.
  49      * Neither the Members of the O-RAN Alliance nor the names of its
  50      contributors may be used to endorse or promote products derived from
  51      this software without specific prior written permission.";
  52
  53   revision "2022-12-05" {
  54    description
  55      "version 10.1.0
  56
  57      1) Clarifications for Network Energy Saving";
  58
  59    reference "ORAN-WG4.M.0-v10.00";
  60   }
  61
  62   revision "2022-08-15" {
  63     description
  64       "version 10.0.0
  65
  66       1) introduction of O-RU connector functionality.
  67       2) fixing constraints";
  68
  69     reference "ORAN-WG4.M.0-v10.00";
  70   }
  71
  72   revision "2021-12-01" {
  73     description
  74       "version 5.2.0
  75
  76       1) typographical corrections in descriptions.";
  77
  78     reference "ORAN-WG4.M.0-v05.00";
  79   }
  80
  81   revision "2021-03-22" {
  82     description
  83       "version 5.1.0
  84
  85       1) typographical corrections in descriptions.";
  86
  87     reference "ORAN-WG4.M.0-v05.00";
  88   }
  89
  90   revision "2020-12-10" {
  91     description
  92       "version 5.0.0
  93
  94       1) added date-last-service leaf used in pnfRegistration";
  95
  96     reference "ORAN-WG4.M.0-v05.00";
  97   }
  98
  99   revision "2020-04-17" {
 100     description
 101       "version 3.0.0
 102
 103       1) added new leaf to indicate whether O-RU supports dying gasp
 104       2) added new identities for PA and FPGA";
 105
 106     reference "ORAN-WG4.M.0-v03.00";
 107   }
 108
 109   revision "2019-07-03" {
 110     description
 111       "version 1.1.0
 112
 113       1) added new identities to accommodate cross working group use of
 114       o-ran-hardware and assoicated set of augmentations that are backwards
 115       compatible to version 1.0.0";
 116
 117     reference "ORAN-WG4.M.0-v01.00";
 118   }
 119
 120   revision "2019-02-04" {
 121     description
 122       "version 1.0.0
 123
 124       1) imported model from xRAN
 125       2) changed namespace and reference from xran to o-ran";
 126
 127     reference "ORAN-WG4.M.0-v01.00";
 128   }
 129
 130   feature ENERGYSAVING {
 131     description
 132       "Indicates that the Radio Unit supports energy saving state.";
 133   }
 134
 135   // identity statements
 136   identity O-RAN-RADIO {
 137     base ianahw:module;
 138     description
 139       "Module used as it represents a self-contained sub-system
 140       used in /hw:/hardware/hw:component/hw:class to represent
 141       an O-RAN RU";
 142   }
 143
 144   identity O-RAN-HW-COMPONENT {
 145     base ianahw:module;
 146     description
 147       "Module used as it represents a self-contained sub-system
 148       used in /hw:/hardware/hw:component/hw:class to represent
 149       any O-RAN hardware component";
 150   }
 151
 152   identity O-DU-COMPONENT {
 153     base O-RAN-HW-COMPONENT;
 154     description
 155       "Used in /hw:/hardware/hw:component/hw:class to represent
 156       any O-RAN defined O-DU hardware component";
 157   }
 158
 159   identity O-RU-COMPONENT {
 160     base O-RAN-HW-COMPONENT;
 161     description
 162       "Used in /hw:/hardware/hw:component/hw:class to represent
 163       any O-RAN defined O-RU hardware component, including a stand-alone
 164       O-RU or an O-RU component integrated into a multi-module system.";
 165   }
 166
 167   identity O-RU-POWER-AMPLIFIER {
 168     base O-RU-COMPONENT;
 169     description
 170       "Used in /hw:/hardware/hw:component/hw:class to represent
 171       an O-RU's power amplifier, and may be used for reporting
 172       measurements on a per class basis";
 173   }
 174
 175   identity O-RU-FPGA {
 176     base O-RU-COMPONENT;
 177     description
 178       "Used in /hw:/hardware/hw:component/hw:class to represent
 179       an FPGA in an O-RU, and may be used for reporting
 180       measurements on a per class basis";
 181   }
 182
 183   identity O-RU-CONNECTOR {
 184     base ianahw:hardware-class;
 185     description
 186       "This identity is applicable if the hardware class is some sort
 187       of O-RU connector.";
 188   }
 189
 190   identity O-RU-ANTENNA-CONNECTOR {
 191     base O-RU-CONNECTOR;
 192     description
 193       "This identity is applicable if the hardware class is some sort
 194       of connector capable of interfacing between an O-RU and some
 195       antenna function.";
 196   }
 197
 198   identity O-RU-FEEDER {
 199     base O-RU-ANTENNA-CONNECTOR;
 200     description
 201       "This identity is applicable if the hardware class is an
 202       antenna feeder.";
 203   }
 204
 205   identity O-RU-BF-CAL {
 206     base O-RU-ANTENNA-CONNECTOR;
 207     description
 208       "This identity is applicable if the hardware class is for
 209       beamforming calibration.";
 210   }
 211
 212   // typedef statements
 213   typedef energysaving-state {
 214     type enumeration {
 215       enum UNKNOWN {
 216         description
 217           "The O-RU is unable to report its energy saving state.";
 218       }
 219       enum SLEEPING {
 220         description
 221           "The O-RU is in energy saving state. In this mode M-Plane connection is active. Depending
 222           on the O-RU's design - other planes, functions and hardware components which are not needed
 223           by the O-RU in energy saving state can be disabled or switched off by the O-RU autonomously.";
 224       }
 225       enum AWAKE {
 226         description
 227           "The O-RU is not in an energy saving state.";
 228       }
 229     }
 230     description
 231       "New typedef since ietf-hardware only covers power-state
 232       for redundancy purposes, not to indicate energy saving operations.
 233       For details please see O-RAN WG4 M-Plane specification, clause 9.1.3 'Modify state'";
 234   }
 235
 236   typedef availability-type {
 237     type enumeration {
 238       enum UNKNOWN {
 239         description "The Radio Unit is unable to report its availability state.";
 240       }
 241       enum NORMAL {
 242         description
 243           "The equipment is functioning correctly.";
 244       }
 245       enum DEGRADED {
 246         description
 247           "The equipment may be reporting a major alarm or may be reporting a critical
 248            alarm that is only impacting one or more subcomponent, but where the
 249            equipment's implementation permit it to continue operation (server traffic)
 250            in a degraded state.
 251
 252            Used for example, when the equipment has M identical sub-components and
 253            when a critical alarm is impacting only N subcomponents, where N<M.";
 254       }
 255       enum FAULTY {
 256         description
 257           "The (sub-)components impacted by the critical alarm(s) impact the
 258           ability of the equipment to continue operation (serve traffic).";
 259       }
 260     }
 261     description
 262       "Equipment's availability-state is derived by matching active faults
 263        and their impact to module's operation and enables an equipment to indicate
 264        that even though it may have one or more critical alarms, it can continue
 265        to serve traffic.";
 266   }
 267
 268   // common WG4 and cross-WG augmentations using O-RAN-RADIO identity
 269
 270   augment "/hw:hardware/hw:component" {
 271     when "(derived-from-or-self(hw:class, 'o-ran-hw:O-RAN-RADIO')) or
 272     (derived-from-or-self(hw:class, 'o-ran-hw:O-RAN-HW-COMPONENT'))";
 273     description "New O-RAN parameters for o-ran hardware";
 274
 275     container label-content {
 276       config false;
 277       description
 278         "Which set of attributes are printed on the Radio Unit's label";
 279       leaf model-name {
 280         type boolean;
 281         description
 282           "indicates whether model-name is included on the equipment's label";
 283       }
 284       leaf serial-number {
 285         type boolean;
 286         description
 287           "indicates whether serial number is included on the equipment's label";
 288       }
 289     }
 290     leaf product-code {
 291       type string;
 292       config false;
 293       mandatory true;
 294       description
 295         "O-RAN term that is distinct from model-name in ietf-hardware.";
 296     }
 297     leaf energy-saving-enabled {
 298       if-feature "ENERGYSAVING";
 299       type boolean;
 300       default false;
 301       description
 302         "This parameter enables the O-RU to enter into energy saving state if there is no need to keep processing
 303          paths working.
 304          TRUE is used to permit the O-RU to enter energy saving state. If there is still need keep any
 305          processing path, functions or HW components working.
 306          The O-RU shall keep necessary processing paths working if there is any [tr]x-array-carrier with
 307          'state' != DISABLED.
 308          There may be also additional implementation-specific conditions which may require keeping processing paths,
 309          functions or HW components working.
 310          FALSE is used to prohibit the O-RU to enter or to stay in energy saving state. This value is also used
 311          to awake the O-RU from sleeping when the O-RU is already in energy saving state. Setting this value has
 312          no effect on [tr]x-array-carrier::active.
 313          When the O-RU enters energy saving state, the O-RU shall reduce its power consumption to the lowest level
 314          whilst M-plane remains available. Ongoing Netconf session(s) shall not be affected when the O-RU enters
 315          energy saving state.
 316          The O-RU uses RO node power-state to inform if the O-RU is in energy saving state.
 317          NETCONF client should set energy-saving-enabled to FALSE to ensure O-RU is ready to immediately activate a carrier.";
 318     }
 319     leaf dying-gasp-support {
 320       type boolean;
 321       default false;
 322       config false;
 323       description
 324         "indicates whether the O-RU supports the dying gasp
 325         capability";
 326     }
 327     leaf last-service-date {
 328       if-feature "or-feat:NON-PERSISTENT-MPLANE";
 329       type yang:date-and-time;
 330       description
 331         "Date of last service or repair of hardware component. How this gets
 332         populated is a vendor specific issue.";
 333       reference
 334         "3GPP 32.692";
 335     }
 336   }
 337
 338   augment "/hw:hardware/hw:component" {
 339     when "(derived-from-or-self(hw:class, 'o-ran-hw:O-RAN-RADIO')) or
 340     (derived-from-or-self(hw:class, 'ianahw:port')) or
 341     (derived-from-or-self(hw:class, 'o-ran-hw:O-RAN-HW-COMPONENT'))";
 342     description "New O-RAN parameters for o-ran naming";
 343     leaf o-ran-name {
 344       type leafref {
 345         path "/hw:hardware/hw:component/hw:name";
 346       }
 347       must "re-match(current(),'[a-zA-Z0-9][a-zA-Z0-9\\.\\-_]{0,253}[a-zA-Z0-9]')" {
 348         error-message "Name must match pattern and length.";
 349       }
 350       mandatory true;
 351       description
 352         "O-RAN name needed to bind and match with the name of hw element,
 353         to be compliant with O-RAN naming convention.";
 354     }
 355   }
 356
 357   augment "/hw:hardware/hw:component/hw:state"  {
 358     when "(derived-from-or-self(../hw:class, 'o-ran-hw:O-RAN-RADIO')) or
 359     (derived-from-or-self(../hw:class, 'o-ran-hw:O-RAN-HW-COMPONENT'))";
 360     description
 361       "new O-RAN defined state";
 362     leaf power-state {
 363       if-feature "ENERGYSAVING";
 364       type energysaving-state;
 365       config false;
 366       description
 367         "The current power saving state for this component.
 368         Note - hw:/hardware/component/state/standby-state defined in RFC 4268 is
 369         used for redundancy purposes but not for power saving operations.";
 370     }
 371     leaf availability-state {
 372       type availability-type;
 373       config false;
 374       description
 375         "Equipment's availability-state is derived by matching active faults
 376          and their impact to module's operation and enables an equipment to indicate
 377          that even though it may have one or more critical alarms, it can continue
 378          to serve traffic.";
 379     }
 380   }
 381
 382   augment "/hw:hardware/hw:component" {
 383     when "(derived-from-or-self(hw:class, 'o-ran-hw:O-RU-ANTENNA-CONNECTOR'))";
 384     description "New O-RAN parameters for O-RAN Antenna connectors";
 385
 386     leaf connector-label {
 387       type string;
 388       config false;
 389       description
 390         "the label used to identify the connector on an O-RU ";
 391     }
 392   }
 393
 394
 395 // augmentations to Notifications
 396
 397   augment "/hw:hardware-state-oper-enabled"  {
 398     description "new availability state";
 399     leaf availability-state {
 400     if-feature hw:hardware-state;
 401       type leafref {
 402         path "/hw:hardware/hw:component/hw:state/o-ran-hw:availability-state";
 403       }
 404       description
 405         "The availability-state of the O-RU.";
 406     }
 407   }
 408
 409   augment "/hw:hardware-state-oper-disabled"  {
 410     description "new availability state";
 411     leaf availability-state {
 412      if-feature hw:hardware-state;
 413       type leafref {
 414         path "/hw:hardware/hw:component/hw:state/o-ran-hw:availability-state";
 415       }
 416       description
 417         "The availability-state of the O-RU.";
 418     }
 419   }
 420 }