idxvpp

README

NameToIdx

The NameToIdx mapping is an extension of the NamedMapping mapping. It is used by VPP Agent plugins that interact with VPP to map between VPP interface handles (the sw_if_index entities) and the string-based object identifiers used by northbound clients of the Agent.

The mappings are used to implement the re-configuration and state re-synchronization after failures. Furthermore, a mapping registry may be shared between plugins. For example, ifplugin exposes the sw_if_index->name mapping so that other plugins may reference interfaces from objects that depend on them, such as bridge domains or IP routes.

API

Mapping

Every plugin is allowed to allocate a new mapping using the function NewNameToIdxRW(logger, owner, title, indexfunction), giving in-memory-only storage capabilities. Specifying an indexFunction allows to query mappings by secondary indices computed from metadata.

The NameToIdxRW interface supports read and write operations. While the registry owner is allowed to do both reads and writes, only the read interface NameToIdx is typically exposed to the other plugins. See for example the sw_if_index->name mapping defined in ifplugin. Its read-only interface supports index-by-name and name-by-index look-ups using the LookupIdx and LookupName functions. Additionally, a client can use the Watch function to watch for changes in the registry. The registry owner can register a new mapping using the RegisterName function and remove an existing mapping using the UnregisterName function.

Example

Here is a simplified code snippet from ifplugin showing how to use the sw_if_index->name mapping:

// Plugin allocates new registries by its name and automatically becomes
// their owner.
const PluginID pluginapi.PluginName = "ifplugin"

// InterfaceMeta defines the attributes of metadata as used by the 
// interface plugin.
type InterfaceMeta struct {
	InterfaceType intf.InterfaceType
}

// Init initializes the interface plugin
func (plugin *InterfaceConfigurator) Init() {
    // Allocate registry for sw_if_index to name mappings.
    plugin.swIfIndexes, err = idxmap.NewNameToIdx(logger, PluginID, "sw_if_indexes", nil)
    if err != nil {
        // handle error
    }
    
    // Continue with the initialization...
}

// ConfigureInterface configures a new VPP or Linux interface.
func (plugin *InterfaceConfigurator) ConfigureInterface(iface *intf.Interfaces_Interface) {
    // Create the interface ...
    // ifIdx := ...
    
    
    // Once a new interface is created in VPP/Linux, add new mapping into the registry
    // if it doesn't exist yet
    _, _, found := plugin.SwIfIndexes.LookupName(ifIdx)
    if !found {
        plugin.SwIfIndexes.RegisterName(iface.Name, ifIdx, &InterfaceMeta{iface.Type})
    }
}

// DeleteInterface removes an existing VPP or Linux interface.
func (plugin *InterfaceConfigurator) DeleteInterface(iface *intf.Interfaces_Interface) {
    // Delete the interface ...
    
    // When the interface gets deleted from VPP/Linux, the mapping must be removed as well.
    plugin.SwIfIndexes.UnregisterName(iface.Name)
}

Documentation

Overview

Package idxvpp implements name-to-index mapping used by VPP plugins to keep a map between VPP interface handles and northbound string-based identifiers.

Index

• type NameToIdx
• type NameToIdxDto
• type NameToIdxDtoWithoutMeta
  • func (dto *NameToIdxDtoWithoutMeta) Done() error
  • func (dto *NameToIdxDtoWithoutMeta) IsDelete() bool
• type NameToIdxRW

Types

type NameToIdx

