TR181-XPON  1.4.0
TR-181 PON manager.
tr181-xpon_ANI.odl.m4
Go to the documentation of this file.
1 /****************************************************************************
2 **
3 ** Copyright (c) 2022 SoftAtHome
4 **
5 ** Redistribution and use in source and binary forms, with or
6 ** without modification, are permitted provided that the following
7 ** conditions are met:
8 **
9 ** 1. Redistributions of source code must retain the above copyright
10 ** notice, this list of conditions and the following disclaimer.
11 **
12 ** 2. Redistributions in binary form must reproduce the above
13 ** copyright notice, this list of conditions and the following
14 ** disclaimer in the documentation and/or other materials provided
15 ** with the distribution.
16 **
17 ** Subject to the terms and conditions of this license, each
18 ** copyright holder and contributor hereby grants to those receiving
19 ** rights under this license a perpetual, worldwide, non-exclusive,
20 ** no-charge, royalty-free, irrevocable (except for failure to
21 ** satisfy the conditions of this license) patent license to make,
22 ** have made, use, offer to sell, sell, import, and otherwise
23 ** transfer this software, where such license applies only to those
24 ** patent claims, already acquired or hereafter acquired, licensable
25 ** by such copyright holder or contributor that are necessarily
26 ** infringed by:
27 **
28 ** (a) their Contribution(s) (the licensed copyrights of copyright
29 ** holders and non-copyrightable additions of contributors, in
30 ** source or binary form) alone; or
31 **
32 ** (b) combination of their Contribution(s) with the work of
33 ** authorship to which such Contribution(s) was added by such
34 ** copyright holder or contributor, if, at the time the Contribution
35 ** is added, such addition causes such combination to be necessarily
36 ** infringed. The patent license shall not apply to any other
37 ** combinations which include the Contribution.
38 **
39 ** Except as expressly stated above, no rights or licenses from any
40 ** copyright holder or contributor is granted under this license,
41 ** whether expressly, by implication, estoppel or otherwise.
42 **
43 ** DISCLAIMER
44 **
45 ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
46 ** CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
47 ** INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
48 ** MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
49 ** DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
50 ** CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
51 ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
52 ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
53 ** USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
54 ** AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
55 ** LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
56 ** ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
57 ** POSSIBILITY OF SUCH DAMAGE.
58 **
59 ****************************************************************************/
60 
61 %define {
62  /**
63  Access Node Interface (ANI) table. An ANI models the xPON MAC/PHY as
64  defined in the ITU-T PON standards.
65 
66  This object is not an interface object as described in [Section
67  4.2/TR-181i2], but it has many of the same core parameters as an
68  interface object, and they follow largely the same conventions. The most
69  important deviations are:
70 
71  - This object does not have a LowerLayers parameter.
72  - The value LowerLayerDown is not a valid value for its Status parameter.
73 
74  Because it's not an interface object, it does not occur in the
75  InterfaceStack table.
76 
77  At most one entry in this table can exist with a given value for Alias,
78  or with a given value for Name.
79  */
80  select XPON.ONU.ANI {
81  on action destroy call interface_object_destroyed;
82 
83  /**
84  Enables or disables the interface.
85 
86  If disabled, the device should force the ONU state of this ANI to O1
87  (Initial state).
88 
89  This parameter is based on ifAdminStatus from [RFC2863].
90 
91  Note: forcing the state to O1 implies the device disables the TX
92  laser of the associated transceiver(s). It's not required to disable
93  the RX part of the transceivers as well.
94 
95  This parameter is read-write. But because the plugin does not
96  handle its persistency via the odl mechanism, this parameter
97  does not have the attribute '%persistent'.
98  */
99  bool Enable = false;
100 
101  /**
102  The current operational state of the interface. Although this object
103  is not an interface object, it follows largely the conventions of
104  [Section 4.2.2/TR-181i2]. The most important deviation is that
105  LowerLayerDown is not a valid value.
106 
107  When Enable is false then Status SHOULD normally be Down (or
108  NotPresent or Error if there is a fault condition on the interface).
109 
110  When Enable becomes true then Status SHOULD change to Up if and only
111  if the interface is able to transmit and receive network traffic;
112  more specifically, Status should change to Up if
113  TC.ONUActivation.ONUState becomes O5; it SHOULD change to Dormant if
114  and only if the interface is operable but is waiting for external
115  actions before it can transmit and receive network traffic (and
116  subsequently change to Up if still operable when the expected
117  actions have completed); it SHOULD remain in the Error state if
118  there is an error or other fault condition detected on the
119  interface; it SHOULD remain in the NotPresent state if the interface
120  has missing (typically hardware) components; it SHOULD change to
121  Unknown if the state of the interface can not be determined for some
122  reason.
123 
124  This parameter is based on ifOperStatus from [RFC2863].
125  */
126  %read-only string Status {
127  default "Down";
128  on action validate call check_enum
129  ["NotPresent", "Down", "Dormant", "Up", "Error", "Unknown"];
130  }
131 
132  /**
133  A non-volatile handle used to reference this instance. Alias
134  provides a mechanism for an ACS to label this instance for future
135  reference.
136 
137  If the CPE supports the Alias-based Addressing feature as defined in
138  [Section 3.6.1/TR-069] and described in [Appendix II/TR-069], the
139  following mandatory constraints MUST be enforced:
140 
141  - Its value MUST NOT be empty.
142  - Its value MUST start with a letter.
143  - If its value is not assigned by the ACS, it MUST start with a "cpe-" prefix.
144  - The CPE MUST NOT change the parameter value.
145  */
146  %unique %key string Alias {
147  on action validate call check_maximum_length 64;
148  }
149 
150  /**
151  The textual name of the ANI entry as assigned by the CPE.
152  */
153  %unique %key string Name {
154  on action validate call check_maximum_length 64;
155  }
156 
157  /**
158  The accumulated time in seconds since the interface entered its
159  current operational state.
160  */
161  %read-only uint32 LastChange {
162  on action read call lastchange_on_read;
163  }
164 
165  /**
166  PON mode.
167 
168  The object Transceiver has a parameter of the same name. For proper
169  operation, the PON mode of the transceiver(s) corresponding to this
170  ANI must be equal to the PON mode of this ANI. But a user might e.g.
171  accidentally insert a G-PON SFP while the PON mode of the ANI is
172  XGS-PON.
173  */
174  %read-only string PONMode {
175  default "Unknown";
176  on action validate call check_enum
177  ["Unknown", "G-PON", "XG-PON", "NG-PON2", "XGS-PON" ];
178  }
179 
180  /**
181  This object represents an ITU-T PON TC layer device.
182  */
183  object TC {
184 
185  /**
186  This object shows info related to the activation of this ANI by
187  an OLT.
188  */
189  object ONUActivation {
190 
191  /**
192  ONU activation state.
193 
194  See:
195  - [Section C.12/G.9807.1]
196  - [Section 10/G.984.3]
197  - [Section 12/G.987.3]
198  - [Section 12/G.989.3]
199  */
200  %read-only string ONUState {
201  default "O1";
202  on action validate call check_enum
203  ["O1", "O2", "O3", "O2-3", "O4", "O5", "O6", "O7", "O8", "O9" ];
204  }
205 
206  /**
207  Identifies the vendor of the ONU. See [Section 9.1.1/G.988].
208  */
209  %read-only string VendorID {
210  on action validate call check_maximum_length 4;
211  }
212 
213  /**
214  Represents the combination of the Vendor-ID and the
215  Vendor-specific serial number (VSSN). The parameter shows
216  the serial number in a human readable format. Example: if
217  the vendor ID is ABCD and the VSSN encodes the number
218  1234568, the value of this parameter is ABCD12345678. See
219  [Section 9.1.1/G.988].
220  */
221  %read-only string SerialNumber {
222  on action validate call check_maximum_length 12;
223  }
224 
225  /**
226  Identifier that the OLT assigns to this ANI during the
227  activation. See:
228 
229  - [Section C.6.1.5.6/G.9807.1]
230  - [Section 5.5.2/G.984.3]
231  - [Section 6.4.2/G.987.3]
232  - [Section 6.1.5.6/G.989.3]
233  */
234  %read-only uint32 ONUID {
235  on action validate call check_maximum 1022;
236  }
237  }
238 
239  object Authentication {
240 
241  /**
242  All ITU based PON standards specify authentication by PLOAM
243  password or registration ID.
244 
245  See:
246  * G.9807.1 Section C.15.2.1
247  * G.984.3 Section VI.2
248  * G.987.3 Section 15.2.1
249  * G.989.3 Section 15.2.1
250 
251  All those standards mention that a method to enter the
252  password is beyond their scope. This parameter and the
253  parameter 'HexadecimalPassword' standardize a method to
254  enter the password.
255 
256  In case of G-PON as PON mode, the password can be up to 10
257  bytes long. See G.984.3 Section 9.2.4.2. For the other PON
258  modes, the password can be up to 36 bytes long. See:
259 
260  * G.9807.1 Section C.11.3.4.2
261  * G.987.3 Section 11.3.4.2
262  * G.989.3 Section 11.3.4.2
263 
264  If 'HexadecimalPassword' is false, the password is in ASCII
265  format. Then all 95 printable characters with decimal codes
266  in the range 32 to 126 inclusive are allowed. Each character
267  corresponds with 1 byte in the password.
268 
269  If 'HexadecimalPassword' is true, the password is in
270  hexadecimal format. Then only the characters 0 to 9, a to f,
271  and A to F are allowed. Each character corresponds with 1
272  nibble in the password.
273 
274  Depending on the value of 'HexadecimalPassword' and the PON
275  mode, a different number of characters are applicable. If
276  'HexadecimalPassword' is false:
277 
278  * In case of G-PON as PON mode, only the 1st 10 characters are
279  applicable.
280 
281  * In case of another PON mode, only the 1st 36 characters are
282  applicable.
283 
284  If 'HexadecimalPassword' is true:
285 
286  * In case of G-PON as PON mode, the 1st 20 characters are all
287  relevant. The other characters are not applicable.
288 
289  * In case of another PON mode, all 72 characters are relevant.
290 
291  This parameter is set to empty if no authentication via a
292  password is required.
293 
294  When read, this parameter returns an empty string,
295  regardless of the actual value, unless the Controller has a
296  "secured" role.
297 
298  NOTE - For now this parameter always returns an empty string
299  when read.
300  */
301  string Password {
302  on action validate call check_password;
303  on action read call hide_value;
304  }
305  /**
306  If false, 'Password' is in ASCII format. If true, 'Password'
307  is in hexadecimal format.
308 
309  See the parameter 'Password' for more info.
310  */
311  bool HexadecimalPassword;
312  }
313 
314  /**
315  Performance monitoring (PM) counters.
316  */
317  object PM {
318 
319  /**
320  PHY PM.
321  */
322  object PHY {
323  %read-only uint64 CorrectedFECBytes;
324  %read-only uint64 CorrectedFECCodewords;
325  %read-only uint64 UncorrectableFECCodewords;
326  %read-only uint64 TotalFECCodewords;
327  %read-only uint32 PSBdHECErrorCount;
328  %read-only uint32 HeaderHECErrorCount;
329  %read-only uint32 UnknownProfile;
330  }
331 
332  /**
333  (X)GEM PM.
334  */
335  object GEM {
336  %read-only uint64 FramesSent;
337  %read-only uint64 FramesReceived;
338  %read-only uint32 FrameHeaderHECErrors;
339  %read-only uint32 KeyErrors;
340  }
341 
342  /**
343  PLOAM PM.
344  */
345  object PLOAM {
346  %read-only uint32 MICErrors;
347  %read-only uint64 DownstreamMessageCount;
348  %read-only uint64 RangingTime;
349  %read-only uint64 UpstreamMessageCount;
350  }
351 
352  /**
353  OMCI PM.
354  */
355  object OMCI {
356  %read-only uint64 BaselineMessagesReceived;
357  %read-only uint64 ExtendedMessagesReceived;
358  %read-only uint32 MICErrors;
359  }
360  }
361 
362  /**
363  Info about the GEM ports of this ANI.
364  */
365  object GEM {
366 
367  /**
368  GEM port table. Each entry gives info about a(n) (X)GEM port.
369 
370  At most one entry in this table can exist with a given value
371  for PortID.
372  */
373  %read-only object Port[] {
374  counted with PortNumberOfEntries;
375 
376  /**
377  Identifies a GEM port.
378 
379  See:
380  - [Section C.6.1.5.8/G.9807.1]
381  - [Section 5.5.5/G.984.3]
382  - [Section 6.4.4/G.987.3]
383  - [Section 6.1.5.8/G.989.3]
384  */
385  %unique %key uint32 PortID {
386  on action validate call check_maximum 65534;
387  }
388 
389  /**
390  Type of connection this GEM port is used for.
391 
392  See: [Section 9.2.3/G.988].
393  */
394  %read-only string Direction {
395  default "UNI-to-ANI";
396  on action validate call check_enum
397  ["UNI-to-ANI", "ANI-to-UNI", "bidirectional" ];
398  }
399 
400  /**
401  GEM port type.
402  */
403  %read-only string PortType {
404  default "unicast";
405  on action validate call check_enum
406  ["unicast", "multicast", "broadcast" ];
407  }
408 
409  /**
410  Performance monitoring (PM) counters for this (X)GEM port.
411  */
412  object PM {
413  %read-only uint64 FramesSent;
414  %read-only uint64 FramesReceived;
415  }
416  }
417  }
418  object PerformanceThresholds {
419  %read-only uint32 SignalFail {
420  default 5;
421  on action validate call check_range [3, 8];
422  }
423  %read-only uint32 SignalDegrade {
424  default 9;
425  on action validate call check_range [4, 10];
426  }
427  }
428 
429  /**
430  Alarms at TC level for this ANI.
431  */
432  object Alarms {
433  // Loss of signal. See [Section 11.1.2/G.984.3].
434  %read-only bool LOS;
435  // Loss of frame. See [Section 11.1.2/G.984.3].
436  %read-only bool LOF;
437  // Signal failed. See [Section 11.1.2/G.984.3].
438  %read-only bool SF;
439  // Signal degraded. See [Section 11.1.2/G.984.3].
440  %read-only bool SD;
441  // Loss of GEM channel delineation. See [Section 11.1.2/G.984.3].
442  %read-only bool LCDG;
443  // Transmitter failure. See [Section 11.1.2/G.984.3].
444  %read-only bool TF;
445  // Start-up failure. See [Section 11.1.2/G.984.3].
446  %read-only bool SUF;
447  // Message error message. See [Section 11.1.2/G.984.3].
448  %read-only bool MEM;
449  // Deactivate ONU-ID. See [Section 11.1.2/G.984.3].
450  %read-only bool DACT;
451  // Disabled ONU. See [Section 11.1.2/G.984.3].
452  %read-only bool DIS;
453  // Link mismatching. See [Section 11.1.2/G.984.3].
454  %read-only bool MIS;
455  // When the ONU receives a PEE message. See [Section 11.1.2/G.984.3].
456  %read-only bool PEE;
457  // Remote defect indication. See [Section 11.1.2/G.984.3].
458  %read-only bool RDI;
459  // Loss of downstream synchronization. See [G.9807.1].
460  %read-only bool LODS;
461 
462  /**
463  The ANI behaves rogue: it is not transmitting in a manner
464  consistent with parameters specified in the ITU-T PON
465  standards. Hence it can threaten all upstream transmissions
466  on the PON, causing interference and disrupting
467  communications of other ONUs on the PON. An example of rogue
468  behavior is transmitting in the wrong timeslot.
469 
470  See:
471  - [Section C.19/G.9807.1]
472  - [Section 19/G.989.3]
473  */
474  %read-only bool ROGUE;
475  }
476  }
477 
478  /**
479  Transceiver table. Each entry models a PON transceiver.
480 
481  This table MUST contain at least 0 and at most 2 entries.
482 
483  At most one entry in this table can exist with a given value for ID.
484  */
485  %read-only object Transceiver[2] {
486  counted with TransceiverNumberOfEntries;
487 
488  /**
489  The ID as assigned by the CPE to this Transceiver entry.
490  */
491  %unique %key uint32 ID {
492  on action validate call check_maximum 1;
493  }
494 
495  /**
496  Transceiver type. Allowed values are given by [Table 4-1/SFF-8024].
497  */
498  %read-only uint32 Identifier {
499  on action validate call check_maximum 255;
500  }
501 
502  /**
503  Vendor name. See [Table 4-1/SFF-8472].
504  */
505  %read-only string VendorName {
506  on action validate call check_maximum_length 256;
507  }
508  /**
509  Vendor part number. See "Vendor PN" in [Table 4-1/SFF-8472].
510  */
511  %read-only string VendorPartNumber {
512  on action validate call check_maximum_length 256;
513  }
514 
515  /**
516  Vendor revision. See "Vendor rev" in [Table 4-1/SFF-8472].
517  */
518  %read-only string VendorRevision {
519  on action validate call check_maximum_length 256;
520  }
521 
522  %read-only string PONMode {
523  default "Unknown";
524  on action validate call check_enum
525  ["Unknown", "G-PON", "XG-PON", "NG-PON2", "XGS-PON" ];
526  }
527 
528  // Connector type.
529  %read-only string Connector {
530  default "Unknown";
531  on action validate call check_enum
532  ["Unknown", "LC", "SC", "ST", "FC", "MT-RJ"];
533  }
534 
535  // Nominal data rate downstream in kbps.
536  %read-only uint32 NominalBitRateDownstream;
537 
538  // Nominal data rate upstream in kbps.
539  %read-only uint32 NominalBitRateUpstream;
540 
541  // Measured RX power in 0.1 dBm.
542  %read-only %volatile int32 RxPower {
543  on action read call read_trx_param;
544  }
545 
546  // Measured TX power in 0.1 dBm.
547  %read-only %volatile int32 TxPower {
548  on action read call read_trx_param;
549  }
550 
551  // Measured supply voltage in mV.
552  %read-only %volatile uint32 Voltage {
553  on action read call read_trx_param;
554  }
555 
556  // Measured bias current in µA.
557  %read-only %volatile uint32 Bias {
558  on action read call read_trx_param;
559  }
560 
561  /**
562  Measured temperature in degrees celsius.
563 
564  A value of -274 (which is below absolute zero) indicates a good
565  reading has not been obtained.
566  */
567  %read-only %volatile int32 Temperature {
568  on action read call read_trx_param;
569  on action validate call check_minimum -274;
570  }
571  }
572 
573  ifdef(`CONFIG_SAH_AMX_TR181_XPON_USE_NETDEV_COUNTERS', /**
574  * Throughput statistics for this interface.
575  *
576  * The CPE MUST reset the interface's Stats parameters
577  * (unless otherwise stated in individual object or parameter descriptions) either
578  * when the interface becomes operationally down due to a previous administrative
579  * down (i.e. the interface's Status parameter transitions to a down state after
580  * the interface is disabled) or when the interface becomes administratively up
581  * (i.e. the interface's Enable parameter transitions from false to true).
582  * Administrative and operational interface status is discussed in [Section 4.2.2/TR-181i2].
583  *
584  * @version 1.0
585  */
586  object Stats {
587  on action read call stats_object_read;
588  on action list call stats_object_list;
589  on action describe call stats_object_describe;
590  })
591  }
592 }
593