# Creating a timing reference priorities file

The timing reference priorities file is specified with the -f option on the command line. It lists boards and trunks on the boards, and rates their reliability. clockdemo uses this information to determine how best to configure the boards, and which boards or timing references to use in case of signal failure.

The timing reference priorities file is an ASCII text file. In the file, trunks are listed one to a line, in this fashion:

priority board_number trunk_number

where:

Parameter | Description
--- | ---
priority | Indicates the reliability of the trunk. priority is an integer between 0 (best) and 99 (worst). Trunks with equivalent reliability can be given identical priority numbers.
board_number | Indicates the number of the board on which the trunk is located. board_number is an integer between 0 and 32767.
trunk_number | Indicates the trunk number. trunk_number is an integer between 0 and the total number of trunks supported by the board type. 0 designates the board's internal oscillator (OSC).

The values on each line are separated by spaces. Any text following a number sign (#) denotes a comment and is ignored.

clockdemo follows these rules when choosing primary and secondary masters and timing references for each:

- The system must have one (and only one) primary master.

- If possible, the system should also have one (and only one) secondary master.

- The primary and secondary masters must be different boards.

- The primary and fallback timing references for a master board must be trunks on that board or the board's internal oscillator.

- In case of a need to reconfigure clocking, reconfigure as few boards as necessary to maintain system integrity.

## Sample timing reference priorities file

The following is a sample listing of a timing reference priorities file:

# A list of timing references that are prioritized
# Priority Board Trunk
0 0 1
0 0 2
0 3 1
1 1 1
99 0 0 # OSC
99 1 0 # OSC
99 2 0 # OSC
99 3 0 # OSC
# end of list

The text in this file denotes the following:

- Board 0, trunks 1 and 2, and board 3, trunk 1 are all equally reliable, and are the most reliable trunks available.

- Board 1, trunk 1 is also available as a timing reference, but is not as reliable as the trunks listed above it.

- Boards 0, 1, 2, and 3 also have internal oscillators that can be used as timing references, but only as a last resort.

Assuming all trunks are non-operational to begin with, clockdemo makes the following initial assignments based on this file:

- Board 0 is primary master, driving A_CLOCK using its internal oscillator as a timing reference.

- Board 1 is secondary master, driving B_CLOCK based on A_CLOCK.

- Boards 2 and 3 are slaves to A_CLOCK.

clockdemo displays the configuration as follows:

CLOCKDEMO Version 2.0 Mar 15 2001 15:00:36
Boards Clock Mode Current Mastering Fallback
Clock Source A Clock B Clock Occurred
-----------------------------------------------------------------
0: PRIMARY INTERNAL YES NO
3: SLAVE H100_A NO
1: SECONDARY H100_A YES NO
2: SLAVE H100_A NO
-----------------------------------------------------------------
(Press 'q' then ENTER to Exit.)

Board 0 is primary master, driving A_CLOCK using its internal oscillator. Board 1 is secondary master. Its fallback timing reference is OSC. All other boards are clock slaves.

If board 1, trunk 1 becomes operational, the clock configuration changes as follows:

Boards Clock Mode Current Mastering Fallback
Clock Source A Clock B Clock Occurred
-----------------------------------------------------------------
0: SECONDARY H100_A YES NO
3: SLAVE H100_A NO
1: PRIMARY NETWORK 1 YES NO
2: SLAVE H100_A NO
-----------------------------------------------------------------
(Press 'q' then ENTER to Exit.)

Board 1 has become primary master, driving A_CLOCK using trunk 1 as its primary timing reference. (Its secondary timing reference is OSC.) Board 0 has been demoted to secondary master. (Its secondary timing reference is OSC.)

If board 3, trunk 1 then becomes operational, board 3 becomes primary master, since it has a higher priority rating in the timing reference priorities file. (Its fallback timing reference is OSC.) Board 1 is demoted to secondary master. (Its fallback timing reference is trunk 1.) Board 0 is demoted to slave:

Boards Clock Mode Current Mastering Fallback
Clock Source A Clock B Clock Occurred
----------------------------------------------------------------
0: SLAVE H100_A NO
3: PRIMARY NETWORK 1 YES NO
1: SECONDARY H100_A YES NO
2: SLAVE H100_A NO
----------------------------------------------------------------
(Press 'q' then ENTER to Exit.)

Now board 0, trunk 2 becomes operational. Simultaneously, board 0, trunk 1 momentarily becomes operational, and then stops. clockdemo creates the following configuration:

Boards Clock Mode Current Mastering Fallback
Clock Source A Clock B Clock Occurred
----------------------------------------------------------------
0: SECONDARY H100_A YES NO
3: PRIMARY NETWORK 1 YES NO
1: SLAVE H100_A NO
2: SLAVE H100_A NO
----------------------------------------------------------------
(Press 'q' then ENTER to Exit.)

Now board 0, trunk 2 becomes non-operational:

Boards Clock Mode Current Mastering Fallback
Clock Source A Clock B Clock Occurred
----------------------------------------------------------------
0: SLAVE H100_A NO
3: PRIMARY NETWORK 1 YES NO
1: SECONDARY H100_A YES NO
2: SLAVE H100_A NO
----------------------------------------------------------------
(Press 'q' then ENTER to Exit.)

Now board 3, trunk 1 becomes non-operational:

Boards Clock Mode Current Mastering Fallback
Clock Source A Clock B Clock Occurred
----------------------------------------------------------------
0: SECONDARY H100_A YES NO
3: SLAVE H100_A NO
1: PRIMARY NETWORK 1 YES NO
2: SLAVE H100_A NO
----------------------------------------------------------------
(Press 'q' then ENTER to Exit.)

Lastly, board 1, trunk 1 becomes non-operational:

Boards Clock Mode Current Mastering Fallback
Clock Source A Clock B Clock Occurred
----------------------------------------------------------------
0: SECONDARY H100_A YES NO
3: SLAVE H100_A NO
1: PRIMARY INTERNAL YES NO
2: SLAVE H100_A NO
----------------------------------------------------------------
(Press 'q' then ENTER to Exit.)