wrs-user-manual.in

	level (@t{INFO}).

	@b{Note:} all messages produced by these programs if syslog is
	configured will be passed to the syslog at the same
	configured @i{<facility>.<level>}, no matter of verbosity of a message.

@item CONFIG_WRS_LOG_LEVEL_PTP

	Specify verbosity of PPSi daemon as a string. This string will be
	passed to the PPSI after @t{-d} parameter. Please refer to the PPSI's
	documentation for more details.

	By leaving this item empty, PPSi daemon will use its default
	verbosity level.
	
	@b{Note:} all messages produced by PPSi if syslog is
	configured will be passed to the syslog at the same
	configured @i{<facility>.<level>}, no matter of verbosity of a message.

@item CONFIG_WRS_LOG_SNMPD

	Value can be a pathname, either to a file (e.g. 
        @t{/dev/kmsg} is a possible ``file'' target) or a valid snmpd log
        option (without -L).
        Allowed strings are in the format ``@t{S} @i{level} @i{facility}'' (e.g.
        ``@t{S 2 daemon}''). For example, ``@t{s daemon}'' will forward
        messages to syslog with daemon as facility. To set level (i.e. 5) use
	``@t{S 5 daemon}''. For details please check @t{man snmpcmd}. An empty
	string turns suppresses all logging. Please note that unknown facility
	names will generate a runtime error on the switch.

  @b{Note:} It looks
	like @t{Notice} is not a default logging priority as written in
	@i{net-snmp} manual.

@item CONFIG_WRS_LOG_MONIT
	The string can be a pathname (e.g. @t{/dev/kmsg}) or a @t{syslog}
	string.
	An empty string is used to represent no logging. If it is needed to
	select facility and level please leave an empty string here and change
	@t{/etc/monitrc} or @t{/usr/etc/monitrc} file directly.
	Please note that unknown facility names will generate a runtime error
	on the switch.

@item CONFIG_PTP_OPT_EXT_PORT_CONFIG_ENABLED
@itemx CONFIG_PORT@i{xx}_@i{zz}
@itemx ...

	These configuration items are used to set up timing parameters of all
	WR ports. 
	
	Items are named according to the format  @t{CONFIG_PORT@i{xx}_@i{zz}} where : 

	@itemize
		@item @i{xx} -- represents the port number ('01' to '18')
		@item @i{zz} -- is the property name for the given port @i{xx} 
    @end itemize

    The default configuration provided with the firmware release will
    most likely work for the majority of @sc{wr} networks. In case some
    customization of these parameters is required, please see
    @ref{Timing Configuration} for details.

@item CONFIG_N_SFP_ENTRIES
@itemx CONFIG_SFP00_PARAMS
@itemx ...
@itemx CONFIG_SFP17_PARAMS

   Configuration for @sc{sfp} models.
   
   @t{CONFIG_N_SFP_ENTRIES} indicates the number of SFP entries defined. Up to 18 SFPs
   can be defined. 
    
   @t{CONFIG_SFP@i{xx}_PARAMS} with index @i{xx} in range 00 to 17, contains @sc{sfp} parameters.
	 All @sc{sfp} models their respective wavelengths you are using in your @sc{wrs}
   should be entered here.
	@itemize
		@item @t{vn} (@i{optional}) -- Vendor Name of an SFP
		@item @t{pn} -- Part Number of an SFP
		@item @t{vs} (@i{optional}) -- Vendor Serial (serial number) of
					       an SFP
		@item @t{tx} -- TX delay of an SFP in picoseconds
		@item @t{rx} -- RX delay of an SFP in picoseconds
		@item @t{wl_txrx} -- Tx wavelength separated by "+" with Rx
				     wavelength of an SFP;
				     for example @t{wl_txrx=1490+1310} (for
				     1490nm Tx wavelength and 1310nm Rx
				     wavelength)
        @end itemize
        See @ref{Timing Configuration} for details.

@item CONFIG_N_FIBER_ENTRIES
@item CONFIG_FIBER00_PARAMS
@itemx ...
@itemx CONFIG_FIBER17_PARAMS

	These parameters specify the characteristics of fiber types used in your @sc{WR} installation.
	
	@t{CONFIG_N_FIBER_ENTRIES} indicates the number of fiber types defined. Up to 18 
	different fiber types can be defined. 
   
	@t{CONFIG_FIBER@i{xx}_PARAMS} with index @i{xx} in range 00 to 17, specifies
  the alpha value for each pair of used wavelengths.
	This parameter follows the format:

	@t{alpha_@i{xxxx}_@i{yyyy}=1.23e-04,alpha_@i{aaaa}_@i{bbbb}=4.56e-04,...}

	Where:
	@itemize
	@item @t{@i{xxxx}_@i{yyyy}} and @t{@i{aaaa}_@i{bbbb}} are pairs of used wavelengths
	@item @t{1.23e-04} and @t{4.56e-04} are alpha values to be used for
	      a particular combination of wavelengths.
	@end itemize
	The index (@t{00} to @t{17}) is then entered as @t{CONFIG_PORT@i{xx}_FIBER}
  port parameter to reference the connected fiber type.
  @xref{Timing Configuration}.

	You are expected to have no more than 18 fiber types installed in
	your @sc{WR} network.

@item CONFIG_TIME_GM
@itemx CONFIG_TIME_ARB_GM
@itemx CONFIG_TIME_FM
@itemx CONFIG_TIME_BC
@itemx CONFIG_TIME_CUSTOM

	The type of PTP clock this switch is. Only one of the five first
        items should be set (e.g. running ``@t{make menuconfig}'' offers
        them as an exclusive choice). The options select: 
        @itemize 
	        @item @t{CONFIG_TIME_GM} a grand-master with external reference, e.g. GPS or Cesium.
	        @item @t{CONFIG_TIME_ARB_GM} a arbitrary grand-master which designates 
	        	a clock that is synchronized to an application-specific source of time. 
	        @item @t{CONFIG_TIME_FM} a free-running master (FM), used for isolated 
	        	acquisition networks, without an external reference. 
	        @item @t{CONFIG_TIME_BC} a normal ``boundary-clock'' device that
	        	is slave on some ports and master on other ports.  
 	        @item @t{CONFIG_TIME_CUSTOM} an option which leaves the possibility
            to define freely the PTP clock class.
        @end itemize
    
