This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "".

The branch, master has been updated via cabee48a54a68f333569ee1904bc04d53da7c9c6 (commit) via 183ce9babe20e161caef6b55eccfd043b334f748 (commit) via 0fa9977e21010f963892f59a75f03e3ba800bc74 (commit) via b0b07f403ffc22349ac8dd75f47238bea40891be (commit) via bd0377ae95427e80f04b0dd5f3a8dcb0b1ab89e3 (commit) via 5555878edbda765134fbe50f3181f409963037ea (commit) via 009dab38672eaf8ab6eddc551da41a84e86915a5 (commit) from 290decaf3259b036c3a402be428b04ba100f0f81 (commit)

Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below.

- Log ----------------------------------------------------------------- commit cabee48a54a68f333569ee1904bc04d53da7c9c6 Author: Bill Fischofer bill.fischofer@linaro.org Date: Sun Apr 8 16:36:23 2018 -0500

doc: userguide: add pktio capability and config info

Update PktIO section of Users Guide to cover pktio capability and input/output/parser configuration features.

Signed-off-by: Bill Fischofer bill.fischofer@linaro.org Reviewed-by: Josep Puigdemont josep.puigdemont@linaro.org Signed-off-by: Maxim Uvarov maxim.uvarov@linaro.org

diff --git a/doc/users-guide/users-guide-pktio.adoc b/doc/users-guide/users-guide-pktio.adoc index 79d6b1a2..73d6e048 100644 --- a/doc/users-guide/users-guide-pktio.adoc +++ b/doc/users-guide/users-guide-pktio.adoc @@ -132,6 +132,304 @@ use for packet allocation if not overridden by the classifier due to a specific or default Class-of-Service (CoS) match on the packet. The *param* struct, in turn, specifies the input and output *modes* of the PktIO.

