ndni

package
v0.0.0-...-1e60831 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 23, 2024 License: NIST-PD-fallback Imports: 20 Imported by: 2

README

ndn-dpdk/ndni

This package implements NDN layer 2 and layer 3 packet representations for internal use in NDN-DPDK codebase.

Layer 2 implementation follows NDN Link Protocol v2 (NDNLPv2) specification, revision 59. It supports indexed fragmentation, PIT token, network nack, and congestion mark features.

Layer 3 implementation follows NDN Packet Format specification, version 0.3. The decoder supports TLV encoding evolvability in most situations.

Low-Level TLV Functions

This package provides low-level pktmbuf and TLV functions including:

  • Encoding and decoding of VAR-NUMBER used in TLV-TYPE and TLV-LENGTH.
  • Encoding and decoding of NonNegativeInteger.
  • Creating indirect pktmbuf.
  • Linearizing pktmbuf.

Name Representation

A name is represented as a buffer containing a sequence of name components, i.e. TLV-VALUE of the Name element. TLV-LENGTH of the Name element cannot exceed NameMaxLength; this constant can be adjusted up to around 48KB, but it has implication in memory usage of table entries.

Two C types can represent a name:

  • LName includes a pointer to the buffer of name components, and TLV-LENGTH of the Name element.
  • PName additionally contains offsets of parsed name components.

All name components must are in a consecutive memory buffer. If this condition is not met, calling code must linearize the Name element's TLV-VALUE with TlvDecoder_Linearize function. Having a linearized buffer, one can trivially construct an LName, or invoke PName_Parse function to construct a PName. Neither types own the name components buffer.

PName contains offsets of name components. Internally, it only has space for the initial PNameCachedComponents name components. However, its APIs allow unlimited number of name components: accessing a name component after PNameCachedComponents involves re-parsing and is inefficient. PName_ComputePrefixHash function computes SipHash of the name or its prefix, which is useful in table implementation.

In Go, ndn.Name type should be used to represent a name. To interact with C code, temporary allocate a C.PName via Go ndni.PName type.

Packet Representation

In C, Packet type represents a L2 or L3 packet. Packet* is actually struct rte_mbuf*, with a PacketPriv placed at the private data area of the direct mbuf. Within a PacketPriv:

  • LpL3 contains layer 3 fields in NDNLPv2 header, accessible via Packet_GetLpL3Hdr.
  • LpL2 contains layer 2 fields in NDNLPv2 header.
  • LpHeader combines LpL3 and LpL2, accessible via Packet_GetLpHdr.
  • PInterest is a parsed Interest, accessible via Packet_GetInterestHdr. It must be used together with the mbuf containing the Interest packet.
  • PData is a parsed Data, accessible via Packet_GetDataHdr. It must be used together with the mbuf containing the Data packet.
  • PNack represents a parsed Nack, accessible via Packet_GetNackHdr. It overlays LpL3 (where NackReason field is located) and PInterest.

Packet_GetType indicates what headers are currently accessible. Attempting to access an inaccessible header type would result in assertion failure.

To receive and parse a packet, calling code should:

  1. Ensure the direct mbuf has sufficiently large private data area for a PacketPriv.
  2. Cast the mbuf to Packet* with Packet_FromMbuf function.
  3. Invoke Packet_Parse function to parse the packet. NDNLPv2 headers are stripped from the mbuf during this step. Bare Interest/Data is considered valid LpPacket.
  4. If Packet_GetType indicates the packet is a fragment, perform reassembly according to LpL2, and invoke Packet_ParseL3 to parse network layer.
  5. At this point, PInterest, PData, or PNack becomes available, and the mbuf only contains Interest or Data packet. Fragmented names are moved or copied into consecutive memory, allocated from the same mempool as the input mbuf. LpL2 is overwritten but LpL3 survives.
Interest Decoding Details

PInterest_Parse function decodes an Interest. If the Interest carries a forwarding hint, up to PInterestMaxFwHints names are recognized, and any remaining names are ignored. The decoder only determines the length of each name, but does not parse at component level. PInterest_SelectFwHint function activates a forwarding hint, parses the name into components on demand; only one name can be active at any time.

