added description

3f10e63b · Maciej Lipinski · Marek Gumiński · 0c089ba4 · 3f10e63b · 3f10e63b
Commit 3f10e63b authored Nov 13, 2015 by Maciej Lipinski Committed by Marek Gumiński Aug 19, 2019
5 changed files
--- a/modules/wrsw_psu/psu_announce_snooper.vhd
+++ b/modules/wrsw_psu/psu_announce_snooper.vhd
@@ -10,9 +10,9 @@
 -- Platform   : FPGA-generic
 -- Standard   : VHDL'93
 -------------------------------------------------------------------------------
-- Description: this module recognizes PTP Announce messages (over 802.3 Ethernet
-- and UDP) and extracts from them required info on the fly, i.e. sequence ID and
-- clock class)
+-- Description: this module recognizes PTP Announce messages (over 802.1D and Q Ethernet
+-- and UDP) and extracts from them required info on the fly, i.e. sequence ID, sourcePortID 
+-- and clock class)
 -- useful: http://wiki.hevs.ch/uit/index.php5/Standards/Ethernet_PTP/frames
 -- 
 -- Where            | what      |  offset  16bit words   | value

--- a/modules/wrsw_psu/psu_packet_injection.vhd
+++ b/modules/wrsw_psu/psu_packet_injection.vhd
@@ -21,7 +21,7 @@
 -- within each template with a user-provided value.
 -------------------------------------------------------------------------------
 --
-- Copyright (c) 2012 CERN
+-- Copyright (c) 2015 CERN
 --
 -- This source file is free software; you can redistribute it   
 -- and/or modify it under the terms of the GNU Lesser General   

--- a/modules/wrsw_psu/psu_tx_ctrl.vhd
+++ b/modules/wrsw_psu/psu_tx_ctrl.vhd
@@ -10,7 +10,24 @@
 -- Platform   : FPGA-generic
 -- Standard   : VHDL'93
 -------------------------------------------------------------------------------
-- Description:
+-- Description: This is a simple Finite State Machine that controls the operation
+-- of transmitting PTP Announce messages. It looks at the vector (config reg) of
+-- PTP master ports and uses the psu_packet_injection module to inject PTP
+-- Announces to each port, starting with the port that is at the least significant
+-- position in the config reg vector (simple prio_encoder is used). 
+-- this module also creates an interfame gap/spacing between frames.
+-- Once the injection operation is strated, it blocks all the traffic from the NIC
+-- (stall) and cannot be stopped untill Announces on all PTP Master ports (configured
+-- to be) are sent. 
+-- Once finished, FSM goes into IN_HOLDOVER state and cannot be re-triggered until 
+-- back in IDLE. It goes into idle when leaving holdover (falling edge) is detected.
+-- This means that 
+-- * the injection of frames is triggered only when entering holdover (rising edge of 
+--   holdover input)
+-- * the FSM is reseted when exiting holdover
+
+-- TODO: consider possibility of retrigerring/resending frames 
+
 -------------------------------------------------------------------------------

 -- Copyright (c) 2015 CERN / BE-CO-HT

--- a/modules/wrsw_psu/xwrsw_psu.vhd
+++ b/modules/wrsw_psu/xwrsw_psu.vhd
@@ -10,8 +10,72 @@
 -- Platform   : FPGA-generic
 -- Standard   : VHDL'93
 -------------------------------------------------------------------------------
-- Description: This unit supports ultra-fast tx and rx of Announce messages
-- with informatin about holdover
+-- Description: This is a top entity of a PTP Support Unit (PSU) 
+-- 
+-- This module was developed to speed up the propagation of information to the downstream
+-- PTP nodes about the holdover. This is done by speaking directly to rt_subsystem
+-- (SoftPLL) and doing two things:
+-- 1. injecting Announce with the holdover clockClass, as soon as SoftPLL goes into holdover 
+-- 2. recognizing Announce messages wiht holdover clockClass, this information is provided
+--    directly to SoftPLL, the PLL then switches to backup, if available. otherwise, the 
+--    injection is repeated 
+-- 
+-- This unit provides
+-- * snooping of transmitted frames, recognition of PTP Announce frames, remembering of
+--   announce frames and dumping of Announce frames with preconfigured params detected
+-- * ultra-fast transmission of Announce messages with configured ClockClass
+--   to configured ports (PTP Masters) by injecting a remebered Announce
+-- * snooping of received frames, recognition of Announce messages with configured 
+--   ClockClass and other characteristics and providing informaiton about the recognized
+--   Announces
+-- * interface with rt_subsystem, the communication includes
+--   -> rt_subsystem to PSU
+--      1. information about holdover
+--      2. informaiton about current active port
+--      3. command to clear the high bit about detection of preconfigured Announce message
+--   -> PSU to rt_subsystem
+--      1. information that a preconfigured Announce was detected
+
+-- Transmission of Announce messages:
+-- - The module snoops all transmitted frames and recognizes PTP announce messages,
+--   it is possible to recognize Announce send over 
+--   1) raw Ethernet frames (802.1) with and without VLAN TAG
+--   2) IPv4-UDP
+-- - it remembers the frame in the RAM (assuming that the only difference
+--   between Annonce messages sent to different port are:
+--   1) sequence number
+--   2) port number
+--   the above are stored per-port in RAM, the rest of the frame is stored 
+--   for all frames. the RAM memory is devided into 3 parts:
+--   * bank 1
+--   * bank 2
+--   * per-port info
+--   Always, one bank is the one being read, the second is the one being written.
+--   When the frame is validated (rendered OK), two things happen:
+--   1. banks are swapped
+--   2. the sequence ID is written to the "per-port info" addres
+-- - the transmitted Announce message can be configured to be dumped if some
+--   of the following is wrong (this is evaluated only if in Holdover):
+--   1. the message is duplicate, so the sequence number is the same as of the
+--      previous Anounce on that port
+--   2. sequence number is wrong, i.e.different than: current = previous+1
+--   3. sourcePortID does not match the previous Announce
+--   4. clock class is not equal to the holdover ClockClass, configured
+--
+--
+-- Reception of Announce messaeges
+-- - The module snoops all received frames and recognizes PTP announce messages,
+--   it is possible to recognize Announce send over 
+--   1) raw Ethernet frames (802.1) with and without VLAN TAG
+--   2) IPv4-UDP
+-- - [not implemented but prepared for] the sourcePortID is remembered
+-- - preconfigured announce messages are recognized, in particular the module looks for
+--   Announce messages with configured ClockClass (the same config as transmission). 
+--   additionally, it can check whether the SourcePort of the announce message with 
+--   configured ClockClass has the same sourcePort as the previous one [if support implemented].
+--   The sequence number can be checked as well.
+--
+-- NOTE: RAM is shared between psu_anounce_snooper and 
 -------------------------------------------------------------------------------

 -- Copyright (c) 2015 CERN / BE-CO-HT

--- a/syn/scb_8ports/test_scb.xise
+++ b/syn/scb_8ports/test_scb.xise