eal

Documentation

Overview

Package eal wraps EAL initialization and provides some additional functionality on top of that. Every CPU's logical core which is setup by EAL runs its own function which essentially receives functions to execute via Go channel. So you may run arbitrary Go code in the context of EAL thread.

EAL may be initialized via command line string, parsed command line string or a set of Options.

Please note that some functions may be called only in EAL thread because of TLS (Thread Local Storage) dependency.

API is a subject to change. Be aware.

Index

• Constants
• Variables
• func Cleanup() error
• func ExecOnLcore(lcoreID uint, fn func(*LcoreCtx)) error
• func ExecOnLcoreAsync(lcoreID uint, ret chan error, fn func(*LcoreCtx)) <-chan error
• func ExecOnMain(fn func(*LcoreCtx)) error
• func ExecOnMainAsync(ret chan error, fn func(*LcoreCtx)) <-chan error
• func GetMainLcore() uint
• func HasHugePages() bool
• func HasPCI() bool
• func Init(args []string) (n int, err error)
• func InitCmd(input string) (int, error)
• func InitOnce(args []string)
• func InitOnceSafe(cmdname string, lcores int)
• func LcoreCount() uint
• func LcoreID() uint
• func LcoreToSocket(id uint) uint
• func Lcores() []uint
• func LcoresWorker() []uint
• func PrimaryProcAlive(path string) bool
• func ProcessType() int
• func SafeEALArgs(cmdname string, lcores int) []string
• func SocketID() uint
• func Sockets() []uint
• func StopLcores()
• type ErrLcorePanic
  • func (e *ErrLcorePanic) Error() string
  • func (e *ErrLcorePanic) FprintStack(w io.Writer)
  • func (e *ErrLcorePanic) Unwrap() error
• type LcoreCtx
  • func (ctx *LcoreCtx) String() string

Examples

• ExecOnLcore
• ExecOnLcore (Error)
• Init (Flags)

Constants

const (
	// PmdPath is the default location of shared objects to load by
	// rte_eal_init.
	PmdPath = C.RTE_EAL_PMD_PATH
)

Variables

var ErrLcoreInvalid = fmt.Errorf("Invalid logical core")

ErrLcoreInvalid is returned by ExecOnLcore in case the desired lcore ID is invalid.

var PanicAsErr = false

PanicAsErr controls whether logical core should recover from panic occurred in Go code. If true then panic will lead to an error sent through the job channel. If false (as default) panic will crash the process.

Please set this before running logical cores functions to prevent race condition.

Functions

func Cleanup

func Cleanup() error

Cleanup releases EAL-allocated resources, ensuring that no hugepage memory is leaked. It is expected that all DPDK applications call rte_eal_cleanup() before exiting. Not calling this function could result in leaking hugepages, leading to failure during initialization of secondary processes.

func ExecOnLcore

func ExecOnLcore(lcoreID uint, fn func(*LcoreCtx)) error

ExecOnLcore sends fn to execute on CPU logical core lcoreID, i.e. in EAL-owned thread on that lcore. Then it waits for the execution to finish and returns the execution result.

Possible panic in lcore function will be intercepted and returned as an error of type ErrLcorePanic. If lcoreID is invalid, ErrLcoreInvalid error will be returned.

Example

// Lcore ID 1
lid := uint(1)

err := ExecOnLcore(lid, func(ctx *LcoreCtx) {
	log.Printf("this is lcore #%d\n", LcoreID())
})

if err == ErrLcoreInvalid {
	// lid doesn't exist
	log.Fatalf("invalid lcore %d\n", lid)
}

if e, ok := err.(*ErrLcorePanic); ok {
	// lcore panicked
	log.Fatalln(e)
}

Example (Error)

// Lcore ID 1
lid := uint(1)

someErr := fmt.Errorf("lcore error")
err := ExecOnLcore(lid, func(ctx *LcoreCtx) {
	if 2+2 != 4 {
		panic(someErr)
	}
})

if e, ok := err.(*ErrLcorePanic); ok {
	// lcore panicked
	if err := e.Unwrap(); err == someErr {
		log.Fatalln("check the math")
	}
}

// or, as of Go 1.13
//   if errors.Is(err, someErr) { ...

func ExecOnLcoreAsync

func ExecOnLcoreAsync(lcoreID uint, ret chan error, fn func(*LcoreCtx)) <-chan error

ExecOnLcoreAsync sends fn to execute on CPU logical core lcoreID, i.e. in EAL-owned thread on that lcore.

Possible panic in lcore function will be intercepted and returned as an error of type ErrLcorePanic through ret channel specified by caller. If lcoreID is invalid, ErrLcoreInvalid error will be returned the same way.

