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 - Custom interrupt handlers
  22
  23 Device Setup
  24 ------------
  25
  26 The BPHY CGX/RPM devices will need to be bound to a user-space IO driver for
  27 use. The script ``dpdk-devbind.py`` script included with DPDK can be used to
  28 view the state of the devices and to bind them to a suitable DPDK-supported
  29 kernel driver. When querying the status of the devices, they will appear under
  30 the category of "Misc (rawdev) devices", i.e. the command
  31 ``dpdk-devbind.py --status-dev misc`` can be used to see the state of those
  32 devices alone.
  33
  34 Before performing actual data transfer one needs to first retrieve number of
  35 available queues with ``rte_rawdev_queue_count()`` and capacity of each
  36 using ``rte_rawdev_queue_conf_get()``.
  37
  38 To perform data transfer use standard ``rte_rawdev_enqueue_buffers()`` and
  39 ``rte_rawdev_dequeue_buffers()`` APIs. Not all messages produce sensible
  40 responses hence dequeuing is not always necessary.
  41
  42 BPHY CGX/RPM PMD
  43 ----------------
  44
  45 BPHY CGX/RPM PMD accepts ``struct cnxk_bphy_cgx_msg`` messages which differ by type and payload.
  46 Message types along with description are listed below. As for the usage examples please refer to
  47 ``cnxk_bphy_cgx_dev_selftest()``.
  48
  49 Get link information
  50 ~~~~~~~~~~~~~~~~~~~~
  51
  52 Message is used to get information about link state.
  53
  54 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_GET_LINKINFO``. In response one will
  55 get message containing payload i.e ``struct cnxk_bphy_cgx_msg_link_info`` filled with information
  56 about current link state.
  57
  58 Change internal loopback state
  59 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  60
  61 Message is used to enable or disable internal loopback.
  62
  63 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_INTLBK_ENABLE`` or
  64 ``CNXK_BPHY_CGX_MSG_TYPE_INTLBK_DISABLE``. Former will activate internal loopback while the latter
  65 will do the opposite.
  66
  67 Change PTP RX state
  68 ~~~~~~~~~~~~~~~~~~~
  69
  70 Message is used to enable or disable PTP mode.
  71
  72 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_PTP_RX_ENABLE`` or
  73 ``CNXK_BPHY_CGX_MSG_TYPE_PTP_RX_DISABLE``. Former will enable PTP while the latter will do the
  74 opposite.
  75
  76 Set link mode
  77 ~~~~~~~~~~~~~
  78
  79 Message is used to change link mode.
  80
  81 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_SET_LINK_MODE``. Prior to sending actual
  82 message payload i.e ``struct cnxk_bphy_cgx_msg_link_mode`` needs to be filled with relevant
  83 information.
  84
  85 Change link state
  86 ~~~~~~~~~~~~~~~~~
  87
  88 Message is used to set link up or down.
  89
  90 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_SET_LINK_STATE``. Prior to sending actual
  91 message payload i.e ``struct cnxk_bphy_cgx_msg_set_link_state`` needs to be filled with relevant
  92 information.
  93
  94 Start or stop RX/TX
  95 ~~~~~~~~~~~~~~~~~~~
  96
  97 Message is used to start or stop accepting traffic.
  98
  99 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_START_RXTX`` or
 100 ``CNXK_BPHY_CGX_MSG_TYPE_STOP_RXTX``. Former will enable traffic while the latter will
 101 do the opposite.
 102
 103 Change mode from eCPRI to CPRI
 104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 105
 106 Message is used to change operating mode from eCPRI to CPRI along with other
 107 settings.
 108
 109 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_CPRI_MODE_CHANGE``.
 110 Prior to sending actual message payload i.e
 111 ``struct cnxk_bphy_cgx_msg_cpri_mode_change`` needs to be filled with relevant
 112 information.
 113
 114 Enable TX for CPRI SERDES
 115 ~~~~~~~~~~~~~~~~~~~~~~~~~
 116
 117 Message is used to enable TX for SERDES configured in CPRI mode.
 118
 119 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_CPRI_TX_CONTROL``.
 120 Prior to sending actual message payload i.e
 121 ``struct cnxk_bphy_cgx_msg_cpri_mode_tx_ctrl`` needs to be filled with relevant
 122 information.
 123
 124 Change CPRI misc settings
 125 ~~~~~~~~~~~~~~~~~~~~~~~~~
 126
 127 Message is used to change misc CPRI settings, for example to reset RX state
 128 machine on CPRI SERDES.
 129
 130 Message must have type set to ``CNXK_BPHY_CGX_MSG_TYPE_CPRI_MODE_MISC``.
 131 Prior to sending actual message payload i.e
 132 ``struct cnxk_bphy_cgx_msg_cpri_mode_misc`` needs to be filled with relevant
 133 information.
 134
 135 BPHY PMD
 136 --------
 137
 138 BPHY PMD accepts ``struct cnxk_bphy_irq_msg`` messages which differ by type and payload.
 139 Message types along with description are listed below. For some usage examples please refer to
 140 ``bphy_rawdev_selftest()``.
 141
 142 Initialize or finalize interrupt handling
 143 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 144
 145 Message is used to setup low level interrupt handling.
 146
 147 Message must have type set to ``CNXK_BPHY_IRQ_MSG_TYPE_INIT`` or ``CNXK_BPHY_IRQ_MSG_TYPE_FINI``.
 148 The former will setup low level interrupt handling while the latter will tear everything down. There
 149 are also two convenience functions namely ``rte_pmd_bphy_intr_init()`` and
 150 ``rte_pmd_bphy_intr_fini()`` that take care of all details.
 151
 152
 153 Register or remove interrupt handler
 154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 155
 156 Message is used setup custom interrupt handler.
 157
 158 Message must have type set to ``CNXK_BPHY_IRQ_MSG_TYPE_REGISTER`` or
 159 ``CNXK_BPHY_IRQ_MSG_TYPE_UNREGISTER``. The former will register an interrupt handler while the
 160 latter will remove it. Prior sending actual message payload i.e ``struct cnxk_bphy_irq_info`` needs
 161 to be filled with relevant information. There are also two convenience functions namely
 162 ``rte_pmd_bphy_intr_register()`` and ``rte_pmd_bphy_intr_unregister()`` that take care of all
 163 details.
 164
 165 Get device memory
 166 ~~~~~~~~~~~~~~~~~
 167
 168 Message is used to read device MMIO address.
 169
 170 Message must have type set to ``CNXK_BPHY_IRQ_MSG_TYPE_MEM_GET``. There's a convenience function
 171 ``rte_pmd_bphy_intr_mem_get()`` available that takes care of retrieving that address.
 172
 173 Self test
 174 ---------
 175
 176 On EAL initialization BPHY and BPHY CGX/RPM devices will be probed and populated into
 177 the raw devices. The rawdev ID of the device can be obtained using invocation
 178 of ``rte_rawdev_get_dev_id("NAME:x")`` from the test application, where:
 179
 180 - NAME is the desired subsystem: use "BPHY" for regular, and "BPHY_CGX" for
 181   RFOE module.
 182 - x is the device's bus id specified in "bus:device.func" (BDF) format. BDF follows convention
 183   used by lspci i.e bus, device and func are specified using respectively two, two and one hex
 184   digit(s).
 185
 186 Use this identifier for further rawdev function calls.
 187
 188 Selftest rawdev API can be used to verify the BPHY and BPHY CGX/RPM functionality.