+=== PktIO Capabilities and PktIn/PktOut Configuration +Associated with each PktIO is a set of _capabilities_ that provide information +such as the maximum number of input/output queues it supports, its configuration +options, and the operations is supports. These are aggregated into +the struct: +[source,c] +----- +/** + * Packet IO capabilities + */ +typedef struct odp_pktio_capability_t { + /** Maximum number of input queues */ + unsigned max_input_queues; + + /** Maximum number of output queues */ + unsigned max_output_queues; + + /** Supported pktio configuration options */ + odp_pktio_config_t config; + + /** Supported set operations + * + * A bit set to one indicates a supported operation. All other bits are + * set to zero. */ + odp_pktio_set_op_t set_op; + + /** @deprecated Use enable_loop inside odp_pktin_config_t */ + odp_bool_t ODP_DEPRECATE(loop_supported); +} odp_pktio_capability_t; +----- +That is returned by the `odp_pktio_capability()` API. This returns the +limits and default values for these capabilities which can in turn be set +via the `odp_pktio_config()` API, which takes as input the struct: +[source,c] +----- +/** + * Packet IO configuration options + * + * Packet IO interface level configuration options. Use odp_pktio_capability() + * to see which options are supported by the implementation. + * Use odp_pktio_config_init() to initialize the structure with default values. + */ +typedef struct odp_pktio_config_t { + /** Packet input configuration options bit field + * + * Default value for all bits is zero. */ + odp_pktin_config_opt_t pktin; + + /** Packet output configuration options bit field + * + * Default value for all bits is zero. */ + odp_pktout_config_opt_t pktout; + + /** Packet input parser configuration */ + odp_pktio_parser_config_t parser; + + /** Interface loopback mode + * + * In this mode the packets sent out through the interface is + * looped back to input of the same interface. Supporting loopback mode + * is an optional feature per interface and should be queried in the + * interface capability before enabling the same. */ + odp_bool_t enable_loop; + + /** Inbound IPSEC inlined with packet input + * + * Enable/disable inline inbound IPSEC operation. When enabled packet + * input directs all IPSEC packets automatically to IPSEC inbound + * processing. IPSEC configuration is done through the IPSEC API. + * Packets that are not (recognized as) IPSEC are processed + * according to the packet input configuration. + * + * 0: Disable inbound IPSEC inline operation (default) + * 1: Enable inbound IPSEC inline operation + * + * @see odp_ipsec_config(), odp_ipsec_sa_create() + */ + odp_bool_t inbound_ipsec; + + /** Outbound IPSEC inlined with packet output + * + * Enable/disable inline outbound IPSEC operation. When enabled IPSEC + * outbound processing can send outgoing IPSEC packets directly + * to the pktio interface for output. IPSEC configuration is done + * through the IPSEC API. + * + * Outbound IPSEC inline operation cannot be combined with traffic + * manager (ODP_PKTOUT_MODE_TM). + * + * 0: Disable outbound IPSEC inline operation (default) + * 1: Enable outbound IPSEC inline operation + * + * @see odp_ipsec_config(), odp_ipsec_sa_create() + */ + odp_bool_t outbound_ipsec; + +} odp_pktio_config_t; +----- +The IPsec related configurations will be discussed later in the IPsec chapter, +but for now we'll focus on the PktIn/PktOut configuration and the +parser configuration. + +==== PktIn Configuration +For PktIOs that will receive packets, the `odp_pktin_config_opt_t` struct +controls RX processing to be performed on these packets as they are received: +[source,c] +----- +/** + * Packet input configuration options bit field + * + * Packet input configuration options listed in a bit field structure. Packet + * input timestamping may be enabled for all packets or at least for those that + * belong to time synchronization protocol (PTP). + * + * Packet input checksum checking may be enabled or disabled. When it is + * enabled, implementation will attempt to verify checksum correctness on + * incoming packets and depending on drop configuration either deliver erroneous + * packets with appropriate flags set (e.g. odp_packet_has_l3_error(), + * odp_packet_l3_chksum_status()) or drop those. When packet dropping is + * enabled, application will never receive a packet with the specified error + * and may avoid to check the error flag. + * + * If checksum checking is enabled, IPv4 header checksum checking is always + * done for packets that do not have IP options and L4 checksum checking + * is done for unfragmented packets that do not have IPv4 options or IPv6 + * extension headers. In other cases checksum checking may or may not + * be done. For example, L4 checksum of fragmented packets is typically + * not checked. + * + * IPv4 checksum checking may be enabled only when parsing level is + * ODP_PROTO_LAYER_L3 or higher. Similarly, L4 level checksum checking + * may be enabled only with parsing level ODP_PROTO_LAYER_L4 or higher. + * + * Whether checksum checking was done and whether a checksum was correct + * can be queried for each received packet with odp_packet_l3_chksum_status() + * and odp_packet_l4_chksum_status(). + */ +typedef union odp_pktin_config_opt_t { + /** Option flags */ + struct { + /** Timestamp all packets on packet input */ + uint64_t ts_all : 1; + + /** Timestamp (at least) IEEE1588 / PTP packets + * on packet input */ + uint64_t ts_ptp : 1; + + /** Check IPv4 header checksum on packet input */ + uint64_t ipv4_chksum : 1; + + /** Check UDP checksum on packet input */ + uint64_t udp_chksum : 1; + + /** Check TCP checksum on packet input */ + uint64_t tcp_chksum : 1; + + /** Check SCTP checksum on packet input */ + uint64_t sctp_chksum : 1; + + /** Drop packets with an IPv4 error on packet input */ + uint64_t drop_ipv4_err : 1; + + /** Drop packets with an IPv6 error on packet input */ + uint64_t drop_ipv6_err : 1; + + /** Drop packets with a UDP error on packet input */ + uint64_t drop_udp_err : 1; + + /** Drop packets with a TCP error on packet input */ + uint64_t drop_tcp_err : 1; + + /** Drop packets with a SCTP error on packet input */ + uint64_t drop_sctp_err : 1; + + } bit; + + /** All bits of the bit field structure + * + * This field can be used to set/clear all flags, or bitwise + * operations over the entire structure. */ + uint64_t all_bits; +} odp_pktin_config_opt_t; +----- +These are used to control packet timestamping as well as default packet checkum +verification processing. + +==== PktIO Parsing Configuration +For RX processing, packets may also be parsed automatically as part of +receipt as controlled by the `odp_pktio_parser_config_t` struct: +[source,c] +----- +/** + * Parser configuration + */ +typedef struct odp_pktio_parser_config_t { + /** Protocol parsing level in packet input + * + * Application requires that protocol headers in a packet are checked + * up to this layer during packet input. Use ODP_PROTO_LAYER_ALL for + * all layers. Packet metadata for this and all preceding layers are + * set. In addition, offset (and pointer) to the next layer is set. + * Other layer/protocol specific metadata have undefined values. + * + * The default value is ODP_PROTO_LAYER_ALL. */ + odp_proto_layer_t layer; + +} odp_pktio_parser_config_t; +----- +Note that parsing is automatically done whenever classification is enabled +for an RX interface (see below). + +==== PktOut Configuration +For PktIOs that will transmit packets, the `odp_pktout_config_opt_t` struct +controls TX processing to be performed on these packets as they are +transmitted: +[source,c] +----- +/** + * Packet output configuration options bit field + * + * Packet output configuration options listed in a bit field structure. Packet + * output checksum insertion may be enabled or disabled (e.g. ipv4_chksum_ena): + * + * 0: Disable checksum insertion. Application will not request checksum + * insertion for any packet. This is the default value for xxx_chksum_ena + * bits. + * 1: Enable checksum insertion. Application will request checksum insertion + * for some packets. + * + * When checksum insertion is enabled, application may use configuration options + * to set the default behaviour on packet output (e.g. ipv4_chksum): + * + * 0: Do not insert checksum by default. This is the default value for + * xxx_chksum bits. + * 1: Calculate and insert checksum by default. + * + * These defaults may be overridden on per packet basis using e.g. + * odp_packet_l4_chksum_insert(). + * + * For correct operation, packet metadata must provide valid offsets for the + * appropriate protocols. For example, UDP checksum calculation needs both L3 + * and L4 offsets (to access IP and UDP headers). When application + * (e.g. a switch) does not modify L3/L4 data and thus checksum does not need + * to be updated, checksum insertion should be disabled for optimal performance. + * + * Packet flags (odp_packet_has_*()) are ignored for the purpose of checksum + * insertion in packet output. + * + * UDP, TCP and SCTP checksum insertion must not be requested for IP fragments. + * Use checksum override function (odp_packet_l4_chksum_insert()) to disable + * checksumming when sending a fragment through a packet IO interface that has + * the relevant L4 checksum insertion enabled. + * + * Result of checksum insertion at packet output is undefined if the protocol + * headers required for checksum calculation are not well formed. Packet must + * contain at least as many data bytes after L3/L4 offsets as the headers + * indicate. Other data bytes of the packet are ignored for the checksum + * insertion. + */ +typedef union odp_pktout_config_opt_t { + /** Option flags for packet output */ + struct { + /** Enable IPv4 header checksum insertion. */ + uint64_t ipv4_chksum_ena : 1; + + /** Enable UDP checksum insertion */ + uint64_t udp_chksum_ena : 1; + + /** Enable TCP checksum insertion */ + uint64_t tcp_chksum_ena : 1; + + /** Enable SCTP checksum insertion */ + uint64_t sctp_chksum_ena : 1; + + /** Insert IPv4 header checksum by default */ + uint64_t ipv4_chksum : 1; + + /** Insert UDP checksum on packet by default */ + uint64_t udp_chksum : 1; + + /** Insert TCP checksum on packet by default */ + uint64_t tcp_chksum : 1; + + /** Insert SCTP checksum on packet by default */ + uint64_t sctp_chksum : 1; + + } bit; + + /** All bits of the bit field structure + * + * This field can be used to set/clear all flags, or bitwise + * operations over the entire structure. */ + uint64_t all_bits; +} odp_pktout_config_opt_t; +----- +These are used to control default checksum generation processing for +transmitted packets. + === PktIO Input and Output Modes PktIO objects support four different Input and Output modes, that may be specified independently at *open* time.

