doc/guides/rawdevs/cnxk_bphy.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2021 Marvell.
   3
   4 Marvell CNXK BPHY Driver
   5 ========================
   6
   7 CN10K/CN9K Fusion product families offer an internal BPHY unit which provides
   8 set of hardware accelerators for performing baseband related operations.
   9 Connectivity to the outside world happens through a block called RFOE which is
  10 backed by ethernet I/O block called CGX or RPM (depending on the chip version).
  11 RFOE stands for Radio Frequency Over Ethernet and provides support for
  12 IEEE 1904.3 (RoE) standard.
  13
  14 Features
  15 --------
  16
  17 The BPHY CGX/RPM implements following features in the rawdev API:
  18
  19 - Access to BPHY CGX/RPM via a set of predefined messages
  20 - Access to BPHY memory
  21
  22 Device Setup
  23 ------------
  24
  25 The BPHY CGX/RPM devices will need to be bound to a user-space IO driver for
  26 use. The script ``dpdk-devbind.py`` script included with DPDK can be used to
  27 view the state of the devices and to bind them to a suitable DPDK-supported
  28 kernel driver. When querying the status of the devices, they will appear under
  29 the category of "Misc (rawdev) devices", i.e. the command
  30 ``dpdk-devbind.py --status-dev misc`` can be used to see the state of those
  31 devices alone.
  32
  33 Before performing actual data transfer one needs to first retrieve number of
  34 available queues with ``rte_rawdev_queue_count()`` and capacity of each
  35 using ``rte_rawdev_queue_conf_get()``.
  36
  37 To perform data transfer use standard ``rte_rawdev_enqueue_buffers()`` and
  38 ``rte_rawdev_dequeue_buffers()`` APIs. Not all messages produce sensible
  39 responses hence dequeueing is not always necessary.
  40
  41 BPHY CGX/RPM PMD
  42 ----------------
  43
  44 BPHY CGX/RPM PMD accepts ``struct cnxk_bphy_cgx_msg`` messages which differ by type and payload.
  45 Message types along with description are listed below. As for the usage examples please refer to
  46 ``cnxk_bphy_cgx_dev_selftest()``.
  47
  48 Get link information
  49 ~~~~~~~~~~~~~~~~~~~~
  50
  51 Message is used to get information about link state.
  52
  53 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_GET_LINKINFO``. In response one will
  54 get message containing payload i.e ``struct cnxk_bphy_cgx_msg_link_info`` filled with information
  55 about current link state.
  56
  57 Change internal loopback state
  58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  59
  60 Message is used to enable or disable internal loopback.
  61
  62 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_INTLBK_ENABLE`` or
  63 ``CNXK_BPHY_CGX_MSG_TYPE_INTLBK_DISABLE``. Former will activate internal loopback while the latter
  64 will do the opposite.
  65
  66 Change PTP RX state
  67 ~~~~~~~~~~~~~~~~~~~
  68
  69 Message is used to enable or disable PTP mode.
  70
  71 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_PTP_RX_ENABLE`` or
  72 ``CNXK_BPHY_CGX_MSG_TYPE_PTP_RX_DISABLE``. Former will enable PTP while the latter will do the
  73 opposite.
  74
  75 Set link mode
  76 ~~~~~~~~~~~~~
  77
  78 Message is used to change link mode.
  79
  80 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_SET_LINK_MODE``. Prior to sending actual
  81 message payload i.e ``struct cnxk_bphy_cgx_msg_link_mode`` needs to be filled with relevant
  82 information.
  83
  84 Change link state
  85 ~~~~~~~~~~~~~~~~~
  86
  87 Message is used to set link up or down.
  88
  89 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_SET_LINK_STATE``. Prior to sending actual
  90 message payload i.e ``struct cnxk_bphy_cgx_msg_set_link_state`` needs to be filled with relevant
  91 information.
  92
  93 Start or stop RX/TX
  94 ~~~~~~~~~~~~~~~~~~~
  95
  96 Message is used to start or stop accepting traffic.
  97
  98 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_START_RXTX`` or
  99 ``CNXK_BPHY_CGX_MSG_TYPE_STOP_RXTX``. Former will enable traffic while the latter will
 100 do the opposite.
 101
 102 BPHY PMD
 103 --------
 104
 105 BPHY PMD accepts ``struct cnxk_bphy_irq_msg`` messages which differ by type and payload.
 106 Message types along with description are listed below. For some usage examples please refer to
 107 ``bphy_rawdev_selftest()``.
 108
 109 Initialize or finalize interrupt handling
 110 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 111
 112 Message is used to setup low level interrupt handling.
 113
 114 Message must have type set to ``CNXK_BPHY_IRQ_MSG_TYPE_INIT`` or ``CNXK_BPHY_IRQ_MSG_TYPE_FINI``.
 115 The former will setup low level interrupt handling while the latter will tear everything down. There
 116 are also two convenience functions namely ``rte_pmd_bphy_intr_init()`` and
 117 ``rte_pmd_bphy_intr_fini()`` that take care of all details.
 118
 119
 120 Get device memory
 121 ~~~~~~~~~~~~~~~~~
 122
 123 Message is used to read device MMIO address.
 124
 125 Message must have type set to ``CNXK_BPHY_IRQ_MSG_TYPE_MEM_GET``. There's a convenience function
 126 ``rte_pmd_bphy_intr_mem_get()`` available that takes care of retrieving that address.
 127
 128 Self test
 129 ---------
 130
 131 On EAL initialization, BPHY CGX/RPM devices will be probed and populated into
 132 the raw devices. The rawdev ID of the device can be obtained using invocation
 133 of ``rte_rawdev_get_dev_id("NAME:x")`` from the test application, where:
 134
 135 - NAME is the desired subsystem: use "BPHY_CGX" for
 136   RFOE module,
 137 - x is the device's bus id specified in "bus:device.func" (BDF) format.
 138
 139 Use this identifier for further rawdev function calls.
 140
 141 The driver's selftest rawdev API can be used to verify the BPHY CGX/RPM
 142 functionality.