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. More...
#define	SgCtx_PitScratchT(ctx, T)
	Access PIT entry scratch area as T* type. More...
#define	SgGetJSONScalar(ctx, path, dflt)
	Retrieve JSON parameter integer scalar value. More...
#define	SgGetJSONSlice(dst, ctx, path, dflt)
	Retrieve JSON parameter integer array. More...
#define	SGINIT_SCHEMA(...)    char SgJSONSchema[] __attribute__((section(SGSEC_SCHEMA), used)) = #__VA_ARGS__;
	Declare JSON schema. More...

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

Enumerations
enum	SgEvent {   SGEVT_NONE , SGEVT_INTEREST , SGEVT_DATA , SGEVT_NACK ,   SGEVT_TIMER }
	Indicate why the strategy program is invoked. More...
enum	SgForwardInterestResult {   SGFWDI_OK , SGFWDI_BADFACE , SGFWDI_ALLOCERR , SGFWDI_NONONCE ,   SGFWDI_SUPPRESSED , SGFWDI_HOPZERO }
enum	{ SGJSON_SCALAR = -1 , SGJSON_LEN = -2 }

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

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

(

...

)

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

typedef enum SgEvent SgEvent

Indicate why the strategy program is invoked.

SgForwardInterestResult

typedef enum SgForwardInterestResult SgForwardInterestResult

SgGlobal

typedef struct SgGlobal SgGlobal

Global static parameters.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
SGJSON_SCALAR
SGJSON_LEN

SgEvent

enum SgEvent

Indicate why the strategy program is invoked.

Enumerator
SGEVT_NONE
SGEVT_INTEREST	Interest arrives.
SGEVT_DATA	Data arrives.
SGEVT_NACK	Nack arrives.
SGEVT_TIMER	timer expires

SgForwardInterestResult

enum SgForwardInterestResult

Enumerator
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.

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.