(generated_monitoring_points_timing)=
# Timing

(generated_monitoring_points_timing_clocks)=
## Clocks

(generated_monitoring_points_timing_clocks_fpga0)=
### FPGA0

(generated_monitoring_points_timing_clocks_fpga0_jesd)=
#### JESD

**Description**:

  Status of TPM FPGA clocks.

Status of the 100 MHz FPGA JESD User Clock in FPGA0. This clock is derived 
from the 100 MHz JESD reference clock by the JESD MMCM which is in turn 
derived by the external AD9528 PLL. 






If ``True``, the clock is operating as expected. If ``False`` a clock overrun,
underrun, glitch or stop error has been detected by the FPGA.
- **Groups**: ``timing``, ``clocks``
- **Reported By**: TPM FPGAs
- **Expected**: `True`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_status(fpga_id=0, clock_name='JESD')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **clock_name** (*str*): Specify name of clock or None for all clocks. Input is non case sensitive. Options 'jesd', 'ddr', 'udp'
    - **Returns**: True when Status is OK, no errors (*bool*)
  - **Tile Method to Clear**: `clear_clock_status(fpga_id=0, clock_name='JESD')`

</details>
<br>


(generated_monitoring_points_timing_clocks_fpga0_ddr)=
#### DDR

**Description**:

  Status of TPM FPGA clocks.



Status of the 200 MHz FPGA DDR User Clock in FPGA0. This clock is derived 
from an external 100 MHz oscillator by an external PLL. 




If ``True``, the clock is operating as expected. If ``False`` a clock overrun,
underrun, glitch or stop error has been detected by the FPGA.
- **Groups**: ``timing``, ``clocks``
- **Reported By**: TPM FPGAs
- **Expected**: `True`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_status(fpga_id=0, clock_name='DDR')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **clock_name** (*str*): Specify name of clock or None for all clocks. Input is non case sensitive. Options 'jesd', 'ddr', 'udp'
    - **Returns**: True when Status is OK, no errors (*bool*)
  - **Tile Method to Clear**: `clear_clock_status(fpga_id=0, clock_name='DDR')`

</details>
<br>


(generated_monitoring_points_timing_clocks_fpga0_udp)=
#### UDP

**Description**:

  Status of TPM FPGA clocks.





Status of the 156.25 MHz FPGA UDP (40GbE) User Clock in FPGA0. This clock is 
derived from an external 156.25 MHz oscillator by the external AD9550 PLL. 


If ``True``, the clock is operating as expected. If ``False`` a clock overrun,
underrun, glitch or stop error has been detected by the FPGA.
- **Groups**: ``timing``, ``clocks``
- **Reported By**: TPM FPGAs
- **Expected**: `True`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_status(fpga_id=0, clock_name='UDP')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **clock_name** (*str*): Specify name of clock or None for all clocks. Input is non case sensitive. Options 'jesd', 'ddr', 'udp'
    - **Returns**: True when Status is OK, no errors (*bool*)
  - **Tile Method to Clear**: `clear_clock_status(fpga_id=0, clock_name='UDP')`

</details>
<br>



(generated_monitoring_points_timing_clocks_fpga1)=
### FPGA1

(generated_monitoring_points_timing_clocks_fpga1_jesd)=
#### JESD

**Description**:

  Status of TPM FPGA clocks.


Status of the 100 MHz FPGA JESD User Clock in FPGA1. This clock is derived 
from the 100 MHz JESD reference clock by the JESD MMCM which is in turn 
derived by the external AD9528 PLL. 





If ``True``, the clock is operating as expected. If ``False`` a clock overrun,
underrun, glitch or stop error has been detected by the FPGA.
- **Groups**: ``timing``, ``clocks``
- **Reported By**: TPM FPGAs
- **Expected**: `True`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_status(fpga_id=1, clock_name='JESD')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **clock_name** (*str*): Specify name of clock or None for all clocks. Input is non case sensitive. Options 'jesd', 'ddr', 'udp'
    - **Returns**: True when Status is OK, no errors (*bool*)
  - **Tile Method to Clear**: `clear_clock_status(fpga_id=1, clock_name='JESD')`

</details>
<br>


(generated_monitoring_points_timing_clocks_fpga1_ddr)=
#### DDR

**Description**:

  Status of TPM FPGA clocks.




