doc/guides/windows_gsg/run_apps.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2020 Dmitry Kozlyuk
   3
   4 Running DPDK Applications
   5 =========================
   6
   7 Grant *Lock pages in memory* Privilege
   8 --------------------------------------
   9
  10 Use of hugepages ("large pages" in Windows terminology) requires
  11 ``SeLockMemoryPrivilege`` for the user running an application.
  12
  13 1. Open *Local Security Policy* snap-in, either:
  14
  15    * Control Panel / Computer Management / Local Security Policy;
  16    * or Win+R, type ``secpol``, press Enter.
  17
  18 2. Open *Local Policies / User Rights Assignment / Lock pages in memory.*
  19
  20 3. Add desired users or groups to the list of grantees.
  21
  22 4. Privilege is applied upon next logon. In particular, if privilege has been
  23    granted to current user, a logoff is required before it is available.
  24
  25 See `Large-Page Support`_ in MSDN for details.
  26
  27 .. _Large-Page Support: https://docs.microsoft.com/en-us/windows/win32/memory/large-page-support
  28
  29
  30 Load virt2phys Driver
  31 ---------------------
  32
  33 Access to physical addresses is provided by a kernel-mode driver, virt2phys.
  34 It is mandatory at least for using hardware PMDs, but may also be required
  35 for mempools.
  36
  37 Refer to documentation in ``dpdk-kmods`` repository for details on system
  38 setup, driver build and installation. This driver is not signed, so signature
  39 checking must be disabled to load it.
  40
  41 .. warning::
  42
  43     Disabling driver signature enforcement weakens OS security.
  44     It is discouraged in production environments.
  45
  46 Compiled package consists of ``virt2phys.inf``, ``virt2phys.cat``,
  47 and ``virt2phys.sys``. It can be installed as follows
  48 from Elevated Command Prompt:
  49
  50 .. code-block:: console
  51
  52     pnputil /add-driver Z:\path\to\virt2phys.inf /install
  53
  54 On Windows Server additional steps are required:
  55
  56 1. From Device Manager, Action menu, select "Add legacy hardware".
  57 2. It will launch the "Add Hardware Wizard". Click "Next".
  58 3. Select second option "Install the hardware that I manually select
  59    from a list (Advanced)".
  60 4. On the next screen, "Kernel bypass" will be shown as a device class.
  61 5. Select it, and click "Next".
  62 6. The previously installed drivers will now be installed for the
  63    "Virtual to physical address translator" device.
  64
  65 When loaded successfully, the driver is shown in *Device Manager* as *Virtual
  66 to physical address translator* device under *Kernel bypass* category.
  67 Installed driver persists across reboots.
  68
  69 If DPDK is unable to communicate with the driver, a warning is printed
  70 on initialization (debug-level logs provide more details):
  71
  72 .. code-block:: text
  73
  74     EAL: Cannot open virt2phys driver interface
  75
  76
  77
  78 Run the ``helloworld`` Example
  79 ------------------------------
  80
  81 Navigate to the examples in the build directory and run `dpdk-helloworld.exe`.
  82
  83 .. code-block:: console
  84
  85     cd C:\Users\me\dpdk\build\examples
  86     dpdk-helloworld.exe
  87     hello from core 1
  88     hello from core 3
  89     hello from core 0
  90     hello from core 2
  91
  92 Note for MinGW-w64: applications are linked to ``libwinpthread-1.dll``
  93 by default. To run the example, either add toolchain executables directory
  94 to the PATH or copy the library to the working directory.
  95 Alternatively, static linking may be used (mind the LGPLv2.1 license).