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 -c 2 -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_mempool_create("MBUF_POOL",
 175                                    NUM_MBUFS * nb_ports,
 176                                    MBUF_SIZE,
 177                                    MBUF_CACHE_SIZE,
 178                                    sizeof(struct rte_pktmbuf_pool_private),
 179                                    rte_pktmbuf_pool_init, NULL,
 180                                    rte_pktmbuf_init,      NULL,
 181                                    rte_socket_id(),
 182                                    0);
 183
 184 Mbufs are the packet buffer structure used by DPDK. They are explained in
 185 detail in the "Mbuf Library" section of the *DPDK Programmer's Guide*.
 186
 187 The ``main()`` function also initializes all the ports using the user defined
 188 ``port_init()`` function with portmask provided by user:
 189
 190 .. code-block:: c
 191
 192     for (portid = 0; portid < nb_ports; portid++)
 193         if ((ptp_enabled_port_mask & (1 << portid)) != 0) {
 194
 195             if (port_init(portid, mbuf_pool) == 0) {
 196                 ptp_enabled_ports[ptp_enabled_port_nb] = portid;
 197                 ptp_enabled_port_nb++;
 198             } else {
 199                 rte_exit(EXIT_FAILURE, "Cannot init port %"PRIu8 "\n",
 200                         portid);
 201             }
 202         }
 203
 204
 205 Once the initialization is complete, the application is ready to launch a
 206 function on an lcore. In this example ``lcore_main()`` is called on a single
 207 lcore.
 208
 209 .. code-block:: c
 210
 211         lcore_main();
 212
 213 The ``lcore_main()`` function is explained below.
 214
 215
 216 The Lcores Main
 217 ~~~~~~~~~~~~~~~
 218
 219 As we saw above the ``main()`` function calls an application function on the
 220 available lcores.
 221
 222 The main work of the application is done within the loop:
 223
 224 .. code-block:: c
 225
 226         for (portid = 0; portid < ptp_enabled_port_nb; portid++) {
 227
 228             portid = ptp_enabled_ports[portid];
 229             nb_rx = rte_eth_rx_burst(portid, 0, &m, 1);
 230
 231             if (likely(nb_rx == 0))
 232                 continue;
 233
 234             if (m->ol_flags & PKT_RX_IEEE1588_PTP)
 235                 parse_ptp_frames(portid, m);
 236
 237             rte_pktmbuf_free(m);
 238         }
 239
 240 Packets are received one by one on the RX ports and, if required, PTP response
 241 packets are transmitted on the TX ports.
 242
 243 If the offload flags in the mbuf indicate that the packet is a PTP packet then
 244 the packet is parsed to determine which type:
 245
 246 .. code-block:: c
 247
 248             if (m->ol_flags & PKT_RX_IEEE1588_PTP)
 249                  parse_ptp_frames(portid, m);
 250
 251
 252 All packets are freed explicitly using ``rte_pktmbuf_free()``.
 253
 254 The forwarding loop can be interrupted and the application closed using
 255 ``Ctrl-C``.
 256
 257
 258 PTP parsing
 259 ~~~~~~~~~~~
 260
 261 The ``parse_ptp_frames()`` function processes PTP packets, implementing slave
 262 PTP IEEE1588 L2 functionality.
 263
 264 .. code-block:: c
 265
 266     void
 267     parse_ptp_frames(uint8_t portid, struct rte_mbuf *m) {
 268         struct ptp_header *ptp_hdr;
 269         struct ether_hdr *eth_hdr;
 270         uint16_t eth_type;
 271
 272         eth_hdr = rte_pktmbuf_mtod(m, struct ether_hdr *);
 273         eth_type = rte_be_to_cpu_16(eth_hdr->ether_type);
 274
 275         if (eth_type == PTP_PROTOCOL) {
 276             ptp_data.m = m;
 277             ptp_data.portid = portid;
 278             ptp_hdr = (struct ptp_header *)(rte_pktmbuf_mtod(m, char *)
 279                         + sizeof(struct ether_hdr));
 280
 281             switch (ptp_hdr->msgtype) {
 282             case SYNC:
 283                 parse_sync(&ptp_data);
 284                 break;
 285             case FOLLOW_UP:
 286                 parse_fup(&ptp_data);
 287                 break;
 288             case DELAY_RESP:
 289                 parse_drsp(&ptp_data);
 290                 print_clock_info(&ptp_data);
 291                 break;
 292             default:
 293                 break;
 294             }
 295         }
 296     }
 297
 298 There are 3 types of packets on the RX path which we must parse to create a minimal
 299 implementation of the PTP slave client:
 300
 301 * SYNC packet.
 302 * FOLLOW UP packet
 303 * DELAY RESPONSE packet.
 304
 305 When we parse the *FOLLOW UP* packet we also create and send a *DELAY_REQUEST* packet.
 306 Also when we parse the *DELAY RESPONSE* packet, and all conditions are met we adjust the PTP slave clock.