diff options
Diffstat (limited to 'doc/users-guide/users-guide-packet.adoc')
| -rw-r--r-- | doc/users-guide/users-guide-packet.adoc | 69 |
1 files changed, 42 insertions, 27 deletions
diff --git a/doc/users-guide/users-guide-packet.adoc b/doc/users-guide/users-guide-packet.adoc index d5f2ff192..246cf7702 100644 --- a/doc/users-guide/users-guide-packet.adoc +++ b/doc/users-guide/users-guide-packet.adoc @@ -42,11 +42,11 @@ to manipulate its structure. To support packet manipulation, predefined _headroom_ and _tailroom_ areas are logically associated with a packet. Packets can be adjusted by _pulling_ and _pushing_ these areas. Typical packet processing might consist -of stripping headers from a packet via `odp_pull_head()` calls as part of +of stripping headers from a packet via `odp_packet_pull_head()` calls as part of receive processing and then replacing them with new headers via -`odp_push_head()` calls as the packet is being prepared for transmit. Note that -while headroom and tailroom represent reserved areas of memory, these areas -not not addressable or directly usable by ODP applications until they are +`odp_packet_push_head()` calls as the packet is being prepared for transmit. +Note that while headroom and tailroom represent reserved areas of memory, these +areas are not addressable or directly usable by ODP applications until they are made part of the packet via associated push operations. Similarly, bytes removed via pull operations become part of a packet's headroom or tailroom and are again no longer accessible to the application. @@ -473,32 +473,16 @@ reliability, the shared data contained in any packet referred to by references should be treated as read only once it has been successfully referenced until it is known that all references to it have been freed. -To assist applications in working with references, ODP provides two additional -APIs: +To assist applications in working with references, ODP provides the additional +API: [source,c] ----- int odp_packet_has_ref(odp_packet_t pkt); - -uint32_t odp_packet_unshared_len(odp_packet_t pkt); ----- The `odp_packet_has_ref()` API says whether any other packets exist that share any bytes with this packet. -Because references and referenced packets consist of an unshared -prefix, that is modifiable, followed by a shared body that should not be -modified, the `odp_packet_unshared_len()` API is available that operates as -shown here: - -.Packet Reference Lengths -image::reflen.svg[align="center"] - -`odp_packet_unshared_len()` returns the same value as `odp_packet_len()` when -`odp_packet_has_ref()` returns 0, but for packets for which -`odp_packet_has_ref()` returns 1, only returns the number of unshared bytes -prefixed to them. To ensure portability and reliability, only offsets -0..`odp_packet_unshared_len()`-1 should be modified by the caller. - ===== Compound References Note that architecturally ODP does not limit referencing and so it is possible that a reference may be used as a basis for creating another reference. The @@ -509,13 +493,44 @@ As noted earlier, the intent behind references is that they are lightweight objects that can be implemented without requiring data copies. The existence of compound references may complicate this goal for some implementations. As a result, implementations are always free to perform partial or full copies of -packets as part of any reference creation call. The -`odp_packet_unshared_len()` API will always provide an authoritative answer to -the question of how many bytes of a packet may safely be modified in any -context, so whether or not copies have been performed applications can be -assured of portability across all conforming ODP implementations. +packets as part of any reference creation call. 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. |