Status of the 200 MHz FPGA DDR User Clock in FPGA1. This clock is derived 
from an external 100 MHz oscillator by an external PLL. 



If ``True``, the clock is operating as expected. If ``False`` a clock overrun,
underrun, glitch or stop error has been detected by the FPGA.
- **Groups**: ``timing``, ``clocks``
- **Reported By**: TPM FPGAs
- **Expected**: `True`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_status(fpga_id=1, clock_name='DDR')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **clock_name** (*str*): Specify name of clock or None for all clocks. Input is non case sensitive. Options 'jesd', 'ddr', 'udp'
    - **Returns**: True when Status is OK, no errors (*bool*)
  - **Tile Method to Clear**: `clear_clock_status(fpga_id=1, clock_name='DDR')`

</details>
<br>


(generated_monitoring_points_timing_clocks_fpga1_udp)=
#### UDP

**Description**:

  Status of TPM FPGA clocks.






Status of the 156.25 MHz FPGA UDP (40GbE) User Clock in FPGA1. This clock is 
derived from an external 156.25 MHz oscillator by the external AD9550 PLL. 

If ``True``, the clock is operating as expected. If ``False`` a clock overrun,
underrun, glitch or stop error has been detected by the FPGA.
- **Groups**: ``timing``, ``clocks``
- **Reported By**: TPM FPGAs
- **Expected**: `True`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_status(fpga_id=1, clock_name='UDP')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **clock_name** (*str*): Specify name of clock or None for all clocks. Input is non case sensitive. Options 'jesd', 'ddr', 'udp'
    - **Returns**: True when Status is OK, no errors (*bool*)
  - **Tile Method to Clear**: `clear_clock_status(fpga_id=1, clock_name='UDP')`

</details>
<br>




(generated_monitoring_points_timing_clock_managers)=
## Clock Managers

(generated_monitoring_points_timing_clock_managers_fpga0)=
### FPGA0

(generated_monitoring_points_timing_clock_managers_fpga0_c2c_mmcm)=
#### C2C MMCM

**Description**:

  Check status of named TPM clock manager cores (MMCM Core).
Reports the status of each MMCM lock and its lock loss counter.

The current status and historical status of C2C Mixed-Mode Clock Manager 
(MMCM) PLL in FPGA0. 
This MMCM is responsible for generating the Chip-to-Chip clocks for the 
FPGA0 to CPLD interface derived from a 50 MHz clock generated by the CPLD. 
This includes a 125 MHz streaming clock and a 50 MHz memory map clock. 






**Example:** **(** current_status, historical_status_counter **)**

**current_status**: The current MMCM PLL lock status.

* True → MMCM PLL is currently locked as expected.
* False → MMCM PLL is not currently locked.

**historical_status_counter**: To detect transient loss of the PLL lock that
occurs for less than 1 second, there is also the historical loss of lock
counter. This counts the number of loss of lock events since the last query.

* 0 → No loss of PLL lock events have occured since the last query.
* N > 0 → N loss of PLL lock events have occured since the last query.
- **Groups**: ``timing``, ``clock_managers``
- **Reported By**: TPM FPGAs
- **Expected**: `(True, 0)`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_manager_status(fpga_id=0, name='C2C')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **name** (*str*): Specify name of clock manager (non case sensitive)
    - **Returns**: (True, 0) if lock is up and no loss of lock (*dict of tuple with an entry for each FPGA and MMCM*)
  - **Tile Method to Clear**: `clear_clock_manager_status(fpga_id=0, name='C2C')`

</details>
<br>


(generated_monitoring_points_timing_clock_managers_fpga0_jesd_mmcm)=
#### JESD MMCM

**Description**:

  Check status of named TPM clock manager cores (MMCM Core).
Reports the status of each MMCM lock and its lock loss counter.



The current status and historical status of JESD Mixed-Mode Clock Manager 
(MMCM) PLL in FPGA0. 
This MMCM is responsible for generating the 100 MHz JESD user clock, the 
200 MHz ADC user clock and the 400 MHz high frequency clock used for 
capturing the one Pulse-Per-Second (PPS). 


The current status and historical status of DSP Mixed-Mode Clock Manager 
(MMCM) PLL in FPGA0. 
This MMCM is responsible for generating the 237 MHz DSP clock used by the 
channelizer, tile beamformer and station beamformer as well as the 474 MHz 
DSP 2x clock used by the channelizer. 


