48 ASSERT (NULL != dst_prefix);
70 "LISP-src for [%d,%U]",
127 return (src_fib_index);
149 ASSERT (NULL != dst_prefix);
150 ASSERT (NULL != src_prefix);
169 if (n_entries == 0 || (have_default && n_entries == 1))
245 if (paths[0].
priority != best_priority)
288 return fib_entry_index;
295 u8 found = 0, ip_version;
303 if (lfei[0] == new_lfei)
338 memcpy (&ippref, &lfe->
key->
lcl.
ippref, sizeof (ippref));
343 memcpy (&ippref, &lfe->
key->
rmt.
ippref, sizeof (ippref));
442 return (p1->
priority - p2->priority);
456 path = &lfe->
paths[index];
497 memcpy (key_copy, &key,
sizeof (*key_copy));
531 return VNET_API_ERROR_INVALID_VALUE;
536 memcpy (lfe->
key, &key, sizeof (key));
614 return VNET_API_ERROR_INVALID_VALUE;
625 kv->key[0] = (((
u64) bd_index) << 48) |
mac_to_u64 (dst_mac);
692 if (BV (clib_bihash_search) (&lgm->l2_fib, &kv, &value) == 0)
693 old_val = value.value;
705 #define L2_FIB_DEFAULT_HASH_NUM_BUCKETS (64 * 1024) 706 #define L2_FIB_DEFAULT_HASH_MEMORY_SIZE (32<<20) 738 lfe->
l2.child_index);
770 return VNET_API_ERROR_INVALID_VALUE;
848 return VNET_API_ERROR_INVALID_VALUE;
853 memcpy (lfe->
key, &key, sizeof (key));
863 lfe->
l2.eid_bd_index = bd_indexp[0];
881 lfe->
l2.path_list_index =
888 lfe->
l2.child_index =
920 kv.key[0] = spi_si_net_order;
931 return &lfe->
nsh.choice;
955 kv.key[0] = clib_host_to_net_u32 (spi_si_host_order);
958 if (BV (clib_bihash_search) (&lgm->nsh_fib, &kv, &value) == 0)
959 old_val = value.value;
971 #define NSH_FIB_DEFAULT_HASH_NUM_BUCKETS (64 * 1024) 972 #define NSH_FIB_DEFAULT_HASH_MEMORY_SIZE (32<<20) 999 lfe->
nsh.child_index);
1030 return VNET_API_ERROR_INVALID_VALUE;
1123 return VNET_API_ERROR_INVALID_VALUE;
1128 memcpy (lfe->
key, &key, sizeof (key));
1154 lfe->
nsh.path_list_index =
1161 lfe->
nsh.child_index =
1215 return (&(lfe->
node));
1257 return VNET_API_ERROR_LISP_DISABLED;
1280 clib_warning (
"Forwarding entries for type %d not supported!", type);
1319 key_copy = (
void *) (hp->
key);
1328 u32 fwd_entry_index)
1362 switch (fid_addr_type(&lfe->key->rmt))
1365 del_l2_fwd_entry_i (lgm, lfe);
1367 case FID_ADDR_IP_PREF:
1368 del_ip_fwd_entry_i (lgm, lfe);
1371 del_nsh_fwd_entry_i (lgm, lfe);
1384 s =
format (s,
"adj:[%U]\n",
1407 s =
format (s,
"VNI:%d VRF:%d EID: %U -> %U [index:%d]",
1415 s =
format (s,
"\n Negative - action:%U",
1422 s =
format (s,
"\n via:");
1434 s =
format (s,
" fib-path-list:%d\n", lfe->
l2.path_list_index);
1438 s =
format (s,
" fib-path-list:%d\n", lfe->
nsh.path_list_index);
1458 if (
unformat (input,
"vni %d", &vni))
1460 else if (
unformat (input,
"%d", &index))
1483 (lfe->key->vni == vni))
1484 vlib_cli_output (vm,
"%U", format_lisp_gpe_fwd_entry, lfe,
1485 LISP_GPE_FWD_ENTRY_FORMAT_NONE);
1494 .path =
"show gpe entry",
1495 .short_help =
"show gpe entry vni <vni> vrf <vrf> [leid <leid>] reid <reid>",
1527 hash_set (vnis, lfe->key->vni, 0);
1544 if (lfe->key->vni == vni)
1546 clib_memset (&e, 0, sizeof (e));
1547 e.dp_table = lfe->eid_table_id;
1548 e.vni = lfe->key->vni;
1549 if (lfe->type == LISP_GPE_FWD_ENTRY_TYPE_NEGATIVE)
1550 e.action = lfe->action;
1551 e.fwd_entry_index = lfe - lgm->lisp_fwd_entry_pool;
1552 memcpy (&e.reid, &lfe->key->rmt, sizeof (e.reid));
1553 memcpy (&e.leid, &lfe->key->lcl, sizeof (e.leid));
1554 vec_add1 (entries, e);
void dpo_unlock(dpo_id_t *dpo)
Release a reference counting lock on the DPO.
#define vec_validate(V, I)
Make sure vector is long enough for given index (no header, unspecified alignment) ...
static void ip_src_dst_fib_del_route(u32 src_fib_index, const ip_prefix_t *src_prefix, u32 dst_fib_index, const ip_prefix_t *dst_prefix)
Del route to IP4 or IP6 SD FIB.
u16 lb_n_buckets
number of buckets in the load-balance.
void dpo_stack_from_node(u32 child_node_index, dpo_id_t *dpo, const dpo_id_t *parent)
Stack one DPO object on another, and thus establish a child parent relationship.
fib_protocol_t fp_proto
protocol type
static void lisp_del_adj_stats(lisp_gpe_main_t *lgm, u32 fwd_entry_index, u32 ti)
#define vec_foreach_index(var, v)
Iterate over vector indices.
ip46_address_t frp_addr
The next-hop address.
vlib_combined_counter_main_t lbm_to_counters
static const fib_node_vft_t lisp_fwd_vft
Virtual function table to register with FIB for the LISP type.
struct lisp_gpe_fwd_entry_t_::@323::@329 l2
Fields relevant to an L2 entry.
static int add_l2_fwd_entry(lisp_gpe_main_t *lgm, vnet_lisp_gpe_add_del_fwd_entry_args_t *a)
Add LISP L2 forwarding entry.
#define gid_address_type(_a)
static void l2_fib_init(lisp_gpe_main_t *lgm)
negative_fwd_actions_e action
When the type is negative.
void vlib_validate_combined_counter(vlib_combined_counter_main_t *cm, u32 index)
validate a combined counter
void fib_path_list_child_remove(fib_node_index_t path_list_index, u32 si)
fib_node_index_t fib_table_lookup_exact_match(u32 fib_index, const fib_prefix_t *prefix)
Perfom an exact match in the non-forwarding table.
const dpo_id_t * lisp_cp_dpo_get(dpo_proto_t proto)
u8 vnet_lisp_gpe_enable_disable_status(void)
Check if LISP-GPE is enabled.
A representation of a path as described by a route producer.
u32 * vnet_lisp_gpe_get_fwd_entry_vnis(void)
u32 bd_id
bridge domain id
static fib_node_t * lisp_gpe_fwd_entry_get_fib_node(fib_node_index_t index)
Get a fib_node_t struct from the index of a LISP fwd entry.
void vnet_lisp_gpe_fwd_entry_flush(void)
Flush all the forwrding entries.
fib_node_index_t fib_table_entry_update(u32 fib_index, const fib_prefix_t *prefix, fib_source_t source, fib_entry_flag_t flags, fib_route_path_t *paths)
Update an entry to have a new set of paths.
static u32 lisp_l2_fib_add_del_entry(u16 bd_index, u8 src_mac[6], u8 dst_mac[6], const dpo_id_t *dpo, u8 is_add)
Add/del L2 SD FIB entry.
clib_memset(h->entries, 0, sizeof(h->entries[0]) *entries)
enum fib_node_back_walk_rc_t_ fib_node_back_walk_rc_t
Return code from a back walk function.
static vnet_hw_interface_t * vnet_get_hw_interface(vnet_main_t *vnm, u32 hw_if_index)
void dpo_copy(dpo_id_t *dst, const dpo_id_t *src)
atomic copy a data-plane object.
u32 index_t
A Data-Path Object is an object that represents actions that are applied to packets are they are swit...
#define vec_add1(V, E)
Add 1 element to end of vector (unspecified alignment).
Combined counter to hold both packets and byte differences.
u32 src_fib_index
The SRC-FIB index for created for anding source-route entries.
u32 eid_table_id
The VRF ID.
lisp_gpe_fwd_entry_key_t * key
The Entry's key: {lEID,rEID,vni}.
#define hash_set_mem(h, key, value)
#define STRUCT_OFFSET_OF(t, f)
static u8 * format_lisp_fwd_path(u8 *s, va_list *ap)
void vnet_lisp_gpe_add_fwd_counters(vnet_lisp_gpe_add_del_fwd_entry_args_t *a, u32 fwd_entry_index)
dpo_proto_t frp_proto
The protocol of the address below.
u32 lisp_gpe_tenant_find_or_create(u32 vni)
Find or create a tenant for the given VNI.
#define NSH_FIB_DEFAULT_HASH_MEMORY_SIZE
#define pool_get(P, E)
Allocate an object E from a pool P (unspecified alignment).
u32 fib_path_list_child_add(fib_node_index_t path_list_index, fib_node_type_t child_type, fib_node_index_t child_index)
vlib_counter_t ** counters
Per-thread u64 non-atomic counter pairs.
enum fib_protocol_t_ fib_protocol_t
Protocol Type.
u32 tenant
The tenant the entry belongs to.
void fib_node_register_type(fib_node_type_t type, const fib_node_vft_t *vft)
fib_node_register_type
static void delete_fib_entries(lisp_gpe_fwd_entry_t *lfe)
index_t load_balance_create(u32 n_buckets, dpo_proto_t lb_proto, flow_hash_config_t fhc)
const dpo_id_t * drop_dpo_get(dpo_proto_t proto)
static clib_error_t * lisp_gpe_fwd_entry_show(vlib_main_t *vm, unformat_input_t *input, vlib_cli_command_t *cmd)
static lisp_gpe_main_t * vnet_lisp_gpe_get_main()
const dpo_id_t * nsh_cp_lkup
static int add_ip_fwd_entry(lisp_gpe_main_t *lgm, vnet_lisp_gpe_add_del_fwd_entry_args_t *a)
Add/Delete LISP IP forwarding entry.
enum lisp_gpe_fwd_entry_format_flag_t_ lisp_gpe_fwd_entry_format_flag_t
static fib_node_index_t ip_src_fib_add_route(u32 src_fib_index, const ip_prefix_t *src_prefix, const lisp_fwd_path_t *paths)
Add route to IP4 or IP6 SRC FIB.
#define pool_foreach(VAR, POOL, BODY)
Iterate through pool.
u32 frp_sw_if_index
The interface.
int clib_bihash_add_del(clib_bihash *h, clib_bihash_kv *add_v, int is_add)
Add or delete a (key,value) pair from a bi-hash table.
#define VLIB_INIT_FUNCTION(x)
clib_error_t * lisp_gpe_fwd_entry_init(vlib_main_t *vm)
void fib_table_entry_special_remove(u32 fib_index, const fib_prefix_t *prefix, fib_source_t source)
Remove a 'special' entry from the FIB.
u16 lb_n_buckets_minus_1
number of buckets in the load-balance - 1.
vlib_combined_counter_main_t counters
u8 * format_fib_prefix(u8 *s, va_list *args)
static void lisp_gpe_fwd_entry_mk_paths(lisp_gpe_fwd_entry_t *lfe, vnet_lisp_gpe_add_del_fwd_entry_args_t *a)
void lisp_gpe_adjacency_unlock(index_t lai)
lisp_gpe_fwd_entry_type_t type
The forwarding entry type.
void vnet_lisp_gpe_del_fwd_counters(vnet_lisp_gpe_add_del_fwd_entry_args_t *a, u32 fwd_entry_index)
Aggregate type for a prefix.
uword * lisp_gpe_fwd_entries
DB of all forwarding entries.
#define hash_get_pair(h, key)
Contribute an object that is to be used to forward Ethernet packets.
enum dpo_proto_t_ dpo_proto_t
Data path protocol.
#define vlib_call_init_function(vm, x)
uword * bd_index_by_bd_id
Common utility functions for IPv4, IPv6 and L2 LISP-GPE adjacencys.
static void make_mac_fib_key(BVT(clib_bihash_kv) *kv, u16 bd_index, u8 src_mac[6], u8 dst_mac[6])
void gid_to_dp_address(gid_address_t *g, dp_address_t *d)
vl_api_fib_path_type_t type
The identity of a DPO is a combination of its type and its instance number/index of objects of that t...
void ip_address_to_46(const ip_address_t *addr, ip46_address_t *a, fib_protocol_t *proto)
#define pool_elt_at_index(p, i)
Returns pointer to element at given index.
static void vlib_zero_combined_counter(vlib_combined_counter_main_t *cm, u32 index)
Clear a combined counter Clears the set of per-thread counters.
fib_node_index_t fib_path_list_create(fib_path_list_flags_t flags, const fib_route_path_t *rpaths)
#define hash_unset_mem(h, key)
static int lisp_gpe_fwd_entry_path_sort(void *a1, void *a2)
u32 table_id
table (vrf) id
u8 * format_negative_mapping_action(u8 *s, va_list *args)
static u32 lisp_nsh_fib_add_del_entry(u32 spi_si_host_order, u32 lfei, u8 is_add)
Add/del NSH FIB entry.
index_t dpoi_index
used for getting load balance statistics
static int del_ip_fwd_entry(lisp_gpe_main_t *lgm, vnet_lisp_gpe_add_del_fwd_entry_args_t *a)
Add/Delete LISP IP forwarding entry.
static const dpo_id_t * load_balance_get_bucket_i(const load_balance_t *lb, u32 bucket)
u32 vlib_combined_counter_n_counters(const vlib_combined_counter_main_t *cm)
The number of counters (not the number of per-thread counters)
static void del_l2_fwd_entry_i(lisp_gpe_main_t *lgm, lisp_gpe_fwd_entry_t *lfe)
load-balancing over a choice of [un]equal cost paths
#define pool_put(P, E)
Free an object E in pool P.
int vnet_lisp_flush_stats(void)
u32 fib_table_get_num_entries(u32 fib_index, fib_protocol_t proto, fib_source_t source)
Return the number of entries in the FIB added by a given source.
#define vec_del1(v, i)
Delete the element at index I.
u32 sw_if_index
The SW IF index of the sub-interface this adjacency uses.
const lisp_gpe_adjacency_t * lisp_gpe_adjacency_get(index_t lai)
void lookup_dpo_add_or_lock_w_fib_index(fib_node_index_t fib_index, dpo_proto_t proto, lookup_cast_t cast, lookup_input_t input, lookup_table_t table_config, dpo_id_t *dpo)
load_balance_main_t load_balance_main
The one instance of load-balance main.
static u32 ip_dst_fib_add_route(u32 dst_fib_index, const ip_prefix_t *dst_prefix)
Add route to IP4 or IP6 Destination FIB.
An node in the FIB graph.
void clib_bihash_init(clib_bihash *h, char *name, u32 nbuckets, uword memory_size)
initialize a bounded index extensible hash table
void fib_table_unlock(u32 fib_index, fib_protocol_t proto, fib_source_t source)
Take a reference counting lock on the table.
#define gid_address_ippref(_a)
#define L2_FIB_DEFAULT_HASH_MEMORY_SIZE
u8 is_negative
type of mapping
index_t lisp_gpe_adjacency_find_or_create_and_lock(const locator_pair_t *pair, u32 overlay_table_id, u32 vni)
u32 vni
VNI/tenant id in HOST byte order.
int fib_entry_is_sourced(fib_node_index_t fib_entry_index, fib_source_t source)
u32 fwd_entry_index
forwarding entry index of
static void vlib_get_combined_counter(const vlib_combined_counter_main_t *cm, u32 index, vlib_counter_t *result)
Get the value of a combined counter, never called in the speed path Scrapes the entire set of per-thr...
Contribute an object that is to be used to forward NSH packets.
#define vec_free(V)
Free vector's memory (no header).
void fib_table_entry_delete(u32 fib_index, const fib_prefix_t *prefix, fib_source_t source)
Delete a FIB entry.
static void lisp_gpe_fwd_entry_fib_node_last_lock_gone(fib_node_t *node)
An indication from the graph that the last lock has gone.
#define clib_warning(format, args...)
u32 fib_node_index_t
A typedef of a node index.
#define pool_is_free_index(P, I)
Use free bitmap to query whether given index is free.
void dpo_set(dpo_id_t *dpo, dpo_type_t type, dpo_proto_t proto, index_t index)
Set/create a DPO ID The DPO will be locked.
lisp_gpe_main_t lisp_gpe_main
LISP-GPE global state.
static int del_l2_fwd_entry(lisp_gpe_main_t *lgm, vnet_lisp_gpe_add_del_fwd_entry_args_t *a)
Delete LISP L2 forwarding entry.
fib_entry_t * fib_entry_get(fib_node_index_t index)
#define fid_addr_ippref(_a)
Context passed between object during a back walk.
#define VLIB_CLI_COMMAND(x,...)
static int add_nsh_fwd_entry(lisp_gpe_main_t *lgm, vnet_lisp_gpe_add_del_fwd_entry_args_t *a)
Add LISP NSH forwarding entry.
static lisp_gpe_fwd_entry_t * lisp_gpe_fwd_entry_from_fib_node(fib_node_t *node)
conver from the embedded fib_node_t struct to the LSIP entry
int vnet_lisp_gpe_add_del_fwd_entry(vnet_lisp_gpe_add_del_fwd_entry_args_t *a, u32 *hw_if_indexp)
Forwarding entry create/remove dispatcher.
void ip_prefix_to_fib_prefix(const ip_prefix_t *ipp, fib_prefix_t *fibp)
convert from a LISP to a FIB prefix
fib_node_index_t fib_table_entry_special_dpo_add(u32 fib_index, const fib_prefix_t *prefix, fib_source_t source, fib_entry_flag_t flags, const dpo_id_t *dpo)
Add a 'special' entry to the FIB that links to the DPO passed A special entry is an entry that the FI...
static u8 * format_lisp_gpe_fwd_entry(u8 *s, va_list *ap)
#define fid_addr_type(_a)
const void * fib_entry_get_source_data(fib_node_index_t fib_entry_index, fib_source_t source)
int clib_bihash_search_inline_2(clib_bihash *h, clib_bihash_kv *search_key, clib_bihash_kv *valuep)
Search a bi-hash table.
static void del_nsh_fwd_entry_i(lisp_gpe_main_t *lgm, lisp_gpe_fwd_entry_t *lfe)
static load_balance_t * load_balance_get(index_t lbi)
A path on which to forward lisp traffic.
u8 weight
[UE]CMP weigt for the path
static void clib_mem_free(void *p)
uword * hw_if_index_by_dp_table
Lookup lisp-gpe interfaces by dp table (eg.
u32 fib_table_find_or_create_and_lock(fib_protocol_t proto, u32 table_id, fib_source_t src)
Get the index of the FIB for a Table-ID.
static fib_node_index_t ip_src_fib_add_route_w_dpo(u32 src_fib_index, const ip_prefix_t *src_prefix, const dpo_id_t *src_dpo)
Add route to IP4 or IP6 SRC FIB.
static lisp_gpe_fwd_entry_t * find_fwd_entry(lisp_gpe_main_t *lgm, vnet_lisp_gpe_add_del_fwd_entry_args_t *a, lisp_gpe_fwd_entry_key_t *key)
static u64 mac_to_u64(u8 *m)
dpo_proto_t fib_proto_to_dpo(fib_protocol_t fib_proto)
static index_t create_fib_entries(lisp_gpe_fwd_entry_t *lfe)
gid_address_t rmt_eid
remote eid
void load_balance_set_bucket(index_t lbi, u32 bucket, const dpo_id_t *next)
static void * clib_mem_alloc(uword size)
u8 * format_dpo_id(u8 *s, va_list *args)
Format a DPO_id_t oject
vl_api_mfib_path_t paths[n_paths]
dpo_id_t fe_lb
The load-balance used for forwarding.
static void gpe_native_fwd_add_del_lfe(lisp_gpe_fwd_entry_t *lfe, u8 is_add)
static void lisp_gpe_nsh_update_fwding(lisp_gpe_fwd_entry_t *lfe)
Construct and insert the forwarding information used by an NSH entry.
negative_fwd_actions_e action
action for negative mappings
static vlib_cli_command_t lisp_gpe_fwd_entry_show_command
(constructor) VLIB_CLI_COMMAND (lisp_gpe_fwd_entry_show_command)
u32 eid_fib_index
The FIB index for the overlay, i.e.
index_t dpoi_index
the index of objects of that type
#define FIB_NODE_INDEX_INVALID
struct lisp_gpe_fwd_entry_t_ * lisp_fwd_entry_pool
A Pool of all LISP forwarding entries.
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)
dpo_id_t l2_lb_cp_lkup
Load-balance for a miss in the table.
u32 tunnel_index
The index of the LISP GPE tunnel that provides the transport in the underlay.
static uword max_log2(uword x)
u32 dp_table
generic access
#define vec_sort_with_function(vec, f)
Sort a vector using the supplied element comparison function.
static void del_ip_fwd_entry_i(lisp_gpe_main_t *lgm, lisp_gpe_fwd_entry_t *lfe)
static fib_route_path_t * lisp_gpe_mk_fib_paths(const lisp_fwd_path_t *paths)
locator_pair_t * locator_pairs
vector of locator pairs
#define DPO_INVALID
An initialiser for DPOs declared on the stack.
#define ip_prefix_version(_a)
A collection of combined counters.
void fib_path_list_contribute_forwarding(fib_node_index_t path_list_index, fib_forward_chain_type_t fct, fib_path_list_fwd_flags_t flags, dpo_id_t *dpo)
lisp_fwd_path_t * paths
When the type is 'normal' The RLOC pair that form the route's paths.
#define hash_get_mem(h, key)
static void nsh_fib_init(lisp_gpe_main_t *lgm)
A FIB graph nodes virtual function table.
u8 * format_lisp_gpe_adjacency(u8 *s, va_list *args)
index_t lisp_l2_fib_lookup(lisp_gpe_main_t *lgm, u16 bd_index, u8 src_mac[6], u8 dst_mac[6])
Lookup L2 SD FIB entry.
clib_error_t * lisp_cp_dpo_module_init(vlib_main_t *vm)
fib_route_path_t * native_fwd_rpath[2]
Native fwd data structures.
int vnet_lisp_gpe_get_fwd_stats(vnet_lisp_gpe_add_del_fwd_entry_args_t *a, vlib_counter_t *c)
static fib_node_back_walk_rc_t lisp_gpe_fib_node_back_walk(fib_node_t *node, fib_node_back_walk_ctx_t *ctx)
Function invoked during a backwalk of the FIB graph.
void dpo_reset(dpo_id_t *dpo)
reset a DPO ID The DPO will be unlocked.
#define vec_foreach(var, vec)
Vector iterator.
#define NSH_FIB_DEFAULT_HASH_NUM_BUCKETS
struct lisp_gpe_fwd_entry_t_::@323::@330 nsh
Fields relevant to an NSH entry.
uword * lisp_stats_index_by_key
static void lisp_gpe_l2_update_fwding(lisp_gpe_fwd_entry_t *lfe)
Construct and insert the forwarding information used by an L2 entry.
static int del_nsh_fwd_entry(lisp_gpe_main_t *lgm, vnet_lisp_gpe_add_del_fwd_entry_args_t *a)
Delete LISP NSH forwarding entry.
u8 frp_weight
[un]equal cost path weight
fib_node_t node
This object joins the FIB control plane graph to receive updates to for changes to the graph...
u8 * format_fid_address(u8 *s, va_list *args)
gid_address_t lcl_eid
local eid
u32 fib_table_create_and_lock(fib_protocol_t proto, fib_source_t src, const char *const fmt,...)
Create a new table with no table ID.
tunnel_lookup_t nsh_ifaces
void vlib_cli_output(vlib_main_t *vm, char *fmt,...)
#define L2_FIB_DEFAULT_HASH_NUM_BUCKETS
void fib_entry_set_source_data(fib_node_index_t fib_entry_index, fib_source_t source, const void *data)
const dpo_id_t * lisp_nsh_fib_lookup(lisp_gpe_main_t *lgm, u32 spi_si_net_order)
Lookup NSH SD FIB entry.
lisp_gpe_fwd_entry_format_flag_t_
ip_address_t remote_rloc
remote RLOC.
lisp_api_gpe_fwd_entry_t * vnet_lisp_gpe_fwd_entries_get_by_vni(u32 vni)
u8 is_src_dst
Follows src/dst or dst only forwarding policy.
index_t lisp_adj
The adjacency constructed for the locator pair.