Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document config-cross-recipe.sh helper script #276

Merged
merged 4 commits into from
Sep 12, 2023
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 163 additions & 0 deletions docs/scripts/config-cross-recipe.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
.. 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).

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.

The directory 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.
1 change: 1 addition & 0 deletions docs/scripts/helper-scripts.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,4 @@ Helper Scripts
:maxdepth: 1

make-all
config-cross-recipe