**Example:** **(** current_status, historical_status_counter **)**

**current_status**: The current MMCM PLL lock status.

* True → MMCM PLL is currently locked as expected.
* False → MMCM PLL is not currently locked.

**historical_status_counter**: To detect transient loss of the PLL lock that
occurs for less than 1 second, there is also the historical loss of lock
counter. This counts the number of loss of lock events since the last query.

* 0 → No loss of PLL lock events have occured since the last query.
* N > 0 → N loss of PLL lock events have occured since the last query.
- **Groups**: ``timing``, ``clock_managers``
- **Reported By**: TPM FPGAs
- **Expected**: `(True, 0)`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_manager_status(fpga_id=0, name='JESD')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **name** (*str*): Specify name of clock manager (non case sensitive)
    - **Returns**: (True, 0) if lock is up and no loss of lock (*dict of tuple with an entry for each FPGA and MMCM*)
  - **Tile Method to Clear**: `clear_clock_manager_status(fpga_id=0, name='JESD')`

</details>
<br>


(generated_monitoring_points_timing_clock_managers_fpga0_dsp_mmcm)=
#### DSP MMCM

**Description**:

  Check status of named TPM clock manager cores (MMCM Core).
Reports the status of each MMCM lock and its lock loss counter.







**Example:** **(** current_status, historical_status_counter **)**

**current_status**: The current MMCM PLL lock status.

* True → MMCM PLL is currently locked as expected.
* False → MMCM PLL is not currently locked.

**historical_status_counter**: To detect transient loss of the PLL lock that
occurs for less than 1 second, there is also the historical loss of lock
counter. This counts the number of loss of lock events since the last query.

* 0 → No loss of PLL lock events have occured since the last query.
* N > 0 → N loss of PLL lock events have occured since the last query.
- **Groups**: ``timing``, ``clock_managers``
- **Reported By**: TPM FPGAs
- **Expected**: `(True, 0)`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_manager_status(fpga_id=0, name='DSP')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **name** (*str*): Specify name of clock manager (non case sensitive)
    - **Returns**: (True, 0) if lock is up and no loss of lock (*dict of tuple with an entry for each FPGA and MMCM*)
  - **Tile Method to Clear**: `clear_clock_manager_status(fpga_id=0, name='DSP')`

</details>
<br>



(generated_monitoring_points_timing_clock_managers_fpga1)=
### FPGA1

(generated_monitoring_points_timing_clock_managers_fpga1_c2c_mmcm)=
#### C2C MMCM

**Description**:

  Check status of named TPM clock manager cores (MMCM Core).
Reports the status of each MMCM lock and its lock loss counter.


The current status and historical status of C2C Mixed-Mode Clock Manager 
(MMCM) PLL in FPGA1. 
This MMCM is responsible for generating the Chip-to-Chip clocks for the 
FPGA1 to CPLD interface derived from a 50 MHz clock generated by the CPLD. 
This includes a 125 MHz streaming clock and a 50 MHz memory map clock. 





**Example:** **(** current_status, historical_status_counter **)**

**current_status**: The current MMCM PLL lock status.

* True → MMCM PLL is currently locked as expected.
* False → MMCM PLL is not currently locked.

**historical_status_counter**: To detect transient loss of the PLL lock that
occurs for less than 1 second, there is also the historical loss of lock
counter. This counts the number of loss of lock events since the last query.

* 0 → No loss of PLL lock events have occured since the last query.
* N > 0 → N loss of PLL lock events have occured since the last query.
- **Groups**: ``timing``, ``clock_managers``
- **Reported By**: TPM FPGAs
- **Expected**: `(True, 0)`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_manager_status(fpga_id=1, name='C2C')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **name** (*str*): Specify name of clock manager (non case sensitive)
    - **Returns**: (True, 0) if lock is up and no loss of lock (*dict of tuple with an entry for each FPGA and MMCM*)
  - **Tile Method to Clear**: `clear_clock_manager_status(fpga_id=1, name='C2C')`

</details>
<br>


(generated_monitoring_points_timing_clock_managers_fpga1_jesd_mmcm)=
#### JESD MMCM

