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