src/vnet/dpo/load_balance.h

   1 /*
   2  * Copyright (c) 2016 Cisco and/or its affiliates.
   3  * Licensed under the Apache License, Version 2.0 (the "License");
   4  * you may not use this file except in compliance with the License.
   5  * You may obtain a copy of the License at:
   6  *
   7  *     http://www.apache.org/licenses/LICENSE-2.0
   8  *
   9  * Unless required by applicable law or agreed to in writing, software
  10  * distributed under the License is distributed on an "AS IS" BASIS,
  11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12  * See the License for the specific language governing permissions and
  13  * limitations under the License.
  14  */
  15 /**
  16  * \brief
  17  * The load-balance object represents an ECMP choice. The buckets of a load
  18  * balance object point to the sub-graph after the choice is made.
  19  * THe load-balance object is also object type returned from a FIB table lookup.
  20  * As such it needs to represent the case where there is only one coice. It may
  21  * seem like overkill to use a load-balance object in this case, but the reason
  22  * is for performance. If the load-balance object were not the result of the FIB
  23  * lookup, then some other object would be. The case where there was ECMP
  24  * this other object would need a load-balance as a parent and hence just add
  25  * an unnecessary indirection.
  26  *
  27  * It is also the object in the DP that represents a via-fib-entry in a recursive
  28  * route.
  29  *
  30  */
  31
  32 #ifndef __LOAD_BALANCE_H__
  33 #define __LOAD_BALANCE_H__
  34
  35 #include <vlib/vlib.h>
  36 #include <vnet/ip/lookup.h>
  37 #include <vnet/dpo/dpo.h>
  38 #include <vnet/fib/fib_types.h>
  39 #include <vnet/fib/fib_entry.h>
  40
  41 /**
  42  * Load-balance main
  43  */
  44 typedef struct load_balance_main_t_
  45 {
  46     vlib_combined_counter_main_t lbm_to_counters;
  47     vlib_combined_counter_main_t lbm_via_counters;
  48 } load_balance_main_t;
  49
  50 extern load_balance_main_t load_balance_main;
  51
  52 /**
  53  * The maximum number of buckets that a load-balance object can have
  54  * This must not overflow the lb_n_buckets field
  55  */
  56 #define LB_MAX_BUCKETS 8192
  57
  58 /**
  59  * The number of buckets that a load-balance object can have and still
  60  * fit in one cache-line
  61  */
  62 #define LB_NUM_INLINE_BUCKETS 4
  63
  64 /**
  65  * @brief One path from an [EU]CMP set that the client wants to add to a
  66  * load-balance object
  67  */
  68 typedef struct load_balance_path_t_ {
  69     /**
  70      * ID of the Data-path object.
  71      */
  72     dpo_id_t path_dpo;
  73
  74     /**
  75      * The index of the FIB path
  76      */
  77     fib_node_index_t path_index;
  78
  79     /**
  80      * weight for the path.
  81      */
  82     u32 path_weight;
  83 } load_balance_path_t;
  84
  85 /**
  86  * Flags controlling load-balance creation and modification
  87  */
  88 typedef enum load_balance_attr_t_ {
  89     LOAD_BALANCE_ATTR_USES_MAP = 0,
  90     LOAD_BALANCE_ATTR_STICKY = 1,
  91 } load_balance_attr_t;
  92
  93 #define LOAD_BALANCE_ATTR_NAMES  {                  \
  94     [LOAD_BALANCE_ATTR_USES_MAP] = "uses-map",      \
  95     [LOAD_BALANCE_ATTR_STICKY] = "sticky",          \
  96 }
  97
  98 #define FOR_EACH_LOAD_BALANCE_ATTR(_attr)                       \
  99     for (_attr = 0; _attr <= LOAD_BALANCE_ATTR_STICKY; _attr++)
 100
 101 typedef enum load_balance_flags_t_ {
 102     LOAD_BALANCE_FLAG_NONE = 0,
 103     LOAD_BALANCE_FLAG_USES_MAP = (1 << 0),
 104     LOAD_BALANCE_FLAG_STICKY = (1 << 1),
 105 } __attribute__((packed)) load_balance_flags_t;
 106
 107 /**
 108  * The FIB DPO provieds;
 109  *  - load-balancing over the next DPOs in the chain/graph
 110  *  - per-route counters
 111  */
 112 typedef struct load_balance_t_ {
 113     /**
 114      * required for pool_get_aligned.
 115      *  memebers used in the switch path come first!
 116      */
 117     CLIB_CACHE_LINE_ALIGN_MARK(cacheline0);
 118
 119     /**
 120      * number of buckets in the load-balance. always a power of 2.
 121      */
 122     u16 lb_n_buckets;
 123     /**
 124      * number of buckets in the load-balance - 1. used in the switch path
 125      * as part of the hash calculation.
 126      */
 127     u16 lb_n_buckets_minus_1;
 128
 129    /**
 130      * The protocol of packets that traverse this LB.
 131      * need in combination with the flow hash config to determine how to hash.
 132      * u8.
 133      */
 134     dpo_proto_t lb_proto;
 135
 136     /**
 137      * Flags concenring the LB's creation and modification
 138      */
 139     load_balance_flags_t lb_flags;
 140
 141     /**
 142      * Flags from the load-balance's associated fib_entry_t
 143      */
 144     fib_entry_flag_t lb_fib_entry_flags;
 145
 146     /**
 147      * The number of locks, which is approximately the number of users,
 148      * of this load-balance.
 149      * Load-balance objects of via-entries are heavily shared by recursives,
 150      * so the lock count is a u32.
 151      */
 152     u32 lb_locks;
 153
 154     /**
 155      * index of the load-balance map, INVALID if this LB does not use one
 156      */
 157     index_t lb_map;
 158
 159     /**
 160      * This is the index of the uRPF list for this LB
 161      */
 162     index_t lb_urpf;
 163
 164     /**
 165      * the hash config to use when selecting a bucket. this is a u16
 166      */
 167     flow_hash_config_t lb_hash_config;
 168
 169     /**
 170      * Vector of buckets containing the next DPOs, sized as lbo_num
 171      */
 172     dpo_id_t *lb_buckets;
 173
 174     /**
 175      * The rest of the cache line is used for buckets. In the common case
 176      * where there there are less than 4 buckets, then the buckets are
 177      * on the same cachlie and we save ourselves a pointer dereferance in
 178      * the data-path.
 179      */
 180     dpo_id_t lb_buckets_inline[LB_NUM_INLINE_BUCKETS];
 181 } load_balance_t;
 182
 183 STATIC_ASSERT(sizeof(load_balance_t) <= CLIB_CACHE_LINE_BYTES,
 184               "A load_balance object size exceeds one cacheline");
 185 STATIC_ASSERT (LB_MAX_BUCKETS <= CLIB_U16_MAX,
 186                "Too many buckets for load_balance object");
 187 STATIC_ASSERT (LB_MAX_BUCKETS && !(LB_MAX_BUCKETS & (LB_MAX_BUCKETS - 1)),
 188                "LB_MAX_BUCKETS must be a power of 2");
 189
 190 /**
 191  * Flags controlling load-balance formatting/display
 192  */
 193 typedef enum load_balance_format_flags_t_ {
 194     LOAD_BALANCE_FORMAT_NONE,
 195     LOAD_BALANCE_FORMAT_DETAIL = (1 << 0),
 196 } load_balance_format_flags_t;
 197
 198 extern index_t load_balance_create(u32 num_buckets,
 199                                    dpo_proto_t lb_proto,
 200                                    flow_hash_config_t fhc);
 201 extern flow_hash_config_t load_balance_get_default_flow_hash(dpo_proto_t lb_proto);
 202 extern void load_balance_multipath_update(
 203     const dpo_id_t *dpo,
 204     const load_balance_path_t * raw_next_hops,
 205     load_balance_flags_t flags);
 206
 207 extern void load_balance_set_bucket(index_t lbi,
 208                                     u32 bucket,
 209                                     const dpo_id_t *next);
 210 extern void load_balance_set_urpf(index_t lbi,
 211                                   index_t urpf);
 212 extern void load_balance_set_fib_entry_flags(index_t lbi,
 213                                              fib_entry_flag_t flags);
 214 extern index_t load_balance_get_urpf(index_t lbi);
 215
 216 extern u8* format_load_balance(u8 * s, va_list * args);
 217
 218 extern const dpo_id_t *load_balance_get_bucket(index_t lbi,
 219                                                u32 bucket);
 220 extern int load_balance_is_drop(const dpo_id_t *dpo);
 221 extern u16 load_balance_n_buckets(index_t lbi);
 222
 223 extern f64 load_balance_get_multipath_tolerance(void);
 224
 225 /**
 226  * The encapsulation breakages are for fast DP access
 227  */
 228 extern load_balance_t *load_balance_pool;
 229 static inline load_balance_t*
 230 load_balance_get (index_t lbi)
 231 {
 232     return (pool_elt_at_index(load_balance_pool, lbi));
 233 }
 234
 235 static inline load_balance_t *
 236 load_balance_get_or_null (index_t lbi)
 237 {
 238   if (pool_is_free_index (load_balance_pool, lbi))
 239     return 0;
 240   return (pool_elt_at_index (load_balance_pool, lbi));
 241 }
 242
 243 #define LB_HAS_INLINE_BUCKETS(_lb)              \
 244     ((_lb)->lb_n_buckets <= LB_NUM_INLINE_BUCKETS)
 245
 246 static inline const dpo_id_t *
 247 load_balance_get_bucket_i (const load_balance_t *lb,
 248                            u32 bucket)
 249 {
 250     ASSERT(bucket < lb->lb_n_buckets);
 251
 252     if (PREDICT_TRUE(LB_HAS_INLINE_BUCKETS(lb)))
 253     {
 254         return (&lb->lb_buckets_inline[bucket]);
 255     }
 256     else
 257     {
 258         return (&lb->lb_buckets[bucket]);
 259     }
 260 }
 261
 262 extern void load_balance_module_init(void);
 263
 264 #endif