api.h File Reference

#include "../strategycode/sec.h"
#include "fib.h"
#include "packet.h"
#include "pit.h"

Go to the source code of this file.

Data Structures
struct	SgGlobal
	Global static parameters. More...
struct	SgCtx
	Context of strategy invocation. More...

Macros
#define	SgCtx_FibScratchT(ctx, T)
	Access FIB entry scratch area as T* type.
#define	SgCtx_PitScratchT(ctx, T)
	Access PIT entry scratch area as T* type.
#define	SgGetJSONScalar(ctx, path, dflt)
	Retrieve JSON parameter integer scalar value.
#define	SgGetJSONSlice(dst, ctx, path, dflt)
	Retrieve JSON parameter integer array.
#define	SGINIT_SCHEMA(...)
	Declare JSON schema.

Typedefs
typedef struct SgGlobal	SgGlobal
	Global static parameters.
typedef enum __rte_packed_begin SgEvent	SgEvent
	Indicate why the strategy program is invoked.
typedef struct SgCtx	SgCtx
	Context of strategy invocation.
typedef enum __rte_packed_begin SgForwardInterestResult	SgForwardInterestResult

Enumerations
enum	{ SGJSON_SCALAR = -1 , SGJSON_LEN = -2 }

Functions
SUBROUTINE TscDuration	SgTscFromMillis (SgCtx *ctx, uint64_t millis)
	Convert milliseconds to TscDuration.
SUBROUTINE void	SgFibNexthopIt_InitCtx (SgFibNexthopIt *it, const SgCtx *ctx)
	Iterate over FIB nexthops passing ctx->nhFlt.
uint32_t	SgRandInt (SgCtx *ctx, uint32_t max)
	Generate a random integer.
bool	SgSetTimer (SgCtx *ctx, TscDuration after)
	Set a timer to invoke strategy after a duration.
SgForwardInterestResult	SgForwardInterest (SgCtx *ctx, FaceID nh)
	Forward an Interest to a nexthop.
void	SgReturnNacks (SgCtx *ctx, NackReason reason)
	Return Nacks downstream and erase PIT entry.
uint64_t	SgMain (SgCtx *ctx)
	The strategy dataplane program.
bool	SgGetJSON (SgCtx *ctx, const char *path, int index, int64_t *dst)
	Retrieve JSON parameter integer value.
uint64_t	SgInit (SgCtx *ctx)
	The strategy initialization procedure.

Variables
	SGEVT_NONE
	SGEVT_INTEREST
	Interest arrives.
	SGEVT_DATA
	Data arrives.
	SGEVT_NACK
	Nack arrives.
	SGEVT_TIMER
	timer expires
	SGFWDI_OK
	success
	SGFWDI_BADFACE
	face is down or FaceID is invalid
	SGFWDI_ALLOCERR
	allocation error
	SGFWDI_NONONCE
	upstream has rejected all nonces
	SGFWDI_SUPPRESSED
	forwarding is suppressed
	SGFWDI_HOPZERO
	HopLimit has become zero.

Macro Definition Documentation

SgCtx_FibScratchT

#define SgCtx_FibScratchT	(		ctx,
			T )

Value:

  __extension__({                                                                                  \
    static_assert(sizeof(T) <= FibScratchSize, "");                                                \
    (T*)(ctx)->fibEntryDyn->scratch;                                                               \
  })

Access FIB entry scratch area as T* type.

SgCtx_PitScratchT

#define SgCtx_PitScratchT	(		ctx,
			T )

Value:

  __extension__({                                                                                  \
    static_assert(sizeof(T) <= PitScratchSize, "");                                                \
    (T*)(ctx)->pitEntry->scratch;                                                                  \
  })

Access PIT entry scratch area as T* type.

SgGetJSONScalar

#define SgGetJSONScalar	(		ctx,
			path,
			dflt )

Value:

  __extension__({                                                                                  \
    int64_t value = (dflt);                                                                        \
    char pathA[] = (path);                                                                         \
    SgGetJSON((ctx), pathA, SGJSON_SCALAR, &value);                                                \
    value;                                                                                         \
  })

Retrieve JSON parameter integer scalar value.

Parameters

path	JSON property path, using '.' separator for nested path.
dflt	default value.

Returns

retrieved or default value.

SgGetJSONSlice

#define SgGetJSONSlice	(		dst,
			ctx,
			path,
			dflt )

Value:

  __extension__({                                                                                  \
    int64_t length = (0);                                                                          \
    char pathA[] = (path);                                                                         \
    SgGetJSON((ctx), pathA, SGJSON_LEN, &length);                                                  \
    for (int64_t i = 0; i < RTE_DIM((dst)); ++i) {                                                 \
      int64_t value = (dflt);                                                                      \
      if (i < length) {                                                                            \
        SgGetJSON((ctx), pathA, i, &value);                                                        \
      }                                                                                            \
      (dst)[i] = value;                                                                            \
    }                                                                                              \
    length;                                                                                        \
  })