The function returns ret. You may specify ret to be nil, in which case no error will be reported.

func ExecOnMain

func ExecOnMain(fn func(*LcoreCtx)) error

ExecOnMain is a shortcut for ExecOnLcore with main lcore as a destination.

func ExecOnMainAsync

func ExecOnMainAsync(ret chan error, fn func(*LcoreCtx)) <-chan error

ExecOnMainAsync is a shortcut for ExecOnLcoreAsync with main lcore as a destination.

func GetMainLcore

func GetMainLcore() uint

GetMainLcore returns CPU logical core id where the main thread is executed.

func HasHugePages

func HasHugePages() bool

HasHugePages tells if huge pages are activated.

func HasPCI

func HasPCI() bool

HasPCI tells whether EAL is using PCI bus. Disabled by –no-pci option.

func Init

func Init(args []string) (n int, err error)

Init initializes EAL as in rte_eal_init. Options are specified in a parsed command line string.

This function initialized EAL and waits for executable functions on each of EAL-owned threads.

Returns number of parsed args and an error.

Example (Flags)

// If your executable is to be launched like a DPDK example:
//   /path/to/exec -c 3f -m 1024 <other-eal-options> -- <go-flags>
// then you may do the following:
n, err := Init(os.Args)
if err != nil {
	panic(err)
}

// to be able to do further flag processing, i.e. pretend the cmd was:
//   /path/to/exec <go-flags>
os.Args[n], os.Args = os.Args[0], os.Args[n:]
flag.Parse()

func InitCmd

func InitCmd(input string) (int, error)

InitCmd initializes EAL as in rte_eal_init. Options are specified in a unparsed command line string. This string is parsed and Init is then called upon.

func InitOnce

func InitOnce(args []string)

InitOnce calls Init guarded with global lock.

If Init returns error it panics. If Init was already called it simply returns.

It's mostly intended to use in tests.

func InitOnceSafe

func InitOnceSafe(cmdname string, lcores int)

InitOnceSafe calls Init guarded with global lock on arguments returned by SafeEALArgs.

If Init returns error it panics. If Init was already called it simply returns.

It's mostly intended to use in tests.

func LcoreCount

func LcoreCount() uint

LcoreCount returns number of CPU logical cores configured by EAL.

func LcoreID

func LcoreID() uint

LcoreID returns CPU logical core id. This function must be called only in EAL thread.

func LcoreToSocket

func LcoreToSocket(id uint) uint

LcoreToSocket return socket id for given lcore LcoreID.

func Lcores

func Lcores() []uint

Lcores returns all lcores registered in EAL.

func LcoresWorker

func LcoresWorker() []uint

LcoresWorker returns all worker lcores registered in EAL. Lcore is worker if it is not main.

func PrimaryProcAlive

func PrimaryProcAlive(path string) bool

PrimaryProcAlive checks if a primary process is currently alive.

func ProcessType

func ProcessType() int

ProcessType returns the current process type.

func SafeEALArgs

func SafeEALArgs(cmdname string, lcores int) []string

SafeEALArgs returns safe parameters to be used for testing purposes. Specify cmdname as the binary name in argv[0] and number of lcores. All lcores will be assigned to core 0.

func SocketID

func SocketID() uint

SocketID returns NUMA socket where the current thread resides. This function must be called only in EAL thread.

func Sockets

func Sockets() []uint

Sockets returns list of socket ids.

func StopLcores

func StopLcores()

StopLcores sends signal to EAL threads to finish execution of go-dpdk lcore function executor.

Warning: it will block until all lcore threads finish execution.

Types

type ErrLcorePanic

type ErrLcorePanic struct {
	Pc      []uintptr
	LcoreID uint

	// value returned by recover()
	R interface{}
}

ErrLcorePanic is an error returned by ExecOnLcore in case lcore function panics.

func (*ErrLcorePanic) Error

func (e *ErrLcorePanic) Error() string

Error implements error interface.

func (*ErrLcorePanic) FprintStack

func (e *ErrLcorePanic) FprintStack(w io.Writer)

FprintStack prints PCs into w.

func (*ErrLcorePanic) Unwrap

func (e *ErrLcorePanic) Unwrap() error

Unwrap returns error value if it was supplied to panic() as an argument.

type LcoreCtx

type LcoreCtx struct {
	// Value is a user-specified context. You may change it as you
	// will and it will persist across function invocations on
	// particular lcore.
	Value interface{}
	// contains filtered or unexported fields
}

LcoreCtx is a per-lcore context and is supplied to function running to particular lcore.

func (*LcoreCtx) String

func (ctx *LcoreCtx) String() string

String implements fmt.Stringer.