@item CONFIG_PTP_OPT_DOMAIN_NUMBER
	A domain consists of one or more PTP devices communicating with each
	other as defined by the PTP protocol. A domain defines the scope of
	PTP message communication, state, operations, data sets, and
	timescale. PTP devices may participate in multiple domains.
	For more details please refer to the IEEE 1588-2008 standard.

@item CONFIG_PTP_OPT_PRIORITY1
	A user configurable designation that a clock belongs to an ordered
	set of PTP devices from which a PTP Master is selected.
	For more details please refer to the IEEE 1588-2008 standard.

@item CONFIG_PTP_OPT_PRIORITY2
	A user configurable designation that provides finer grained ordering
	among otherwise equivalent PTP devices.
	For more details please refer to the IEEE 1588-2008 standard.

@item CONFIG_PTP_OPT_CLOCK_CLASS

	An attribute defining the TAI traceability, synchronization state and
	expected performance of the time or frequency distributed by a
	Boundary Clock or Ordinary Clock.
	Its value can be set only if @t{CONFIG_TIME_CUSTOM} parameter is selected.
  The following table shows the default values
	used depending on the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice:
		@multitable @columnfractions .3 .4
		@headitem  Timing mode @tab CONFIG_PTP_OPT_CLOCK_CLASS 
		@item  CONFIG_TIME_GM @tab 6
		@item  CONFIG_TIME_ARB_GM @tab 13
		@item  CONFIG_TIME_FM @tab 193
		@item  CONFIG_TIME_BC @tab 248
		@end multitable

	For more details please refer to the IEEE 1588-2008 standard.

	
@item CONFIG_PTP_OPT_CLOCK_ACCURACY

	An attribute defining the accuracy of the Local Clock (e.g. local
	oscillator) of a Boundary Clock or Ordinary Clock.
	Its value is set automatically according to the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice.
	It can be also manually set when either @t{CONFIG_PTP_OPT_OVERWRITE_ATTRIBUTES} is set 
	or the timing mode ``@t{CONFIG_TIME_CUSTOM}`` is selected.
	The following table gives the default values depending on the timing mode
  ''@t{CONFIG_TIME_@i{xx}}'' choice :
		@multitable @columnfractions .3 .4
		@headitem  Timing mode @tab CONFIG_PTP_OPT_CLOCK_ACCURACY 
		@item  CONFIG_TIME_GM @tab 33
		@item  CONFIG_TIME_ARB_GM @tab 33
		@item  CONFIG_TIME_FM @tab 32
		@item  CONFIG_TIME_BC @tab 254
		@end multitable

	For more details please refer to the IEEE 1588-2008 standard.
	
@item CONFIG_PTP_OPT_CLOCK_ALLAN_VARIANCE
	An attribute defining the stability of the Local Clock of a
	Boundary Clock or Ordinary Clock.
	Its value is set automatically according to the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice.
	It can be also manually set either @t{CONFIG_PTP_OPT_OVERWRITE_ATTRIBUTES} is set 
	or the timing mode ``@t{CONFIG_TIME_CUSTOM}`` is selected.
	The following table gives the default values depending on the timing mode
  ''@t{CONFIG_TIME_@i{xx}}'' choice :
		@multitable @columnfractions .3 .4
		@headitem  Timing mode @tab CONFIG_PTP_OPT_CLOCK_ALLAN_VARIANCE 
		@item  CONFIG_TIME_GM @tab 47360
		@item  CONFIG_TIME_ARB_GM @tab 47360
		@item  CONFIG_TIME_FM @tab 50973
		@item  CONFIG_TIME_BC @tab 65535
		@end multitable

	For more details please refer to the IEEE 1588-2008 standard.


@item CONFIG_PTP_OPT_TIME_SOURCE
	This information-only attribute indicates the source of time used
	by the grandmaster or free-running master. In case the timing mode is set to
  ``@t{CONFIG_TIME_BC}`` this configuration option is not used and thus hidden
  from options available e.g. through ``@t{make menuconfig}''.
	
	The following table gives the default values depending on the timing mode
  ''@t{CONFIG_TIME_@i{xx}}'' choice :
		@multitable @columnfractions .3 .4
		@headitem  Timing mode @tab CONFIG_PTP_OPT_TIME_SOURCE 
		@item  CONFIG_TIME_GM @tab 32 (GNSS)
		@item  CONFIG_TIME_ARB_GM @tab 32 (GNSS)
		@item  CONFIG_TIME_FM @tab 160 (INTERNAL_OSCILLATOR)
		@item  CONFIG_TIME_BC @tab --
		@end multitable
		
@item CONFIG_PTP_PORT_PARAMS
@itemx CONFIG_PTP_CUSTOM
@itemx CONFIG_PTP_REMOTE_CONF

	By default (@t{CONFIG_PTP_PORT_PARAMS}), PTP daemon (PPSi) configuration file
  is generated based on the values stored in @t{CONFIG_PORT@i{xx}_@i{zz}}
  parameters. 
  If VLANs are configured, the items @t{CONFIG_VLANS_PORT@i{xx}_VID} are used as well.
  Any additional, global PPSi settings can be added by editing manually the
  @t{/wr/etc/ppsi-pre.conf} file, which is then used as the base for the final
  PPSi configuration file.

	Alternatively, PPSi can use a fully custom, user-defined file for
  configuration (@t{CONFIG_PTP_CUSTOM}).

	Finally, you can choose @t{PTP_REMOTE_CONF} to
        specify an URL whence the switch will download the @t{ppsi.conf} at
        boot time.

        Please see the help provided within @i{Kconfig} for more details about
        the various supported options.
	