commit 183ce9babe20e161caef6b55eccfd043b334f748 Author: Bill Fischofer bill.fischofer@linaro.org Date: Sun Apr 8 16:35:21 2018 -0500

doc: userguide: add packet checksum and parsing info

Update packet documentation to include information on packet parsing and checksum override handling.

Signed-off-by: Bill Fischofer bill.fischofer@linaro.org Reviewed-by: Josep Puigdemont josep.puigdemont@linaro.org Signed-off-by: Maxim Uvarov maxim.uvarov@linaro.org

diff --git a/doc/users-guide/users-guide-packet.adoc b/doc/users-guide/users-guide-packet.adoc index 6d9e98a5..c38c5c86 100644 --- a/doc/users-guide/users-guide-packet.adoc +++ b/doc/users-guide/users-guide-packet.adoc @@ -499,3 +499,38 @@ Note also that a packet may not reference itself, nor may circular reference relationships be formed, _e.g.,_ packet A is used as a header for a reference to packet B and B is used as a header for a reference to packet A. Results are undefined if such circular references are attempted. + +=== Packet Parsing, Checksum Processing, and Overrides +Packet parsing is normally triggered automatically as part of packet RX +processing. However, the application can trigger parsing explicitly via the +API: +[source,c] +----- +int odp_packet_parse(odp_packet_t pkt, uint32_t offset, + const odp_packet_parse_param_t *param); +----- +This is typically done following packet decapsulation or other preprocessing +that would prevent RX parsing from "seeing" the relevant portion of the +packet. The `odp_packet_parse_param_t` struct that is passed to control the +depth of the desired parse, as well as whether checksum validation should be +performed as part of the parse, and if so which checksums require this +processing. + +Packets containing Layer 3 (IPv4) and Layer 4 (TCP, UDP, SCTP) checksums +can have these validated (on RX) and generated (on TX) automatically. +This is normally controlled by the settings on the PktIOs that +receive/transmit them, however they can also be controlled on an +individual packet basis. + +Packets have associated `odp_packet_chksum_status_t` metadata that indicates +the state any checksums contained in that packet. These can be queried via +the APIs `odp_packet_l3_chksum_status()` and `odp_packet_l4_chksum_status()`, +respectively. Checksums can either be known good, known bad, or unknown, where +unknown means that checksum validation processing has not occurred or the +attempt to validate the checksum failed. + +Similarly, the `odp_packet_l3_chksum_insert()` and +`odp_packet_l4_chksum_insert()` APIs may be used to override default checksum +processing for individual packets prior to transmission. If no explicit +checksum processing is specified for a packet, then any checksum generation +is controlled by the PktIO configuration of the interface used to transmit it.

