net: ena: Add PHC documentation

than RX copybreak bytes is received, it is copied into a new memory

buffer and the RX descriptor is returned to HW.

.. _`PHC`:

PTP Hardware Clock (PHC)

========================

.. _`ptp-userspace-api`: https://docs.kernel.org/driver-api/ptp.html#ptp-hardware-clock-user-space-api

.. _`testptp`: https://elixir.bootlin.com/linux/latest/source/tools/testing/selftests/ptp/testptp.c

ENA Linux driver supports PTP hardware clock providing timestamp reference to achieve nanosecond resolution.

**PHC support**

PHC depends on the PTP module, which needs to be either loaded as a module or compiled into the kernel.

Verify if the PTP module is present:

.. code-block:: shell

  grep -w '^CONFIG_PTP_1588_CLOCK=[ym]' /boot/config-`uname -r`

- If no output is provided, the ENA driver cannot be loaded with PHC support.

**PHC activation**

The feature is turned off by default, in order to turn the feature on, the ENA driver

can be loaded in the following way:

- devlink:

.. code-block:: shell

  sudo devlink dev param set pci/<domain:bus:slot.function> name enable_phc value true cmode driverinit

  sudo devlink dev reload pci/<domain:bus:slot.function>

  # for example:

  sudo devlink dev param set pci/0000:00:06.0 name enable_phc value true cmode driverinit

  sudo devlink dev reload pci/0000:00:06.0

All available PTP clock sources can be tracked here:

.. code-block:: shell

  ls /sys/class/ptp

PHC support and capabilities can be verified using ethtool:

.. code-block:: shell

  ethtool -T <interface>

**PHC timestamp**

To retrieve PHC timestamp, use `ptp-userspace-api`_, usage example using `testptp`_:

.. code-block:: shell

  testptp -d /dev/ptp$(ethtool -T <interface> | awk '/PTP Hardware Clock:/ {print $NF}') -k 1

PHC get time requests should be within reasonable bounds,

avoid excessive utilization to ensure optimal performance and efficiency.

The ENA device restricts the frequency of PHC get time requests to a maximum

of 125 requests per second. If this limit is surpassed, the get time request

will fail, leading to an increment in the phc_err_ts statistic.

**PHC statistics**

PHC can be monitored using debugfs (if mounted):

.. code-block:: shell

  sudo cat /sys/kernel/debug/<domain:bus:slot.function>/phc_stats

  # for example:

  sudo cat /sys/kernel/debug/0000:00:06.0/phc_stats

PHC errors must remain below 1% of all PHC requests to maintain the desired level of accuracy and reliability

=================   ======================================================

**phc_cnt**         | Number of successful retrieved timestamps (below expire timeout).

**phc_exp**         | Number of expired retrieved timestamps (above expire timeout).

**phc_skp**         | Number of skipped get time attempts (during block period).

**phc_err_dv**      | Number of failed get time attempts due to device errors (entering into block state).

**phc_err_ts**      | Number of failed get time attempts due to timestamp errors (entering into block state),

                    | This occurs if driver exceeded the request limit or device received an invalid timestamp.

=================   ======================================================

PHC timeouts:

=================   ======================================================

**expire**          | Max time for a valid timestamp retrieval, passing this threshold will fail

                    | the get time request and block new requests until block timeout.

**block**           | Blocking period starts once get time request expires or fails,

                    | all get time requests during block period will be skipped.

=================   ======================================================

Statistics

==========