Retrieve JSON parameter integer array.

Parameters

dst	destination array.
path	JSON property path, using '.' separator for nested path.
dflt	default value.

Returns

retrieved length.

SGINIT_SCHEMA

#define SGINIT_SCHEMA

(

...

)

Value:

  char SgJSONSchema[] __attribute__((section(SGSEC_SCHEMA), used)) = #__VA_ARGS__;

Declare JSON schema.

A strategy should provide a JSON schema if it accepts parameters. Input parameters are validated against this schema prior to calling SgInit .

Typedef Documentation

SgCtx

typedef struct SgCtx SgCtx

Context of strategy invocation.

SgEvent

enum __rte_packed_begin SgEvent

Indicate why the strategy program is invoked.

SgForwardInterestResult

enum __rte_packed_begin SgForwardInterestResult

SgGlobal

typedef struct SgGlobal SgGlobal

Global static parameters.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
SGJSON_SCALAR
SGJSON_LEN

Function Documentation

SgFibNexthopIt_InitCtx()

SUBROUTINE void SgFibNexthopIt_InitCtx	(	SgFibNexthopIt *	it,
		const SgCtx *	ctx )

Iterate over FIB nexthops passing ctx->nhFlt.

See also

SgFibNexthopIt

SgForwardInterest()

SgForwardInterestResult SgForwardInterest	(	SgCtx *	ctx,
		FaceID	nh )

Forward an Interest to a nexthop.

Precondition

Not available in SGEVT_DATA .

SgGetJSON()

bool SgGetJSON	(	SgCtx *	ctx,
		const char *	path,
		int	index,
		int64_t *	dst )

Retrieve JSON parameter integer value.

Parameters

path	JSON property path, using '.' separator for nested path. Due to eBPF loader limitation, this string should be written as a mutable char[] allocated on stack. A string literal may cause "resolve_xsym(.L.str) error -2".
index	index into JSON array, or SGJSON_SCALAR to retrieve scalar value, or SGJSON_LEN to retrieve array length.
dst	destination pointer.

Returns

whether success.

Precondition

Only available in SgInit .

SgInit()

uint64_t SgInit

(

SgCtx *

ctx

)

The strategy initialization procedure.

Returns

status code, ignored but may appear in logs.

A strategy should implement this function if it accepts parameters. This is called when a strategy is activated on a FIB entry. It should populate FIB entry scratch area according to JSON parameters.

SgMain()

uint64_t SgMain

(

SgCtx *

ctx

)

The strategy dataplane program.

Returns

status code, ignored but may appear in logs.

Every strategy must implement this function.

SgRandInt()

uint32_t SgRandInt	(	SgCtx *	ctx,
		uint32_t	max )

Generate a random integer.

Parameters

max	exclusive maximum.

Returns

uniformly distributed random number r, where 0 <= r < max .

SgReturnNacks()

void SgReturnNacks	(	SgCtx *	ctx,
		NackReason	reason )

Return Nacks downstream and erase PIT entry.

Precondition

Only available in SGEVT_INTEREST .

SgSetTimer()

bool SgSetTimer	(	SgCtx *	ctx,
		TscDuration	after )

Set a timer to invoke strategy after a duration.

Parameters

after

duration in TSC unit, cannot exceed PIT entry expiration time.

Precondition

Not available in SGEVT_DATA .

Strategy program will be invoked again with SGEVT_TIMER after after . However, the timer would be cancelled if strategy program is invoked for any other event, a different timer is set, or the strategy choice has been changed.

SgTscFromMillis()

SUBROUTINE TscDuration SgTscFromMillis	(	SgCtx *	ctx,
		uint64_t	millis )

Convert milliseconds to TscDuration.

Variable Documentation

SGEVT_DATA

SGEVT_DATA

Data arrives.

SGEVT_INTEREST

SGEVT_INTEREST

Interest arrives.

SGEVT_NACK

SGEVT_NACK

Nack arrives.

SGEVT_NONE

SGEVT_NONE

SGEVT_TIMER

SGEVT_TIMER

timer expires

SGFWDI_ALLOCERR

SGFWDI_ALLOCERR

allocation error

SGFWDI_BADFACE

SGFWDI_BADFACE

face is down or FaceID is invalid

SGFWDI_HOPZERO

SGFWDI_HOPZERO

HopLimit has become zero.

SGFWDI_NONONCE

SGFWDI_NONONCE

upstream has rejected all nonces

SGFWDI_OK

SGFWDI_OK

success

SGFWDI_SUPPRESSED

SGFWDI_SUPPRESSED

forwarding is suppressed