.. _xy_pi_clip:

xy_pi_clip
==========

Description
'''''''''''

| 
|  Proportional-Integral gain for multiplexed X-Y data stream,
|  with programmable clip levels.  Timing plan shown below.
| 
|  Spartan-6: 159 LUTs, 1 DSP48A1
|   (not counting ~36 LUTs needed to generate coeff and lim)
|  XXX this is the critical timing path, streamline and/or pipeline some more
|  XXX proportional and integral gain terms need very different scaling?
| 
|  Serious pipelining internally.
|  At any one point, the data flow sequence is:
|    X integral     high-side clip (new data from multiplier summed with previous X integral term)
|    Y integral     high-side clip (new data from multiplier summed with previous Y integral term)
|    X proportional high-side clip (new data from multiplier summed with previous X integral term)
|    Y proportional high-side clip (new data from multiplier summed with previous Y integral term)
|    X integral      low-side clip (recirculated data from high-side clip)
|    Y integral      low-side clip (recirculated data from high-side clip)
|    X proportional  low-side clip (recirculated data from high-side clip)
|    Y proportional  low-side clip (recirculated data from high-side clip)
| 
|         in_xy  coeff   lim
|   sync  xerr
|   .     yerr   x_int
|   .     .      y_int
|   .     .      x_prop
|   .     .      y_prop
|   .     .      .       x_hi
|   .     .      .       y_hi
|   .     .      .       x_hi
|   sync  .      .       y_hi
|   .     .      .       x_lo
|   .     .      .       y_lo
|   .     .      .       x_lo
|   .     .      .       y_lo
|   .     .      .       .      o_sync  out_x
|   .     .      .       .      .       out_y

Pinout
''''''

.. _fig:xy_pi_clip_block:
.. figure:: xy_pi_clip_block.png
    :alt: Schematic symbol

Parameters
''''''''''

.. list-table:: xy_pi_clip_param_table
   :header-rows: 1

   * - Name
     - Min
     - Max
     - Default
     - Description
   * - ff_dshift
     - ?
     - ?
     - 0
     - Deferred ff_ddrive downshift

Ports
'''''

.. list-table:: xy_pi_clip_port_table
   :header-rows: 1

   * - Signal
     - Direction
     - Description
   * - clk
     - Input
     - timespec 6.8 ns
   * - sync
     - Input
     - high for the first of the xy pair
   * - in_xy[17:0]
     - Input
     - 
   * - out_xy[17:0]
     - Output
     - 
   * - o_sync
     - Output
     - 
   * - coeff[17:0]
     - Input
     - 
   * - lim[17:0]
     - Input
     - 
   * - ffd_en
     - Input
     - 
   * - ff_ddrive[17:0]
     - Input
     - FF drive (derivative) to be accumulated in I term
   * - ff_dphase[17:0]
     - Input
     - FF phase (derivative); currently unused
   * - ffp_en
     - Input
     - 
   * - ff_drive[17:0]
     - Input
     - FF drive added to P term
   * - ff_phase[17:0]
     - Input
     - FF phase
   * - clipped[3:0]
     - Output
     - 

Implementation and use
''''''''''''''''''''''

The `portable`_ `Verilog`_
implementation can be found in :ref:`xy_pi_clip_source`

.. _`portable`: https://en.wikipedia.org/wiki/Software_portability
.. _`Verilog`: https://en.wikipedia.org/wiki/Verilog

Timing Diagram
''''''''''''''

A `GTKWave`_-generated timing diagram is shown below:

.. _`GTKWave`: https://gtkwave.sourceforge.net/

.. _fig:xy_pi_clip_timing:
.. figure:: xy_pi_clip_timing.png
    :alt: Timing diagram