Documentation/group-selection-method-property.txt

   1 Proposal for Group Selection Method Property
   2 Version: 0.0.3
   3
   4 Author: Simon Horman <simon.horman@netronome.com>, et al.
   5 Initial Public Revision: September 2014
   6
   7
   8 Contents
   9 ========
  10
  11 1. Introduction
  12 2. How it Works
  13 3. Experimenter Id
  14 4. Experimenter Messages
  15 5. History
  16
  17
  18 1. Introduction
  19 ===============
  20
  21 This text describes a Netronome Extension to (draft) OpenFlow 1.5 that allows a
  22 controller to provide more information on the selection method for select
  23 groups.  This proposal is in the form of an enhanced select group type.
  24
  25 This may subsequently be proposed as an extension or update to
  26 the OpenFlow specification.
  27
  28
  29 2. How it works
  30 ===============
  31
  32 A new Netronome group experimenter property is defined which provides
  33 compatibility with the group mod message defined in draft Open Flow 1.5
  34 (also known as ONF EXT-350) and allows parameters for the selection
  35 method of select groups to be passed by the controller. In particular it
  36 allows controllers to:
  37
  38 * Specify the fields used for bucket selection by the select group.
  39
  40 * Designate the selection method used.
  41
  42 * Provide a non-field parameter to the selection method.
  43
  44
  45 3. Experimenter ID
  46 ==================
  47
  48 The Experimenter ID of this extension is:
  49
  50 NTR_VENDOR_ID = 0x0000154d
  51
  52
  53 4. Group Experimenter Property
  54 ==============================
  55
  56 The following group property experimenter type defined by this extension.
  57
  58 enum ntr_group_mod_subtype {
  59         NTRT_SELECTION_METHOD = 1,
  60 };
  61
  62
  63 Modifications to the group table from the controller may be done with a
  64 OFPT_GROUP_MOD message described (draft) Open Flow 1.5.  Group Entry
  65 Message. Of relevance here is that (draft) Open Flow 1.5 group messages
  66 have properties.
  67
  68 This proposal is defined in terms of an implementation of struct
  69 ofp_group_prop_experimenter which is described in (draft) Open Flow 1.5.
  70 The implementation is:
  71
  72 struct ntr_group_prop_selection_method {
  73     ovs_be16 type;                  /* OFPGPT_EXPERIMENTER. */
  74     ovs_be16 length;                /* Length in bytes of this property. */
  75     ovs_be32 experimenter;          /* NTR_VENDOR_ID. */
  76     ovs_be32 exp_type;              /* NTRT_SELECTION_METHOD. */
  77     ovs_be32 pad;
  78     char selection_method[NTR_MAX_SELECTION_METHOD_LEN];
  79                                     /* Null-terminated */
  80     ovs_be64 selection_method_param;  /* Non-Field parameter for
  81                                        * bucket selection. */
  82
  83     /* Followed by:
  84      *   - Exactly (length - 40) (possibly 0) bytes containing OXM TLVs, then
  85      *   - Exactly ((length + 7)/8*8 - length) (between 0 and 7) bytes of
  86      *     all-zero bytes
  87      * In summary, ntr_group_prop_selection_method is padded as needed,
  88      * to make its overall size a multiple of 8, to preserve alignment
  89      * in structures using it.
  90      */
  91     /* uint8_t field_array[0]; */   /* Zero or more fields encoded as
  92                                      * OXM TLVs where the has_mask bit must
  93                                      * be zero and the value it specifies is
  94                                      * a mask to apply to packet fields and
  95                                      * then input them to the selection
  96                                      * method of a select group. */
  97     /* uint8_t pad2[0]; */
  98 };
  99 OFP_ASSERT(sizeof(struct ntr_group_mod) == 40);
 100
 101
 102 This property may only be used with group mod messages whose:
 103 * command is OFPGC_ADD or OFPGC_MODIFY; and
 104 * type is OFPGT_SELECT
 105
 106
 107 The type field is the OFPGPT_EXPERIMENTER which is
 108 defined in EXT-350 as 0xffff.
 109
 110
 111 The experimenter field is the Experimenter ID (see 3).
 112
 113
 114 The exp_type field is NTRT_SELECTION_METHOD.
 115
 116
 117 The group selection_method is a null-terminated string which if non-zero
 118 length specifies a selection method known to an underlying layer of the
 119 switch. The value of NTR_MAX_SELECTION_METHOD_LEN is 16.
 120
 121 The group selection_method may be zero-length to request compatibility with
 122 Open Flow 1.4.
 123
 124
 125 The selection_method_param provides a non-field parameter for
 126 the group selection_method. It must be all-zeros unless the
 127 group selection_method is non-zero length.
 128
 129 The selection_method_param may for example be used as an initial value for
 130 the hash of a hash group selection method.
 131
 132
 133 The fields field is an ofp_match structure which includes the fields which
 134 should be used as inputs to bucket selection. ofp_match is described in
 135 Open Flow 1.4 section 7.2.2 Flow Match Structures.
 136
 137 Fields must not be specified unless the group selection_method is non-zero
 138 length.
 139
 140 The pre-requisites for fields specified must be satisfied in the match for
 141 any flow that uses the group.
 142
 143 Masking is allowed but not required for fields whose TLVs allow masking.
 144
 145 The fields may for example be used as the fields that are hashed
 146 by a hash group selection method.
 147
 148
 149 5. History
 150 ==========
 151
 152 This proposal has been developed independently of any similar work in this
 153 area. No such work is known.