commit 0fa9977e21010f963892f59a75f03e3ba800bc74 Author: Bill Fischofer bill.fischofer@linaro.org Date: Thu Apr 5 17:04:13 2018 -0500

doc: userguide: refresh pktio code examples

Update pktio code examples to reflect latest API definitions.

Signed-off-by: Bill Fischofer bill.fischofer@linaro.org Reviewed-by: Josep Puigdemont josep.puigdemont@linaro.org Signed-off-by: Maxim Uvarov maxim.uvarov@linaro.org

diff --git a/doc/users-guide/users-guide-pktio.adoc b/doc/users-guide/users-guide-pktio.adoc index ef5cced6..79d6b1a2 100644 --- a/doc/users-guide/users-guide-pktio.adoc +++ b/doc/users-guide/users-guide-pktio.adoc @@ -38,6 +38,9 @@ PktIO objects begin life by being _opened_ via the call: * errno set. Use odp_pktio_lookup() to obtain a handle to an already open * device. Packet IO parameters provide interface level configuration options. * + * Use odp_pktio_param_init() to initialize packet IO parameters into their + * default values. Default values are also used when 'param' pointer is NULL. + * * Packet input queue configuration must be setup with * odp_pktin_queue_config() before odp_pktio_start() is called. When packet * input mode is ODP_PKTIN_MODE_DISABLED, odp_pktin_queue_config() call is @@ -66,7 +69,7 @@ PktIO objects begin life by being _opened_ via the call: * @param name Packet IO device name * @param pool Default pool from which to allocate storage for packets * received over this interface, must be of type ODP_POOL_PACKET - * @param param Packet IO parameters + * @param param Packet IO parameters. Uses defaults when NULL. * * @return Packet IO handle * @retval ODP_PKTIO_INVALID on failure @@ -85,7 +88,7 @@ PktIO objects begin life by being _opened_ via the call: * @see odp_pktio_start(), odp_pktio_stop(), odp_pktio_close() */ odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, - const odp_pktio_param_t *param); + const odp_pktio_param_t *param); ----- `odp_pktio_open()` takes three arguments: a *name*, which is an implementation-defined string that identifies the logical interface to be @@ -97,18 +100,20 @@ I/O options to be associated with this PktIO instance. /** * Packet IO parameters * - * In minimum, user must select input and output modes. Use 0 for defaults. - * Initialize entire struct with zero to maintain API compatibility. + * Packet IO interface level parameters. Use odp_pktio_param_init() to + * initialize the structure with default values. */ typedef struct odp_pktio_param_t { /** Packet input mode * * The default value is ODP_PKTIN_MODE_DIRECT. */ odp_pktin_mode_t in_mode; + /** Packet output mode * * The default value is ODP_PKTOUT_MODE_DIRECT. */ odp_pktout_mode_t out_mode; + } odp_pktio_param_t; ----- ODP defines *"loop"* as a reserved name to indicate that this PktIO represents @@ -209,25 +214,48 @@ typedef struct odp_pktin_queue_param_t { * applicable. */ odp_pktio_op_mode_t op_mode;

+ /** Enable classifier + * + * * 0: Classifier is disabled (default) + * * 1: Classifier is enabled. Use classifier to direct incoming + * packets into pktin event queues. Classifier can be enabled + * only in ODP_PKTIN_MODE_SCHED and ODP_PKTIN_MODE_QUEUE modes. + * Both classifier and hashing cannot be enabled simultaneously + * ('hash_enable' must be 0). */ + odp_bool_t classifier_enable; + /** Enable flow hashing - * 0: Do not hash flows - * 1: Hash flows to input queues */ + * + * * 0: Do not hash flows (default) + * * 1: Enable flow hashing. Use flow hashing to spread incoming + * packets into input queues. Hashing can be enabled in all + * modes. Both classifier and hashing cannot be enabled + * simultaneously ('classifier_enable' must be 0). */ odp_bool_t hash_enable;

- /** Protocol field selection for hashing. Multiple protocols can be - * selected. */ + /** Protocol field selection for hashing + * + * Multiple protocols can be selected. Ignored when 'hash_enable' is + * zero. The default value is all bits zero. */ odp_pktin_hash_proto_t hash_proto;

- /** Number of input queues to be created. More than one input queue - * require input hashing or classifier setup. Hash_proto is ignored - * when hash_enable is zero or num_queues is one. This value must be - * between 1 and interface capability. Queue type is defined by the - * input mode. The default value is 1. */ + /** Number of input queues to be created + * + * When classifier is enabled in odp_pktin_queue_config() this + * value is ignored, otherwise at least one queue is required. + * More than one input queues require flow hashing configured. + * The maximum value is defined by pktio capability 'max_input_queues'. + * Queue type is defined by the input mode. The default value is 1. */ unsigned num_queues;

- /** Queue parameters for creating input queues in ODP_PKTIN_MODE_QUEUE + /** Queue parameters + * + * These are used for input queue creation in ODP_PKTIN_MODE_QUEUE * or ODP_PKTIN_MODE_SCHED modes. Scheduler parameters are considered - * only in ODP_PKTIN_MODE_SCHED mode. */ + * only in ODP_PKTIN_MODE_SCHED mode. Default values are defined in + * odp_queue_param_t documentation. + * When classifier is enabled in odp_pktin_queue_config() this + * value is ignored. */ odp_queue_param_t queue_param;

} odp_pktin_queue_param_t; @@ -347,8 +375,10 @@ Once started, the PktIn queue handles are used as arguments to /** * Receive packets directly from an interface input queue * - * Receives up to 'num' packets from the pktio interface input queue. When - * input queue parameter 'op_mode' has been set to ODP_PKTIO_OP_MT_UNSAFE, + * Receives up to 'num' packets from the pktio interface input queue. Returns + * the number of packets received. + * + * When input queue parameter 'op_mode' has been set to ODP_PKTIO_OP_MT_UNSAFE, * the operation is optimized for single thread operation per queue and the same * queue must not be accessed simultaneously from multiple threads. * @@ -478,6 +508,11 @@ Once the PktIO has been configured for output and started via * is less than 'num', the remaining packets at the end of packets[] array * are not consumed, and the caller has to take care of them. * + * Entire packet data is sent out (odp_packet_len() bytes of data, starting from + * odp_packet_data()). All other packet metadata is ignored unless otherwise + * specified e.g. for protocol offload purposes. Link protocol specific frame + * checksum and padding are added to frames before transmission. + * * @param queue Packet output queue handle for sending packets * @param packets[] Array of packets to send * @param num Number of packets to send @@ -485,7 +520,8 @@ Once the PktIO has been configured for output and started via * @return Number of packets sent * @retval <0 on failure */ -int odp_pktout_send(odp_pktout_queue_t queue, odp_packet_t packets[], int num); +int odp_pktout_send(odp_pktout_queue_t queue, const odp_packet_t packets[], + int num);; ----- Note that the argument to this call specifies the PktOut queue that the packet is to be added to rather than the PktIO itself. This permits multiple