Although the packet format specifies Nonce as optional, it is required when an Interest is transmitted over network links. Thus, PInterest_Parse requires Nonce to be present. It stores the position of Nonce, InterestLifetime, and HopLimit elements in nonceOffset and guiderSize fields. Interest_ModifyGuiders uses this information to modify these fields.

The decoder can accept unrecognized non-critical elements in most situations. One exception is that, if there are too many unrecognized non-critical elements such that they inflate the distance between Nonce and HopLimit beyond 255 bytes, decoding will fail. Also, Interest_ModifyGuiders does not preserve unrecognized non-critical elements between Nonce and HopLimit.

Packet Encoding

There are limited support for packet encoding.

  • InterestTemplate struct and related functions can encode Interest packets.
  • DataGen struct and related functions can generate Data packets from a template without signing.
  • DataEnc_* functions can generate Data packets with payload without signing.
  • Nack_FromInterest turns an Interest packet into a Nack packet in-place.

Documentation

Overview

Package ndni implements NDN layer 2 and layer 3 packet representations for internal use.

Index

Constants

View Source 
const (
	// LpHeaderHeadroom is the required headroom to prepend NDNLPv2 header.
	LpHeaderHeadroom = 0 +
		1 + 5 +
		1 + 1 + 8 +
		1 + 1 + 2 +
		1 + 1 + 2 +
		1 + 1 + 8 +
		3 + 1 + 3 + 1 + 1 +
		3 + 1 + 1 +
		1 + 5 // Payload TL

	// LpMaxFragments is the maximum number of NDNLPv2 fragments.
	LpMaxFragments = 31

	// L3TypeLengthHeadroom is the required headroom to prepend Interest/Data TLV-TYPE TLV-LENGTH fields.
	L3TypeLengthHeadroom = 1 + 3

	// NameMaxLength is the maximum TLV-LENGTH for Name.
	NameMaxLength = 2048

	// ImplicitDigestLength is the TLV-LENGTH of ImplicitDigestNameComponent.
	ImplicitDigestLength = 32

	// ImplicitDigestSize is size of ImplicitDigestNameComponent TLV.
	ImplicitDigestSize = 34

	// PNameCachedComponents is the number of cached component boundaries and hashes in PName struct.
	PNameCachedComponents = 17

	// PInterestMaxFwHints is the maximum number of decoded forwarding hints on Interest.
	// Additional forwarding hints are ignored.
	PInterestMaxFwHints = 4

	// DefaultInterestLifetime is the default value of InterestLifetime.
	DefaultInterestLifetime = 4000

	// InterestTemplateBufLen is the buffer length for InterestTemplate.
	// It can accommodate two forwarding hints.
	InterestTemplateBufLen = 2*NameMaxLength + 256

	// InterestTemplateDataroom is the required dataroom to encode Interest with InterestTemplate.
	InterestTemplateDataroom = 0 +
		1 + 5 +
		1 + 3 + NameMaxLength +
		InterestTemplateBufLen // other fields

	// DataEncNullSigLen is the required tailroom in DataEnc to append NullSignature.
	DataEncNullSigLen = 0 +
		1 + 1 + 1 + 1 + 1 +
		1 + 1 // DSigValue

	// DataGenBufLen is the buffer length for DataGen.
	DataGenBufLen = 0 +
		1 + 3 + NameMaxLength +
		1 + 1 + 1 + 1 + 4 +
		1 + 3 + 0 +
		39 // Signature

	// DataGenDataroom is the required dataroom to encode Data with DataGen.
	DataGenDataroom = 0 +
		1 + 5 +
		1 + 3 + NameMaxLength // Name prefix

)

Variables

View Source 
var (
	GqlNameType                   *graphql.Scalar
	GqlInterestTemplateInput      *graphql.InputObject
	GqlInterestTemplateFieldTypes gqlserver.FieldTypes
	GqlDataGenInput               *graphql.InputObject
)

GraphQL types.

View Source 
var (
	// PacketMempool is a mempool template for receiving packets.
	// This is an alias of pktmbuf.Direct.
	PacketMempool pktmbuf.Template

	// IndirectMempool is a mempool template for referencing buffers.
	// This is an alias of pktmbuf.Indirect.
	IndirectMempool pktmbuf.Template

	// HeaderMempool is a mempool template for packet headers.
	// This includes T-L portion of an L3 packet, NDNLP header, and Ethernet header.
	// It is also used for Interest guiders.
	HeaderMempool pktmbuf.Template

	// InterestMempool is a mempool template for encoding Interests.
	InterestMempool pktmbuf.Template

	// DataMempool is a mempool template for encoding Data headers.
	DataMempool pktmbuf.Template

	// PayloadMempool is a mempool template for encoding Data payload.
	PayloadMempool pktmbuf.Template
)

