docs: networking: timestamping: update for DSA switches

allow the delivery of multiple hardware timestamps for the same packet, so

anybody else except for the DSA switch port must be prevented from doing so.

In code, DSA provides for most of the infrastructure for timestamping already,

in generic code: a BPF classifier (``ptp_classify_raw``) is used to identify

PTP event messages (any other packets, including PTP general messages, are not

timestamped), and provides two hooks to drivers:

- ``.port_txtstamp()``: The driver is passed a clone of the timestampable skb

  to be transmitted, before actually transmitting it. Typically, a switch will

  have a PTP TX timestamp register (or sometimes a FIFO) where the timestamp

  becomes available. There may be an IRQ that is raised upon this timestamp's

  availability, or the driver might have to poll after invoking

  ``dev_queue_xmit()`` towards the host interface. Either way, in the

  ``.port_txtstamp()`` method, the driver only needs to save the clone for

  later use (when the timestamp becomes available). Each skb is annotated with

  a pointer to its clone, in ``DSA_SKB_CB(skb)->clone``, to ease the driver's

  job of keeping track of which clone belongs to which skb.

- ``.port_rxtstamp()``: The original (and only) timestampable skb is provided

  to the driver, for it to annotate it with a timestamp, if that is immediately

  available, or defer to later. On reception, timestamps might either be

  available in-band (through metadata in the DSA header, or attached in other

  ways to the packet), or out-of-band (through another RX timestamping FIFO).

  Deferral on RX is typically necessary when retrieving the timestamp needs a

  sleepable context. In that case, it is the responsibility of the DSA driver

  to call ``netif_rx_ni()`` on the freshly timestamped skb.

In the generic layer, DSA provides the following infrastructure for PTP

timestamping:

- ``.port_txtstamp()``: a hook called prior to the transmission of

  packets with a hardware TX timestamping request from user space.

  This is required for two-step timestamping, since the hardware

  timestamp becomes available after the actual MAC transmission, so the

  driver must be prepared to correlate the timestamp with the original

  packet so that it can re-enqueue the packet back into the socket's

  error queue. To save the packet for when the timestamp becomes

  available, the driver can call ``skb_clone_sk`` , save the clone pointer

  in skb->cb and enqueue a tx skb queue. Typically, a switch will have a

  PTP TX timestamp register (or sometimes a FIFO) where the timestamp

  becomes available. In case of a FIFO, the hardware might store

  key-value pairs of PTP sequence ID/message type/domain number and the

  actual timestamp. To perform the correlation correctly between the

  packets in a queue waiting for timestamping and the actual timestamps,

  drivers can use a BPF classifier (``ptp_classify_raw``) to identify

  the PTP transport type, and ``ptp_parse_header`` to interpret the PTP

  header fields. There may be an IRQ that is raised upon this

  timestamp's availability, or the driver might have to poll after

  invoking ``dev_queue_xmit()`` towards the host interface.

  One-step TX timestamping do not require packet cloning, since there is

  no follow-up message required by the PTP protocol (because the

  TX timestamp is embedded into the packet by the MAC), and therefore

  user space does not expect the packet annotated with the TX timestamp

  to be re-enqueued into its socket's error queue.

- ``.port_rxtstamp()``: On RX, the BPF classifier is run by DSA to

  identify PTP event messages (any other packets, including PTP general

  messages, are not timestamped). The original (and only) timestampable

  skb is provided to the driver, for it to annotate it with a timestamp,

  if that is immediately available, or defer to later. On reception,

  timestamps might either be available in-band (through metadata in the

  DSA header, or attached in other ways to the packet), or out-of-band

  (through another RX timestamping FIFO). Deferral on RX is typically

  necessary when retrieving the timestamp needs a sleepable context. In

  that case, it is the responsibility of the DSA driver to call

  ``netif_rx_ni()`` on the freshly timestamped skb.

3.2.2 Ethernet PHYs

^^^^^^^^^^^^^^^^^^^