commit b0b07f403ffc22349ac8dd75f47238bea40891be Author: Bill Fischofer bill.fischofer@linaro.org Date: Wed Apr 4 16:20:47 2018 -0500

doc: userguide: change sched type none to parallel

Replace old ODP_SCHED_SYNC_NONE with current ODP_SCHED_SYNC_PARALLEL when describing queue scheduling options.

Signed-off-by: Bill Fischofer bill.fischofer@linaro.org Reviewed-by: Josep Puigdemont josep.puigdemont@linaro.org Signed-off-by: Maxim Uvarov maxim.uvarov@linaro.org

diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 9c1307b4..7914459e 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -998,7 +998,7 @@ odp_queue_param_init(&qp); odp_schedule_prio_t prio = ...; odp_schedule_group_t sched_group = ...; qp.sched.prio = prio; -qp.sched.sync = ODP_SCHED_SYNC_[NONE|ATOMIC|ORDERED]; +qp.sched.sync = ODP_SCHED_SYNC_[PARALLEL|ATOMIC|ORDERED]; qp.sched.group = sched_group; qp.lock_count = n; /* Only relevant for ordered queues */ odp_queue_t sched_q1 = odp_queue_create("sched queue 1", ODP_QUEUE_TYPE_SCHED, &qp); @@ -1054,8 +1054,8 @@ Three types of queue scheduler synchronization area supported: Parallel, Atomic, and Ordered.

==== Parallel Queues -SCHED queues that specify a sync mode of ODP_SCHED_SYNC_NONE are unrestricted -in how events are processed. +SCHED queues that specify a sync mode of ODP_SCHED_SYNC_PARALLEL are +unrestricted in how events are processed.

.Parallel Queue Scheduling image::parallel_queue.svg[align="center"]

commit bd0377ae95427e80f04b0dd5f3a8dcb0b1ab89e3 Author: Bill Fischofer bill.fischofer@linaro.org Date: Wed Apr 4 16:19:27 2018 -0500

doc: userguide: shm corrections

Clarify the use of the ODP_SHM_SINGLE_VM flag on shm operations.

Signed-off-by: Bill Fischofer bill.fischofer@linaro.org Reviewed-by: Josep Puigdemont josep.puigdemont@linaro.org Signed-off-by: Maxim Uvarov maxim.uvarov@linaro.org

diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index e480c69d..9c1307b4 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -798,16 +798,16 @@ shared_data_t *shared_data; shared_data = odp_shm_addr(shm); ----

