doc: update documentation for packages

Updating the documentation with instructions to install: * Release package * Devel package * Deal with dependency issue Signed-off-by: Harman Kalra <hkalra@marvell.com> Change-Id: I7f104428112a4cddee8a3f026987abc5e2efe996 Reviewed-on: https://sj1git1.cavium.com/c/IP/SW/dataplane/dpu-offload/+/136725 Tested-by: sa_ip-toolkits-Jenkins <sa_ip-toolkits-jenkins@marvell.com>
MarvellEmbeddedProcessors · Oct 7, 2024 · ad98b55 · ad98b55
1 parent 5a34b0d
commit ad98b55
Show file tree

Hide file tree

Showing 4 changed files with 232 additions and 20 deletions.
diff --git a/doc/guides/faq/faq.rst b/doc/guides/faq/faq.rst
@@ -12,3 +12,95 @@ Eg. The DPDK graph library, utilized by many DAO applications, has the
 uses custom nodes from the node library. However, these nodes being constructor
 declarations, fail to become part of the constructed graph when DPDK is not
 statically linked.
+
+.. _dep_issue:
+
+Why is installing older DAO version causing dependency issues?
+--------------------------------------------------------------
+
+DAO package is dependent on DPDK and it gets installed as a dependency when
+DAO is installed. If user wants to install an older version of DAO and it may be
+dependent on older DPDK version.
+
+``apt-get`` may insist to install latest version of DPDK when installing the older
+version of DAO, which may cause dependency issues:
+
+.. code-block:: bash
+
+   The following packages have unmet dependencies:
+    dao-cn10k : Depends: dpdk-23.11-cn10k (= 24.07.0) but 24.08.0 is to be installed
+   E: Unable to correct problems, you have held broken package
+
+To avoid this user may follow two approaches:
+
+1. Install dependent DPDK package alongside required DAO version.
+
+.. code-block:: bash
+
+    sudo apt-get install dao-cn10k=<version> dpdk-23.11-cn10k=<dependent_version>
+
+.. code-block:: bash
+
+    # apt-get install dao-cn10k=24.09.0 dpdk-23.11-cn10k=24.07.0
+    Reading package lists... Done
+    Building dependency tree... Done
+    Reading state information... Done
+    The following NEW packages will be installed:
+      dao-cn10k dpdk-23.11-cn10k
+    0 upgraded, 2 newly installed, 0 to remove and 33 not upgraded.
+    Need to get 0 B/309 MB of archives.
+    After this operation, 0 B of additional disk space will be used.
+    Selecting previously unselected package dpdk-23.11-cn10k.
+    (Reading database ... 115644 files and directories currently installed.)
+    Preparing to unpack .../dpdk-23.11-cn10k_24.07.0_arm64.deb ...
+    Unpacking dpdk-23.11-cn10k (24.07.0) ...
+    Selecting previously unselected package dao-cn10k.
+    Preparing to unpack .../dao-cn10k_24.09.0_arm64.deb ...
+    Unpacking dao-cn10k (24.09.0) ...
+    Setting up dpdk-23.11-cn10k (24.07.0) ...
+    Setting up dao-cn10k (24.09.0) ...
+
+2. User can follow an interactive process using ``aptitude`` which gives suggestions
+   and let user choose the version to downgrade the packages:
+
+.. code-block:: bash
+
+    # sudo apt-get install aptitude
+    # aptitude install dao-cn10k=24.09.0
+    The following NEW packages will be installed:
+      dao-cn10k{b}
+    0 packages upgraded, 1 newly installed, 0 to remove and 33 not upgraded.
+    Need to get 39.0 MB of archives. After unpacking 0 B will be used.
+    The following packages have unmet dependencies:
+     dao-cn10k : Depends: dpdk-23.11-cn10k (= 24.07.0) but it is not going to be installed
+    The following actions will resolve these dependencies:
+
+         Keep the following packages at their current version:
+    1)     dao-cn10k [Not Installed]
+
+    Accept this solution? [Y/n/q/?] n
+    The following actions will resolve these dependencies:
+
+         Install the following packages:
+    1)     dpdk-23.11-cn10k [24.07.0 (<NULL>)]
+
+    Accept this solution? [Y/n/q/?] Y
+    The following NEW packages will be installed:
+      dao-cn10k dpdk-23.11-cn10k{a}
+    0 packages upgraded, 2 newly installed, 0 to remove and 33 not upgraded.
+    Need to get 309 MB of archives. After unpacking 0 B will be used.
+    Do you want to continue? [Y/n/?] Y
+    Get: 1 https://www.marvell.com/public/repo/octeon/dao/cn10k/ubuntu/v2204/release ./ dpdk-23.11-cn10k 24.07.0 [270 MB]
+    Get: 2 https://www.marvell.com/public/repo/octeon/dao/cn10k/ubuntu/v2204/release ./ dao-cn10k 24.09.0 [39.0 MB]
+    Fetched 309 MB in 46s (6,666 kB/s)
+    Selecting previously unselected package dpdk-23.11-cn10k.
+    (Reading database ... 115644 files and directories currently installed.)
+    Preparing to unpack .../dpdk-23.11-cn10k_24.07.0_arm64.deb ...
+    Unpacking dpdk-23.11-cn10k (24.07.0) ...
+    Selecting previously unselected package dao-cn10k.
+    Preparing to unpack .../dao-cn10k_24.09.0_arm64.deb ...
+    Unpacking dao-cn10k (24.09.0) ...
+    Setting up dpdk-23.11-cn10k (24.07.0) ...
+    Setting up dao-cn10k (24.09.0) ...
+
+    Current status: 35 (+2) upgradable.
diff --git a/doc/guides/gsg/build.rst b/doc/guides/gsg/build.rst
@@ -8,6 +8,8 @@ Developers can refer to the following guide, which provides various options
 for manually compiling DAO sources, allowing them to tailor the process
 according to their specific needs.
 
