lib/ofp-prop.h

   1 /*
   2  * Copyright (c) 2014, 2015, 2016 Nicira, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef OFP_PROP_H
  18 #define OFP_PROP_H 1
  19
  20 /* OpenFlow 1.3+ property support
  21  * ==============================
  22  *
  23  * Several OpenFlow 1.3+ messages use type-length-value (TLV) properties that
  24  * take the common form shown by "struct ofp_prop_header".  This module
  25  * provides support for serializing and deserializing properties in this
  26  * format.
  27  *
  28  *
  29  * Property types
  30  * --------------
  31  *
  32  * This module uses uint64_t values to identify property types
  33  *
  34  *     - OpenFlow assigns 16-bit type values to its own standardized
  35  *       properties.  ofpprop uses these values directly in uint64_t.
  36  *
  37  *       The 16-bit value 0xffff (and for some kinds of properties  0xfffe) is
  38  *       reserved as a kind of escape to introduce an "experimenter" property
  39  *       (see below).
  40  *
  41  *     - Vendor-specific "experimenter" properties have a 32-bit "experimenter
  42  *       ID" (generally an Ethernet OUI) and a 32-bit experimenter-defined
  43  *       "exp_type".  ofpprop encodes these with the experimenter ID in the
  44  *       high 32 bits and exp_type in the low 32 bits.  (All existing
  45  *       experimenter IDs are nonzero, so this is unambiguous.)  Use
  46  *       OFPPROP_EXP to encode these property types.
  47  */
  48
  49 #include <stdbool.h>
  50 #include <stddef.h>
  51 #include <stdint.h>
  52 #include "ofp-errors.h"
  53 #include "openvswitch/types.h"
  54
  55 struct ofpbuf;
  56 struct uuid;
  57 struct vlog_module;
  58
  59 /* Given an OpenFlow experimenter ID (e.g. NX_VENDOR_ID) 'exp_id' and type
  60  * 'exp_type', yields the code that ofpprop_pull() would use to identify the
  61  * given experimenter property. */
  62 #define OFPPROP_EXP(EXP_ID, EXP_TYPE) \
  63     (((uint64_t) (EXP_ID) << 32) | (EXP_TYPE))
  64
  65 /* Returns true if 'type' represents an experimenter property type,
  66  * false if it represents a standard property type.*/
  67 static inline bool
  68 ofpprop_is_experimenter(uint64_t type)
  69 {
  70     return type > UINT16_MAX;
  71 }
  72
  73 /* Deserializing properties.  */
  74 enum ofperr ofpprop_pull__(struct ofpbuf *msg, struct ofpbuf *property,
  75                            unsigned int alignment, unsigned int min_exp,
  76                            uint64_t *typep);
  77 enum ofperr ofpprop_pull(struct ofpbuf *msg, struct ofpbuf *property,
  78                          uint64_t *typep);
  79
  80 enum ofperr ofpprop_parse_be16(const struct ofpbuf *, ovs_be16 *value);
  81 enum ofperr ofpprop_parse_be32(const struct ofpbuf *, ovs_be32 *value);
  82 enum ofperr ofpprop_parse_be64(const struct ofpbuf *, ovs_be64 *value);
  83 enum ofperr ofpprop_parse_u8(const struct ofpbuf *, uint8_t *value);
  84 enum ofperr ofpprop_parse_u16(const struct ofpbuf *, uint16_t *value);
  85 enum ofperr ofpprop_parse_u32(const struct ofpbuf *, uint32_t *value);
  86 enum ofperr ofpprop_parse_u64(const struct ofpbuf *, uint64_t *value);
  87 enum ofperr ofpprop_parse_uuid(const struct ofpbuf *, struct uuid *);
  88 enum ofperr ofpprop_parse_nested(const struct ofpbuf *, struct ofpbuf *);
  89
  90 /* Serializing properties. */
  91 void ofpprop_put(struct ofpbuf *, uint64_t type,
  92                  const void *value, size_t len);
  93 void *ofpprop_put_zeros(struct ofpbuf *, uint64_t type, size_t len);
  94 void ofpprop_put_be16(struct ofpbuf *, uint64_t type, ovs_be16 value);
  95 void ofpprop_put_be32(struct ofpbuf *, uint64_t type, ovs_be32 value);
  96 void ofpprop_put_be64(struct ofpbuf *, uint64_t type, ovs_be64 value);
  97 void ofpprop_put_u8(struct ofpbuf *, uint64_t type, uint8_t value);
  98 void ofpprop_put_u16(struct ofpbuf *, uint64_t type, uint16_t value);
  99 void ofpprop_put_u32(struct ofpbuf *, uint64_t type, uint32_t value);
 100 void ofpprop_put_u64(struct ofpbuf *, uint64_t type, uint64_t value);
 101 void ofpprop_put_bitmap(struct ofpbuf *, uint64_t type, uint64_t bitmap);
 102 void ofpprop_put_flag(struct ofpbuf *, uint64_t type);
 103 void ofpprop_put_uuid(struct ofpbuf *, uint64_t type, const struct uuid *);
 104 void ofpprop_put_nested(struct ofpbuf *, uint64_t type, const struct ofpbuf *);
 105
 106 size_t ofpprop_start(struct ofpbuf *, uint64_t type);
 107 void ofpprop_end(struct ofpbuf *, size_t start_ofs);
 108
 109 size_t ofpprop_start_nested(struct ofpbuf *, uint64_t type);
 110
 111 /* Logging errors while deserializing properties.
 112  *
 113  * The attitude that a piece of code should take when it deserializes an
 114  * unknown property type depends on the code in question:
 115  *
 116  *    - In a "loose" context (with LOOSE set to true), that is, where the code
 117  *      is parsing the property to find out about the state or the capabilities
 118  *      of some piece of the system, generally an unknown property type is not
 119  *      a big deal, because it only means that there is additional information
 120  *      that the receiver does not understand.
 121  *
 122  *    - In a "strict" context (with LOOSE set to false), that is, where the
 123  *      code is parsing the property to change the state or configuration of a
 124  *      part of the system, generally an unknown property type is an error,
 125  *      because it means that the receiver is being asked to configure the
 126  *      system in some way it doesn't understand.
 127  *
 128  * Given LOOSE, this macro automatically logs chooses an appropriate log
 129  * level. */
 130 #define OFPPROP_LOG(RL, LOOSE, ...)                         \
 131     VLOG_RL(RL, (LOOSE) ? VLL_DBG : VLL_WARN, __VA_ARGS__)
 132
 133 enum ofperr ofpprop_unknown(struct vlog_module *, bool loose, const char *msg,
 134                             uint64_t type);
 135 #define OFPPROP_UNKNOWN(LOOSE, MSG, TYPE) \
 136     ofpprop_unknown(&this_module, LOOSE, MSG, TYPE)
 137
 138 #endif /* ofp-prop.h */