submodule bbf-vdsl-xtu-sub-carrier-status-body {

    yang-version 1.1;

    belongs-to bbf-vdsl {
        prefix bbf-vdsl;
    }

    include bbf-vdsl-base-body;
    include bbf-vdsl-line-spectrum-profile-body;

    organization
      "Broadband Forum <https://www.broadband-forum.org>
Common YANG Work Area";

    contact
      "Comments or questions about this Broadband Forum YANG module
should be directed to <mailto:help@broadband-forum.org>.

Editor:      Ken Kerpez, ASSIA, Inc.

Editor:      Joey Boyd, Adtran

PS Leader:   Joey Boyd, Adtran

WA Director: Sven Ooghe, Nokia

WA Director: Joey Boyd, Adtran";

    description
      "This submodule contains a collection of YANG definitions for
managing Broadband Forum TR-252i3 clause 9.1 xDSL Transceiver
Unit (xTU) Sub-Carrier Status.

Copyright (c) 2016-2022 Broadband Forum

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The above license is used as a license under copyright only.
Please reference the Forum IPR Policy for patent licensing terms
<https://www.broadband-forum.org/ipr-policy>.

Any moral rights which are necessary to exercise under the above
license grant are also deemed granted under this license.

This version of this YANG module is part of TR-355a4; see
the TR itself for full legal notices.";

    revision "2022-05-23" {
      description
        "Amendment 4.
* Approval Date:    2022-05-23
* Publication Date: 2022-05-23.";
      reference
        "TR-355a4: YANG Modules for FTTdp Management
        	    <https://www.broadband-forum.org/download/
        		   TR-355_Amendment-4.pdf>";

    }

    revision "2020-10-13" {
      description
        "Amendment 3.
* Approval Date:    2020-10-13
* Publication Date: 2020-10-13.";
      reference
        "TR-355a3: YANG Modules for FTTdp Management
        	    <https://www.broadband-forum.org/download/
        		   TR-355_Amendment-3.pdf>";

    }

    revision "2019-10-21" {
      description
        "Amendment 2 Corrigendum 1.
* Approval Date:    2019-10-21
* Publication Date: 2019-10-21.";
      reference
        "TR-355a2c1: YANG Modules for FTTdp Management
        	    <https://www.broadband-forum.org/download/
        		   TR-355_Amendment-2.pdf>";

    }

    revision "2019-06-11" {
      description
        "Amendment 2.
* Approval Date:    2019-06-11
* Publication Date: 2019-06-11.";
      reference
        "TR-355a2: YANG Modules for FTTdp Management
        	  <https://www.broadband-forum.org/technical/download/
        		 TR-355_Amendment-2.pdf>";

    }

    revision "2018-10-01" {
      description
        "Amendment 1.
* Approval Date:    2018-10-01
* Publication Date: 2018-10-01.";
      reference
        "TR-355a1: YANG Modules for FTTdp Management
        	  <https://www.broadband-forum.org/technical/download/
        		 TR-355_Amendment-1.pdf>";

    }

    revision "2017-03-13" {
      description
        "Corrigendum 1 (fixes to the initial revision).
* Approval Date:    see revision date above.
* Publication Date: 2017-04-12.";
      reference
        "TR-355c1: YANG Modules for FTTdp Management
        	  <https://www.broadband-forum.org/technical/download/
        		 TR-355_Corrigendum-1.pdf>";

    }

    revision "2016-07-18" {
      description
        "Initial revision.
* Approval Date:    see revision date above.
* Publication Date: 2016-08-05.";
      reference
        "TR-355: YANG Modules for FTTdp Management
        	<https://www.broadband-forum.org/technical/download/
        		 TR-355.pdf>";

    }


    typedef per-sub-carrier-group-uint8 {
      type binary {
        length "0..512";
      }
      description
        "A binary type where each octet represents data belonging to
a sub-carrier group. The first octet represents sub-carrier
group 0 and the last represents sub-carrier group 511.";
    }

    typedef per-sub-carrier-group-uint16 {
      type binary {
        length "0..1024";
      }
      description
        "A binary type where each pair of octets represents data
belonging to a sub-carrier group. The first two octets
represents sub-carrier group 0 and the last two represents
sub-carrier group 511. In each pair of octets, the most
significant byte is loaded first.";
    }

    typedef per-sub-carrier-group-int16-tuple {
      type binary {
        length "0..2048";
      }
      description
        "A binary type where a tuple of octet pairs represent data
belonging to a sub-carrier group. The first tuple represents
sub-carrier group 0 and the last tuple represents sub-carrier
group 511. In each pair of octets in the tuple, the most
significant byte is loaded first. The order of the tuple is
determined by the node to which this type is associated.";
    }

    typedef per-sub-carrier-group-uint16-tuple {
      type binary {
        length "0..2048";
      }
      description
        "A binary type where a tuple of octet pairs represent data
belonging to a sub-carrier group. The first tuple represents
sub-carrier group 0 and the last tuple represents sub-carrier
group 511. In each pair of octets in the tuple, the most
significant byte is loaded first. The order of the tuple is
determined by the node to which this type is associated.";
    }

    typedef per-sub-carrier-nibble {
      type binary {
        length "4096";
      }
      description
        "A binary type where each nibble represents data belonging to
a sub-carrier. The first nibble represents sub-carrier 0 and
the last represents sub-carrier 8191.";
    }

    typedef per-sub-carrier-uint16 {
      type binary {
        length "16384";
      }
      description
        "A binary type where each pair of octets represents data
belonging to a sub-carrier. The first two octets represent
sub-carrier 0 and the last two represent sub-carrier 8191.
In each pair of octets, the most significant byte is loaded
first.";
    }

    typedef sub-carrier-group-size {
      type uint8 {
        range "1 | 2 | 4 | 8 | 16";
      }
      description
        "This parameter is the number of subcarriers per group. The
valid values are 1, 2, 4, 8 and 16. For ADSL, this parameter is
equal to 1 and, for VDSL2, it is equal to the size of a
subcarrier group used to compute these parameters.";
      reference
        "ITU-T G.993.2 clause 11.4.1";

    }

    grouping xtu-sub-carrier-status {
      description
        "The xDSL Transceiver Unit (xTU) Sub-Carrier Status data nodes
represent current detailed status / measurements relating to a
particular sub-carrier or a sub-carrier group in an xDSL Line
at a particular xTU.";
      container hlin {
        description
          "State data nodes related to sub-carrier Hlin.";
        leaf hlin-scale {
          type uint16 {
            range "1..65535";
          }
          description
            "This parameter is the scale factor to be applied to the
Hlin(f) values. It is represented as an unsigned integer
in the range from 1 to 65535 = 2^16 - 1. This parameter
is only available after a loop diagnostic procedure.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.26.1 (HLINSCds) and 7.5.1.26.7
            (HLINSCus)";

        }

        leaf hlin-sub-carrier-group-size {
          type sub-carrier-group-size;
          description
            "This parameter is the number of subcarriers per group
used to report HLINps.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.26.2 (HLINGds) and 7.5.1.26.8
            (HLINGus)";

        }

        leaf hlinps {
          type per-sub-carrier-group-int16-tuple;
          description
            "This parameter is an array of complex values in linear
scale for Hlin(f). Each array entry represents the
Hlin(f = i*HLING*deltaf) value for a particular
subcarrier group index i. The Hlin(f) is represented as
((HLINSC/2^15) * ((a(i) + j * b(i))/2^15)), where a(i)
and b(i) are signed integers in the (-2^15 + 1) to
(+2^15 - 1) range.

For each 16-bit tuple, the first 16-bit value, a(i), can
have values in the range -32767 to 32767. The second
16-bit value, b(i), can have values in the range -32767
to 32767. In each tuple the value for a(i) is loaded
first.

A special value (-32768) indicates that no measurement
could be done for this subcarrier group because it is out
of the passband or that the attenuation is out of range to
be represented.

This parameter is only available after a loop diagnostic
procedure.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.26.3 (HLINpsds) and 7.5.1.26.9
            (HLINpsus)";

        }
      }  // container hlin

      container hlog {
        description
          "State data nodes related to sub-carrier Hlog.";
        leaf hlog-measurement-time {
          type uint16 {
            range "1..65535";
          }
          units "symbols";
          description
            "This parameter contains the number of symbols used to
measure the Hlog(f) values. It is represented as an
unsigned integer in the range from 1 to 2^16 - 1.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.26.4  (HLOGMTds) and
            7.5.1.26.10 (HLOGMTus)";

        }

        leaf hlog-sub-carrier-group-size {
          type sub-carrier-group-size;
          description
            "This parameter is the number of subcarriers per group
used to report HLOGps.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.26.5 (HLOGGds) and 7.5.1.26.11
            (HLOGGus)";

        }

        leaf hlogps {
          type per-sub-carrier-group-uint16;
          description
            "This parameter is an array of real values in dB for
Hlog(f). Each array entry represents the real Hlog(f = i
* HLOGG * deltaf) value for a particular subcarrier
group subcarrier index i. The real Hlog(f) value is
represented as (6 - m(i)/10), where m(i) is an unsigned
integer in the range from 0 to 1022.

A special value (1023) indicates that no measurement could
be done for this subcarrier group because it is out of the
passband or that the attenuation is out of range to be
represented.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.26.6 (HLOGpsds) and 7.5.1.26.12
            (HLOGpsus)";

        }
      }  // container hlog

      container qln {
        description
          "State data nodes related to sub-carrier Quiet Line
Noise (QLN).";
        leaf qln-measurement-time {
          type uint16 {
            range "1..65535";
          }
          units "symbols";
          description
            "This parameter contains the number of symbols used to
measure the QLN(f) values. It is an unsigned integer in
the range from 1 to 2^16 - 1.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.27.1 (QLNMTds) and 7.5.1.27.4
            (QLNMTus)";

        }

        leaf qln-sub-carrier-group-size {
          type sub-carrier-group-size;
          description
            "This parameter is the number of subcarriers per group
used to report QLNps.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.27.2 (QLNGds) and 7.5.1.27.5
            (QLNGus)";

        }

        leaf qlnps {
          type per-sub-carrier-group-uint8;
          description
            "This parameter is an array of real values in dBm perHz for
QLN(f). Each array entry represents the QLN(f = i * QLNG
* deltaf) value for a particular subcarrier group index
i. The QLN(f) is represented as (-23 - n(i)/2), where
n(i) is an unsigned integer in the range from 0 to 254.

A special value (255) indicates that no measurement could
be done for this subcarrier group because it is out of the
passband or that the noise PSD is out of range to be
represented.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.27.3 (QLNpsds) and 7.5.1.27.6
            (QLNpsus)";

        }
      }  // container qln

      container snr {
        description
          "State data nodes related to sub-carrier Signal-to-Noise
Ratio (SNR) values.";
        leaf snr-measurement-time {
          type uint16 {
            range "1..65535";
          }
          units "symbols";
          description
            "This parameter contains the number of symbols used to
measure the SNR(f) values. It is an unsigned integer in
the range from 1 to 2^16 - 1.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.28.1 (SNRMTds) and 7.5.1.28.4
            (SNRMTus)";

        }

        leaf snr-sub-carrier-group-size {
          type sub-carrier-group-size;
          description
            "This parameter is the number of subcarriers per group
used to report SNRps.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.28.2 (SNRGds) and 7.5.1.28.5
            (SNRGus)";

        }

        leaf snrps {
          type per-sub-carrier-group-uint8;
          description
            "This parameter is an array of real values in dB for
SNR(f). Each array entry represents the SNR(f = i * SNRG
* deltaf) value for a particular subcarrier group index
i. The SNR(f) is represented as (-32 + snr(i)/2), where
snr(i) is an unsigned integer in the range from 0 to 254.

A special value (255) indicates that no measurement could
be done for this subcarrier group because it is out of
the passband or that the SNR is out of range to be
represented.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.28.3 (SNRpsds) and 7.5.1.28.6
            (SNRpsus)";

        }
      }  // container snr

      leaf bitsps {
        type per-sub-carrier-nibble;
        description
          "This parameter defines the downstream bits allocation table
per subcarrier. It is an array of integer values in the 0 to
15 range for each subcarrier. The reported bits of
subcarriers out of the MEDLEY set will be set to 0. This
parameter will be reported with the most recent values when
read over the Q-interface.";
        reference
          "ITU-T G.997.1 clauses 7.5.1.29.1 (BITSpsds) and 7.5.1.29.2
          (BITSpsus)";

      }

      leaf gainsps {
        type per-sub-carrier-uint16;
        description
          "This parameter defines the gains allocation table per
subcarrier. It is an array of integer values in the 0 to
4095 range for each subcarrier. The gain value is represented
as a multiple of 1/512 on linear scale. The reported gains of
subcarriers out of the MEDLEY set will be set to 0. This
arameter will be reported with the most recent values when
read over the Q interface.";
        reference
          "ITU-T G.997.1 clauses 7.5.1.29.3 (GAINSpsds) and 7.5.1.29.4
          (GAINSpsus)";

      }
    }  // grouping xtu-sub-carrier-status

    grouping transmit-psd {
      description
        "Transmit Power Spectral Density (PSD) parameters.";
      leaf tssps {
        type per-sub-carrier-group-uint16-tuple;
        description
          "This parameter contains the transmit spectrum shaping
parameters expressed as the set of breakpoints exchanged
during G.994.1. Each breakpoint consists of a subcarrier
index and the associated shaping parameter. The shaping
parameter is an integer value in the 0 to 126 range. It
is represented as a multiple of -0.5 dB.

A special value (255) indicates that the subcarrier is not
transmitted.

This is encoded as an array of 16-bit tuples where the first
16-bit value represents the sub-carrier index and the second
represents the shaping parameter.

TSS only applies to G.992.3 and G.992.5.";
        reference
          "ITU-T G.997.1 clauses 7.5.1.29.5 (TSSpsds) and 7.5.1.29.6
          (TSSpsus)";

      }

      leaf mrefpsd {
        type per-sub-carrier-group-uint16-tuple;
        description
          "This parameter will contain the set of breakpoints, which for
downstream are exchanged in the MREFPSDds fields of the O-PRM
message of ITU-T G.993.2, and which for upstream are
exchanged in the MREFPSDus fields of the R-PRM message of
ITU-T G.993.2.

This is encoded as an array of 16-bit tuples where the first
16-bit value represents the sub-carrier index and the second
represents the Power Spectral Density (PSD).

The format of the PSD is as specified in [ITU-T G.993.2],
using 12 bits to indicate MREFPSD level in steps of 0.1 dB
with an offset of -140 dBm per Hz.

MEDLEY Reference PSD (MREFPSD) only applies to G.993.2.";
        reference
          "ITU-T G.997.1 clauses 7.5.1.29.7 (MREFPSDds) and 7.5.1.29.8
          (MREFPSDus)";

      }
    }  // grouping transmit-psd

    grouping xlin {
      description
        "Crosstalk coupling, XLIN(f), parameters.";
      container xlin {
        description
          "State data nodes related to sub-carrier Xlin.";
        leaf xlin-scale {
          type uint16 {
            range "0..65535";
          }
          description
            "This parameter is the scale factor to be applied to the
Xlinps values.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.39.1 (XLINSCds) and 7.5.1.39.5
            (XLINSCus)";

        }

        leaf xlin-sub-carrier-group-size {
          type sub-carrier-group-size;
          description
            "This parameter is the number of subcarriers per group
used to report Xlinps.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.39.2 (XLINGds) and 7.5.1.39.6
            (XLINGus)";

        }

        leaf xlin-disturber {
          type vce-port-index;
          description
            "The Xlin disturber Vectoring Control Entity (VCE) port
index.";
        }

        list xlinbands {
          key "band-index";
          description
            "XLINBANDS contains pairs of (start_subcarrier_index,
stop_subcarrier_index) for every band in which XLINps is
reported.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.38.3 (XLINBANDSds) and
            7.5.1.38.7 (XLINBANDSus)";

          leaf band-index {
            type uint16;
            description "Xlin band index.";
          }

          uses sub-carrier-range {
            refine 
          }
        }  // list xlinbands

        leaf xlinps {
          type per-sub-carrier-group-int16-tuple;
          description
            "For each given Vectoring Control Entity (VCE) port index k,
this parameter is a one-dimensional array of complex values
in linear scale for Far-End Crosstalk (FEXT) coupling
coefficients Xlin(f) originating from the loop connected to
the VCE port k into the loop for which Xlin(f) is being
reported. Each array entry represents the
Xlinds(f = n*deltaf) value for a  particular subcarrier
index n. The Xlin(f = n*deltaf) value is represented as
((XLINSC/2^15) * ((a(n) + j*b(n))/2^15)), where a(n) and
b(n) are signed integers in the (-2^15 + 1) to (+2^15 - 1)
range. The format of XLINps is defined in ITU-T G.993.5.

For each 16-bit tuple, the first 16-bit value, a(n), can
have values in the range -32767 to 32767. The second
16-bit value, b(n), can have values in the range -32767
to 32767. In each tuple the value for a(n) is loaded
first.

A special value (-32768) indicates that no measurement
could be done from line k into this line for subcarrier n;

Another special value indicates that there is no phase
information and the magnitude of Xlin(f = n*deltaf) is
((XLINSC/2^15)*(a(n)/2^15)), and for G.993.5 this special
value is indicated as a(n) >= 0 and b(n) = 0
for all reported n.";
          reference
            "ITU-T G.997.1 clauses 7.5.1.38.4 (XLINpsds) and 7.5.1.38.8
            (XLINpsus)";

        }
      }  // container xlin
    }  // grouping xlin
  }  // submodule bbf-vdsl-xtu-sub-carrier-status-body