@item CONFIG_PTP_CUSTOM_FILENAME

	If you chose @t{CONFIG_PTP_CUSTOM} from the options described above, you
  can provide your own filename for the PPSi configuration file.
  The introduced filename is expected to be installed in the @sc{wrs}
  filesystem.

@item CONFIG_PTP_CONF_URL

	If you choose @t{CONFIG_PTP_REMOTE_CONF} specify an URL
	(@t{http://}, @t{ftp://} or @t{tftp://}) whence
        the switch will download the @t{ppsi.conf} at boot time.
        The filename in the URL can include @t{HOSTNAME}, @t{IPADDR}
        and/or @t{MACADDR}, so the same configuration string can be used to set
        up a batch of switches with different configurations (similar to the
        @t{CONFIG_DOTCONF_URL}, please refer to @ref{The Configuration File}).

@item CONFIG_PPSGEN_PTP_FALLBACK
@itemx CONFIG_PPSGEN_PTP_THRESHOLD_MS
@itemx CONFIG_PPSGEN_GM_DELAY_TO_GEN_PPS_SEC
@itemx CONFIG_PPSGEN_FORCE
@itemx CONFIG_PPSGEN_FR_ON_SYNC_ONLY

	Configuration of the 1-PPS (Pulse Per Second) output.
  The generation of 1-PPS output heavily depends on the configured timing mode:
  @itemize
    @item GrandMaster (@t{CONFIG_TIME_GM}, PTP clock class 6)
      PPS generation is always enabled.
    @item Free-running Master (@t{CONFIG_TIME_FM}, PTP clock class 193)
      PPS generation is by default always enabled.
      If @t{CONFIG_PPSGEN_FR_ON_SYNC_ONLY} is set, then PPS is generated only
      when a switch becomes slave and synchronize to another master.
    @item Arbitrary GrandMaster (@t{CONFIG_TIME_ARB_GM}, PTP clock class 13)
      PPS generation is disabled unless @t{CONFIG_PPSGEN_FORCE} is set
    @item Boundary Clock (@t{CONFIG_TIME_BC}, PTP clock class 248)
      PPS is generated only when the device is synchronized. If @t{CONFIG_PPSGEN_FORCE}
      is set, PPS is generated at all times.
    @item Custom mode (@t{CONFIG_TIME_CUSTOM})
      PPS generation depends on configured PTP clock class, e.g. if PTP clock class
      is set to 6, PPS generation scheme will be the one of the GrandMaster
      listed above. If @t{CONFIG_PPSGEN_FORCE} is set, PPS is generated at all times.
  @end itemize

  Additionally to the conditions listed above, if PTP Best Master Clock Algorithm (BMCA) is enabled
  some spurious PPS can be generated during the transitory phase e.g. when the whole network is
  initialized. To suppress those @t{CONFIG_PPSGEN_GM_DELAY_TO_GEN_PPS_SEC} defines a delay time
  in seconds from the moment @sc{wrs} became a PTP grandmaster to the moment PPS starts to be generated.
  By default this parameter is set to 60s.
  
	The @t{CONFIG_PPSGEN_PTP_THRESHOLD_MS} option is applied when @sc{wrs} is synchronized to a regular
  (non-@sc{wr}) PTP master. This threshold defines a maximum offset to master
  (in miliseconds) when the @sc{wrs} is considered synchronized. Once the calculated offset falls
  below the configured threshold, PPS generation starts. To disable PPS, PTP offset must be
  greater than the @t{CONFIG_PPSGEN_PTP_THRESHOLD_MS} + 20%.
	Setting this parameter to 0 will block any PPS generation for those cases. 
	  
	The @t{CONFIG_PPSGEN_PTP_FALLBACK} option, if activated, enables the PPS generation
  when a slave instance programmed to use an extension protocol (WR, L1Sync, ...)
  is falling back to regular PTP synchronization. 

@item CONFIG_RVLAN_ENABLE
@itemx CONFIG_RVLAN_PMASK
@itemx CONFIG_RVLAN_AUTH_VLAN
@itemx CONFIG_RVLAN_NOAUTH_VLAN
@itemx CONFIG_RVLAN_OBEY_DOTCONFIG
@itemx CONFIG_RVLAN_RADIUS_SERVERS
@itemx CONFIG_RVLAN_RADIUS_SECRET
	Configuration items related to @i{radiusvlans}, which can be used to
	limit access to WR network for connected devices based on MAC address.
	For more details please refer to @i{White Rabbit Switch: Radius Vlan}.

@item CONFIG_SNMP_TRAPSINK_ADDRESS
@itemx CONFIG_SNMP_TRAP2SINK_ADDRESS
@itemx CONFIG_SNMP_RO_COMMUNITY
@itemx CONFIG_SNMP_RW_COMMUNITY

	Configuration for the @sc{snmp} agent. Addresses can be IP addresses
        or names (if DNS is configured and working), they are unset by
        default. Community values are strings and they default to
        @t{public} (@t{RO_COMMUNITY}) and @t{private} (@t{RW_COMMUNITY}).

@item CONFIG_SNMP_TEMP_THOLD_FPGA
@itemx CONFIG_SNMP_TEMP_THOLD_PLL
@itemx CONFIG_SNMP_TEMP_THOLD_PSL
@itemx CONFIG_SNMP_TEMP_THOLD_PSR
	Threshold levels for FPGA, PLL, Power Supply Left (PSL) and Power
        Supply Right (PSR) temperature sensors. When any temperature exceeds
        threshold level, SNMP object @t{WR-SWITCH-MIB::tempWarning} will change
        accordingly.

@item CONFIG_SNMP_SWCORESTATUS_DISABLE

	Force SNMP object @t{wrsSwcoreStatus} to be always OK. It can be used
	to ignore all Ethernet frames switching related issues.

@c @item CONFIG_SNMP_SWCORESTATUS_HP_FRAME_RATE
@c
@c	Error via SNMP if the rate of HP frames on any port exceed given value.
@c	(currently not implemented)

@c@item CONFIG_SNMP_SWCORESTATUS_RX_FRAME_RATE
@c
@c	Error via SNMP if rate of RX frames on any port exceed given value.
@c	(currently not implemented)

@c@item CONFIG_SNMP_SWCORESTATUS_RX_PRIO_FRAME_RATE
@c
@c	Error if frame rate of any RX priority exceed given value.
@c	(currently not implemented)

@item CONFIG_SNMP_SYSCONTACT
	Free text intended to be the textual identification of the contact
	person for this switch, together with information on how to contact this
	person. Reported by SNMP as SNMPv2-MIB::sysContact.0

@item CONFIG_SNMP_SYSLOCATION
	Free text intended to be The physical location of this node.
	Reported by SNMP as SNMPv2-MIB::sysLocation.0

@item CONFIG_SNMP_SYSTEM_CLOCK_MONITOR_ENABLED
@itemx CONFIG_SNMP_SYSTEM_CLOCK_DRIFT_THOLD
@itemx CONFIG_SNMP_SYSTEM_CLOCK_UNIT_DAYS
@itemx CONFIG_SNMP_SYSTEM_CLOCK_UNIT_HOURS
@itemx CONFIG_SNMP_SYSTEM_CLOCK_UNIT_MINUTES
@itemx CONFIG_SNMP_SYSTEM_CLOCK_CHECK_INTERVAL_DAYS
@itemx CONFIG_SNMP_SYSTEM_CLOCK_CHECK_INTERVAL_HOURS
@itemx CONFIG_SNMP_SYSTEM_CLOCK_CHECK_INTERVAL_MINUTES

	When @t{CONFIG_SNMP_SYSTEM_CLOCK_MONITOR_ENABLED} option is set, 
  the local system time is compared to the time 
  acquired from the external NTP server (according to @t{CONFIG_NTP_SERVER}).
  If the difference of time exceeds a given threshold
  (defined by @t{CONFIG_SNMP_SYSTEM_CLOCK_DRIFT_THOLD})
  expressed in seconds, an error is reported through SNMP.
		
	This comparison is done periodically at a rate expressed either in days 
	(@t{CONFIG_SNMP_SYSTEM_CLOCK_UNIT_DAYS}), hours (@t{CONFIG_SNMP_SYSTEM_CLOCK_UNIT_HOURS}) or
	minutes (@t{CONFIG_SNMP_SYSTEM_CLOCK_UNIT_MINUTES}).
	
	According to the selected unit, the repetition rate will be stored in the appropriate location:  
	@multitable @columnfractions .3 .7
	@headitem  Unit @tab Storage 
	@item  @t{...UNIT_DAYS} @tab @t{...CHECK_INTERVAL_DAYS}
	@item  @t{...UNIT_HOURS} @tab @t{...CHECK_INTERVAL_MINUTES}
	@item  @t{...UNIT_MINUTES} @tab @t{...CHECK_INTERVAL_MINUTES}
	@end multitable
	
	The @t{CONFIG_SNMP_SYSTEM_CLOCK_MONITOR_ENABLED} option is available only if a
	NTP server has been defined (@t{CONFIG_NTP_SERVER}).

@item CONFIG_WRSAUXCLK_FREQ
@itemx CONFIG_WRSAUXCLK_DUTY
@itemx CONFIG_WRSAUXCLK_CSHIFT
@itemx CONFIG_WRSAUXCLK_SIGDEL
@itemx CONFIG_WRSAUXCLK_PPSHIFT

  Configuration parameters to generate WR-synchronized 10MHz clock on the
  @i{clk2} output of the @sc{wrs} front panel. All these parameters are directly
  passed to @t{wrs_auxclk} tool of @sc{wrs}.
  In case you need to generate another clock frequency, please refer to
  @ref{wrs_auxclk}.

@item CONFIG_NIC_THROTTLING_ENABLED
@itemx CONFIG_NIC_THROTTLING_VAL

	Limit the Rx bandwidth of the traffic that goes from WR ports to Linux.
	Throttling can be enabled to prevent Linux using 100% of the processing
	power to receive Ethernet frames coming from WR ports to the CPU.
	To enable the throttling set @t{CONFIG_NIC_THROTTLING_ENABLED}.
	@t{CONFIG_NIC_THROTTLING_VAL} contains maximum allowed bandwidth
	in KB/s.

@item CONFIG_PPS_IN_TERM_50OHM
	Enable 50ohm termination for 1-PPS input.

@item CONFIG_CUSTOM_BOOT_SCRIPT_ENABLED
@itemx CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_LOCAL
@itemx CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE
@itemx CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE_URL

	It is possible to run a custom script at boot time. In this case please
        set @t{CONFIG_CUSTOM_BOOT_SCRIPT_ENABLED}.
        To run a script @t{/wr/bin/custom_boot_script.sh} from the local
        filesystem please set @t{CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_LOCAL}.

	As an alternative, you can choose
        @t{CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE} and specify an URL
        (@t{http://}, @t{ftp://} or @t{tftp://}) in
        @t{CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE_URL} whence
        the switch will download the script to be executed at boot time.
        The filename in the URL can include @t{HOSTNAME}, @t{IPADDR}
        and/or @t{MACADDR}, so the same configuration string can be used to set
        up a batch of switches with different configurations (similar to the
        @t{CONFIG_DOTCONF_URL}, please refer to @ref{The Configuration File}).

@item CONFIG_LLDPD_DISABLE
@itemx CONFIG_LLDPD_TX_INTERVAL
@itemx CONFIG_LLDPD_MANAGEMENT_PORT_DISABLE
@itemx CONFIG_LLDPD_MINIMUM_FRAME_SIZE

	Set of parameters related to the LLDP daemon (lldpd) configuration.
	Starting from version 6.0, switch by default sends LLDP frames on all
	ports (including management). In some installations it may be necessary
	to disable LLDP traffic on the management port (option
	@t{CONFIG_LLDPD_MANAGEMENT_PORT_DISABLE}). Additionally, in some cases
	(e.g. low latency networks) it may be necessary to disable
	LLDP at all (@t{CONFIG_LLDPD_DISABLE}).

	The transmission frequency of LLDP frames can be changed using option
	@t{CONFIG_LLDPD_TX_INTERVAL}.

	Networks that would benefit from the LLDP, but have low latency
	constraints can use option @t{CONFIG_LLDPD_MINIMUM_FRAME_SIZE}. With
	this option LLPD daemon includes only minimal set of information into
	LLPD frames.
	
	The table below contains comparison of LLDP frame fields for standard
	and minimal frame size (with
	@t{CONFIG_LLDPD_MINIMUM_FRAME_SIZE} option enabled). Size of some of
	those fields (like @t{System name} or	@t{System Description}) depends on
	the network configuration.

@multitable @columnfractions .25 .25 .35
@headitem Standard frame @tab Minimum frame @tab Description
@item 14
@tab 14
@tab ETH header
@item 9
@tab 9
@tab Chasis ID (with MAC)
@item 9
@tab 9
@tab Port ID (with MAC)
@item 4
@tab 4
@tab Time To Live
@item 2+len(System name)
@tab 2+len(System name)
@tab System name
@item 2+len(System desc.)
@tab 2+len(@t{WR-SWITCH})
@tab System description
@item 6
@tab 0
@tab Capabilities
@item 14
@tab 0
@tab Management Address
@item 7
@tab 7
@tab Port description
@item 2
@tab 2
@tab End of LLDP frame

@item 69

+len(System name)

+len(System desc.)
@tab 58

+len(System name)
@tab Total length

@end multitable

@item CONFIG_HTTPD_DISABLE

	Disable web interface on a switch.
	Web interface is now disabled by default and considered deprecated.
	A number of security vulnerabilities were found in the web interface
	(including CVE-2023-22577).
	Please note that it is still possible to enable web interface in
	run-time.
	@b{Users are strongly discouraged from using the web interface}.
	In exceptional cases the use of web-interface can be limited to well
	controlled networks.

@item CONFIG_MONIT_DISABLE

	Disable monitoring of running processes by @i{Monit}. @i{Monit} by
        default
        re-spawns processes that have died. This option should be used only during
        development.

@item CONFIG_FAN_HYSTERESIS
@itemx CONFIG_FAN_HYSTERESIS_T_DISABLE
@itemx CONFIG_FAN_HYSTERESIS_T_ENABLE
@itemx CONFIG_FAN_HYSTERESIS_PWM_VAL

	Use hysteresis to control fans. Enable fans with PWM value
	@t{CONFIG_FAN_HYSTERESIS_PWM_VAL} when PLL's temperature exceeds
	@t{CONFIG_FAN_HYSTERESIS_T_ENABLE}. Disable fans when temperature drops
	below @t{CONFIG_FAN_HYSTERESIS_T_DISABLE}. These options are intended to
	be used during development to reduce noise generated by a switch.
	Don't use in production as this may affect the synchronization
	performance.

@item CONFIG_READ_SFP_DIAG_ENABLE

	Enable readout of additional monitoring information (DOM) like temperature,
  Tx/Rx power, from SFP transceivers. Please note that not all Gigabit Ethernet
  SFP transceivers provide the DOM structure.

@item CONFIG_OPTIMIZATION_DEBUGGING
@itemx CONFIG_OPTIMIZATION_NONE_DEBUGGING
@itemx CONFIG_OPTIMIZATION_SIZE_SPEED
@itemx CONFIG_OPTIMIZATION_SPEED
	
	Compilation options. Chose one of these four choices to control the 
	compilation flags.
	
	@t{CONFIG_OPTIMIZATION_DEBUGGING}: Should be the optimization level choice 
	  for the standard edit-compile-debug cycle.
	
	@t{CONFIG_OPTIMIZATION_NONE_DEBUGGING}: Compile without optimization and with debug information
	
	@t{CONFIG_OPTIMIZATION_SIZE_SPEED}: Optimize for size. Enables all -O2 optimizations except those 
	  that often increase the code size.
	
	@t{CONFIG_OPTIMIZATION_SPEED}: GCC performs nearly all supported optimizations 
	  that do not involve a space-speed trade-off.
	 
@item CONFIG_RTU_HP_MASK_ENABLE
@itemx CONFIG_RTU_HP_MASK_VAL

	Set the mask which VLAN priorities are considered High Priority traffic
	(this
	only concerns the traffic which is fast-forwarded).
	To enable a custom mask please set
	@t{CONFIG_RTU_HP_MASK_ENABLE}.
	@t{CONFIG_RTU_HP_MASK_VAL} shall contain the mask to be used.

@item CONFIG_VLANS_ENABLE

	Enable VLANs configuration. All below VLAN config options
	(@t{CONFIG_VLANS_*}) require this filed to be set.

@item CONFIG_VLANS_PORT@i{xx}_MODE_ACCESS
@itemx CONFIG_VLANS_PORT@i{xx}_MODE_TRUNK
@itemx CONFIG_VLANS_PORT@i{xx}_MODE_DISABLED
@itemx CONFIG_VLANS_PORT@i{xx}_MODE_UNQUALIFIED

	VLANs port mode configuration for ports 1..18.
	It can be one of: Access, Trunk, Disabled or Unqualified.
	For details please refer to the @ref{VLANs Configuration}

@item CONFIG_VLANS_PORT@i{xx}_UNTAG_ALL
@itemx CONFIG_VLANS_PORT@i{xx}_UNTAG_NONE

	Define whether to remove a VLAN tag from egress frames on port 1..18.

@item CONFIG_VLANS_PORT@i{xx}_PRIO

	Priority value used when tagging incoming frames or to locally override
	the priority (in Unqualified and Disabled modes).
	-1 disables the priority overwrite. Valid values are
	from -1 to 7.

@item CONFIG_VLANS_PORT@i{xx}_VID

  Define the  VID tagging incoming frames and notify PPSi which 
  VLAN shall be used for synchronization; only one VLAN number 
  shall be used.
  This parameter is available for @t{MODE_ACCESS} mode.
	The range of a valid VID is from 0 to 4094.

 	For details please refer to the @ref{VLANs Configuration}

@item CONFIG_VLANS_PORT@i{xx}_PTP_VID

  Notify PPSi which VLAN(s) shall it use for synchronization; semicolon separated list is allowed.
  This parameter is available for @t{MODE_TRUNK}, @t{MODE_DISABLED} and
  @t{MODE_UNQUALIFIED} modes. 
  The range of a valid VID is from 0 to 4094.

	For details please refer to the @ref{VLANs Configuration}

@item CONFIG_VLANS_PORT@i{xx}_LLDP_TX_VID
@itemx CONFIG_VLANS_PORT@i{xx}_LLDP_TX_PRIO

  Notify lldpd which VLAN shall it use for sending LLDP frames.
  Incoming LLDP frames are accepted on all VLANs.
  This parameter is available for @t{MODE_TRUNK}, @t{MODE_DISABLED} and
  @t{MODE_UNQUALIFIED} modes. 
  The range of a valid VID is from 0 to 4094.
  @t{VLANS_PORTxx_LLDP_TX_PRIO} defines the priority to be inserted into
  a VLAN tag of LLDP frames sent by lldpd.

@item CONFIG_VLANS_RAW_PORT_CONFIG

  Expert mode. Allow to control all VLAN parameters (CONFIG_VLANS_PORT@i{xx}_PTP_VID,
  CONFIG_VLANS_PORT@i{xx}_VID, CONFIG_VLANS_PORT@i{xx}_MODE_@i{yy} and
  CONFIG_VLANS_PORT@i{xx}_UNTAG_@i{xx} ) without any restrictions. 
  The user must be aware of what it is doing.
  
@item CONFIG_VLANS_VLAN@i{xxxx}

	Provide a configuration for VLAN from the range 0000-4094.
	This option is a comma separated string in the following format:

	@t{fid=<0..4094>,prio=<-1|0..7>,drop=<y|n>,ports=<1;2;...;...-...;18>}

	Where:
	@itemize
	@item @t{fid} is a associated Filtering ID (FID) number. This parameter
	  may be useful for complex VLAN configurations. In simple cases it can
	  be omitted. One FID can be
	  associated with many VIDs. RTU learning is performed per-FID.
	  Associating many VIDs with a single FID allowed shared-VLANs
	  learning.
	@item @t{prio} is a priority of a VLAN; can take values between -1 and
	  7;
	  -1 disables priority override, any other valid number takes
	  precedence over the port priority
	@item If @t{drop} is set to @t{y}, @t{yes} or @t{1}, all frames
	  belonging to this VID are dropped (note that frame can belong to a
	  VID as a consequence of per-port Endpoint configuration); can take
	  values @t{y}, @t{yes}, @t{1}, @t{n}, @t{no}, @t{0}
	@item @t{ports} is a list of ports separated with a semicolon sign
	  (";"); ports ranges are supported (with a dash character)
	@end itemize
	Example:

	@t{fid=4,prio=2,drop=n,ports=1;3-5;15}

	It sets FID as 4, priority 2, don't drop frames belonging to this VLAN,
	assign ports 1, 3-5 and 15 to this VLAN.

	For more details about VLANs configuration please refer to the
	@ref{VLANs Configuration}

	
@end table

@c ==========================================================================
@node Timing Configuration
@section Timing Configuration

This section describes how timing configuration works in the switch.
Please note that, comparing to previous firmware releases, the timing configuration
has considerably evolved in version @value{release_version}.
 
Timing configuration now depends on four sets of @t{dot-config}
variables: common port information, per-port information, sfp information and fiber
description.

This is, for explanation's sake, an example of such items:

@smallexample
# common port information
PTP_OPT_EXT_PORT_CONFIG_ENABLED=yes
...
# per-port information
CONFIG_PORT09_IFACE="wri9"
CONFIG_PORT09_FIBER=2
CONFIG_PORT09_INSTANCE_COUNT_1=yes
CONFIG_PORT09_INST01_PROTOCOL_RAW=yes
CONFIG_PORT09_INST01_PROFILE_WR=yes
CONFIG_PORT09_INST01_DESIRADE_STATE_SLAVE=yes
CONFIG_PORT09_INST01_EGRESS_LATENCY=226214
CONFIG_PORT09_INST01_INGRESS_LATENCY=226758
...
# sfp information
CONFIG_SFP00_PARAMS="pn=AXGE-1254-0531,tx=0,rx=0,wl_txrx=1310+1490"
...
# fiber infomation
CONFIG_FIBER02_PARAMS="alpha_1310_1490=2.6787e-04"
@end smallexample

When making timing calculation for port @t{wri9}, assuming the
auto-detected @sc{sfp} model is``AXGE-1254-0531'', the software
uses configuration in the following way:

@itemize @bullet

@item The port has known tx (@t{CONFIG_PORT09_INST01_EGRESS_LATENCY}) and 
rx (@t{CONFIG_PORT09_INST01_INGRESS_LATENCY}) delays (around 226ns); the
values depend on trace length and other hardware-specific details
and are determined by the @sc{wr}  calibration procedure.  These values are
used by the @sc{WR} PTP daemon for accurate estimation of the transmission
link asymmetry.

@item The port is configured as WR slave (@t{CONFIG_PORT09_INST01_DESIRADE_STATE_SLAVE}) 
using raw Ethernet (@t{CONFIG_PORT09_INST01_PROTOCOL_RAW}) to synchronize using the
White-Rabbit protocol (@t{CONFIG_PORT09_INST01_PROFILE_WR}) and is deployed using
fiber type 2 (@t{CONFIG_PORT09_FIBER}) -- this number
is just a local enumeration of fiber types corresponding to an entry in
the @i{fiber information} section of the configuration. Most typical @sc{wr}
installations use a single type of fiber, indexed as "0" for every port.

@item The SFP transceiver used in this example emits 1310nm light for tx
and receives 1490nm light (this is part of the specification of the
transceiver, and cannot be auto-detected). Moreover, it has 0 constant
delay in both directions (tx/rx), determined by the @sc{wr} calibration
procedure.

@item The relative asymmetry of the fiber type being used (type 2 here), when
driven with 1310nm and 1490nm wavelengths, is characterized with an @i{alpha}
parameter of 0.00026787 (i.e. a ratio of 1.00026787). This value depends on
both, the fiber type and the wavelength used, and is determined, again,
by the @sc{wr} calibration procedure.

@end itemize

Please note that only one alpha value has to be provided for each fiber type.
The @i{alpha} in the opposite direction (@t{alpha_1490_1310}) is calculated
by the software.

@subsection Common port configuration

The following table lists the configuration items that are common to all port
instances of the WR switch.

@table @code

@item CONFIG_PTP_OPT_EXT_PORT_CONFIG_ENABLED

	  This option enables forcing the PTP state for each port instance using
    @t{CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_*} parameters. 
	  When set, each port instance can be forces to always stay either in the
    slave, master or passive state.
	  The PTP Best Master Clock Algorithm (BMCA) is then disabled.
	  This option is only available for a boundary clock (@t{CONFIG_TIME_BC}).
	  For more details please refer to the IEEE 1588-2020 (clause 17.6.2)
	  
@item CONFIG_PTP_SLAVE_ONLY

	  A slaveOnly Ordinary Clock utilizes the slaveOnly state machine
	  which does not enable transition to MASTER state.
	  This option is only available if @t{PTP_OPT_EXT_PORT_CONFIG_ENABLED}
	  is not used.
	  For more details please refer to the IEEE 1588-2020 (clause 9.2.2.1)
	
@end table

@subsection  Per-port configuration

@table @code
@item @t{CONFIG_PORT@i{xx}_INSTANCE_COUNT_1}
@item @t{CONFIG_PORT@i{xx}_INSTANCE_COUNT_0}

  Each physical @sc{wrs} port can be configured to run several PPSi instances.
  However, only one instance per-port can be active at any given moment. This functionality
  is required to support several PTP extensions (e.g. @sc{wr}, @sc{HA} - High Accuracy
  profile). The active instance will dependent then of the profile used by the peer on
  the other side of the link.

  WR switch firmware version @value{release_version} implements only a single,
  @sc{WR} extension, therefore the possibility of running several instances on a single
  port is disabled. The number of port instances must be set to either 1
  (@t{CONFIG_PORT@i{xx}_INSTANCE_COUNT_1=yes}) or 0 (@t{CONFIG_PORT@i{xx}_INSTANCE_COUNT_0=yes})
  if the port is not used. @i{xx} represents the port number in the range 01 to 18. 

@end table

@subheading  Common instance configuration

A set of parameters common to all instances running on the same physical port. The 
@i{xx} value in the parameter name represents the port number.

@table @code

@item  CONFIG_PORT@i{xx}_IFACE
	 Used to define the physical port interface name: "wri[1-18]"
	 
@item  CONFIG_PORT@i{xx}_FIBER
	Identify the fiber type. This is a number (@i{zz}) referring to the corresponding 
	@t{CONFIG_FIBER@i{zz}_PARAMS})
	
@item  CONFIG_PORT@i{xx}_CONSTANT_ASYMMETRY
	Defines an additional constant asymmetry (e.g. of a fiber amplifier used in longhaul @sc{wr}
  networks) that should be compensated by @sc{wr} PTP calculations.

@end table
  
@subheading  Instance information description

All port instance parameters shared the following naming scheme:
CONFIG_PORT@i{xx}_INST@i{yy}_@i{pp}, where @i{xx} represents the port number,
@i{yy} the instance number (01 to 02) and @i{pp} a key describing the
parameter itself. 

@table @code

@item  CONFIG_PORT@i{xx}_INST@i{yy}_PROTOCOL_RAW
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_PROTOCOL_UDP_IPV4
  Network transport layer selection, either raw Ethernet or UDP over IPv4 can be used.
 
@item  CONFIG_PORT@i{xx}_INST@i{yy}_PROFILE_WR
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_PROFILE_PTP
  Profile selection. @t{CONFIG_PORT@i{xx}_INST@i{yy}_PROFILE_WR} must be set to use the White Rabbit profile and 
  @t{CONFIG_PORT@i{xx}_INST@i{yy}_PROFILE_PTP} for pure PTP profile.
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_MECHANISM_E2E
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_MECHANISM_P2P
  PTP delay mechanism, either 'end-to-end' (E2E) or 'peer-to-peer' (P2P) can be used.
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_MASTER
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_SLAVE
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_PASSIVE
  If @t{CONFIG_PTP_OPT_EXT_PORT_CONFIG_ENABLED} is enabled then the desired PTP state
  of the instance must be defined as follows:
  @multitable @columnfractions .2 .8 
  @headitem State @tab Parameter
  @item MASTER  @tab @t{CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_MASTER}
  @item SLAVE   @tab @t{CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_SLAVE}
  @item PASSIVE @tab @t{CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_PASSIVE}
  @end multitable
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_ASYMMETRY_CORRECTION_ENABLE
  This option is only accessible when the PTP profile is selected otherwise this option is enabled by default. 
  It is used to force the servo to integrate on its calculation the computation of the delay asymmetry. 
  
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_BMODE_AUTO
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_BMODE_MASTER_ONLY
  Indicates the BMCA mode to be used. The choice is available only when
  @t{CONFIG_PTP_OPT_EXT_PORT_CONFIG_ENABLED} is disabled. Either the regular PTP BMCA
  (@t{BMODE_AUTO}) or PTP masterOnly feature (@t{BMODE_MASTER_ONLY})
  can be used.
  For more details please refer to the IEEE 1588-2020 (clause 9.2.2.2)
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_EGRESS_LATENCY
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_INGRESS_LATENCY
  Defines the reception (@t{CONFIG_PORT@i{xx}_INST@i{yy}_INGRESS_LATENCY}) and transmission 
  (@t{CONFIG_PORT@i{xx}_INST@i{yy}_EGRESS_LATENCY}) constant delays expressed in pico-seconds.
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_ANNOUNCE_INTERVAL
  The mean time interval between transmissions of successive
	PTP Announce messages. The value expressed as base 2 logarithm.
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_ANNOUNCE_RECEIPT_TIMEOUT
  The number of announceIntervals that must pass without receipt of an Announce
  message before the occurrence of the PTP event ANNOUNCE_RECEIPT_TIMEOUT_EXPIRES.
	The value expressed as base 2 logarithm. For more details please refer to
  IEEE 1588-2020 standard.
    
@item  CONFIG_PORT@i{xx}_INST@i{yy}_SYNC_INTERVAL
	  The mean time interval between transmission of successive
	  PTP Sync messages, i.e., the sync-interval, when transmitted
	  as multicast messages. The value expressed as base 2 logarithm.

@item  CONFIG_PORT@i{xx}_INST@i{yy}_MIN_DELAY_REQ_INTERVAL
	  The minDelayRequestInterval specifies the minimum permitted
	  mean time interval between successive Delay_Req messages.
    The value expressed as base 2 logarithm.
    This option is available when 'end-to-end' delay mechanism is selected 
    (@t{CONFIG_PORT@i{xx}_INST@i{yy}_MECHANISM_E2E}).

@item  CONFIG_PORT@i{xx}_INST@i{yy}_MIN_PDELAY_REQ_INTERVAL
	  The minPDelayRequestInterval specifies the minimum permitted
	  mean time interval between successive Pdelay_Req messages.
    The value expressed as base 2 logarithm.
    This option is only available when 'peer-to-peer' delay mechanism is selected
    (@t{CONFIG_PORT@i{xx}_INST@i{yy}_MECHANISM_P2P}).

@item  CONFIG_PORT@i{xx}_INST@i{yy}_MONITOR
  Option to decide whether timing-related errors for a given port will be reported
  through SNMP.

@c  --------------------------
@c Option that will be available whe HA will be deployed
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_ENABLED
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_INTERVAL
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_RECEIPT_TIMEOUT
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_TX_COHERENCY_IS_REQUIRED
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_RX_COHERENCY_IS_REQUIRED
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_CONGRUENCY_IS_REQUIRED
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_OPT_PARAMS_ENABLED
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_OPT_PARAMS_TS_CORRECTED_TX_ENABLED


@end table

@subsection SFP name matching

Each time you plug an SFP transceiver into any of the @sc{wrs} ports, it has to be matched
against @t{dot-config} entries specifying the timing parameters and wavelength for the
supported transceivers.
The matching algorithm reads from the SFP its vendor name (@i{vn}), part number (@i{pn}), vendor
serial (@i{vs}) and TX wavelength in @t{nm}. Note that it only reads the integer part (i.e. rounded down)
of the TX wavelength, as shown by @t{wrs_sfp_dump}. Then, these SFP parameters are compared
 with the values stored in the @t{CONFIG_SFP@i{xx}_PARAMS} @t{dot-config} entries:
@itemize
@item
  The @i{wl_txrx} field in the @t{CONFIG_SFP@i{xx}_PARAMS} must contain the transmit and receive
  wavelengths of the SFP in @t{nm}, as integers, separated by a '+'. The TX wavelength as
  reported by the SFP is matched against the tx entry (first number) in the @i{wl_txrx} entry. If these do
  not match, then this @t{CONFIG_SFP@i{xx}_PARAMS} entry cannot match against this SFP.
@item 
  For the remaining parameters, first a match against all the vendor SFP identifiers
  (@i{vn}, @i{pn} and @i{vs}) is attempted.
@item
  If a corresponding entry cannot be found, the match is limited to @i{vn} and @i{pn} and
  compared only with those @t{dot-config} entries that do not specify any vendor serial.
@item
  If the match still cannot be found, it is limited again, to @i{pn} only.

@end itemize

To understand better the operation of SFP matching algorithm, please see below some examples:
@itemize @bullet
@item
  @t{CONFIG_SFP00_PARAMS="vn=Axcen Photonics,pn=AXGE-3454-0531,vs=AX12390009629,
  tx=0,rx=0,wl_txrx=1490+1310"}

  This entry can be matched only to one SFP transceiver as it specifies full set of parameters,
  including the unique vendor serial number (@i{vs}).

@item
  @t{CONFIG_SFP01_PARAMS="vn=Axcen Photonics,pn=AXGE-3454-0531,tx=0,rx=0,
  wl_txrx=1490+1310"}

  This entry may be matched only to all SFPs with vendor name "Axcen Photonics",
  part number "AXGE-3454-0531" and a TX wavelength of 1490 nm, with exception of the SFP
  that was already matched to
  the previous entry @t{CONFIG_SFP00_PARAMS} (with vendor serial defined).

@item
  @t{CONFIG_SFP02_PARAMS="pn=AXGE-1254-0531,tx=0,rx=0,wl_txrx=1310+1490"}

  This entry will be matched to all SFPs with part number "AXGE-3454-0531" and TX wavelength of
  1310 nm, that were not matched by any of the entries listed earlier.

@end itemize

@subsection Other Deployments

All examples from previous sections match typical @sc{wr} networks we setup at
CERN with a single mono-modal fiber and 1310/1490 nm light wavelengths.

If you are using dual-fiber transceivers, which is acceptable for
short links, you use the same wavelength in both directions, over two
fibers of the same length. In this case you may omit the 
@t{wl_txrx} parameter in @sc{sfp} @t{dot-config} configuration and the
@t{alpha_@i{xx}_@i{xx}} parameter in fiber configuration.  The missing
parameters will cause warning messages to log destination, but are not
fatal, and a default alpha of 0 is used.

If you are using a pair of transceivers with different wavelengths,
and long fibers, you should provide an appropriate value of alpha,
according to laboratory measures of your fiber type. The
@t{CONFIG_FIBER@i{xx}_PARAMS} items are parsed as a list of
comma-separated assignments, so you can specify multiple