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:   Sowrirajan Padmanabhan, Nokia

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-2020 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-355a3; see
the TR itself for full legal notices.";

    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..192";
      }
      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 object
represents 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 clause 7.5.1.26.1 Downstream H(f) linear
            representation scale (HLINSCds) and clause 7.5.1.26.7
            Upstream H(f) linear representation scale (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 clause 7.5.1.26.2 Downstream H(f) linear
            subcarrier group size (HLINGds) and clause 7.5.1.26.8
            Upstream H(f) linear subcarrier group size (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 -32,767 to 32,767. The second
16-bit value, b(i), can have values in the range -32,767
to 32,767. In each tuple the value for a(i) is loaded
first.

A special value (-32,768) 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 clause 7.5.1.26.3 Downstream H(f) linear
            representation (HLINpsds) and 7.5.1.26.9 Upstream H(f)
            linear representation (HLINpsus)";

        }
      }  // container hlin

      container hlog {
        description
          "State data nodes related to sub-carrier Hlog.";
        leaf hlog-measurement-time {
          type uint16 {
            range "1..65535";
          }
          units "DMT 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 clause 7.5.1.26.4 Downstream H(f)
            logarithmic measurement time (HLOGMTds) and clause
            7.5.1.26.10 Upstream H(f) logarithmic measurement time
            (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 clause 7.5.1.26.5 Downstream H(f)
            logarithmic subcarrier group size (HLOGGds) and clause
            7.5.1.26.11 Upstream H(f) logarithmic subcarrier group
            size (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 clause 7.5.1.26.6 Downstream H(f)
            logarithmic representation (HLOGpsds) and clause
            7.5.1.26.12 Upstream H(f) logarithmic representation
            (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 "DMT 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 clause 7.5.1.27.1 Downstream quiet line
            noise PSD measurement time (QLNMTds) and clause
            7.5.1.27.4 Upstream quiet line noise PSD measurement
            time (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 clause 7.5.1.27.2 Downstream QLN(f)
            subcarrier group size (QLNGds) and clause 7.5.1.27.5
            Upstream QLN(f) subcarrier group size (QLNGus)";

        }

        leaf qlnps {
          type per-sub-carrier-group-uint8;
          description
            "This parameter is an array of real values in dBm/Hz 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 clause 7.5.1.27.3 Downstream QLN(f)
            (QLNpsds) and clause 7.5.1.27.6 Upstream QLN(f)
            (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 "DMT 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 clause 7.5.1.28.1 Downstream SNR
            measurement time (SNRMTds) and clause 7.5.1.28.4
            Upstream SNR measurement time (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 clause 7.5.1.28.2 Downstream SNR(f)
            subcarrier group size (SNRGds) and clause 7.5.1.28.5
            Upstream SNR(f) subcarrier group size (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 clause 7.5.1.28.3 Downstream SNR(f)
            (SNRpsds) and clause 7.5.1.28.6 Upstream SNR(f)
            (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 clause 7.5.1.29.1 Downstream bits allocation
          (BITSpsds) and clause 7.5.1.29.2 Upstream bits allocation
          (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 clause 7.5.1.29.3 Downstream gains allocation
          (GAINSpsds) and clause 7.5.1.29.4 Upstream gains allocation
          (GAINSpsus)";

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

    grouping transmit-psd {
      description
        "The transmit-psd object represents the current transmit
power spectral density (PSD).";
      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 clause 7.5.1.29.5 Downstream transmit spectrum
          shaping (TSSpsds) and clause 7.5.1.29.6 Upstream transmit
          spectrum shaping (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/Hz.

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

      }
    }  // grouping transmit-psd

    grouping xlin {
      description
        "The Xlin object represents the crosstalk coupling,
XLIN(f).";
      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 clause 7.5.1.39.1 Downstream XLIN scale
            (XLINSCds) and clause 7.5.1.39.5 Upstream XLIN scale
            (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 clause 7.5.1.39.2 Downstream XLIN
            subcarrier group size (XLINGds) and clause 7.5.1.39.6
            Upstream XLIN subcarrier group size (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 clause 7.5.1.38.3 Downstream XLIN
            bandedges (XLINBANDSds) and clause 7.5.1.38.7 Upstream
            XLIN bandedges (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 -32,767 to 32,767. The second
16-bit value, b(n), can have values in the range -32,767
to 32,767. In each tuple the value for a(n) is loaded
first.

A special value (-32,768) 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 clause 7.5.1.38.4 Downstream FEXT coupling
            (XLINpsds) and clause 7.5.1.38.8 Upstream FEXT coupling
            (XLINpsus)";

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