**Description**:

  Check status of named TPM clock manager cores (MMCM Core).
Reports the status of each MMCM lock and its lock loss counter.




The current status and historical status of JESD Mixed-Mode Clock Manager 
(MMCM) PLL in FPGA1. 
This MMCM is responsible for generating the 100 MHz JESD user clock, the 
200 MHz ADC user clock and the 400 MHz high frequency clock used for 
capturing the one Pulse-Per-Second (PPS). 


The current status and historical status of DSP Mixed-Mode Clock Manager 
(MMCM) PLL in FPGA1. 
This MMCM is responsible for generating the 237 MHz DSP clock used by the 
channelizer, tile beamformer and station beamformer as well as the 474 MHz 
DSP 2x clock used by the channelizer. 

**Example:** **(** current_status, historical_status_counter **)**

**current_status**: The current MMCM PLL lock status.

* True → MMCM PLL is currently locked as expected.
* False → MMCM PLL is not currently locked.

**historical_status_counter**: To detect transient loss of the PLL lock that
occurs for less than 1 second, there is also the historical loss of lock
counter. This counts the number of loss of lock events since the last query.

* 0 → No loss of PLL lock events have occured since the last query.
* N > 0 → N loss of PLL lock events have occured since the last query.
- **Groups**: ``timing``, ``clock_managers``
- **Reported By**: TPM FPGAs
- **Expected**: `(True, 0)`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_manager_status(fpga_id=1, name='JESD')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **name** (*str*): Specify name of clock manager (non case sensitive)
    - **Returns**: (True, 0) if lock is up and no loss of lock (*dict of tuple with an entry for each FPGA and MMCM*)
  - **Tile Method to Clear**: `clear_clock_manager_status(fpga_id=1, name='JESD')`

</details>
<br>


(generated_monitoring_points_timing_clock_managers_fpga1_dsp_mmcm)=
#### DSP MMCM

**Description**:

  Check status of named TPM clock manager cores (MMCM Core).
Reports the status of each MMCM lock and its lock loss counter.







**Example:** **(** current_status, historical_status_counter **)**

**current_status**: The current MMCM PLL lock status.

* True → MMCM PLL is currently locked as expected.
* False → MMCM PLL is not currently locked.

**historical_status_counter**: To detect transient loss of the PLL lock that
occurs for less than 1 second, there is also the historical loss of lock
counter. This counts the number of loss of lock events since the last query.

* 0 → No loss of PLL lock events have occured since the last query.
* N > 0 → N loss of PLL lock events have occured since the last query.
- **Groups**: ``timing``, ``clock_managers``
- **Reported By**: TPM FPGAs
- **Expected**: `(True, 0)`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_clock_manager_status(fpga_id=1, name='DSP')`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
      - **name** (*str*): Specify name of clock manager (non case sensitive)
    - **Returns**: (True, 0) if lock is up and no loss of lock (*dict of tuple with an entry for each FPGA and MMCM*)
  - **Tile Method to Clear**: `clear_clock_manager_status(fpga_id=1, name='DSP')`

</details>
<br>




(generated_monitoring_points_timing_timestamp)=
## Timestamp

(generated_monitoring_points_timing_timestamp_fpga0)=
### FPGA0

**Description**:

  Current FPGA timestamp.
This returned value is the time since sync time expressed in units of 0.27648
ms.

This time scale used for any synchronous operation in the TPM, and the reason
why the tile has to be reinitialised at most every 13.7 days
(2^32 timestamp units).
- **Groups**: ``timing``, ``clock_managers``
- **Reported By**: TPM FPGAs
- **Expected**: Updating/Incrementing
- **Cleared When Read**: No, the timestamp counter continuously increments. 

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `get_fpga_timestamp(device=<Device.FPGA_1: 1>)`
    - **Arguments:**
      - **device** (*Device*): FPGA to read timestamp from
    - **Returns**: PPS time (*int*)
    - **Raises**: Invalid value for device (*LibraryError*)

</details>
<br>


(generated_monitoring_points_timing_timestamp_fpga1)=
### FPGA1

**Description**:

  Current FPGA timestamp.
This returned value is the time since sync time expressed in units of 0.27648
ms.

This time scale used for any synchronous operation in the TPM, and the reason
why the tile has to be reinitialised at most every 13.7 days
(2^32 timestamp units).
- **Groups**: ``timing``, ``clock_managers``
- **Reported By**: TPM FPGAs
- **Expected**: Updating/Incrementing
- **Cleared When Read**: No, the timestamp counter continuously increments. 

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `get_fpga_timestamp(device=<Device.FPGA_2: 2>)`
    - **Arguments:**
      - **device** (*Device*): FPGA to read timestamp from
    - **Returns**: PPS time (*int*)
    - **Raises**: Invalid value for device (*LibraryError*)

</details>
<br>



(generated_monitoring_points_timing_pps)=
## PPS

(generated_monitoring_points_timing_pps_status)=
### Status

**Description**:

  Status of the One Pulse-Per-Second (PPS) reference to the TPM. The PPS is used
coherently time-tag data sampled by the ADC across multiple tiles.

PPS Status is ``True`` if both of the below conditions are met:

* The PPS is detected to be externally provided to the TPM from the subrack.
* The measured PPS period is exactly 1 second to a precision of 5 ns.
- **Groups**: ``timing``, ``pps``
- **Reported By**: TPM FPGAs
- **Expected**: `True`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_pps_status`
    - **Arguments:**
      - **fpga_id** (*int*): Specify which FPGA, 0, 1, or None for both FPGAs
    - **Returns**: True if PPS is detected and PPS period is as expected (*bool*)
  - **Tile Method to Clear**: `clear_pps_status`

