7.3 Controller-to-Switch Messages
7.3.4 Modify State Messages
7.3.4.3 Modify Group Entry Message
Modifications to the group table from the controller are done with the OFPT_GROUP_MOD message:
/* Group setup and teardown (controller -> datapath). */ struct ofp_group_mod {
struct ofp_header header;
uint16_t command; /* One of OFPGC_*. */
uint8_t type; /* One of OFPGT_*. */
uint8_t pad; /* Pad to 64 bits. */
uint32_t group_id; /* Group identifier. */
uint16_t bucket_array_len; /* Length of action buckets data. */
uint8_t pad2[2]; /* Pad to 64 bits. */
uint32_t command_bucket_id; /* Bucket Id used as part of
OFPGC_INSERT_BUCKET and OFPGC_REMOVE_BUCKET commands execution.*/
* - Zero or more bytes of group properties to fill out the overall
* length in header.length. */
struct ofp_bucket buckets[0]; /* The length of the bucket array is bucket_array_len bytes. */ //struct ofp_group_prop_header properties[0];
};
OFP_ASSERT (sizeof(struct ofp_group_mod) == 24);
The semantics of the type and group fields are explained in Section 6.7. The command field must be one of the following:
/* Group commands */
enum ofp_group_mod_command {
OFPGC_ADD = 0, /* New group. */
OFPGC_MODIFY = 1, /* Modify all matching groups. */
OFPGC_DELETE = 2, /* Delete all matching groups. */
OFPGC_INSERT_BUCKET = 3,/* Insert action buckets to the already available list of action buckets in a matching group */
/* OFPGC_??? = 4, */ /* Reserved for future use. */
OFPGC_REMOVE_BUCKET = 5,/* Remove all action buckets or any specific action bucket from matching group */
};
The command OFPGC_ADD creates a new group based on the content of the request (and returns an error if a group with the same group_id already exists). The command OFPGC_MODIFY replaces the definition of an existing group with the content of the request. The command OFPGC_DELETE destroys the group specified by group_id, or all groups if group_id is OFPG_ALL. The command OFPGC_INSERT_BUCKET adds buckets to an existing group. The command OFPGC_REMOVE_BUCKET removes buckets from an existing group.
The type field specifies how the group behaves and which group buckets will be used to process packets (see 5.10.1), it must be one of the following values:
/* Group types. Values in the range [128, 255] are reserved for experimental * use. */
enum ofp_group_type {
OFPGT_ALL = 0, /* All (multicast/broadcast) group. */
OFPGT_SELECT = 1, /* Select group. */
OFPGT_INDIRECT = 2, /* Indirect group. */
OFPGT_FF = 3, /* Fast failover group. */
};
The group_id field uniquely identifies a group within a switch, a group can have any Group ID lower than OFPG_MAX as long as it is unique on the switch. The following special group identifiers are defined:
/* Group numbering. Groups can use any number up to OFPG_MAX. */ enum ofp_group {
/* Last usable group number. */
OFPG_MAX = 0xffffff00,
OFPG_ALL = 0xfffffffc, /* Represents all groups for group delete commands. */
OFPG_ANY = 0xffffffff /* Special wildcard: no group specified. */
};
The bucket_array_len field is the size in bytes of the array of buckets in the buckets field.
The command_bucket_id field is either the Bucket ID of one of the buckets already existing in the group, or one of the following special bucket identifiers:
/* Bucket Id can be any value between 0 and OFPG_BUCKET_MAX */ enum ofp_group_bucket {
OFPG_BUCKET_MAX = 0xffffff00, /* Last usable bucket ID. */
OFPG_BUCKET_FIRST = 0xfffffffd, /* First bucket ID in the list of action buckets of a group. This is applicable for OFPGC_INSERT_BUCKET and
OFPGC_REMOVE_BUCKET commands. */ OFPG_BUCKET_LAST = 0xfffffffe, /* Last bucket ID in the list of action
buckets of a group. This is applicable for OFPGC_INSERT_BUCKET and
OFPGC_REMOVE_BUCKET commands. */
OFPG_BUCKET_ALL = 0xffffffff /* All action buckets in a group,
This is applicable for
only OFPGC_REMOVE_BUCKET command. */ };
The interpretation of the command_bucket_id field and which Bucket IDs are valid for that field depends on the command field. For OFPGC_INSERT_BUCKET, it defines the place in the bucket list to insert the new buckets. For OFPGC_REMOVE_BUCKET, it defines the buckets to be removed. The commands OFPGC_ADD, OFPGC_MODIFYand OFPGC_DELETE don’t use the command_bucket_id field, for those commands it must be set to OFPG_BUCKET_ALL.
The buckets field is a list of buckets. Group buckets are described in the next section (see 7.3.4.3.1). The properties field is a list of group properties. Group properties are described in a following section (see 7.3.4.3.2).
7.3.4.3.1 Group Buckets
The buckets field in the OFPT_GROUP_MOD message is a list of buckets. An Indirect group must contain exactly one bucket (see 5.10.1), therefore the buckets field must contain a single bucket and any command that would make such a group have multiple buckets must return an error (see 7.5.4.7). Other group types may have multiple buckets in the buckets field. For Fast Failover group, the bucket order does define the bucket priorities (see 5.10.1), and the bucket order can be changed by modifying the group (for example using a OFPT_GROUP_MOD message with command OFPGC_MODIFY).
Group buckets use the following structure :
64-bit aligned. */
uint16_t action_array_len; /* Length of all actions in bytes. */
uint32_t bucket_id; /* Bucket Id used to identify bucket*/
/* Followed by:
* - Exactly ’action_array_len’ bytes containing an array of
* struct ofp_action_*.
* - Zero or more bytes of group bucket properties to fill out the
* overall length in header.length. */
struct ofp_action_header actions[0]; /* The length of the action array is action_array_len bytes. */ //struct ofp_group_bucket_prop_header properties[0];
};
OFP_ASSERT(sizeof(struct ofp_bucket) == 8);
The action_array_len field is the size in bytes of the set of actions in the actions field.
The bucket_id field uniquely identifies an action bucket of a group within a switch. Each bucket of the group must have an unique Bucket ID ; if a group mod would make the group have a duplicate Bucket ID, the switch must refuse the group mod and send a Bucket Exist error message (see 7.5.4.7). The bucket_id field must be lower than OFPG_BUCKET_MAX (it can not be one of the special bucket values).
The actions field is the set of actions associated with the bucket. When the bucket is selected for a packet, its actions are applied to the packet as an action set (see 5.6).
The properties field is a list of group bucket properties.
The list of group bucket property types that are currently defined are:
/* Group bucket property types. */ enum ofp_group_bucket_prop_type {
OFPGBPT_WEIGHT = 0, /* Select groups only. */
OFPGBPT_WATCH_PORT = 1, /* Fast failover groups only. */
OFPGBPT_WATCH_GROUP = 2, /* Fast failover groups only. */
OFPGBPT_EXPERIMENTER = 0xFFFF, /* Experimenter defined. */
};
A property definition contains the property type, length, and any associated data:
/* Common header for all group bucket properties. */ struct ofp_group_bucket_prop_header {
uint16_t type; /* One of OFPGBPT_*. */
uint16_t length; /* Length in bytes of this property. */
};
OFP_ASSERT(sizeof(struct ofp_group_bucket_prop_header) == 4);
The OFPGBPT_WEIGHT property uses the following structure and fields:
/* Group bucket weight property, for select groups only. */ struct ofp_group_bucket_prop_weight {
uint16_t type; /* OFPGBPT_WEIGHT. */
uint16_t weight; /* Relative weight of bucket. */
uint8_t pad[2]; /* Pad to 64 bits. */
};
OFP_ASSERT(sizeof(struct ofp_group_bucket_prop_weight) == 8);
The weight field is only defined for select groups, and its support is optional. For other group types, this property must be omitted. In select groups, the weight field is used to support unequal load sharing. If the switch does not support unequal load sharing, this field must be set to 1. The bucket’s share of the traffic processed by the group is defined by the individual bucket’s weight divided by the sum of the bucket weights in the group. If its weight is set to zero, the bucket is not used by the select group. When a port goes down, the change in traffic distribution is undefined. The precision by which a switch’s packet distribution should match bucket weights is undefined.
The OFPGBPT_WATCH_PORT and OFPGBPT_WATCH_GROUP properties use the following structure and fields:
/* Group bucket watch port or watch group property, for fast failover groups * only. */
struct ofp_group_bucket_prop_watch {
uint16_t type; /* OFPGBPT_WATCH_PORT or OFPGBPT_WATCH_GROUP. */
uint16_t length; /* 8. */
uint32_t watch; /* The port or the group. */
};
OFP_ASSERT(sizeof(struct ofp_group_bucket_prop_watch) == 8);
The watch field is respectively the port number or group identifier that is being watched by the bucket. The OFPGBPT_WATCH_PORT and OFPGBPT_WATCH_GROUP properties are only required for fast failover groups, and may be optionally implemented for other group types. These properties indicate the port and/or group whose liveness controls whether this bucket is a candidate for forwarding (see 6.7). If watch_port is OFPP_ANY, no port is being watched. If watch_group is OFPG_ANY, no group is being watched. For fast failover groups, the first bucket defined is the highest-priority bucket, and only the highest-priority live bucket is used (see 5.10.1).
The OFPGBPT_EXPERIMENTER property uses the following structure and fields:
/* Experimenter group bucket property */ struct ofp_group_bucket_prop_experimenter {
uint16_t type; /* OFPGBPT_EXPERIMENTER. */
uint16_t length; /* Length in bytes of this property. */
uint32_t experimenter; /* Experimenter ID which takes the same
form as in struct
ofp_experimenter_header. */
uint32_t exp_type; /* Experimenter defined. */
/* Followed by:
* - Exactly (length - 12) bytes containing the experimenter data, then
* - Exactly (length + 7)/8*8 - (length) (between 0 and 7)
* bytes of all-zero bytes */
The experimenter field is the Experimenter ID, which takes the same form as in the typical experi- menter structure (see 7.2.8).
7.3.4.3.2 Group Properties
The properties field in the OFPT_GROUP_MOD message is a list of group properties. The list of group property types that are currently defined are:
/* Group property types. */
enum ofp_group_prop_type {
OFPGPT_EXPERIMENTER = 0xFFFF, /* Experimenter defined. */
};
A property definition contains the property type, length, and any associated data:
/* Common header for all group properties. */ struct ofp_group_prop_header {
uint16_t type; /* One of OFPGPT_*. */
uint16_t length; /* Length in bytes of this property. */
};
OFP_ASSERT(sizeof(struct ofp_group_prop_header) == 4);
The OFPGPT_EXPERIMENTER property uses the following structure and fields:
/* Experimenter group property */ struct ofp_group_prop_experimenter {
uint16_t type; /* OFPGPT_EXPERIMENTER. */
uint16_t length; /* Length in bytes of this property. */
uint32_t experimenter; /* Experimenter ID which takes the same
form as in struct
ofp_experimenter_header. */
uint32_t exp_type; /* Experimenter defined. */
/* Followed by:
* - Exactly (length - 12) bytes containing the experimenter data, then
* - Exactly (length + 7)/8*8 - (length) (between 0 and 7)
* bytes of all-zero bytes */
uint32_t experimenter_data[0];
};
OFP_ASSERT(sizeof(struct ofp_group_prop_experimenter) == 12);
The experimenter field is the Experimenter ID, which takes the same form as in the typical experi- menter structure (see 7.2.8).