1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2015 Intel Corporation. 3 4PTP Client Sample Application 5============================= 6 7The PTP (Precision Time Protocol) client sample application is a simple 8example of using the DPDK IEEE1588 API to communicate with a PTP master clock 9to synchronize the time on the NIC and, optionally, on the Linux system. 10 11Note, PTP is a time syncing protocol and cannot be used within DPDK as a 12time-stamping mechanism. See the following for an explanation of the protocol: 13`Precision Time Protocol 14<https://en.wikipedia.org/wiki/Precision_Time_Protocol>`_. 15 16 17Limitations 18----------- 19 20The PTP sample application is intended as a simple reference implementation of 21a PTP client using the DPDK IEEE1588 API. 22In order to keep the application simple the following assumptions are made: 23 24* The first discovered master is the main for the session. 25* Only L2 PTP packets are supported. 26* Only the PTP v2 protocol is supported. 27* Only the slave clock is implemented. 28 29 30How the Application Works 31------------------------- 32 33.. _figure_ptpclient_highlevel: 34 35.. figure:: img/ptpclient.* 36 37 PTP Synchronization Protocol 38 39The PTP synchronization in the sample application works as follows: 40 41* Master sends *Sync* message - the slave saves it as T2. 42* Master sends *Follow Up* message and sends time of T1. 43* Slave sends *Delay Request* frame to PTP Master and stores T3. 44* Master sends *Delay Response* T4 time which is time of received T3. 45 46The adjustment for slave can be represented as: 47 48 adj = -[(T2-T1)-(T4 - T3)]/2 49 50If the command line parameter ``-T 1`` is used the application also 51synchronizes the PTP PHC clock with the Linux kernel clock. 52 53Compiling the Application 54------------------------- 55 56To compile the sample application see :doc:`compiling`. 57 58The application is located in the ``ptpclient`` sub-directory. 59 60 61Running the Application 62----------------------- 63 64To run the example in a ``linux`` environment: 65 66.. code-block:: console 67 68 ./<build_dir>/examples/dpdk-ptpclient -l 1 -n 4 -- -p 0x1 -T 0 69 70Refer to *DPDK Getting Started Guide* for general information on running 71applications and the Environment Abstraction Layer (EAL) options. 72 73* ``-p portmask``: Hexadecimal portmask. 74* ``-T 0``: Update only the PTP slave clock. 75* ``-T 1``: Update the PTP slave clock and synchronize the Linux Kernel to the PTP clock. 76 77 78Code Explanation 79---------------- 80 81The following sections provide an explanation of the main components of the 82code. 83 84All DPDK library functions used in the sample code are prefixed with ``rte_`` 85and are explained in detail in the *DPDK API Documentation*. 86 87 88The Main Function 89~~~~~~~~~~~~~~~~~ 90 91The ``main()`` function performs the initialization and calls the execution 92threads for each lcore. 93 94The first task is to initialize the Environment Abstraction Layer (EAL). The 95``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()`` 96function. The value returned is the number of parsed arguments: 97 98.. code-block:: c 99 100 int ret = rte_eal_init(argc, argv); 101 if (ret < 0) 102 rte_exit(EXIT_FAILURE, "Error with EAL initialization\n"); 103 104And than we parse application specific arguments 105 106.. code-block:: c 107 108 argc -= ret; 109 argv += ret; 110 111 ret = ptp_parse_args(argc, argv); 112 if (ret < 0) 113 rte_exit(EXIT_FAILURE, "Error with PTP initialization\n"); 114 115The ``main()`` also allocates a mempool to hold the mbufs (Message Buffers) 116used by the application: 117 118.. code-block:: c 119 120 mbuf_pool = rte_pktmbuf_pool_create("MBUF_POOL", NUM_MBUFS * nb_ports, 121 MBUF_CACHE_SIZE, 0, RTE_MBUF_DEFAULT_BUF_SIZE, rte_socket_id()); 122 123Mbufs are the packet buffer structure used by DPDK. They are explained in 124detail in the "Mbuf Library" section of the *DPDK Programmer's Guide*. 125 126The ``main()`` function also initializes all the ports using the user defined 127``port_init()`` function with portmask provided by user: 128 129.. code-block:: c 130 131 for (portid = 0; portid < nb_ports; portid++) 132 if ((ptp_enabled_port_mask & (1 << portid)) != 0) { 133 134 if (port_init(portid, mbuf_pool) == 0) { 135 ptp_enabled_ports[ptp_enabled_port_nb] = portid; 136 ptp_enabled_port_nb++; 137 } else { 138 rte_exit(EXIT_FAILURE, "Cannot init port %"PRIu8 "\n", 139 portid); 140 } 141 } 142 143 144Once the initialization is complete, the application is ready to launch a 145function on an lcore. In this example ``lcore_main()`` is called on a single 146lcore. 147 148.. code-block:: c 149 150 lcore_main(); 151 152The ``lcore_main()`` function is explained below. 153 154 155The Lcores Main 156~~~~~~~~~~~~~~~ 157 158As we saw above the ``main()`` function calls an application function on the 159available lcores. 160 161The main work of the application is done within the loop: 162 163.. code-block:: c 164 165 for (portid = 0; portid < ptp_enabled_port_nb; portid++) { 166 167 portid = ptp_enabled_ports[portid]; 168 nb_rx = rte_eth_rx_burst(portid, 0, &m, 1); 169 170 if (likely(nb_rx == 0)) 171 continue; 172 173 if (m->ol_flags & PKT_RX_IEEE1588_PTP) 174 parse_ptp_frames(portid, m); 175 176 rte_pktmbuf_free(m); 177 } 178 179Packets are received one by one on the RX ports and, if required, PTP response 180packets are transmitted on the TX ports. 181 182If the offload flags in the mbuf indicate that the packet is a PTP packet then 183the packet is parsed to determine which type: 184 185.. code-block:: c 186 187 if (m->ol_flags & PKT_RX_IEEE1588_PTP) 188 parse_ptp_frames(portid, m); 189 190 191All packets are freed explicitly using ``rte_pktmbuf_free()``. 192 193The forwarding loop can be interrupted and the application closed using 194``Ctrl-C``. 195 196 197PTP parsing 198~~~~~~~~~~~ 199 200The ``parse_ptp_frames()`` function processes PTP packets, implementing slave 201PTP IEEE1588 L2 functionality. 202 203.. code-block:: c 204 205 void 206 parse_ptp_frames(uint16_t portid, struct rte_mbuf *m) { 207 struct ptp_header *ptp_hdr; 208 struct rte_ether_hdr *eth_hdr; 209 uint16_t eth_type; 210 211 eth_hdr = rte_pktmbuf_mtod(m, struct rte_ether_hdr *); 212 eth_type = rte_be_to_cpu_16(eth_hdr->ether_type); 213 214 if (eth_type == PTP_PROTOCOL) { 215 ptp_data.m = m; 216 ptp_data.portid = portid; 217 ptp_hdr = (struct ptp_header *)(rte_pktmbuf_mtod(m, char *) 218 + sizeof(struct rte_ether_hdr)); 219 220 switch (ptp_hdr->msgtype) { 221 case SYNC: 222 parse_sync(&ptp_data); 223 break; 224 case FOLLOW_UP: 225 parse_fup(&ptp_data); 226 break; 227 case DELAY_RESP: 228 parse_drsp(&ptp_data); 229 print_clock_info(&ptp_data); 230 break; 231 default: 232 break; 233 } 234 } 235 } 236 237There are 3 types of packets on the RX path which we must parse to create a minimal 238implementation of the PTP slave client: 239 240* SYNC packet. 241* FOLLOW UP packet 242* DELAY RESPONSE packet. 243 244When we parse the *FOLLOW UP* packet we also create and send a *DELAY_REQUEST* packet. 245Also when we parse the *DELAY RESPONSE* packet, and all conditions are met we adjust the PTP slave clock. 246