</details>
<br>



(generated_monitoring_points_timing_pll)=
## PLL

**Description**:

  Status of TPM [AD9528 PLL](https://www.analog.com/media/en/technical-documentation/data-sheets/ad9528.pdf)
chip. The AD9528 contains two PLLs; the first PLL ``PLL1`` generates a 100 MHz
clock which is locked to the External 10 MHz reference clock provided by the
subrack. The generated 100 MHz clock is forwarded to the FPGA as the primary
reference clock and is also used by the second PLL ``PLL2`` in the AD9528 to
generate the 800 MHz ADC sampling clock.

**Example:** **(** current_status, historical_status_counter **)**

**current_status**: The current PLL lock status.

* True → Both ``PLL1`` and ``PLL2`` are locked as expected.
* False → Either ``PLL1``, ``PLL2`` or both are not currently locked.

**historical_status_counter**: To detect transient loss of the PLL lock that
occurs for less than 1 second, there is also the historical loss of lock
counter. This counts the number of loss of lock events since the last query.

* 0 → No loss of PLL lock events have occured since the last query.
* N > 0 → N loss of PLL lock events have occured since the last query.

**NOTE**: The loss of lock counter increments for a loss of lock event on
either ``PLL1`` or ``PLL2`` of the AD9528.
- **Groups**: ``timing``, ``pll``
- **Reported By**: TPM BIOS (CPLD or MCU)
- **Expected**: `(True, 0)`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_ad9528_pll_status`
    - **Returns**: current lock status and lock loss counter value (*tuple*)
  - **Tile Method to Clear**: `clear_ad9528_pll_status`

</details>
<br>


(generated_monitoring_points_timing_pll_40g)=
## PLL 40G

**Description**:

  Status of TPM [AD9550 PLL](https://www.analog.com/media/en/technical-documentation/data-sheets/ad9550.pdf)
chip. The AD9550 generates a 156.25 MHz clock used for the FPGA 40GbE UDP
clock.

**Example:** **(** current_status, historical_status_counter **)**

**current_status**: The current PLL lock status.

* True → PLL is currently locked as expected.
* False → PLL is not currently locked.

**historical_status_counter**: To detect transient loss of the PLL lock that
occurs for less than 1 second, there is also the historical loss of lock
counter. This counts the number of loss of lock events since the last query.

* 0 → No loss of PLL lock events have occured since the last query.
* N > 0 → N loss of PLL lock events have occured since the last query.
- **Groups**: ``timing``, ``pll``
- **Reported By**: TPM BIOS (CPLD or MCU)
- **Expected**: `(True, 0)`
- **Cleared When Read**: Yes

 <details>
  <summary>Developer info</summary>

  - **Tile Method**: `check_ad9550_pll_status`
    - **Returns**: current lock status and lock loss counter value (*tuple*)
  - **Tile Method to Clear**: `clear_ad9550_pll_status`

</details>
<br>