-The address returned by `odp_shm_addr()` is valid only in the calling ODP -thread space: odp_shm_t handles can be shared between ODP threads and remain -valid within any threads, whereas the address returned by `odp_shm_addr(shm)` -may differ from ODP threads to ODP threads (for the same 'shm' block), and -should therefore not be shared between ODP threads. -For instance, it would be correct to send a shm handle using IPC between two -ODP threads and let each of these thread do their own `odp_shm_addr()` to -get the block address. Directly sending the address returned by -`odp_shm_addr()` from one ODP thread to another would however possibly fail -(the address may have no sense in the receiver address space). +The address returned by `odp_shm_addr()` is normally valid only in the calling +ODP thread space: odp_shm_t handles can be shared between ODP threads and +remain valid within any threads, whereas the address returned by +`odp_shm_addr(shm)` may differ from ODP threads to ODP threads (for the same +'shm' block), and should therefore not be shared between ODP threads. For +instance, it would be correct to send a shm handle using IPC between two ODP +threads and let each of these thread do their own `odp_shm_addr()` to get the +block address. Directly sending the address returned by `odp_shm_addr()` from +one ODP thread to another would however possibly fail (the address may make no +sense in the receiver address space).

The address returned by `odp_shm_addr()` is nevertheless guaranteed to be aligned according to the alignment requirements provided at block creation @@ -819,7 +819,13 @@ All shared memory blocks are contiguous in any ODP thread addressing space: as provided in the `odp_shm_reserve()` call) is read and writeable and mapping the shared memory block. There is no fragmentation.

-=== Memory behaviour +The exception to this rule is if the `odp_shm_t` is created with the +`ODP_SHM_SINGLE_VA` flag. This requests that `odp_shm_addr()` return the same +virtual address for all ODP threads in this instance. Note that there may be a +performance cost or shm size limit associated with providing this function in +some implementations. + +=== Memory behavior By default ODP threads are assumed to behave as cache coherent systems: Any change performed on a shared memory block is guaranteed to eventually become visible to other ODP threads sharing this memory block.

commit 5555878edbda765134fbe50f3181f409963037ea Author: Bill Fischofer bill.fischofer@linaro.org Date: Wed Apr 4 16:18:11 2018 -0500

doc: userguide: change pool queue to plain queue

Queues fall into types PLAIN and SCHED. Correct terminology from the old POLL queue type to the current PLAIN queue type.

Signed-off-by: Bill Fischofer bill.fischofer@linaro.org Reviewed-by: Josep Puigdemont josep.puigdemont@linaro.org Signed-off-by: Maxim Uvarov maxim.uvarov@linaro.org

diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index d0687f97..e480c69d 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -312,7 +312,7 @@ appropriate type represented by the event. A queue is a message passing channel that holds events. Events can be added to a queue via enqueue operations or removed from a queue via dequeue operations. The endpoints of a queue will vary depending on how it is used. -Queues come in two major types: polled and scheduled, which will be +Queues come in two major types: plain and scheduled, which will be discussed in more detail when the event model is introduced. Queues may also have an associated context, which represents a persistent state for all events that make use of it. These states are what permit threads to perform @@ -964,23 +964,23 @@ Queues are the fundamental event sequencing mechanism provided by ODP and all ODP applications make use of them either explicitly or implicitly. Queues are created via the 'odp_queue_create()' API that returns a handle of type `odp_queue_t` that is used to refer to this queue in all subsequent APIs that -reference it. Queues have one of two ODP-defined _types_, POLL, and SCHED that -determine how they are used. POLL queues directly managed by the ODP +reference it. Queues have one of two ODP-defined _types_, PLAIN, and SCHED that +determine how they are used. PLAIN queues directly managed by the ODP application while SCHED queues make use of the *ODP scheduler* to provide automatic scalable dispatching and synchronization services.

-.Operations on POLL queues +.Operations on PLAIN queues [source,c] ---- -odp_queue_t poll_q1 = odp_queue_create("poll queue 1", ODP_QUEUE_TYPE_POLL, NULL); -odp_queue_t poll_q2 = odp_queue_create("poll queue 2", ODP_QUEUE_TYPE_POLL, NULL); +odp_queue_t plain_q1 = odp_queue_create("poll queue 1", ODP_QUEUE_TYPE_PLAIN, NULL); +odp_queue_t plain_q2 = odp_queue_create("poll queue 2", ODP_QUEUE_TYPE_PLAIN, NULL); ... -odp_event_t ev = odp_queue_deq(poll_q1); +odp_event_t ev = odp_queue_deq(plain_q1); ...do something -int rc = odp_queue_enq(poll_q2, ev); +int rc = odp_queue_enq(plain_q2, ev); ----

-The key distinction is that dequeueing events from POLL queues is an +The key distinction is that dequeueing events from PLAIN queues is an application responsibility while dequeueing events from SCHED queues is the responsibility of the ODP scheduler.

commit 009dab38672eaf8ab6eddc551da41a84e86915a5 Author: Bill Fischofer bill.fischofer@linaro.org Date: Wed Apr 4 16:16:11 2018 -0500