type NameToIdx interface {
	// GetRegistryTitle returns the title assigned to the registry.
	GetRegistryTitle() string

	// LookupIdx retrieves a previously stored index for a particular
	// name. Metadata can be nil. If the 'exists' flag is set to false
	// upon return, the init value is undefined and it should be ignored.
	LookupIdx(name string) (idx uint32, metadata interface{}, exists bool)

	// LookupName retrieves a previously stored name by particular index.
	// Metadata can be nil. Name is supposed to be only when exists=false.
	//
	// Principle: A. Registry stores mappings between names and indexes. API can optionally attach metadata to a particular name. TBD index can be 0... B. Metadata is needed for example in the ifplugin. This metadata is used in the following scenarios:
	// - for caching of data (even data that belongs to a different agent)
	// - for remembering the last processed object
	// - for indexing the BD to which a particular interface belongs to (see bd_configurator or fib_configurator)
	LookupName(idx uint32) (name string, metadata interface{}, exists bool)

	// LookupNameByMetadata returns all indexes that contains particular meta field with provided value.
	LookupNameByMetadata(key string, value string) []string

	// ListNames returns all names in the mapping
	ListNames() (names []string)

	// Watch subscribes to watching changes to name-to-index
	// mappings.
	// Watching NameToIndex mapping is critical for performance. You could delay something if you are very slowly handling these events. The idea of this text was to prepare disclaimer for that.
	//
	// Example:
	//
	//    func (plugin *Plugin) watchEvents(ctx context.Context) {
	//       Watch(PluginID, plugin.isubscriberChan)
	//        ...
	//		 select {
	// 		    case ifIdxEv := <-plugin.isubscriberChan:
	//
	//			if ifIdxEv.IsDelete() {
	//				plugin.ResolveDeletedInterface(ifIdxEv.Name)
	//			} else {
	//				plugin.ResolveDeletedInterface(ifIdxEv.Name)
	//			}
	//			ifIdxEv.Done()
	//       ...
	//    }
	Watch(subscriber core.PluginName, callback func(NameToIdxDto))
}

NameToIdx is the "user API" to the NameToIdx registry. It provides read-only access to name-to-index mappings stored in the registry. It is intended for plugins that need to lookup the mappings.

For example, a static L2 FIB table entry refers to an underlying network interface, which is specified as a logical interface name at the L2 plugin's NB API. During configuration, the LookupIdx() function must be called to determine the VPP if index that corresponds to the specified logical name.

type NameToIdxDto

type NameToIdxDto struct {
	NameToIdxDtoWithoutMeta
	// Auxiliary data related to mapping
	Metadata interface{}
}

NameToIdxDto defines the Data Transfer Object (DTO) that carries a mapping between a logical object name defined at Agent's Northbound API and an sw_if_index defined at the VPP binary API.

type NameToIdxDtoWithoutMeta

type NameToIdxDtoWithoutMeta struct {
	idxmap.NamedMappingEvent

	Idx uint32
}

NameToIdxDtoWithoutMeta is the part of NameToIdxDto that can be reused by indices with typed metadata

func (*NameToIdxDtoWithoutMeta) Done

func (dto *NameToIdxDtoWithoutMeta) Done() error

Done is used to signal to the event producer that the event consumer has processed the event.

func (*NameToIdxDtoWithoutMeta) IsDelete

func (dto *NameToIdxDtoWithoutMeta) IsDelete() bool

IsDelete returns true if the mapping was deleted.

type NameToIdxRW

type NameToIdxRW interface {
	NameToIdx

	// RegisterName registers a new name-to-index mapping. After
	// registration, other plugins can use the "user's API" to lookup the
	// index (by providing the name) or the name by providing the index),
	// and/or be notified  when the mapping is changed. A plugins will
	// typically use the change notifications to modify the part of VPP
	// configuration that it owns and use the VPP binary API to push it
	// to VPP.
	RegisterName(name string, idx uint32, metadata interface{})

	// UnregisterName removes a mapping from the registry. Other plugins
	// can be notified and remove the relevant parts of their own respective
	// VPP configurations and use the VPP binary API to clean it up from
	// VPP.
	UnregisterName(name string) (idx uint32, metadata interface{}, exists bool)
}

NameToIdxRW is the "owner API" to the NameToIdx registry. Using this API the owner adds (registers) new mappings to the registry or deletes (unregisters) existing mappings from the registry.