From f9e5e5b383e523f2f92c91abf23f4fcd7f3b12a5 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Tue, 4 Oct 2011 10:31:59 -0700 Subject: [PATCH] vswitchd: Document constraints on keys. Suggested-by: Justin Pettit --- ovsdb/ovsdb-doc.in | 25 +++++++ vswitchd/vswitch.xml | 159 +++++++++++++++++++++++++------------------ 2 files changed, 119 insertions(+), 65 deletions(-) diff --git a/ovsdb/ovsdb-doc.in b/ovsdb/ovsdb-doc.in index 6f77702c3..5aac1ad1d 100755 --- a/ovsdb/ovsdb-doc.in +++ b/ovsdb/ovsdb-doc.in @@ -174,8 +174,33 @@ def columnGroupToNroff(table, groupXml): column = table.columns[name] if node.hasAttribute('key'): key = node.attributes['key'].nodeValue + if node.hasAttribute('type'): + type_string = node.attributes['type'].nodeValue + type_json = ovs.json.from_string(str(type_string)) + if type(type_json) in (str, unicode): + raise error.Error("%s %s:%s has invalid 'type': %s" + % (table.name, name, key, type_json)) + type_ = ovs.db.types.BaseType.from_json(type_json) + else: + type_ = column.type.value + nameNroff = "%s : %s" % (name, key) typeNroff = "optional %s" % column.type.value.toEnglish() + if (column.type.value.type == ovs.db.types.StringType and + type_.type == ovs.db.types.BooleanType): + # This is a little more explicit and helpful than + # "containing a boolean" + typeNroff += r", either \fBtrue\fR or \fBfalse\fR" + else: + if type_.type != column.type.value.type: + type_english = type_.toEnglish() + if type_english[0] in 'aeiou': + typeNroff += ", containing an %s" % type_english + else: + typeNroff += ", containing a %s" % type_english + constraints = type_.constraintsToEnglish(escapeNroffLiteral) + if constraints: + typeNroff += ", %s" % constraints else: nameNroff = name typeNroff = typeAndConstraintsToNroff(column) diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml index 560d22240..56d4a1c2a 100644 --- a/vswitchd/vswitch.xml +++ b/vswitchd/vswitch.xml @@ -104,14 +104,16 @@ omitted.

- + Statistics are disabled by default to avoid overhead in the common case when statistics gathering is not useful. Set this value to true to enable populating the column or to false to explicitly disable it. - +

Number of CPU processors, threads, or cores currently online and available to the operating system on which Open vSwitch is running, @@ -417,12 +419,14 @@ value. May not be all-zero. - + If set to true, disable in-band control on the bridge regardless of controller and manager settings. - + A queue ID as a nonnegative integer. This sets the OpenFlow queue ID that will be used by flows set up by in-band control on this bridge. If unset, or if the port used by an in-band control flow does not have @@ -458,7 +462,8 @@ datapath ID. - +

A number of flows as a nonnegative integer. This sets number of flows at which eviction from the kernel flow table will be triggered. @@ -471,7 +476,8 @@

- + Option to allow forwarding of BPDU frames when NORMAL action if invoked. Frames with reserved Ethernet addresses (e.g. STP BPDU) will be forwarded when this option is enabled. If the Open vSwitch bridge @@ -672,15 +678,16 @@ detects link failure.

- - The means used to detect link failures. Options are - carrier and miimon. Defaults to + + The means used to detect link failures. Defaults to carrier which uses each interface's carrier to detect failures. When set to miimon, will check for failures by polling each interface's MII. - + The interval, in milliseconds, between successive attempts to poll each interface's MII. Relevant only when is miimon. @@ -732,10 +739,11 @@ nonzero MAC address. - + The LACP system priority of this . In LACP negotiations, link status decisions are made by the system with the - numerically lower priority. Must be a number between 1 and 65535. + numerically lower priority. @@ -759,13 +767,16 @@

- - Treats LACP like a simple heartbeat protocol for link state - monitoring. Most features of the LACP protocol are disabled when - this mode is in use. + + Treat LACP like a simple heartbeat protocol for link state + monitoring. Most features of the LACP protocol are disabled + when this mode is in use. The default if not specified is + false. - + An integer hashed along with flows when choosing output slaves. When changed, all flows will be assigned different hash values possibly causing slave selection decisions to change. @@ -780,12 +791,12 @@ because LACP negotiation failed.

- + For an SLB bonded port, the number of milliseconds between successive attempts to rebalance the bond, that is, to move source MACs and their flows from one interface on the bond to another in an attempt - to keep usage of each interface roughly equal. The default is 10000 - (10 seconds), and the minimum is 1000 (1 second). + to keep usage of each interface roughly equal. @@ -1031,21 +1042,22 @@ system default, typically 64). Default is the system default TTL. - + Optional. If enabled, the Don't Fragment bit will be copied from the inner IP headers (those of the encapsulated traffic) to the outer (tunnel) headers. Default is disabled; set to true to enable. - + Optional. If enabled, the Don't Fragment bit will be set by default on tunnel headers if the df_inherit option is not set, or if the encapsulated packet is not IP. Default is enabled; set to false to disable. - + Optional. Enable tunnel path MTU discovery. If enabled ``ICMP Destination Unreachable - Fragmentation Needed'' messages will be generated for IPv4 packets with the DF bit set and IPv6 packets above @@ -1061,7 +1073,7 @@ Only gre interfaces support these options.