Predefined mempool templates.

Functions

This section is empty.

Types

type DataGen 

type DataGen C.DataGen

DataGen is a Data encoder optimized for traffic generator.

func DataGenFromPtr 

func DataGenFromPtr(ptr unsafe.Pointer) *DataGen

DataGenFromPtr converts *C.DataGen pointer to DataGen.

func (*DataGen) Close 

func (gen *DataGen) Close() error

Close discards this DataGen.

func (*DataGen) Encode 

func (gen *DataGen) Encode(prefix ndn.Name, mp *Mempools, fragmentPayloadSize int) *Packet

Encode encodes a Data packet.

func (*DataGen) Init 

func (gen *DataGen) Init(m *pktmbuf.Packet, args ...any)

Init initializes a DataGen. m is a pktmbuf with at least DataGenBufLen + len(content) buffer size; it can be allocated from PayloadMempool. Arguments should be acceptable to ndn.MakeData. Name (used as name suffix), MetaInfo, and Content are saved; other fields are skipped. Panics on error.

func (*DataGen) Ptr 

func (gen *DataGen) Ptr() unsafe.Pointer

Ptr returns *C.DataGen pointer.

type DataGenConfig 

type DataGenConfig struct {
	Suffix          ndn.Name                `json:"suffix,omitempty"`
	FreshnessPeriod nnduration.Milliseconds `json:"freshnessPeriod,omitempty"`
	PayloadLen      int                     `json:"payloadLen,omitempty"`
}

DataGenConfig is a JSON serializable object that can construct DataGen.

func (DataGenConfig) Apply 

func (cfg DataGenConfig) Apply(gen *DataGen, m *pktmbuf.Packet)

Apply initializes DataGen.

type DataSatisfyResult 

type DataSatisfyResult int

DataSatisfyResult indicates the result of Data.CanSatisfy function. 

const (
	DataSatisfyYes        DataSatisfyResult = 0 // Data satisfies Interest
	DataSatisfyNo         DataSatisfyResult = 1 // Data does not satisfy Interest
	DataSatisfyNeedDigest DataSatisfyResult = 2 // need Data digest to determine

)

DataSatisfyResult values.

type InterestTemplate 

type InterestTemplate C.InterestTemplate

InterestTemplate is a template for Interest encoding. A zero InterestTemplate is invalid. It must be initialized before use.

func InterestTemplateFromPtr 

func InterestTemplateFromPtr(ptr unsafe.Pointer) *InterestTemplate

InterestTemplateFromPtr converts *C.InterestTemplate to InterestTemplate.

func (*InterestTemplate) Encode 

func (tpl *InterestTemplate) Encode(m *pktmbuf.Packet, suffix ndn.Name, nonce uint32) *Packet

Encode encodes an Interest via template.

func (*InterestTemplate) Init 

func (tpl *InterestTemplate) Init(args ...any)

Init initializes InterestTemplate. Arguments should be acceptable to ndn.MakeInterest. Name is used as name prefix. Panics on error.

type InterestTemplateConfig 

type InterestTemplateConfig struct {
	Prefix           ndn.Name                `json:"prefix"`
	CanBePrefix      bool                    `json:"canBePrefix,omitempty"`
	MustBeFresh      bool                    `json:"mustBeFresh,omitempty"`
	InterestLifetime nnduration.Milliseconds `json:"interestLifetime,omitempty"`
	HopLimit         ndn.HopLimit            `json:"hopLimit,omitempty"`
}

InterestTemplateConfig is a JSON serializable object that can construct InterestTemplate.

func (InterestTemplateConfig) Apply 

func (cfg InterestTemplateConfig) Apply(tpl *InterestTemplate)

Apply initializes InterestTemplate.

type LNamePrefixFilterBuilder 

type LNamePrefixFilterBuilder struct {
	// contains filtered or unexported fields
}

