1.. SPDX-License-Identifier: GPL-2.0 2 3======================== 4ptp_ocp devlink support 5======================== 6 7This document describes the devlink features implemented by the ``ptp_ocp`` 8device driver: the info versions it reports and its flash update support. 9 10Info versions 11============= 12 13The ``ptp_ocp`` driver reports the following versions 14 15.. list-table:: devlink info versions implemented 16 :widths: 5 5 90 17 18 * - Name 19 - Type 20 - Description 21 * - ``fw`` 22 - running 23 - Version of the firmware running on the card. Reported as ``loader`` 24 instead when the card is running the firmware loader. 25 * - ``board.id`` 26 - fixed 27 - Board identifier, read from the on-card EEPROM. 28 * - ``cpld.id`` 29 - fixed 30 - Lattice device ID (IDCODE) of the TAP CPLD, formatted as ``0x%08x``. 31 Only present on ADVA TimeCard X1 boards, which are the only ones 32 carrying that CPLD. Reading it claims the shared I2C bus and 33 reprograms the on-card mux, so the driver does that from its own 34 worker and reports the cached value here; the version is omitted 35 until that read has succeeded. The read is made once per binding 36 and again after a successful CPLD update. 37 * - ``fw.cpld`` 38 - running 39 - USERCODE of the image programmed into the TAP CPLD, formatted as 40 ``0x%08x``. Read together with ``cpld.id`` and reported the same 41 way. This is the component name to pass to ``devlink dev flash`` 42 to update the CPLD. 43 44Flash update 45============ 46 47The driver implements ``devlink dev flash`` for two separate targets, 48selected with the component name. 49 50.. list-table:: Flash components 51 :widths: 20 80 52 53 * - Component 54 - Description 55 * - (none) 56 - The card's own flash, written through the SPI controller the driver 57 exposes. The card runs the new image after its next reset. 58 * - ``fw.cpld`` 59 - The configuration flash of the TAP CPLD on ADVA TimeCard X1 boards, 60 programmed over I2C with the MachXO3 in-system programming commands 61 and activated with a REFRESH, so the new image runs immediately. 62 The image is the raw configuration bitstream. The only check the 63 driver makes is that its length is a non-zero multiple of the 64 16-byte page size, so a container such as ``.jed`` has to be 65 converted first rather than passed through - one whose length 66 happens to be a multiple of 16 would be programmed as if it were 67 a bitstream. 68 69Programming the CPLD claims the shared I2C bus for the whole cycle, so 70reads of the card's EEPROM block until it completes. Progress is reported 71with the standard devlink status notifications. 72 73Example:: 74 75 $ devlink dev flash pci/0000:02:00.0 file adva-cpld.bin component fw.cpld 76