+.. _getting_dao_sources:
+
 Getting the sources
 -------------------
 Data accelerator offload (DAO) sources can be downloaded from:

diff --git a/doc/guides/gsg/install.rst b/doc/guides/gsg/install.rst
@@ -115,29 +115,96 @@ Once the octeon board is UP with above ubuntu rootfs
 Update ubuntu repository to download dao packages
 -------------------------------------------------
 
+Two types of packages are available for the DAO - stable and release packages.
+Each have their own PPA's. User can choose either stable or development version
+and update the repository accordingly.
+
+PPA for stable version:
+
 .. code-block:: console
 
- # curl -fsSL https://www.marvell.com/public/repo/octeon/dao/ubuntu/v2204/dao.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/dao.gpg
- # curl -SsL -o /etc/apt/sources.list.d/dao.list https://www.marvell.com/public/repo/octeon/dao/ubuntu/v2204/dao.list
+ # curl -fsSL https://www.marvell.com/public/repo/octeon/dao/cn10k/ubuntu/v2204/release/dao.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/dao.gpg
+ # curl -SsL -o /etc/apt/sources.list.d/dao.list https://www.marvell.com/public/repo/octeon/dao/cn10k/ubuntu/v2204/release/dao.list
+ # sudo chmod 644 /etc/apt/sources.list.d/dao.list
+ # sudo chmod 644 /etc/apt/keyrings/dao.gpg
+ # apt-get update
+
+.. _devel_ppa:
+
+PPA for development version:
+
+.. code-block:: console
+
+ # curl -fsSL https://www.marvell.com/public/repo/octeon/dao/cn10k/ubuntu/v2204/devel/dao.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/dao.gpg
+ # curl -SsL -o /etc/apt/sources.list.d/dao.list https://www.marvell.com/public/repo/octeon/dao/cn10k/ubuntu/v2204/devel/dao.list
  # sudo chmod 644 /etc/apt/sources.list.d/dao.list
  # sudo chmod 644 /etc/apt/keyrings/dao.gpg
  # apt-get update
 
 Installing DAO package
 ----------------------
 
+Two typeis of DAO packages are available for installation:
+
+Release version
+^^^^^^^^^^^^^^^
+
+These are stable versions of the DAO package, which are thoroughly tested
+
 .. code-block:: console
 
- # apt-get install dao-cn10k-devel
+ # apt-get install dao-cn10k
 
  This will also install mandatory dependency viz DPDK
 
-Installing OVS package (optional)
----------------------------------
+To check all available release versions of the package, user can run below command:
+
+.. code-block:: console
+
+ # apt-cache policy dao-cn10k
+ dao-cn10k:
+  Installed: (none)
+  Candidate: 24.09.0
+  Version table:
+     24.09.0 500
+        500 https://www.marvell.com/public/repo/octeon/dao/ubuntu/v2204 ./ Packages
+     24.05.1 500
+        500 https://www.marvell.com/public/repo/octeon/dao/ubuntu/v2204 ./ Packages
+     24.05.0 500
+        500 https://www.marvell.com/public/repo/octeon/dao/ubuntu/v2204 ./ Packages
+
+By default it will install the latest version of the package. If user wants to
+install a specific version, then user can specify the version as below:
 
 .. code-block:: console
 
