Documentation/networking/device_drivers/netronome/nfp.rst

   1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2
   3 =============================================
   4 Netronome Flow Processor (NFP) Kernel Drivers
   5 =============================================
   6
   7 Copyright (c) 2019, Netronome Systems, Inc.
   8
   9 Contents
  10 ========
  11
  12 - `Overview`_
  13 - `Acquiring Firmware`_
  14
  15 Overview
  16 ========
  17
  18 This driver supports Netronome's line of Flow Processor devices,
  19 including the NFP4000, NFP5000, and NFP6000 models, which are also
  20 incorporated in the company's family of Agilio SmartNICs. The SR-IOV
  21 physical and virtual functions for these devices are supported by
  22 the driver.
  23
  24 Acquiring Firmware
  25 ==================
  26
  27 The NFP4000 and NFP6000 devices require application specific firmware
  28 to function.  Application firmware can be located either on the host file system
  29 or in the device flash (if supported by management firmware).
  30
  31 Firmware files on the host filesystem contain card type (`AMDA-*` string), media
  32 config etc.  They should be placed in `/lib/firmware/netronome` directory to
  33 load firmware from the host file system.
  34
  35 Firmware for basic NIC operation is available in the upstream
  36 `/*(DEBLOBBED)*/` repository.
  37
  38 Firmware in NVRAM
  39 -----------------
  40
  41 Recent versions of management firmware supports loading application
  42 firmware from flash when the host driver gets probed.  The firmware loading
  43 policy configuration may be used to configure this feature appropriately.
  44
  45 Devlink or ethtool can be used to update the application firmware on the device
  46 flash by providing the appropriate `nic_AMDA*.nffw` file to the respective
  47 command.  Users need to take care to write the correct firmware image for the
  48 card and media configuration to flash.
  49
  50 Available storage space in flash depends on the card being used.
  51
  52 Dealing with multiple projects
  53 ------------------------------
  54
  55 NFP hardware is fully programmable therefore there can be different
  56 firmware images targeting different applications.
  57
  58 When using application firmware from host, we recommend placing
  59 actual firmware files in application-named subdirectories in
  60 `/lib/firmware/netronome` and linking the desired files, e.g.::
  61
  62     $ tree /lib/firmware/netronome/
  63     /lib/firmware/netronome/
  64     ├── bpf
  65     │   ├── nic_AMDA0081-0001_1x40.nffw
  66     │   └── nic_AMDA0081-0001_4x10.nffw
  67     ├── flower
  68     │   ├── nic_AMDA0081-0001_1x40.nffw
  69     │   └── nic_AMDA0081-0001_4x10.nffw
  70     ├── nic
  71     │   ├── nic_AMDA0081-0001_1x40.nffw
  72     │   └── nic_AMDA0081-0001_4x10.nffw
  73     ├── nic_AMDA0081-0001_1x40.nffw -> bpf/nic_AMDA0081-0001_1x40.nffw
  74     └── nic_AMDA0081-0001_4x10.nffw -> bpf/nic_AMDA0081-0001_4x10.nffw
  75
  76     3 directories, 8 files
  77
  78 You may need to use hard instead of symbolic links on distributions
  79 which use old `mkinitrd` command instead of `dracut` (e.g. Ubuntu).
  80
  81 After changing firmware files you may need to regenerate the initramfs
  82 image.  Initramfs contains drivers and firmware files your system may
  83 need to boot.  Refer to the documentation of your distribution to find
  84 out how to update initramfs.  Good indication of stale initramfs
  85 is system loading wrong driver or firmware on boot, but when driver is
  86 later reloaded manually everything works correctly.
  87
  88 Selecting firmware per device
  89 -----------------------------
  90
  91 Most commonly all cards on the system use the same type of firmware.
  92 If you want to load specific firmware image for a specific card, you
  93 can use either the PCI bus address or serial number.  Driver will print
  94 which files it's looking for when it recognizes a NFP device::
  95
  96     nfp: Looking for firmware file in order of priority:
  97     nfp:  /*(DEBLOBBED)*/: not found
  98     nfp:  /*(DEBLOBBED)*/: not found
  99     nfp:  /*(DEBLOBBED)*/: found, loading...
 100
 101 In this case if file (or link) called */*(DEBLOBBED)*/*
 102 or */*(DEBLOBBED)*/* is present in `/lib/firmware/netronome` this
 103 firmware file will take precedence over `nic_AMDA*` files.
 104
 105 Note that `serial-*` and `pci-*` files are **not** automatically included
 106 in initramfs, you will have to refer to documentation of appropriate tools
 107 to find out how to include them.
 108
 109 Firmware loading policy
 110 -----------------------
 111
 112 Firmware loading policy is controlled via three HWinfo parameters
 113 stored as key value pairs in the device flash:
 114
 115 app_fw_from_flash
 116     Defines which firmware should take precedence, 'Disk' (0), 'Flash' (1) or
 117     the 'Preferred' (2) firmware. When 'Preferred' is selected, the management
 118     firmware makes the decision over which firmware will be loaded by comparing
 119     versions of the flash firmware and the host supplied firmware.
 120     This variable is configurable using the 'fw_load_policy'
 121     devlink parameter.
 122
 123 abi_drv_reset
 124     Defines if the driver should reset the firmware when
 125     the driver is probed, either 'Disk' (0) if firmware was found on disk,
 126     'Always' (1) reset or 'Never' (2) reset. Note that the device is always
 127     reset on driver unload if firmware was loaded when the driver was probed.
 128     This variable is configurable using the 'reset_dev_on_drv_probe'
 129     devlink parameter.
 130
 131 abi_drv_load_ifc
 132     Defines a list of PF devices allowed to load FW on the device.
 133     This variable is not currently user configurable.