doc: userguide: typo corrections

Signed-off-by: Bill Fischofer bill.fischofer@linaro.org Signed-off-by: Josep Puigdemont josep.puigdemont@linaro.org Signed-off-by: Maxim Uvarov maxim.uvarov@linaro.org

diff --git a/doc/users-guide/users-guide-cls.adoc b/doc/users-guide/users-guide-cls.adoc index a689826c..359d225d 100644 --- a/doc/users-guide/users-guide-cls.adoc +++ b/doc/users-guide/users-guide-cls.adoc @@ -7,7 +7,7 @@ prioritization, classification and scheduling of each packet, so that the software application can run faster, scale better and adhere to QoS requirements.

-The following API abstraction are not modelled after any existing product +The following API abstraction are not modeled after any existing product implementation, but is instead defined in terms of what a typical data-plane application may require from such a platform, without sacrificing simplicity and avoiding ambiguity. Certain terms that are being used within the context of diff --git a/doc/users-guide/users-guide-crypto.adoc b/doc/users-guide/users-guide-crypto.adoc index 029f47b1..b44402ad 100644 --- a/doc/users-guide/users-guide-crypto.adoc +++ b/doc/users-guide/users-guide-crypto.adoc @@ -175,7 +175,7 @@ any software generated pseudo-random data. May not be available on all platforms.

These form a hierarchy with BASIC being the lowest kind of random and TRUE -behing the highest. The main API for accessing random data is: +being the highest. The main API for accessing random data is:

[source,c] ----- diff --git a/doc/users-guide/users-guide-ipsec.adoc b/doc/users-guide/users-guide-ipsec.adoc index ac4eae85..6af67662 100644 --- a/doc/users-guide/users-guide-ipsec.adoc +++ b/doc/users-guide/users-guide-ipsec.adoc @@ -381,7 +381,7 @@ any further application involvement. Only if a problem arises will the packet be returned to the application with an `odp_ipsec_packet_result_t` indicating the nature of the problem.

