[ovs-dev] [PATCH] RFC: document map members as separate columns
Ben Pfaff
blp at nicira.com
Fri May 6 23:49:58 UTC 2011
The OVS configuration database now has numerous columns that contain fixed
key-value pairs. Currently there's no way to see these at a glance,
because they are not presented in the summary tables just before the
detailed descriptions.
This commit extends the XML format so that keys within a column can be
described individually, as a "proof of concept" of this idea. It also
changes the Open_vSwitch and Bridge tables in vswitch.xml to use this
format.
I'm looking for feedback on whether this change moves in the right
direction. I've posted a copy of the PDF file generated with this commit
at http://benpfaff.org/~blp/ovs-vswitchd.conf.db.5, so please let me know
what you think.
---
ovsdb/ovsdb-doc.in | 24 +++--
vswitchd/vswitch.xml | 288 ++++++++++++++++++++++++--------------------------
2 files changed, 150 insertions(+), 162 deletions(-)
diff --git a/ovsdb/ovsdb-doc.in b/ovsdb/ovsdb-doc.in
index 5ba4e71..c766f38 100755
--- a/ovsdb/ovsdb-doc.in
+++ b/ovsdb/ovsdb-doc.in
@@ -138,12 +138,6 @@ def typeAndConstraintsToNroff(column):
type += ", " + constraints
return type
-def columnToNroff(columnName, column, node):
- type = typeAndConstraintsToNroff(column)
- s = '.IP "\\fB%s\\fR: %s"\n' % (columnName, type)
- s += blockXmlToNroff(node.childNodes, '.IP') + "\n"
- return s
-
def columnGroupToNroff(table, groupXml):
introNodes = []
columnNodes = []
@@ -159,10 +153,18 @@ def columnGroupToNroff(table, groupXml):
body = ''
for node in columnNodes:
if node.tagName == 'column':
- columnName = node.attributes['name'].nodeValue
- column = table.columns[columnName]
- body += columnToNroff(columnName, column, node)
- summary += [('column', columnName, column)]
+ name = node.attributes['name'].nodeValue
+ column = table.columns[name]
+ if node.hasAttribute('key'):
+ key = node.attributes['key'].nodeValue
+ nameNroff = "%s : %s" % (name, key)
+ typeNroff = "optional %s" % column.type.value.toEnglish()
+ else:
+ nameNroff = name
+ typeNroff = typeAndConstraintsToNroff(column)
+ body += '.IP "\\fB%s\\fR: %s"\n' % (nameNroff, typeNroff)
+ body += blockXmlToNroff(node.childNodes, '.IP') + "\n"
+ summary += [('column', nameNroff, typeNroff)]
elif node.tagName == 'group':
title = node.attributes["title"].nodeValue
subSummary, subIntro, subBody = columnGroupToNroff(table, node)
@@ -179,7 +181,7 @@ def tableSummaryToNroff(summary, level=0):
if type == 'column':
s += "%s\\fB%s\\fR\tT{\n%s\nT}\n" % (
- r'\ \ ' * level, name, typeAndConstraintsToNroff(arg))
+ r'\ \ ' * level, name, arg)
else:
if s != "":
s += "_\n"
diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index 1db89dc..68f8a7b 100644
--- a/vswitchd/vswitch.xml
+++ b/vswitchd/vswitch.xml
@@ -68,135 +68,125 @@
</column>
<column name="statistics">
- <p>
Key-value pairs that report statistics about a system running an Open
vSwitch. These are updated periodically (currently, every 5
seconds). Key-value pairs that cannot be determined or that do not
apply to a platform are omitted.
- </p>
+ </column>
- <dl>
- <dt><code>cpu</code></dt>
- <dd>
- <p>
- Number of CPU processors, threads, or cores currently online and
- available to the operating system on which Open vSwitch is
- running, as an integer. This may be less than the number
- installed, if some are not online or if they are not available to
- the operating system.
- </p>
- <p>
- Open vSwitch userspace processes are not multithreaded, but the
- Linux kernel-based datapath is.
- </p>
- </dd>
+ <column name="statistics" key="cpu">
+ <p>
+ Number of CPU processors, threads, or cores currently online and
+ available to the operating system on which Open vSwitch is
+ running, as an integer. This may be less than the number
+ installed, if some are not online or if they are not available to
+ the operating system.
+ </p>
+ <p>
+ Open vSwitch userspace processes are not multithreaded, but the
+ Linux kernel-based datapath is.
+ </p>
+ </column>
- <dt><code>load_average</code></dt>
- <dd>
- <p>
- A comma-separated list of three floating-point numbers,
- representing the system load average over the last 1, 5, and 15
- minutes, respectively.
- </p>
- </dd>
+ <column name="statistics" key="load_average">
+ A comma-separated list of three floating-point numbers,
+ representing the system load average over the last 1, 5, and 15
+ minutes, respectively.
+ </column>
- <dt><code>memory</code></dt>
- <dd>
- <p>
- A comma-separated list of integers, each of which represents a
- quantity of memory in kilobytes that describes the operating
- system on which Open vSwitch is running. In respective order,
- these values are:
- </p>
+ <column name="statistics" key="memory">
+ <p>
+ A comma-separated list of integers, each of which represents a
+ quantity of memory in kilobytes that describes the operating
+ system on which Open vSwitch is running. In respective order,
+ these values are:
+ </p>
- <ol>
- <li>Total amount of RAM allocated to the OS.</li>
- <li>RAM allocated to the OS that is in use.</li>
- <li>RAM that can be flushed out to disk or otherwise discarded
- if that space is needed for another purpose. This number is
- necessarily less than or equal to the previous value.</li>
- <li>Total disk space allocated for swap.</li>
- <li>Swap space currently in use.</li>
- </ol>
+ <ol>
+ <li>Total amount of RAM allocated to the OS.</li>
+ <li>RAM allocated to the OS that is in use.</li>
+ <li>RAM that can be flushed out to disk or otherwise discarded
+ if that space is needed for another purpose. This number is
+ necessarily less than or equal to the previous value.</li>
+ <li>Total disk space allocated for swap.</li>
+ <li>Swap space currently in use.</li>
+ </ol>
- <p>
- On Linux, all five values can be determined and are included. On
- other operating systems, only the first two values can be
- determined, so the list will only have two values.
- </p>
- </dd>
+ <p>
+ On Linux, all five values can be determined and are included. On
+ other operating systems, only the first two values can be
+ determined, so the list will only have two values.
+ </p>
+ </column>
- <dt><code>process_</code><var>name</var></dt>
- <dd>
- <p>
- One such key-value pair will exist for each running Open vSwitch
- daemon process, with <var>name</var> replaced by the daemon's
- name (e.g. <code>process_ovs-vswitchd</code>). The value is a
- comma-separated list of integers. The integers represent the
- following, with memory measured in kilobytes and durations in
- milliseconds:
- </p>
+ <column name="statistics" key="process_NAME">
+ <p>
+ One such key-value pair, with <code>NAME</code> replaced by
+ a process name, will exist for each running Open vSwitch
+ daemon process, with <var>name</var> replaced by the
+ daemon's name (e.g. <code>process_ovs-vswitchd</code>). The
+ value is a comma-separated list of integers. The integers
+ represent the following, with memory measured in kilobytes
+ and durations in milliseconds:
+ </p>
- <ol>
- <li>The process's virtual memory size.</li>
- <li>The process's resident set size.</li>
- <li>The amount of user and system CPU time consumed by the
- process.</li>
- <li>The number of times that the process has crashed and been
- automatically restarted by the monitor.</li>
- <li>The duration since the process was started.</li>
- <li>The duration for which the process has been running.</li>
- </ol>
+ <ol>
+ <li>The process's virtual memory size.</li>
+ <li>The process's resident set size.</li>
+ <li>The amount of user and system CPU time consumed by the
+ process.</li>
+ <li>The number of times that the process has crashed and been
+ automatically restarted by the monitor.</li>
+ <li>The duration since the process was started.</li>
+ <li>The duration for which the process has been running.</li>
+ </ol>
- <p>
- The interpretation of some of these values depends on whether the
- process was started with the <option>--monitor</option>. If it
- was not, then the crash count will always be 0 and the two
- durations will always be the same. If <option>--monitor</option>
- was given, then the crash count may be positive; if it is, the
- latter duration is the amount of time since the most recent crash
- and restart.
- </p>
+ <p>
+ The interpretation of some of these values depends on whether the
+ process was started with the <option>--monitor</option>. If it
+ was not, then the crash count will always be 0 and the two
+ durations will always be the same. If <option>--monitor</option>
+ was given, then the crash count may be positive; if it is, the
+ latter duration is the amount of time since the most recent crash
+ and restart.
+ </p>
- <p>
- There will be one key-value pair for each file in Open vSwitch's
- ``run directory'' (usually <code>/var/run/openvswitch</code>)
- whose name ends in <code>.pid</code>, whose contents are a
- process ID, and which is locked by a running process. The
- <var>name</var> is taken from the pidfile's name.
- </p>
+ <p>
+ There will be one key-value pair for each file in Open vSwitch's
+ ``run directory'' (usually <code>/var/run/openvswitch</code>)
+ whose name ends in <code>.pid</code>, whose contents are a
+ process ID, and which is locked by a running process. The
+ <var>name</var> is taken from the pidfile's name.
+ </p>
- <p>
- Currently Open vSwitch is only able to obtain all of the above
- detail on Linux systems. On other systems, the same key-value
- pairs will be present but the values will always be the empty
- string.
- </p>
- </dd>
+ <p>
+ Currently Open vSwitch is only able to obtain all of the above
+ detail on Linux systems. On other systems, the same key-value
+ pairs will be present but the values will always be the empty
+ string.
+ </p>
+ </column>
- <dt><code>file_systems</code></dt>
- <dd>
- <p>
- A space-separated list of information on local, writable file
- systems. Each item in the list describes one file system and
- consists in turn of a comma-separated list of the following:
- </p>
+ <column name="statistics" key="file_systems">
+ <p>
+ A space-separated list of information on local, writable file
+ systems. Each item in the list describes one file system and
+ consists in turn of a comma-separated list of the following:
+ </p>
- <ol>
- <li>Mount point, e.g. <code>/</code> or <code>/var/log</code>.
- Any spaces or commas in the mount point are replaced by
- underscores.</li>
- <li>Total size, in kilobytes, as an integer.</li>
- <li>Amount of storage in use, in kilobytes, as an integer.</li>
- </ol>
+ <ol>
+ <li>Mount point, e.g. <code>/</code> or <code>/var/log</code>.
+ Any spaces or commas in the mount point are replaced by
+ underscores.</li>
+ <li>Total size, in kilobytes, as an integer.</li>
+ <li>Amount of storage in use, in kilobytes, as an integer.</li>
+ </ol>
- <p>
- This key-value pair is omitted if there are no local, writable
- file systems or if Open vSwitch cannot obtain the needed
- information.
- </p>
- </dd>
- </dl>
+ <p>
+ This key-value pair is omitted if there are no local, writable
+ file systems or if Open vSwitch cannot obtain the needed
+ information.
+ </p>
</column>
</group>
@@ -364,9 +354,12 @@
<column name="datapath_id">
Reports the OpenFlow datapath ID in use. Exactly 16 hex
- digits. (Setting this column will have no useful effect. Set
- <ref column="other_config"/>:<code>other-config</code>
- instead.)
+ digits.
+ </column>
+
+ <column name="other_config" key="datapath-id">
+ Exactly 16 hex digits to set the OpenFlow datapath ID to a specific
+ value. May not be all-zero.
</column>
</group>
@@ -396,31 +389,24 @@
</dl>
</column>
- <column name="other_config">
- Key-value pairs for configuring rarely used bridge
- features. The currently defined key-value pairs are:
- <dl>
- <dt><code>datapath-id</code></dt>
- <dd>Exactly 16 hex
- digits to set the OpenFlow datapath ID to a specific
- value. May not be all-zero.</dd>
- <dt><code>disable-in-band</code></dt>
- <dd>If set to <code>true</code>, disable in-band control on
- the bridge regardless of controller and manager settings.</dd>
- <dt><code>hwaddr</code></dt>
- <dd>An Ethernet address in the form
- <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
- to set the hardware address of the local port and influence the
- datapath ID.</dd>
- <dt><code>in-band-queue</code></dt>
- <dd>
- 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 QoS configured, or if the port does not have a queue
- with the specified ID, the default queue is used instead.
- </dd>
- </dl>
+ <column name="other_config" key="disable-in-band">
+ If set to <code>true</code>, disable in-band control on
+ the bridge regardless of controller and manager settings.
+ </column>
+
+ <column name="other_config" key="hwaddr">
+ An Ethernet address in the form
+ <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
+ to set the hardware address of the local port and influence the
+ datapath ID.
+ </column>
+
+ <column name="other_config" key="in-band-queue">
+ 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 QoS configured, or if the port does not have a queue
+ with the specified ID, the default queue is used instead.
</column>
</group>
</table>
--
1.7.4.4
More information about the dev
mailing list