- + Enable caching of tunnel headers and the output path. This can lead to a significant performance increase without changing behavior. In general it should not be necessary to adjust this setting. However, @@ -1078,7 +1090,7 @@ these options.

- +

Optional. Compute GRE checksums on outgoing packets. Default is disabled, set to true to enable. Checksums present on @@ -1235,10 +1247,10 @@ internal interface such as a bridge port. - - Whether a carrier is detected on . Valid values are down and - up. + + Whether carrier is detected on . @@ -1432,13 +1444,15 @@ collected and written to this column. - + The interval, in milliseconds, between transmissions of CFM heartbeats. Three missed heartbeat receptions indicate a connectivity fault. Defaults to 1000. - + When true, the CFM module operates in extended mode. This causes it to use a nonstandard destination address to avoid conflicting with compliant implementations which may be running concurrently on the @@ -1460,8 +1474,9 @@ - - A positive integer using in stable bond mode to make slave + + Used in stable bond mode to make slave selection decisions. Allocating values consistently across interfaces participating in a bond will guarantee consistent slave selection @@ -1469,25 +1484,25 @@ stable bonding mode. - + The LACP port ID of this . Port IDs are used in LACP negotiations to identify individual ports - participating in a bond. Must be a number between 1 and - 65535. + participating in a bond. - + The LACP port priority of this . In LACP negotiations s with numerically lower - priorities are preferred for aggregation. Must be a number between 1 - and 65535. + priorities are preferred for aggregation. - + The LACP aggregation key of this . s with different aggregation keys may not be active - within a given at the same time. Must be a number - between 1 and 65535. + within a given at the same time. @@ -1580,7 +1595,7 @@ the following key-value pair:

- + Maximum rate shared by all queued traffic, in bit/s. Optional. If not specified, for physical interfaces, the default is the link rate. For other interfaces or if the link rate cannot be determined, the default @@ -1608,7 +1623,8 @@ table="QoS" column="type"/> of min-rate.

- + Minimum guaranteed bandwidth, in bit/s. Required. The floor value is 1500 bytes/s (12,000 bit/s). @@ -1620,30 +1636,33 @@ table="QoS" column="type"/> of linux-htb.

- + Minimum guaranteed bandwidth, in bit/s. - + Maximum allowed bandwidth, in bit/s. Optional. If specified, the queue's rate will not be allowed to exceed the specified value, even if excess bandwidth is available. If unspecified, defaults to no limit. - + Burst size, in bits. This is the maximum amount of ``credits'' that a queue can accumulate while it is idle. Optional. Details of the linux-htb implementation require a minimum burst size, so a too-small burst will be silently ignored. - - A nonnegative 32-bit integer. Defaults to 0 if unspecified. A queue - with a smaller priority will receive all the excess - bandwidth that it can use before a queue with a larger value receives - any. Specific priority values are unimportant; only relative ordering - matters. + + A queue with a smaller priority will receive all the + excess bandwidth that it can use before a queue with a larger value + receives any. Specific priority values are unimportant; only relative + ordering matters. Defaults to 0 if unspecified. @@ -1653,11 +1672,13 @@ table="QoS" column="type"/> of linux-hfsc.

- + Minimum guaranteed bandwidth, in bit/s. - + Maximum allowed bandwidth, in bit/s. Optional. If specified, the queue's rate will not be allowed to exceed the specified value, even if excess bandwidth is available. If unspecified, defaults to no @@ -2040,7 +2061,8 @@ false otherwise. - +

The level of authority this controller has on the associated bridge. Possible values are:

@@ -2066,9 +2088,10 @@ will exist only if an error has occurred. - +

- The state of the connection to the controller. Possible values are: + The state of the connection to the controller:

VOID
@@ -2092,13 +2115,15 @@

- + The amount of time since this controller last successfully connected to the switch (in seconds). Value is empty if controller has never successfully connected. - + The amount of time since this controller last disconnected from the switch (in seconds). Value is empty if controller has never disconnected. @@ -2254,9 +2279,10 @@ will exist only if an error has occurred. - +

- The state of the connection to the manager. Possible values are: + The state of the connection to the manager:

VOID
@@ -2280,13 +2306,15 @@

- + The amount of time since this manager last successfully connected to the database (in seconds). Value is empty if manager has never successfully connected. - + The amount of time since this manager last disconnected from the database (in seconds). Value is empty if manager has never disconnected. @@ -2309,7 +2337,8 @@ stolen from this connection. - +

When specifies a connection method that listens for inbound connections (e.g. ptcp: or -- 2.43.0