-.. BSD LICENSE
- Copyright (C) Cavium, Inc. 2017.
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
-
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in
- the documentation and/or other materials provided with the
- distribution.
- * Neither the name of Cavium, Inc nor the names of its
- contributors may be used to endorse or promote products derived
- from this software without specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-OCTEONTX SSOVF Eventdev Driver
-==============================
-
-The OCTEONTX SSOVF PMD (**librte_pmd_octeontx_ssovf**) provides poll mode
-eventdev driver support for the inbuilt event device found in the **Cavium OCTEONTX**
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2017 Cavium, Inc
+
+OCTEON TX SSOVF Eventdev Driver
+===============================
+
+The OCTEON TX SSOVF PMD (**librte_event_octeontx**) provides poll mode
+eventdev driver support for the inbuilt event device found in the **Cavium OCTEON TX**
SoC family as well as their virtual functions (VF) in SR-IOV context.
More information can be found at `Cavium, Inc Official Website
Features
--------
-Features of the OCTEONTX SSOVF PMD are:
+Features of the OCTEON TX SSOVF PMD are:
- 64 Event queues
- 32 Event ports
- Open system with configurable amount of outstanding events
- HW accelerated dequeue timeout support to enable power management
- SR-IOV VF
+- HW managed event timers support through TIMVF, with high precision and
+ time granularity of 1us.
+- Up to 64 event timer adapters.
-Supported OCTEONTX SoCs
------------------------
+Supported OCTEON TX SoCs
+------------------------
- CN83xx
Prerequisites
-------------
-There are three main pre-perquisites for executing SSOVF PMD on a OCTEONTX
-compatible board:
+See :doc:`../platform/octeontx` for setup information.
+
+
+Initialization
+--------------
+
+The OCTEON TX eventdev is exposed as a vdev device which consists of a set
+of SSO group and work-slot PCIe VF devices. On EAL initialization,
+SSO PCIe VF devices will be probed and then the vdev device can be created
+from the application code, or from the EAL command line based on
+the number of probed/bound SSO PCIe VF device to DPDK by
-1. **OCTEONTX Linux kernel PF driver for Network acceleration HW blocks**
+* Invoking ``rte_vdev_init("event_octeontx")`` from the application
- The OCTEONTX Linux kernel drivers (including the required PF driver for the
- SSOVF) are available on Github at `octeontx-kmod <https://github.com/caviumnetworks/octeontx-kmod>`_
- along with build, install and dpdk usage instructions.
+* Using ``--vdev="event_octeontx"`` in the EAL options, which will call
+ rte_vdev_init() internally
-2. **ARM64 Tool Chain**
+Example:
- For example, the *aarch64* Linaro Toolchain, which can be obtained from
- `here <https://releases.linaro.org/components/toolchain/binaries/4.9-2017.01/aarch64-linux-gnu>`_.
+.. code-block:: console
-3. **Rootfile system**
+ ./your_eventdev_application --vdev="event_octeontx"
- Any *aarch64* supporting filesystem can be used. For example,
- Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
- from `<http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
- As an alternative method, SSOVF PMD can also be executed using images provided
- as part of SDK from Cavium. The SDK includes all the above prerequisites necessary
- to bring up a OCTEONTX board.
+Selftest
+--------
- SDK and related information can be obtained from: `Cavium support site <https://support.cavium.com/>`_.
+The functionality of OCTEON TX eventdev can be verified using this option,
+various unit and functional tests are run to verify the sanity.
+The tests are run once the vdev creation is successfully complete.
-- Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
+.. code-block:: console
-Pre-Installation Configuration
-------------------------------
+ --vdev="event_octeontx,selftest=1"
-Config File Options
-~~~~~~~~~~~~~~~~~~~
-The following options can be modified in the ``config`` file.
-Please note that enabling debugging options may affect system performance.
+Enable TIMvf stats
+------------------
+TIMvf stats can be enabled by using this option, by default the stats are
+disabled.
-- ``CONFIG_RTE_LIBRTE_PMD_OCTEONTX_SSOVF`` (default ``y``)
+.. code-block:: console
- Toggle compilation of the ``librte_pmd_octeontx_ssovf`` driver.
+ --vdev="event_octeontx,timvf_stats=1"
-- ``CONFIG_RTE_LIBRTE_PMD_OCTEONTX_SSOVF_DEBUG`` (default ``n``)
- Toggle display of generic debugging messages
+Limitations
+-----------
-Driver Compilation
+Burst mode support
~~~~~~~~~~~~~~~~~~
-To compile the OCTEONTX SSOVF PMD for Linux arm64 gcc target, run the
-following ``make`` command:
+Burst mode is not supported. Dequeue and Enqueue functions accepts only single
+event at a time.
-.. code-block:: console
+Rx adapter support
+~~~~~~~~~~~~~~~~~~
- cd <DPDK-source-directory>
- make config T=arm64-thunderx-linuxapp-gcc install
+When eth_octeontx is used as Rx adapter event schedule type
+``RTE_SCHED_TYPE_PARALLEL`` is not supported.
+Event timer adapter support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Initialization
---------------
+When timvf is used as Event timer adapter the clock source mapping is as
+follows:
-The octeontx eventdev is exposed as a vdev device which consists of a set
-of SSO group and work-slot PCIe VF devices. On EAL initialization,
-SSO PCIe VF devices will be probed and then the vdev device can be created
-from the application code, or from the EAL command line based on
-the number of probed/bound SSO PCIe VF device to DPDK by
+.. code-block:: console
-* Invoking ``rte_vdev_init("event_octeontx")`` from the application
+ RTE_EVENT_TIMER_ADAPTER_CPU_CLK = TIM_CLK_SRC_SCLK
+ RTE_EVENT_TIMER_ADAPTER_EXT_CLK0 = TIM_CLK_SRC_GPIO
+ RTE_EVENT_TIMER_ADAPTER_EXT_CLK1 = TIM_CLK_SRC_GTI
+ RTE_EVENT_TIMER_ADAPTER_EXT_CLK2 = TIM_CLK_SRC_PTP
-* Using ``--vdev="event_octeontx"`` in the EAL options, which will call
- rte_vdev_init() internally
+When timvf is used as Event timer adapter event schedule type
+``RTE_SCHED_TYPE_PARALLEL`` is not supported.
-Example:
+Max number of events
+~~~~~~~~~~~~~~~~~~~~
+
+Max number of events in OCTEON TX Eventdev (SSO) are only limited by DRAM size
+and they can be configured by passing limits to kernel bootargs as follows:
.. code-block:: console
- ./your_eventdev_application --vdev="event_octeontx"
+ ssopf.max_events=4194304
-Limitations
------------
+The same can be verified by looking at the following sysfs entry:
-Burst mode support
-~~~~~~~~~~~~~~~~~~
+.. code-block:: console
-Burst mode is not supported. Dequeue and Enqueue functions accepts only single
-event at a time.
+ # cat /sys/module/ssopf/parameters/max_events
+ 4194304
+The maximum number of events that can be added to SSO by the event adapters such
+as (Rx/Timer) should be limited to the above configured value.