diff --git a/docs/scripts/config-cross-recipe-flow.png b/docs/scripts/config-cross-recipe-flow.png new file mode 100644 index 00000000..ab1ab1de Binary files /dev/null and b/docs/scripts/config-cross-recipe-flow.png differ diff --git a/docs/scripts/config-cross-recipe.rst b/docs/scripts/config-cross-recipe.rst new file mode 100644 index 00000000..6e31ffa9 --- /dev/null +++ b/docs/scripts/config-cross-recipe.rst @@ -0,0 +1,171 @@ +.. Copyright 2023 Intel Corporation + SPDX-License-Identifier: Apache 2.0 + +====================== +config-cross-recipe.sh +====================== + +Helper script to configure CMake to cross-compile P4 Control Plane +for the Arm Compute Complex (ACC). + +Build flow +========== + +The ``config-cross-recipe.sh`` script is run after ``make-cross-ovs.sh``, +to configure the remainder of the P4 Control Plane build. + +.. image:: config-cross-recipe-flow.png + +After running this script, you will need to issue a separate command +to build and install the software. For example: + +.. code-block:: bash + + cmake --build build -j8 --target install + +Syntax +====== + +.. code-block:: text + + ./scripts/es2k/config-cross-recipe.sh \ + [--help|-h] \ + [--dry-run|-n] \ + [--build=BLDDIR | -B BLDDIR] \ + [--deps=DEPS | -D DEPS] \ + [--host=HOSTDEPS | -H HOSTDEPS] \ + [--ovs=OVS | -O OVS] \ + [--prefix=PREFIX | -P PREFIX] \ + [--sde=SDE | -S SDE] \ + [--toolchain=TOOLFILE | -T TOOLFILE ] \ + [--no-krnlmon] \ + [--no-ovs] + +Command-line parameters +======================= + +General +------- + +``--dry-run``, ``-n`` + Displays the parameters that will be passed to CMake, and exits. + +``--help``, ``-h`` + Displays usage information and exits. + +Paths +----- + +``--build=BLDDIR``, ``-B BLDDIR`` + Directory that CMake will use to perform the build. + Will be created if it does not exist. + + Specifies the value of the ``-B`` CMake option. + Can be used to create separate build directories for native and + cross-compiled builds. + Defaults to ``build``. + +``--deps=DEPS``, ``-D DEPS`` *(see note)* + Directory in which the Stratum dependencies for the runtime system + are installed. + + P4 Control Plane will be linked with these libraries. + Supplies the value of the ``DEPEND_INSTALL_DIR`` listfile variable. + Defaults to the value of the ``DEPEND_INSTALL`` environment variable, + if defined. + Otherwise, defaults to ``//opt/deps``. + +``--host=HOST``, ``-H HOST`` + Directory in which the Stratum dependencies for the development + system are installed. + + Used to compile Protobufs to C++ during cross-compilation. + Supplies the value of the ``HOST_DEPEND_DIR`` listfile variable. + Defaults to the value of the ``HOST_INSTALL`` environment variable, + if defined. + Otherwise, defaults to ``setup/hostdeps``. + +``--ovs=OVS``, ``-O OVS`` *(see note)* + Directory in which Open vSwitch is installed. + + May be omitted if the ``--no-ovs`` option is specified. + Supplies the value of the ``OVS_INSTALL_DIR`` listfile variable for + the P4 Control Plane build. + May be the same as the ``prefix`` directory, in which case OVS and + P4 Control Plane will be installed to the same directory tree. + Defaults to the value of the ``OVS_INSTALL`` environment variable, + if defined. + Otherwise, defaults to ``//opt/ovs``. + +``--prefix=PREFIX``, ``-P PREFIX`` *(see note)* + Directory in which P4 Control Plane will be installed. + Will be created if it does not exist. + + May be the same as the ``--ovs`` option, in which case OVS and + P4 Control Plane will be installed to the same directory tree. + Specifies the value of the ``CMAKE_INSTALL_PREFIX`` variable when + building P4 Control Plane. + +``--sde=SDE``, ``-S SDE`` *(see note)* + Directory in which the SDK for the Intel® IPU E2100 is installed. + + Supplies the value of the ``SDE_INSTALL_DIR`` listfile variable. + Defaults to the value of the ``SDE_INSTALL`` environment variable, + if defined. + Otherwise, defaults to ``//opt/p4sde``. + +``--toolchain=FILE``, ``-T FILE`` + Path to the CMake toolchain file. + + Specifies the value of the ``CMAKE_TOOLCHAIN_FILE`` variable. + Defaults to the value of the ``CMAKE_TOOLCHAIN_FILE`` environment + variable. + +.. note:: + ``//`` at the beginning of the directory path will be replaced with + the *sysroot* directory path. + +Options +------- + +``--no-krnlmon`` + Excludes the Kernel Monitor from the build. + + Sets the ``WITH_KRNLMON`` listfile option to FALSE. + +``--no-ovs`` + Excludes OVS from the build. + + Sets the ``WITH_OVSP4RT`` listfile option to FALSE. + +Environment variables +===================== + +``CMAKE_TOOLCHAIN_FILE`` + Path to the CMake toolchain file to be used. + Specifies the value of the ``CMAKE_TOOLCHAIN_FILE`` variable. + May be overridden by ``--toolchain=TOOLFILE``. + Must be defined. + +``DEPEND_INSTALL`` + Directory in which the Stratum dependencies for the runtime system + are installed. + Supplies the default value of the ``--deps`` option. + +``HOST_INSTALL`` + Directory in which the Stratum dependencies for the development system + are installed. + Supplies the default value of the ``--host`` option. + +``OVS_INSTALL`` + Directory in which Open vSwitch is installed. + Supplies the default value of the ``--ovs`` option. + +``SDE_INSTALL`` + Directory in which the SDK for the IPU E2100 is installed. + Supplies the default value of the ``--sde`` option. + +``SDKTARGETSYSROOT`` + Path to the system root (sysroot) directory for the ARM Compute Complex + (ACC) of the IPU E2100. + Must be defined. diff --git a/docs/scripts/helper-scripts.rst b/docs/scripts/helper-scripts.rst index 9e73d933..c306e6fa 100644 --- a/docs/scripts/helper-scripts.rst +++ b/docs/scripts/helper-scripts.rst @@ -9,3 +9,4 @@ Helper Scripts :maxdepth: 1 make-all + config-cross-recipe