-Note that while operating in inline mode, asychronous lookaside operations are +Note that while operating in inline mode, asynchronous lookaside operations are also permitted. This provide the application with additional flexibility if, for example, some packets need additional handling that cannot be supported directly with inline IPsec processing. @@ -449,7 +449,7 @@ the application continues to receive and process IPsec events as normal. Disable completion is indicated by the application seeing an event of type `ODP_EVENT_IPSEC_STATUS` for this SA that contains an `odp_ipsec_status_id_t` of `ODP_IPSEC_STATUS_SA_DISABLE`. For inbound SAs, receipt of this event means -that the application has seen all IPsec packets associatd with this SA that +that the application has seen all IPsec packets associated with this SA that were pending at the time of the disable call. For outbound SAs, receipt of this event means that the application has seen all result events associated with packets sent via this SA. diff --git a/doc/users-guide/users-guide-pktio.adoc b/doc/users-guide/users-guide-pktio.adoc index 80a58d2f..ef5cced6 100644 --- a/doc/users-guide/users-guide-pktio.adoc +++ b/doc/users-guide/users-guide-pktio.adoc @@ -114,8 +114,8 @@ typedef struct odp_pktio_param_t { ODP defines *"loop"* as a reserved name to indicate that this PktIO represents a loopback interface. Loopback interfaces are useful as a means of recycling packets back for reclassification after decryption or decapsulation, as well as -for diagnostic or testing purposes. For example, when receiving IPSEC traffic, -the classifier is able to recognize that the traffic is IPSEC, however until +for diagnostic or testing purposes. For example, when receiving IPsec traffic, +the classifier is able to recognize that the traffic is IPsec, however until the traffic is decrypted it is unable to say what that traffic contains. So following decryption, sending the decrypted packet back to a loopback interface allows the classifier to take a "second look" at the packet and diff --git a/doc/users-guide/users-guide-tm.adoc b/doc/users-guide/users-guide-tm.adoc index 25129733..55efb1b2 100644 --- a/doc/users-guide/users-guide-tm.adoc +++ b/doc/users-guide/users-guide-tm.adoc @@ -10,7 +10,7 @@ A given platform supporting this TM API could support one or more pure hardware based packet scheduling systems, one or more pure software based systems or one or more hybrid systems - where because of hardware constraints some of the packet scheduling is done in hardware and some is done in software. In -addition, there may also be additional API's beyond those described here for: +addition, there may also be additional APIs beyond those described here for:

- controlling advanced capabilities supported by specific hardware, software or hybrid subsystems @@ -84,7 +84,7 @@ traffic, while allowing for less idle outputs.

==== Weighted Fair Queuing

-Weighted Fair Queuing (WFQ) is used to arbitrate amongst multiple input +Weighted Fair Queuing (WFQ) is used to arbitrate among multiple input packets with the same priority. Each input can be assigned a weight in the range MIN_WFQ_WEIGHT..MAX_WFQ_WEIGHT (nominally 1..255) that affects the way the algorithm chooses the next packet. If all of the weights are equal AND all @@ -158,7 +158,7 @@ final scheduling decision is controlled by equal priority schedulers, strict priority multiplexers, bandwidth shapers - at multiple levels - all forming a tree rooted at a single egress object. In other words, all tm_queues and tm_nodes have the property that their logical "output" feeds -into one fan-in of a subsequent tm_node or egresss object - forming a proper +into one fan-in of a subsequent tm_node or egress object - forming a proper tree.

.Hierarchical Scheduling @@ -178,7 +178,7 @@ choice" of what packet/tm_queue should next be serviced. Tm_nodes are the main "entity"/object that a TM system is composed of. Each tm_node is a mini-TM subsystem of its own, but the interconnection and interplay of a multi-level "tree" of tm_nodes can allow the user to specify -some very sophisticated behaviours. Each tm_node can contain a set of scheduler +some very sophisticated behaviors. Each tm_node can contain a set of scheduler (one per strict priority level), a strict priority multiplexer, a bandwidth shaper and a WRED component - or a subset of these.

diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 7f2ad69e..d0687f97 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -151,7 +151,7 @@ of the specification or other minor changes that do not affect either the syntax or semantics of the specification. Such changes in the API specification are expected to be rare. Increments to the minor level represent the introduction of new APIs or functional capabilities, or changes -to he specified syntax or functional behavior of APIs and thus may require +to the specified syntax or functional behavior of APIs and thus may require application source code changes. Such changes are well documented in the release notes for each revision of the specification. Finally, increments to the major level represent significant structural changes that most likely @@ -247,14 +247,14 @@ polled by ODP _Threads_, or can pass through the _Classifier_ and sorted into Queues that represent individual flows. These queues can then be dispatched to application threads via the _Scheduler_.

-Threads, in term can invoke various ODP APIs to manipulate packet contents +Threads, in turn can invoke various ODP APIs to manipulate packet contents prior to disposing of them. For output processing, packets make by directly queued to a PktIO output queue or else they may be handed to the _Traffic Manager_ for programmatic _Quality of Service (QoS)_ processing before winding up being transmitted (TX). Note that output interfaces may operate in _loopback_ mode, in which case packets sent to them are re-routed back to the -input lines for "second pass" processing. For example, an incoming IPSec packet -cannot be properly classified (beyond being IPSec traffic) until it is +input lines for "second pass" processing. For example, an incoming IPsec packet +cannot be properly classified (beyond being IPsec traffic) until it is decrypted. Once decrypted and its actual contents made visible, it can then be classified into its real flow.

@@ -576,7 +576,7 @@ values. Calling `odp_init_global()` establishes the ODP API framework and MUST be called before any other ODP API may be called. Note that it is only called once per application. A successful call to `odp_init_global()` returns rc = 0 -and sets the `instance` variable supplied as input to the call to an handle +and sets the `instance` variable supplied as input to the call to a handle representing this unique ODP instance.

The `odp_init_t` parameter is used to specify various customizations to the @@ -661,7 +661,7 @@ area and how best to use ODP to achieve these goals. === Portability and Coexistence Because ODP offers a programming _framework_ rather than a programming _environment_, it is designed to be able to work alongside APIs offered by -other frameworks with minimual interference. Therefore when we speak of +other frameworks with minimal interference. Therefore when we speak of portability in an ODP context, we of necessity speak of portability of those portions of the application that make use of ODP APIs. If an application uses non-ODP APIs then those must be taken into consideration as well when @@ -756,10 +756,10 @@ Architecture (ISA), such as x86-64 or AArch64. Binaries cannot directly port between ISAs--that requires a recompilation.

Each ODP implementation will identify which ABI definition it supports, if any. -When compiling against an ODP implementation in ABI compabitilty mode, the +When compiling against an ODP implementation in ABI compatibility mode, the resulting binary is automatically binary compatible with all other ODP implementations that share this ABI. For example, for the x86-64 ISA, both -the `odp-linux` and `odp-dpdk` implemtations are a common ABI. +the `odp-linux` and `odp-dpdk` implementations are a common ABI.

== Shared memory === Allocating shared memory

-----------------------------------------------------------------------

Summary of changes: doc/users-guide/users-guide-cls.adoc | 2 +- doc/users-guide/users-guide-crypto.adoc | 2 +- doc/users-guide/users-guide-ipsec.adoc | 4 +- doc/users-guide/users-guide-packet.adoc | 35 +++ doc/users-guide/users-guide-pktio.adoc | 374 ++++++++++++++++++++++++++++++-- doc/users-guide/users-guide-tm.adoc | 8 +- doc/users-guide/users-guide.adoc | 68 +++--- 7 files changed, 434 insertions(+), 59 deletions(-)

hooks/post-receive