acl

Documentation

Overview

Package acl wraps DPDK ACL packet classification library.

Index

• Constants
• func ListDump()
• func RuleSize(numDefs int) uint32
• type Config
• type Context
  • func Create(p *Param) (*Context, error)
  • func FindExisting(name string) (*Context, error)
  • func (ctx *Context) AddRules(input []Rule) error
  • func (ctx *Context) Build(cfg *Config) error
  • func (ctx *Context) Classify(data []unsafe.Pointer, results []uint32, categories uint32) error
  • func (ctx *Context) Dump()
  • func (ctx *Context) Free()
  • func (ctx *Context) Reset()
  • func (ctx *Context) ResetRules()
• type Field
• type FieldDef
• type Param
• type Rule
• type RuleData

Examples

• Context.AddRules
• Context.Build
• Create

Constants

const (
	FieldTypeMask    uint8 = C.RTE_ACL_FIELD_TYPE_MASK
	FieldTypeBitmask uint8 = C.RTE_ACL_FIELD_TYPE_BITMASK
	FieldTypeRange   uint8 = C.RTE_ACL_FIELD_TYPE_RANGE
)

Type of the field.

Functions

func ListDump

func ListDump()

ListDump dumps all ACL context structures to the console.

func RuleSize

func RuleSize(numDefs int) uint32

RuleSize returns amount of memory occupied by a rule with numDefs fields.

Types

type Config

type Config struct {
	Categories uint32
	Defs       []FieldDef
	MaxSize    int
}

Config is an ACL build configuration. Defines the fields of an ACL trie and number of categories to build with.

type Context

type Context C.struct_rte_acl_ctx

Context is an ACL context containing rules and optimized built trie to search.

func Create

func Create(p *Param) (*Context, error)

Create new Context using specified params. Returns new instance of Context and an error.

Example

defs := []FieldDef{
	// number of field definitions
	// see Build method
}

ctx, err := Create(&Param{
	Name: "my_acl_context",

	// we must specify an exact amount of memory required to
	// contain a rule given the number of field definitions.
	RuleSize: RuleSize(len(defs)),

	// maximum number of rules in a context
	MaxRuleNum: 64,

	SocketID: -1,
})
if err != nil {
	// handle error
}

_ = ctx // ACL context

func FindExisting

func FindExisting(name string) (*Context, error)

FindExisting finds an existing ACL context object and returns a pointer to it.

func (*Context) AddRules

func (ctx *Context) AddRules(input []Rule) error

AddRules adds rules to an existing ACL context. This function is not multi-thread safe.

Example

var ctx *Context

err := ctx.AddRules([]Rule{
	{
		// rule #1
		Data: RuleData{CategoryMask: 3, Priority: 1, Userdata: 1},
		Fields: []Field{
			// 1 byte field with value 1 and bitmask 0xff
			{uint8(1), uint8(0xff)},

			// 1 byte field with value 2 and bitmask 0xff
			{uint8(2), uint8(0xff)},

			// 1 byte field with value 3 and bitmask 0xff
			{uint8(3), uint8(0xff)},

			// 2 byte field with value 0x0102 and '/8' mask.
			{uint16(0x0102), uint8(8)},
		},
	},
})

if err != nil {
	// handle error
}

func (*Context) Build

func (ctx *Context) Build(cfg *Config) error

Build analyzes set of rules and build required internal run-time structures. This function is not multi-thread safe.

Example

defs := []FieldDef{
	{
		Type:       FieldTypeBitmask,
		Size:       1, // mandatory one byte field
		Offset:     0, // at the buffer's top
		FieldIndex: 0, // index of the field
		InputIndex: 0, // group of four (4) consecutive bytes.
	}, {
		Type:       FieldTypeBitmask,
		Size:       1,
		Offset:     1,
		FieldIndex: 1,
		InputIndex: 1, // N.B. same group for these three fields
	}, {
		Type:       FieldTypeBitmask,
		Size:       1,
		Offset:     2,
		FieldIndex: 2,
		InputIndex: 1,
	}, {
		Type:       FieldTypeMask,
		Size:       2,
		Offset:     3,
		FieldIndex: 3,
		InputIndex: 1,
	},
}

cfg := &Config{
	// Number of categories
	Categories: 2,

	// Size of internal data structures in ACL context.
	// 0 is the default which doesn't impose a hard limit.
	MaxSize: 0x800000,

	// Specify fields definitions which define a valid rule for
	// ACL context.
	Defs: defs,
}

// assume we have a context.
var ctx *Context

if err := ctx.Build(cfg); err != nil {
	// handle error
}

func (*Context) Classify

func (ctx *Context) Classify(data []unsafe.Pointer, results []uint32, categories uint32) error

Classify performs search for a matching ACL rule for each input data buffer. Each input data buffer can have up to *categories* matches. That implies that results array should be big enough to hold (categories * len(data)) elements. Also categories parameter should be either one or multiple of RTE_ACL_RESULTS_MULTIPLIER and can't be bigger than RTE_ACL_MAX_CATEGORIES. If more than one rule is applicable for given input buffer and given category, then rule with highest priority will be returned as a match. Note, that it is a caller's responsibility to ensure that input parameters are valid and point to correct memory locations.

data must be an array of buffers NOT allocated in Go.

func (*Context) Dump

func (ctx *Context) Dump()

Dump an ACL context structure to the console.

func (*Context) Free

func (ctx *Context) Free()

Free de-allocates all memory used by ACL context.

func (*Context) Reset

func (ctx *Context) Reset()

Reset deletes all rules from the ACL context and destroys all internal run-time structures. This function is not multi-thread safe.

func (*Context) ResetRules

func (ctx *Context) ResetRules()

ResetRules delete all rules from the ACL context. This function is not multi-thread safe. Note that internal run-time structures are not affected.

type Field

type Field struct {
	// a 1,2,4, or 8 byte value of the field.
	Value any

	// depending on field type:
	// mask -> 1.2.3.4/32 value=0x1020304, mask_range=32,
	// range -> 0 : 65535 value=0, mask_range=65535,
	// bitmask -> 0x06/0xff value=6, mask_range=0xff.
	MaskRange any
}

Field defines the value of a field for a rule.

type FieldDef

type FieldDef struct {
	Type, Size uint8
	FieldIndex uint8
	InputIndex uint8
	Offset     uint32
}

FieldDef is an ACL Field definition.

Each field in the ACL rule has an associate definition. It defines the type of field, its size, its offset in the input buffer, the field index, and the input index. For performance reasons, the inner loop of the search function is unrolled to process four input bytes at a time. This requires the input to be grouped into sets of 4 consecutive bytes. The loop processes the first input byte as part of the setup and then subsequent bytes must be in groups of 4 consecutive bytes.

type Param

type Param struct {
	Name       string
	SocketID   int
	RuleSize   uint32
	MaxRuleNum uint32
}

Param contains parameters used when creating the ACL context.

type Rule

type Rule struct {
	Data   RuleData
	Fields []Field
}

Rule contains a rule to store in ACL context.

type RuleData

type RuleData struct {
	CategoryMask uint32
	Priority     int32
	Userdata     uint32
}

RuleData contains miscellaneous data for ACL rule.