doc/guides/sample_app_ug/ptpclient.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2015 Intel Corporation. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31
  32 PTP Client Sample Application
  33 =============================
  34
  35 The PTP (Precision Time Protocol) client sample application is a simple
  36 example of using the DPDK IEEE1588 API to communicate with a PTP master clock
  37 to synchronize the time on the NIC and, optionally, on the Linux system.
  38
  39 Note, PTP is a time syncing protocol and cannot be used within DPDK as a
  40 time-stamping mechanism. See the following for an explanation of the protocol:
  41 `Precision Time Protocol
  42 <https://en.wikipedia.org/wiki/Precision_Time_Protocol>`_.
  43
  44
  45 Limitations
  46 -----------
  47
  48 The PTP sample application is intended as a simple reference implementation of
  49 a PTP client using the DPDK IEEE1588 API.
  50 In order to keep the application simple the following assumptions are made:
  51
  52 * The first discovered master is the master for the session.
  53 * Only L2 PTP packets are supported.
  54 * Only the PTP v2 protocol is supported.
  55 * Only the slave clock is implemented.
  56
  57
  58 How the Application Works
  59 -------------------------
  60
  61 .. _figure_ptpclient_highlevel:
  62
  63 .. figure:: img/ptpclient.*
  64
  65    PTP Synchronization Protocol
  66
  67 The PTP synchronization in the sample application works as follows:
  68
  69 * Master sends *Sync* message - the slave saves it as T2.
  70 * Master sends *Follow Up* message and sends time of T1.
  71 * Slave sends *Delay Request* frame to PTP Master and stores T3.
  72 * Master sends *Delay Response* T4 time which is time of received T3.
  73
  74 The adjustment for slave can be represented as:
  75
  76    adj = -[(T2-T1)-(T4 - T3)]/2
  77
  78 If the command line parameter ``-T 1`` is used the application also
  79 synchronizes the PTP PHC clock with the Linux kernel clock.
  80
  81
  82 Compiling the Application
  83 -------------------------
  84
  85 To compile the application, export the path to the DPDK source tree and edit
  86 the ``config/common_linuxapp`` configuration file to enable IEEE1588:
  87
  88 .. code-block:: console
  89
  90     export RTE_SDK=/path/to/rte_sdk
  91
  92     # Edit  common_linuxapp and set the following options:
  93     CONFIG_RTE_LIBRTE_IEEE1588=y
  94
  95 Set the target, for example:
  96
  97 .. code-block:: console
  98
  99     export RTE_TARGET=x86_64-native-linuxapp-gcc
 100
 101 See the *DPDK Getting Started* Guide for possible ``RTE_TARGET`` values.
 102
 103 Build the application as follows:
 104
 105 .. code-block:: console
 106
 107     # Recompile DPDK.
 108     make install T=$RTE_TARGET
 109
 110     # Compile the application.
 111     cd ${RTE_SDK}/examples/ptpclient
 112     make
 113
 114
 115 Running the Application
 116 -----------------------
 117
 118 To run the example in a ``linuxapp`` environment:
 119
 120 .. code-block:: console
 121
 122     ./build/ptpclient -l 1 -n 4 -- -p 0x1 -T 0
 123
 124 Refer to *DPDK Getting Started Guide* for general information on running
 125 applications and the Environment Abstraction Layer (EAL) options.
 126
 127 * ``-p portmask``: Hexadecimal portmask.
 128 * ``-T 0``: Update only the PTP slave clock.
 129 * ``-T 1``: Update the PTP slave clock and synchronize the Linux Kernel to the PTP clock.
 130
 131
 132 Code Explanation
 133 ----------------
 134
 135 The following sections provide an explanation of the main components of the
 136 code.
 137
 138 All DPDK library functions used in the sample code are prefixed with ``rte_``
 139 and are explained in detail in the *DPDK API Documentation*.
 140
 141
 142 The Main Function
 143 ~~~~~~~~~~~~~~~~~
 144
 145 The ``main()`` function performs the initialization and calls the execution
 146 threads for each lcore.
 147
 148 The first task is to initialize the Environment Abstraction Layer (EAL).  The
 149 ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
 150 function. The value returned is the number of parsed arguments:
 151
 152 .. code-block:: c
 153
 154     int ret = rte_eal_init(argc, argv);
 155     if (ret < 0)
 156         rte_exit(EXIT_FAILURE, "Error with EAL initialization\n");
 157
 158 And than we parse application specific arguments
 159
 160 .. code-block:: c
 161
 162     argc -= ret;
 163     argv += ret;
 164
 165     ret = ptp_parse_args(argc, argv);
 166     if (ret < 0)
 167         rte_exit(EXIT_FAILURE, "Error with PTP initialization\n");
 168
 169 The ``main()`` also allocates a mempool to hold the mbufs (Message Buffers)
 170 used by the application:
 171
 172 .. code-block:: c
 173
 174     mbuf_pool = rte_pktmbuf_pool_create("MBUF_POOL", NUM_MBUFS * nb_ports,
 175            MBUF_CACHE_SIZE, 0, RTE_MBUF_DEFAULT_BUF_SIZE, rte_socket_id());
 176
 177 Mbufs are the packet buffer structure used by DPDK. They are explained in
 178 detail in the "Mbuf Library" section of the *DPDK Programmer's Guide*.
 179
 180 The ``main()`` function also initializes all the ports using the user defined
 181 ``port_init()`` function with portmask provided by user:
 182
 183 .. code-block:: c
 184
 185     for (portid = 0; portid < nb_ports; portid++)
 186         if ((ptp_enabled_port_mask & (1 << portid)) != 0) {
 187
 188             if (port_init(portid, mbuf_pool) == 0) {
 189                 ptp_enabled_ports[ptp_enabled_port_nb] = portid;
 190                 ptp_enabled_port_nb++;
 191             } else {
 192                 rte_exit(EXIT_FAILURE, "Cannot init port %"PRIu8 "\n",
 193                         portid);
 194             }
 195         }
 196
 197
 198 Once the initialization is complete, the application is ready to launch a
 199 function on an lcore. In this example ``lcore_main()`` is called on a single
 200 lcore.
 201
 202 .. code-block:: c
 203
 204         lcore_main();
 205
 206 The ``lcore_main()`` function is explained below.
 207
 208
 209 The Lcores Main
 210 ~~~~~~~~~~~~~~~
 211
 212 As we saw above the ``main()`` function calls an application function on the
 213 available lcores.
 214
 215 The main work of the application is done within the loop:
 216
 217 .. code-block:: c
 218
 219         for (portid = 0; portid < ptp_enabled_port_nb; portid++) {
 220
 221             portid = ptp_enabled_ports[portid];
 222             nb_rx = rte_eth_rx_burst(portid, 0, &m, 1);
 223
 224             if (likely(nb_rx == 0))
 225                 continue;
 226
 227             if (m->ol_flags & PKT_RX_IEEE1588_PTP)
 228                 parse_ptp_frames(portid, m);
 229
 230             rte_pktmbuf_free(m);
 231         }
 232
 233 Packets are received one by one on the RX ports and, if required, PTP response
 234 packets are transmitted on the TX ports.
 235
 236 If the offload flags in the mbuf indicate that the packet is a PTP packet then
 237 the packet is parsed to determine which type:
 238
 239 .. code-block:: c
 240
 241             if (m->ol_flags & PKT_RX_IEEE1588_PTP)
 242                  parse_ptp_frames(portid, m);
 243
 244
 245 All packets are freed explicitly using ``rte_pktmbuf_free()``.
 246
 247 The forwarding loop can be interrupted and the application closed using
 248 ``Ctrl-C``.
 249
 250
 251 PTP parsing
 252 ~~~~~~~~~~~
 253
 254 The ``parse_ptp_frames()`` function processes PTP packets, implementing slave
 255 PTP IEEE1588 L2 functionality.
 256
 257 .. code-block:: c
 258
 259     void
 260     parse_ptp_frames(uint8_t portid, struct rte_mbuf *m) {
 261         struct ptp_header *ptp_hdr;
 262         struct ether_hdr *eth_hdr;
 263         uint16_t eth_type;
 264
 265         eth_hdr = rte_pktmbuf_mtod(m, struct ether_hdr *);
 266         eth_type = rte_be_to_cpu_16(eth_hdr->ether_type);
 267
 268         if (eth_type == PTP_PROTOCOL) {
 269             ptp_data.m = m;
 270             ptp_data.portid = portid;
 271             ptp_hdr = (struct ptp_header *)(rte_pktmbuf_mtod(m, char *)
 272                         + sizeof(struct ether_hdr));
 273
 274             switch (ptp_hdr->msgtype) {
 275             case SYNC:
 276                 parse_sync(&ptp_data);
 277                 break;
 278             case FOLLOW_UP:
 279                 parse_fup(&ptp_data);
 280                 break;
 281             case DELAY_RESP:
 282                 parse_drsp(&ptp_data);
 283                 print_clock_info(&ptp_data);
 284                 break;
 285             default:
 286                 break;
 287             }
 288         }
 289     }
 290
 291 There are 3 types of packets on the RX path which we must parse to create a minimal
 292 implementation of the PTP slave client:
 293
 294 * SYNC packet.
 295 * FOLLOW UP packet
 296 * DELAY RESPONSE packet.
 297
 298 When we parse the *FOLLOW UP* packet we also create and send a *DELAY_REQUEST* packet.
 299 Also when we parse the *DELAY RESPONSE* packet, and all conditions are met we adjust the PTP slave clock.