net/i40e: fix link down and negotiation
[dpdk.git] / doc / guides / nics / dpaa2.rst
1 ..  BSD LICENSE
2     Copyright 2016 NXP.
3
4     Redistribution and use in source and binary forms, with or without
5     modification, are permitted provided that the following conditions
6     are met:
7
8     * Redistributions of source code must retain the above copyright
9     notice, this list of conditions and the following disclaimer.
10     * Redistributions in binary form must reproduce the above copyright
11     notice, this list of conditions and the following disclaimer in
12     the documentation and/or other materials provided with the
13     distribution.
14     * Neither the name of NXP nor the names of its
15     contributors may be used to endorse or promote products derived
16     from this software without specific prior written permission.
17
18     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29
30 DPAA2 Poll Mode Driver
31 ======================
32
33 The DPAA2 NIC PMD (**librte_pmd_dpaa2**) provides poll mode driver
34 support for the inbuilt NIC found in the **NXP DPAA2** SoC family.
35
36 More information can be found at `NXP Official Website
37 <http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/qoriq-arm-processors:QORIQ-ARM>`_.
38
39 NXP DPAA2 (Data Path Acceleration Architecture Gen2)
40 ----------------------------------------------------
41
42 This section provides an overview of the NXP DPAA2 architecture
43 and how it is integrated into the DPDK.
44
45 Contents summary
46
47 - DPAA2 overview
48 - Overview of DPAA2 objects
49 - DPAA2 driver architecture overview
50
51 .. _dpaa2_overview:
52
53 DPAA2 Overview
54 ~~~~~~~~~~~~~~
55
56 Reference: `FSL MC BUS in Linux Kernel <https://www.kernel.org/doc/readme/drivers-staging-fsl-mc-README.txt>`_.
57
58 DPAA2 is a hardware architecture designed for high-speed network
59 packet processing.  DPAA2 consists of sophisticated mechanisms for
60 processing Ethernet packets, queue management, buffer management,
61 autonomous L2 switching, virtual Ethernet bridging, and accelerator
62 (e.g. crypto) sharing.
63
64 A DPAA2 hardware component called the Management Complex (or MC) manages the
65 DPAA2 hardware resources.  The MC provides an object-based abstraction for
66 software drivers to use the DPAA2 hardware.
67
68 The MC uses DPAA2 hardware resources such as queues, buffer pools, and
69 network ports to create functional objects/devices such as network
70 interfaces, an L2 switch, or accelerator instances.
71
72 The MC provides memory-mapped I/O command interfaces (MC portals)
73 which DPAA2 software drivers use to operate on DPAA2 objects:
74
75 The diagram below shows an overview of the DPAA2 resource management
76 architecture:
77
78 .. code-block:: console
79
80   +--------------------------------------+
81   |                  OS                  |
82   |                        DPAA2 drivers |
83   |                             |        |
84   +-----------------------------|--------+
85                                 |
86                                 | (create,discover,connect
87                                 |  config,use,destroy)
88                                 |
89                   DPAA2         |
90   +------------------------| mc portal |-+
91   |                             |        |
92   |   +- - - - - - - - - - - - -V- - -+  |
93   |   |                               |  |
94   |   |   Management Complex (MC)     |  |
95   |   |                               |  |
96   |   +- - - - - - - - - - - - - - - -+  |
97   |                                      |
98   | Hardware                  Hardware   |
99   | Resources                 Objects    |
100   | ---------                 -------    |
101   | -queues                   -DPRC      |
102   | -buffer pools             -DPMCP     |
103   | -Eth MACs/ports           -DPIO      |
104   | -network interface        -DPNI      |
105   |  profiles                 -DPMAC     |
106   | -queue portals            -DPBP      |
107   | -MC portals                ...       |
108   |  ...                                 |
109   |                                      |
110   +--------------------------------------+
111
112 The MC mediates operations such as create, discover,
113 connect, configuration, and destroy.  Fast-path operations
114 on data, such as packet transmit/receive, are not mediated by
115 the MC and are done directly using memory mapped regions in
116 DPIO objects.
117
118 Overview of DPAA2 Objects
119 ~~~~~~~~~~~~~~~~~~~~~~~~~
120
121 The section provides a brief overview of some key DPAA2 objects.
122 A simple scenario is described illustrating the objects involved
123 in creating a network interfaces.
124
125 DPRC (Datapath Resource Container)
126
127  A DPRC is a container object that holds all the other
128  types of DPAA2 objects.  In the example diagram below there
129  are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC)
130  in the container.
131
132 .. code-block:: console
133
134     +---------------------------------------------------------+
135     | DPRC                                                    |
136     |                                                         |
137     |  +-------+  +-------+  +-------+  +-------+  +-------+  |
138     |  | DPMCP |  | DPIO  |  | DPBP  |  | DPNI  |  | DPMAC |  |
139     |  +-------+  +-------+  +-------+  +---+---+  +---+---+  |
140     |  | DPMCP |  | DPIO  |                                   |
141     |  +-------+  +-------+                                   |
142     |  | DPMCP |                                              |
143     |  +-------+                                              |
144     |                                                         |
145     +---------------------------------------------------------+
146
147 From the point of view of an OS, a DPRC behaves similar to a plug and
148 play bus, like PCI.  DPRC commands can be used to enumerate the contents
149 of the DPRC, discover the hardware objects present (including mappable
150 regions and interrupts).
151
152 .. code-block:: console
153
154     DPRC.1 (bus)
155       |
156       +--+--------+-------+-------+-------+
157          |        |       |       |       |
158        DPMCP.1  DPIO.1  DPBP.1  DPNI.1  DPMAC.1
159        DPMCP.2  DPIO.2
160        DPMCP.3
161
162 Hardware objects can be created and destroyed dynamically, providing
163 the ability to hot plug/unplug objects in and out of the DPRC.
164
165 A DPRC has a mappable MMIO region (an MC portal) that can be used
166 to send MC commands.  It has an interrupt for status events (like
167 hotplug).
168
169 All objects in a container share the same hardware "isolation context".
170 This means that with respect to an IOMMU the isolation granularity
171 is at the DPRC (container) level, not at the individual object
172 level.
173
174 DPRCs can be defined statically and populated with objects
175 via a config file passed to the MC when firmware starts
176 it.  There is also a Linux user space tool called "restool"
177 that can be used to create/destroy containers and objects
178 dynamically.
179
180 DPAA2 Objects for an Ethernet Network Interface
181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
182
183 A typical Ethernet NIC is monolithic-- the NIC device contains TX/RX
184 queuing mechanisms, configuration mechanisms, buffer management,
185 physical ports, and interrupts.  DPAA2 uses a more granular approach
186 utilizing multiple hardware objects.  Each object provides specialized
187 functions. Groups of these objects are used by software to provide
188 Ethernet network interface functionality.  This approach provides
189 efficient use of finite hardware resources, flexibility, and
190 performance advantages.
191
192 The diagram below shows the objects needed for a simple
193 network interface configuration on a system with 2 CPUs.
194
195 .. code-block:: console
196
197     +---+---+ +---+---+
198        CPU0     CPU1
199     +---+---+ +---+---+
200         |         |
201     +---+---+ +---+---+
202        DPIO     DPIO
203     +---+---+ +---+---+
204           \     /
205            \   /
206             \ /
207          +---+---+
208             DPNI  --- DPBP,DPMCP
209          +---+---+
210              |
211              |
212          +---+---+
213            DPMAC
214          +---+---+
215              |
216           port/PHY
217
218 Below the objects are described.  For each object a brief description
219 is provided along with a summary of the kinds of operations the object
220 supports and a summary of key resources of the object (MMIO regions
221 and IRQs).
222
223 DPMAC (Datapath Ethernet MAC): represents an Ethernet MAC, a
224 hardware device that connects to an Ethernet PHY and allows
225 physical transmission and reception of Ethernet frames.
226
227 - MMIO regions: none
228 - IRQs: DPNI link change
229 - commands: set link up/down, link config, get stats, IRQ config, enable, reset
230
231 DPNI (Datapath Network Interface): contains TX/RX queues,
232 network interface configuration, and RX buffer pool configuration
233 mechanisms.  The TX/RX queues are in memory and are identified by
234 queue number.
235
236 - MMIO regions: none
237 - IRQs: link state
238 - commands: port config, offload config, queue config, parse/classify config, IRQ config, enable, reset
239
240 DPIO (Datapath I/O): provides interfaces to enqueue and dequeue
241 packets and do hardware buffer pool management operations.  The DPAA2
242 architecture separates the mechanism to access queues (the DPIO object)
243 from the queues themselves.  The DPIO provides an MMIO interface to
244 enqueue/dequeue packets.  To enqueue something a descriptor is written
245 to the DPIO MMIO region, which includes the target queue number.
246 There will typically be one DPIO assigned to each CPU.  This allows all
247 CPUs to simultaneously perform enqueue/dequeued operations.  DPIOs are
248 expected to be shared by different DPAA2 drivers.
249
250 - MMIO regions: queue operations, buffer management
251 - IRQs: data availability, congestion notification, buffer pool depletion
252 - commands: IRQ config, enable, reset
253
254 DPBP (Datapath Buffer Pool): represents a hardware buffer
255 pool.
256
257 - MMIO regions: none
258 - IRQs: none
259 - commands: enable, reset
260
261 DPMCP (Datapath MC Portal): provides an MC command portal.
262 Used by drivers to send commands to the MC to manage
263 objects.
264
265 - MMIO regions: MC command portal
266 - IRQs: command completion
267 - commands: IRQ config, enable, reset
268
269 Object Connections
270 ~~~~~~~~~~~~~~~~~~
271
272 Some objects have explicit relationships that must
273 be configured:
274
275 - DPNI <--> DPMAC
276 - DPNI <--> DPNI
277 - DPNI <--> L2-switch-port
278
279 A DPNI must be connected to something such as a DPMAC,
280 another DPNI, or L2 switch port.  The DPNI connection
281 is made via a DPRC command.
282
283 .. code-block:: console
284
285     +-------+  +-------+
286     | DPNI  |  | DPMAC |
287     +---+---+  +---+---+
288         |          |
289         +==========+
290
291 - DPNI <--> DPBP
292
293 A network interface requires a 'buffer pool' (DPBP object) which provides
294 a list of pointers to memory where received Ethernet data is to be copied.
295 The Ethernet driver configures the DPBPs associated with the network
296 interface.
297
298 Interrupts
299 ~~~~~~~~~~
300
301 All interrupts generated by DPAA2 objects are message
302 interrupts.  At the hardware level message interrupts
303 generated by devices will normally have 3 components--
304 1) a non-spoofable 'device-id' expressed on the hardware
305 bus, 2) an address, 3) a data value.
306
307 In the case of DPAA2 devices/objects, all objects in the
308 same container/DPRC share the same 'device-id'.
309 For ARM-based SoC this is the same as the stream ID.
310
311
312 DPAA2 DPDK - Poll Mode Driver Overview
313 --------------------------------------
314
315 This section provides an overview of the drivers for
316 DPAA2-- 1) the bus driver and associated "DPAA2 infrastructure"
317 drivers and 2) functional object drivers (such as Ethernet).
318
319 As described previously, a DPRC is a container that holds the other
320 types of DPAA2 objects.  It is functionally similar to a plug-and-play
321 bus controller.
322
323 Each object in the DPRC is a Linux "device" and is bound to a driver.
324 The diagram below shows the dpaa2 drivers involved in a networking
325 scenario and the objects bound to each driver.  A brief description
326 of each driver follows.
327
328 .. code-block: console
329
330
331                                        +------------+
332                                        | DPDK DPAA2 |
333                                        |     PMD    |
334                                        +------------+       +------------+
335                                        |  Ethernet  |.......|  Mempool   |
336                     . . . . . . . . .  |   (DPNI)   |       |  (DPBP)    |
337                    .                   +---+---+----+       +-----+------+
338                   .                        ^   |                  .
339                  .                         |   |<enqueue,         .
340                 .                          |   | dequeue>         .
341                .                           |   |                  .
342               .                        +---+---V----+             .
343              .      . . . . . . . . . .| DPIO driver|             .
344             .      .                   |  (DPIO)    |             .
345            .      .                    +-----+------+             .
346           .      .                     |  QBMAN     |             .
347          .      .                      |  Driver    |             .
348     +----+------+-------+              +-----+----- |             .
349     |   dpaa2 bus       |                    |                    .
350     |   VFIO fslmc-bus  |....................|.....................
351     |                   |                    |
352     |     /bus/fslmc    |                    |
353     +-------------------+                    |
354                                              |
355     ========================== HARDWARE =====|=======================
356                                            DPIO
357                                              |
358                                            DPNI---DPBP
359                                              |
360                                            DPMAC
361                                              |
362                                             PHY
363     =========================================|========================
364
365
366 A brief description of each driver is provided below.
367
368 DPAA2 bus driver
369 ~~~~~~~~~~~~~~~~
370
371 The DPAA2 bus driver is a rte_bus driver which scans the fsl-mc bus.
372 Key functions include:
373
374 - Reading the container and setting up vfio group
375 - Scanning and parsing the various MC objects and adding them to
376   their respective device list.
377
378 Additionally, it also provides the object driver for generic MC objects.
379
380 DPIO driver
381 ~~~~~~~~~~~
382
383 The DPIO driver is bound to DPIO objects and provides services that allow
384 other drivers such as the Ethernet driver to enqueue and dequeue data for
385 their respective objects.
386 Key services include:
387
388 - Data availability notifications
389 - Hardware queuing operations (enqueue and dequeue of data)
390 - Hardware buffer pool management
391
392 To transmit a packet the Ethernet driver puts data on a queue and
393 invokes a DPIO API.  For receive, the Ethernet driver registers
394 a data availability notification callback.  To dequeue a packet
395 a DPIO API is used.
396
397 There is typically one DPIO object per physical CPU for optimum
398 performance, allowing different CPUs to simultaneously enqueue
399 and dequeue data.
400
401 The DPIO driver operates on behalf of all DPAA2 drivers
402 active  --  Ethernet, crypto, compression, etc.
403
404 DPBP based Mempool driver
405 ~~~~~~~~~~~~~~~~~~~~~~~~~
406
407 The DPBP driver is bound to a DPBP objects and provides sevices to
408 create a hardware offloaded packet buffer mempool.
409
410 DPAA2 NIC Driver
411 ~~~~~~~~~~~~~~~~
412 The Ethernet driver is bound to a DPNI and implements the kernel
413 interfaces needed to connect the DPAA2 network interface to
414 the network stack.
415
416 Each DPNI corresponds to a DPDK network interface.
417
418 Features
419 ^^^^^^^^
420
421 Features of the DPAA2 PMD are:
422
423 - Multiple queues for TX and RX
424 - Receive Side Scaling (RSS)
425 - MAC/VLAN filtering
426 - Packet type information
427 - Checksum offload
428 - Promiscuous mode
429 - Multicast mode
430 - Port hardware statistics
431 - Jumbo frames
432 - Link flow control
433 - Scattered and gather for TX and RX
434
435 Supported DPAA2 SoCs
436 --------------------
437
438 - LS2080A/LS2040A
439 - LS2084A/LS2044A
440 - LS2088A/LS2048A
441 - LS1088A/LS1048A
442
443 Prerequisites
444 -------------
445
446 There are three main pre-requisities for executing DPAA2 PMD on a DPAA2
447 compatible board:
448
449 1. **ARM 64 Tool Chain**
450
451    For example, the `*aarch64* Linaro Toolchain <https://releases.linaro.org/components/toolchain/binaries/4.9-2017.01/aarch64-linux-gnu>`_.
452
453 2. **Linux Kernel**
454
455    It can be obtained from `NXP's Github hosting <https://github.com/qoriq-open-source/linux>`_.
456
457 3. **Rootfile system**
458
459    Any *aarch64* supporting filesystem can be used. For example,
460    Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
461    from `here <http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
462
463 As an alternative method, DPAA2 PMD can also be executed using images provided
464 as part of SDK from NXP. The SDK includes all the above prerequisites necessary
465 to bring up a DPAA2 board.
466
467 The following dependencies are not part of DPDK and must be installed
468 separately:
469
470 - **NXP Linux SDK**
471
472   NXP Linux software development kit (SDK) includes support for family
473   of QorIQ® ARM-Architecture-based system on chip (SoC) processors
474   and corresponding boards.
475
476   It includes the Linux board support packages (BSPs) for NXP SoCs,
477   a fully operational tool chain, kernel and board specific modules.
478
479   SDK and related information can be obtained from:  `NXP QorIQ SDK  <http://www.nxp.com/products/software-and-tools/run-time-software/linux-sdk/linux-sdk-for-qoriq-processors:SDKLINUX>`_.
480
481 - **DPDK Extra Scripts**
482
483   DPAA2 based resources can be configured easily with the help of ready scripts
484   as provided in the DPDK Extra repository.
485
486   `DPDK Extras Scripts <https://github.com/qoriq-open-source/dpdk-extras>`_.
487
488 Currently supported by DPDK:
489
490 - NXP SDK **2.0+**.
491 - MC Firmware version **10.0.0** and higher.
492 - Supported architectures:  **arm64 LE**.
493
494 - Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
495
496 .. note::
497
498    Some part of fslmc bus code (mc flib - object library) routines are
499    dual licensed (BSD & GPLv2).
500
501 Pre-Installation Configuration
502 ------------------------------
503
504 Config File Options
505 ~~~~~~~~~~~~~~~~~~~
506
507 The following options can be modified in the ``config`` file.
508 Please note that enabling debugging options may affect system performance.
509
510 - ``CONFIG_RTE_LIBRTE_FSLMC_BUS`` (default ``n``)
511
512   By default it is enabled only for defconfig_arm64-dpaa2-* config.
513   Toggle compilation of the ``librte_bus_fslmc`` driver.
514
515 - ``CONFIG_RTE_LIBRTE_DPAA2_PMD`` (default ``n``)
516
517   By default it is enabled only for defconfig_arm64-dpaa2-* config.
518   Toggle compilation of the ``librte_pmd_dpaa2`` driver.
519
520 - ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_DRIVER`` (default ``n``)
521
522   Toggle display of generic debugging messages
523
524 - ``CONFIG_RTE_LIBRTE_DPAA2_USE_PHYS_IOVA`` (default ``y``)
525
526   Toggle to use physical address vs virtual address for hardware accelerators.
527
528 - ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_INIT`` (default ``n``)
529
530   Toggle display of initialization related messages.
531
532 - ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_RX`` (default ``n``)
533
534   Toggle display of receive fast path run-time message
535
536 - ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_TX`` (default ``n``)
537
538   Toggle display of transmit fast path run-time message
539
540 - ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_TX_FREE`` (default ``n``)
541
542   Toggle display of transmit fast path buffer free run-time message
543
544 Driver compilation and testing
545 ------------------------------
546
547 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
548 for details.
549
550 #. Running testpmd:
551
552    Follow instructions available in the document
553    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
554    to run testpmd.
555
556    Example output:
557
558    .. code-block:: console
559
560       ./arm64-dpaa2-linuxapp-gcc/testpmd -c 0xff -n 1 \
561         -- -i --portmask=0x3 --nb-cores=1 --no-flush-rx
562
563       .....
564       EAL: Registered [pci] bus.
565       EAL: Registered [fslmc] bus.
566       EAL: Detected 8 lcore(s)
567       EAL: Probing VFIO support...
568       EAL: VFIO support initialized
569       .....
570       PMD: DPAA2: Processing Container = dprc.2
571       EAL: fslmc: DPRC contains = 51 devices
572       EAL: fslmc: Bus scan completed
573       .....
574       Configuring Port 0 (socket 0)
575       Port 0: 00:00:00:00:00:01
576       Configuring Port 1 (socket 0)
577       Port 1: 00:00:00:00:00:02
578       .....
579       Checking link statuses...
580       Port 0 Link Up - speed 10000 Mbps - full-duplex
581       Port 1 Link Up - speed 10000 Mbps - full-duplex
582       Done
583       testpmd>
584
585 Limitations
586 -----------
587
588 Platform Requirement
589 ~~~~~~~~~~~~~~~~~~~~
590 DPAA2 drivers for DPDK can only work on NXP SoCs as listed in the
591 ``Supported DPAA2 SoCs``.
592
593 Maximum packet length
594 ~~~~~~~~~~~~~~~~~~~~~
595
596 The DPAA2 SoC family support a maximum of a 10240 jumbo frame. The value
597 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
598 member of ``struct rte_eth_conf`` is set to a value lower than 10240, frames
599 up to 10240 bytes can still reach the host interface.
600
601 Other Limitations
602 ~~~~~~~~~~~~~~~~~
603
604 - RSS hash key cannot be modified.
605 - RSS RETA cannot be configured.
606 - Secondary process packet I/O is not supported.