LNamePrefixFilterBuilder prepares vector for C.LNamePrefixFilter_Find.

func NewLNamePrefixFilterBuilder 

func NewLNamePrefixFilterBuilder(prefixL unsafe.Pointer, sizeL uintptr, prefixV unsafe.Pointer, sizeV uintptr) (b *LNamePrefixFilterBuilder)

NewLNamePrefixFilterBuilder constructs LNamePrefixFilterBuilder.

func (*LNamePrefixFilterBuilder) Append 

func (b *LNamePrefixFilterBuilder) Append(name ndn.Name) error

Append adds a name.

func (*LNamePrefixFilterBuilder) Len 

func (b *LNamePrefixFilterBuilder) Len() int

Len returns number of prefixes added.

type Mempools 

type Mempools C.PacketMempools

Mempools is a set of mempools for packet modification.

func (*Mempools) Assign 

func (mp *Mempools) Assign(socket eal.NumaSocket, tpl ...pktmbuf.Template)

Assign creates mempools from templates.

To use alternate templates: 

Assign([HeaderMempool[, PacketMempool]])

type PName 

type PName C.PName

PName represents a parsed Name.

func NewPName 

func NewPName(name ndn.Name) *PName

NewPName creates PName from ndn.Name.

func (*PName) ComputeHash 

func (p *PName) ComputeHash() uint64

ComputeHash returns LName hash.

func (*PName) Free 

func (p *PName) Free()

Free releases memory.

func (*PName) Ptr 

func (p *PName) Ptr() unsafe.Pointer

Ptr return *C.PName or *C.LName pointer.

type Packet 

type Packet C.Packet

Packet represents a NDN network layer packet with parsed LP and Interest/Data headers.

func PacketFromPtr 

func PacketFromPtr(ptr unsafe.Pointer) (pkt *Packet)

PacketFromPtr converts *C.Packet or *C.struct_rte_mbuf pointer to Packet.

func (*Packet) Clone 

func (pkt *Packet) Clone(mp *Mempools, align PacketTxAlign) *Packet

Clone clones this packet to new mbufs, with specified alignment requirement. Returns nil upon allocation error.

func (*Packet) Close 

func (pkt *Packet) Close() error

Close discards the packet.

func (*Packet) ComputeDataImplicitDigest 

func (pkt *Packet) ComputeDataImplicitDigest() []byte

ComputeDataImplicitDigest computes and stores implicit digest in *C.PData. Panics on non-Data.

func (*Packet) Mbuf 

func (pkt *Packet) Mbuf() *pktmbuf.Packet

Mbuf converts to pktmbuf.Packet.

func (*Packet) PName 

func (pkt *Packet) PName() *PName

PName returns *PName pointer.

func (*Packet) PitToken 

func (pkt *Packet) PitToken() (token []byte)

PitToken retrieves the PIT token.

func (*Packet) Ptr 

func (pkt *Packet) Ptr() unsafe.Pointer

Ptr returns *C.Packet or *C.struct_rte_mbuf pointer.

func (*Packet) SetPitToken 

func (pkt *Packet) SetPitToken(token []byte)

SetPitToken updates the PIT token.

func (*Packet) ToNPacket 

func (pkt *Packet) ToNPacket() (npkt ndn.Packet)

ToNPacket copies this packet into ndn.Packet. Panics on error.

func (*Packet) Type 

func (pkt *Packet) Type() PktType

Type returns packet type.

type ParseFor 

type ParseFor int

ParseFor suggests which fields may be skipped by the decoder. 

const (
	ParseForAny ParseFor = iota
	ParseForFw
	ParseForApp
)

ParseFor values.

type PktType 

type PktType int

PktType indicates packet type in mbuf. 

const (
	PktFragment PktType = iota
	PktInterest         // Interest
	PktData             // Data
	PktNack             // Nack

	PktSInterest // Interest unparsed
	PktSData     // Data unparsed
	PktSNack     // Nack unparsed

	PktMax = PktNack + 1 // exclusive maximum excluding slim types

)

PktType values.

func (PktType) String 

func (t PktType) String() string

Source Files

View all Source files

Directories

Path Synopsis
Package ndnitestenv contains helper functions to construct NDN packets in test code.
 Package ndnitestenv contains helper functions to construct NDN packets in test code.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.