aboutsummaryrefslogtreecommitdiff
path: root/platform/linux-generic/README
diff options
context:
space:
mode:
Diffstat (limited to 'platform/linux-generic/README')
-rw-r--r--platform/linux-generic/README90
1 files changed, 77 insertions, 13 deletions
diff --git a/platform/linux-generic/README b/platform/linux-generic/README
index 3e05dabf2..905b06a4a 100644
--- a/platform/linux-generic/README
+++ b/platform/linux-generic/README
@@ -1,17 +1,81 @@
-Copyright (c) 2014, Linaro Limited
-All rights reserved.
-
-SPDX-License-Identifier: BSD-3-Clause
+SPDX-License-Identifier: BSD-3-Clause
+Copyright (c) 2014-2018 Linaro Limited
+Copyright (c) 2019-2023 Nokia
1. Intro
-
-OpenDataPlane implementation for Linux generic. Directory linux-generic contains ODP headers and implementation
-for linux-generic target. This drop does not target high
-performance. It is rather proof of ODP API functionality. It still uses
-linux-generic's SW scheduler.
+ OpenDataPlane API generic Linux implementation. Directory linux-generic
+ contains the header and source files and additional platform test scripts
+ for ODP linux-generic implementation.
2. Build
-# To compile ODP
-./bootstrap
-./configure
-make
+ See DEPENDENCIES file about system requirements and dependencies to external
+ libraries/packages. It contains also more detailed build instructions.
+
+ Generally, ODP is built with these three steps:
+ ./bootstrap
+ ./configure
+ make
+
+3. Configuration file
+ See config/README for application runtime configuration options.
+
+4. Packet I/O
+ When passing a packet I/O device name to odp_pktio_open() one can explicitly
+ specify the used implementation internal pktio type. The pktio type can be
+ selected by adding a pktio type prefix to the device name separated by a
+ colon (<pktio_type>:<if_name>).
+
+ E.g.
+ socket:eth1
+ socket_xdp:eth2
+
+ The supported pktio types are:
+ dpdk
+ ipc
+ loop
+ null
+ pcap
+ socket
+ socket_mmap
+ socket_xdp
+ tap
+
+5. Random data
+ On x86 ODP_RANDOM_TRUE type random data is generated using rdseed [1] via
+ compiler builtin functions. If OpenSSL is not available or its use for
+ generating random data is disabled with the --disable-openssl-rand
+ configure option, ODP_RANDOM_CRYPTO type random data is generated using
+ rdrand [1].
+
+ Note that there may be issues with the quality or security of rdrand and
+ rdseed. [2]
+
+6. Event validation
+ ODP linux-generic implementation supports additional fast path event
+ validity checks which are disabled by default to minimize overhead. These
+ checks can be enabled with --enable-event-validation [abort/warn] or
+ --enabled-debug=full configuration options.
+
+ Event validation adds additional endmark data to ODP buffers and packets,
+ which is used to detect data writes outside allowed areas. Endmarks are
+ checked by the implementation each time application calls one the following
+ API functions:
+ - odp_buffer_free() / odp_buffer_free_multi()
+ - odp_buffer_is_valid()
+ - odp_event_free() / odp_event_free_multi() / odp_event_free_sp()
+ - odp_event_is_valid()
+ - odp_packet_free() / odp_packet_free_multi() / odp_packet_free_sp()
+ - odp_packet_is_valid()
+ - odp_queue_enq() / odp_queue_enq_multi()
+
+ Event validation can function in two modes: abort (default) and warn. In
+ abort mode the application is terminated immediately if an event validity
+ check fails. In warn mode only an error log message is printed.
+
+7. References
+ [1] Intel Digital Random Number Generator (DRNG) Software Implementation
+ Guide. John P Mechalas, 17 October 2018.
+ https://www.intel.com/content/www/us/en/developer/articles/guide/intel-digital-random-number-generator-drng-software-implementation-guide.html
+
+ [2] RDRAND. Wikipedia, 29 September 2021.
+ https://en.wikipedia.org/wiki/RDRAND#Reception