- # apt-get install ovs-3.3-cn10k-devel
+ # apt-get install dao-cn10k=24.05
+
+.. note:: While installing an older package user may observe some dependency issues:
+
+   ***dao-cn10k : Depends: dpdk-23.11-cn10k (= 24.07.0) but 24.08.0 is to be installed***
+
+   Refer :ref:`troubleshoot dependency issue<dep_issue>` to resolve the dependency issues.
+
+Its recommended to clear the repository cache before installing different versions of the
+package.
+
+:ref:`Clear repository cache<clear_repo_cache>`
+
+Development version
+^^^^^^^^^^^^^^^^^^^
+
+These are the latest versions of the DAO package, which are still under
+development and may contain bugs. User should install these versions only
+at their own risk.
+
+Change the repository to development version as mentioned in
+
+:ref:`PPA for development<devel_ppa>`
+
+.. code-block:: console
+
+ # apt-get install dao-cn10k-devel
 
 Removing old packages
 ---------------------
@@ -146,17 +213,23 @@ Removing old packages
 
 .. code-block:: console
 
+ Remove dao release package
+ # apt-get remove dao-cn10k -y
+
+ Remove dao development package
  # apt-get remove dao-cn10k-devel -y
+
+ Remove dpdk package and its dependents
  # apt-get remove dpdk-23.11-cn10k -y
- # apt-get remove ovs-3.3-cn10k-devel -y
+
+.. _clear_repo_cache:
 
 * Clear ubuntu repo cache
 
 .. code-block:: console
 
- # rm /var/cache/apt/archives/dao-cn10k-devel_*
+ # rm /var/cache/apt/archives/dao-cn10k*
  # rm /var/cache/apt/archives/dpdk-23.11-cn10k_*
- # rm /var/cache/apt/archives/ovs-3.3-cn10k-devel_*
 
 Installation demo
 -----------------

diff --git a/doc/guides/howtoguides/ovs.rst b/doc/guides/howtoguides/ovs.rst
@@ -5,13 +5,48 @@
 Getting Started with OVS
 ************************
 
-Compiling Open vSwitch with DPDK
-================================
+This document provides a step-by-step guide to get started with Open vSwitch (OVS)
+on Marvell CN10K platform.
+
+
+Building and Installing OVS
+===========================
+
+There are two ways to get OVS running on the CN10K platform:
+
+1. Use the OVS package from Marvell's distribution repository
+2. Build OVS from source
+
+Installing OVS from the distribution repository
+-----------------------------------------------
+
+.. code-block:: console
+
+ # apt-get install ovs-3.3.0-cn10k
+
+To remove the installed package:
+
+.. code-block:: console
+
+ # apt-get remove ovs-3.3.0-cn10k
+
+Clear cache:
+
+.. code-block:: console
+
+ # rm /var/cache/apt/archives/ovs-3.3*
+
+Building OVS from source
+------------------------
+
+OVS depends on DPDK for packet processing. The following steps describe how to build OVS with
+DPDK support.
 
 Building and installing DPDK
-----------------------------
+````````````````````````````
 
-Get the DPDK sources, build and install the library
+Before building OVS, DPDK should be built and installed. The following steps describe how to
+build and install DPDK.
 
 .. code-block:: console
 
@@ -31,22 +66,32 @@ The above command should return the DPDK version installed. If not found, export
 
  # export PKG_CONFIG_LIBDIR=<DPDK_INSTALL_DIR>/lib/pkgconfig
 
-Building and Installing OVS
-===========================
-
-Get the sources
----------------
+Get the OVS sources
+```````````````````
 Get the OVS sources by cloning the repository or by download from
 `sources <http://www.openvswitch.org/download/>`_
 
 .. code-block:: console
 
  # git clone https://github.com/openvswitch/ovs
- # git checkout master
+ # git checkout branch-3.3
  # ./boot.sh
 
+Apply custom patches
+````````````````````
+
+OVS custom patches are available as part of DAO repository.
+
+:ref:`Cloning DAO repository<getting_dao_sources>`
+
+Apply the patches:
+
+.. code-block:: console
+
+ # patch -p1 < <DAO_repo>patches/ovs/v3.3.0/*.patch
+
 Compilation
------------
+```````````
 
 For OVS to use DPDK, it should be configured to build against the DPDK library (--with-dpdk).