[mirror_ovs.git] / Documentation / group-selection-method-property.txt

Proposal for Group Selection Method Property
Version: 0.0.3

Author: Simon Horman <simon.horman@netronome.com>, et al.
Initial Public Revision: September 2014


Contents
========

1. Introduction
2. How it Works
3. Experimenter Id
4. Experimenter Messages
5. History


1. Introduction
===============

This text describes a Netronome Extension to OpenFlow 1.5 that allows a
controller to provide more information on the selection method for select
groups.  This proposal is in the form of an enhanced select group type.

This may subsequently be proposed as an extension or update to
the OpenFlow specification.


2. How it works
===============

A new Netronome group experimenter property is defined which provides
compatibility with the group mod message defined in Open Flow 1.5
(also known as ONF EXT-350) and allows parameters for the selection
method of select groups to be passed by the controller. In particular it
allows controllers to:

* Specify the fields used for bucket selection by the select group.

* Designate the selection method used.

* Provide a non-field parameter to the selection method.


3. Experimenter ID
==================

The Experimenter ID of this extension is:

NTR_VENDOR_ID = 0x0000154d


4. Group Experimenter Property
==============================

The following group property experimenter type defined by this extension.

enum ntr_group_mod_subtype {
        NTRT_SELECTION_METHOD = 1,
};


Modifications to the group table from the controller may be done with
a OFPT_GROUP_MOD message described Open Flow 1.5.  Group Entry
Message. Of relevance here is that Open Flow 1.5 group messages have
properties.

This proposal is defined in terms of an implementation of struct
ofp_group_prop_experimenter which is described in Open Flow 1.5.  The
implementation is:

struct ntr_group_prop_selection_method {
    ovs_be16 type;                  /* OFPGPT_EXPERIMENTER. */
    ovs_be16 length;                /* Length in bytes of this property. */
    ovs_be32 experimenter;          /* NTR_VENDOR_ID. */
    ovs_be32 exp_type;              /* NTRT_SELECTION_METHOD. */
    ovs_be32 pad;
    char selection_method[NTR_MAX_SELECTION_METHOD_LEN];
                                    /* Null-terminated */
    ovs_be64 selection_method_param;  /* Non-Field parameter for
                                       * bucket selection. */

    /* Followed by:
     *   - Exactly (length - 40) (possibly 0) bytes containing OXM TLVs, then
     *   - Exactly ((length + 7)/8*8 - length) (between 0 and 7) bytes of
     *     all-zero bytes
     * In summary, ntr_group_prop_selection_method is padded as needed,
     * to make its overall size a multiple of 8, to preserve alignment
     * in structures using it.
     */
    /* uint8_t field_array[0]; */   /* Zero or more fields encoded as
                                     * OXM TLVs where the has_mask bit must
                                     * be zero and the value it specifies is
                                     * a mask to apply to packet fields and
                                     * then input them to the selection
                                     * method of a select group. */
    /* uint8_t pad2[0]; */
};
OFP_ASSERT(sizeof(struct ntr_group_mod) == 40);


This property may only be used with group mod messages whose:
* command is OFPGC_ADD or OFPGC_MODIFY; and
* type is OFPGT_SELECT


The type field is the OFPGPT_EXPERIMENTER which is
defined in EXT-350 as 0xffff.


The experimenter field is the Experimenter ID (see 3).


The exp_type field is NTRT_SELECTION_METHOD.


The group selection_method is a null-terminated string which if non-zero
length specifies a selection method known to an underlying layer of the
switch. The value of NTR_MAX_SELECTION_METHOD_LEN is 16.

The group selection_method may be zero-length to request compatibility with
Open Flow 1.4.


The selection_method_param provides a non-field parameter for
the group selection_method. It must be all-zeros unless the
group selection_method is non-zero length.

The selection_method_param may for example be used as an initial value for
the hash of a hash group selection method.


The fields field is an ofp_match structure which includes the fields which
should be used as inputs to bucket selection. ofp_match is described in
Open Flow 1.4 section 7.2.2 Flow Match Structures.

Fields must not be specified unless the group selection_method is non-zero
length.

The pre-requisites for fields specified must be satisfied in the match for
any flow that uses the group.

Masking is allowed but not required for fields whose TLVs allow masking.

The fields may for example be used as the fields that are hashed
by a hash group selection method.


5. History
==========

This proposal has been developed independently of any similar work in this
area. No such work is known.
Commit	Line	Data
8c254406 SH	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
13c952ca	21	This text describes a Netronome Extension to OpenFlow 1.5 that allows a
8c254406 SH	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
13c952ca	33	compatibility with the group mod message defined in Open Flow 1.5
8c254406 SH	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
c28a1f83	50	NTR_VENDOR_ID = 0x0000154d
8c254406 SH	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 {
5a0e4aec	59	NTRT_SELECTION_METHOD = 1,
8c254406 SH	60	};
	61
	62
13c952ca BP	63	Modifications to the group table from the controller may be done with
	64	a OFPT_GROUP_MOD message described Open Flow 1.5. Group Entry
	65	Message. Of relevance here is that Open Flow 1.5 group messages have
	66	properties.
8c254406 SH	67
8c254406 SH	68	This proposal is defined in terms of an implementation of struct
13c952ca BP	69	ofp_group_prop_experimenter which is described in Open Flow 1.5. The
13c952ca BP	70	implementation is:
8c254406 SH	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.