# HG changeset patch
# User Rob Hoes <rob.hoes@xxxxxxxxxx>
[ocamldoc] Completed docs for all networking modules in xapi
Signed-off-by: Rob Hoes <rob.hoes@xxxxxxxxxx>
diff -r db3f4cda7bae ocaml/doc/ocamldoc.js
--- a/ocaml/doc/ocamldoc.js Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/doc/ocamldoc.js Wed Dec 02 15:15:38 2009 +0000
@@ -144,6 +144,16 @@
return out;
}
+function transform_type(t)
+{
+ params = t.split('->');
+ for (i in params) {
+ params[i] = '<span class="type">' + params[i] + '</span>';
+ }
+ html = params.join('<span class="arrow">\u2192</span>');
+ return html;
+}
+
function value(v, n)
{
l = v.name.split('.');
@@ -163,14 +173,14 @@
html += '<span class="empty">to be completed!</span></div>';
html += '<table class="field-table">';
- html += '<tr><td width="100px"><span
class="field-head">Type:</span></td><td>' + v.type + '</td></tr>';
+ html += '<tr><td width="100px"><span
class="field-head">Type:</span></td><td>' + transform_type(v.type) +
'</td></tr>';
html += '<tr id="' + name + '_params" style="display: none"><td
width="100px"><span class="field-head">Parameters:</span></td><td>';
html += '<table>';
for (c in v.params) {
n = v.params[c].name;
html += '<tr><td width="20%" style="padding: 0 0 .2em">' + (n
== "" ? '(no name)' : v.params[c].name) + '</td>';
- html += '<td style="padding: 0 0 .2em">' + v.params[c].type +
'</td></tr>';
+ html += '<td style="padding: 0 0 .2em">' +
transform_type(v.params[c].type) + '</td></tr>';
}
html += '</table>';
html += '</td></tr>';
@@ -216,7 +226,7 @@
html += '<tr><th
width="25%">Constructor</th><th>Type</th><th>Description</th></tr>';
for (c in cons) {
html += '<tr><td>' + cons[c].name + '</td>'
- html += '<td>' + cons[c].type + '</td>'
+ html += '<td>' + transform_type(cons[c].type) + '</td>'
if (cons[c].description != undefined)
html += '<td>' + transform_links(cons[c].description) +
'</td>';
else
@@ -234,7 +244,7 @@
html += '<tr><th width="25%">Field</th><th
width="20%">Type</th><th>Description</th></tr>';
for (c in fields) {
html += '<tr><td>' + fields[c].name + '</td>'
- html += '<td>' + fields[c].type + '</td>'
+ html += '<td>' + transform_type(fields[c].type) + '</td>'
if (fields[c].description != undefined)
html += '<td>' + transform_links(fields[c].description)
+ '</td>';
else
@@ -305,7 +315,7 @@
else
html += '<span class="empty">to be completed!</span></div>';
html += '<table class="field-table">';
- html += '<tr><td width="100px"><span
class="field-head">Type:</span></td><td>' + v.type + '</td></tr>';
+ html += '<tr><td width="100px"><span
class="field-head">Type:</span></td><td>' + transform_type(v.type) +
'</td></tr>';
html += '<tr><td></td><td><input type="button" class="small-button"
value="details" onclick="location=\'index.html?c=' + component + '&m=' + v.name
+ '\'" /></td></tr>';
html += '</table>';
diff -r db3f4cda7bae ocaml/doc/odoc_json.ml
--- a/ocaml/doc/odoc_json.ml Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/doc/odoc_json.ml Wed Dec 02 15:15:38 2009 +0000
@@ -239,7 +239,7 @@
method t_of_text_element = function
| Odoc_info.Raw s -> Leaf (remove_asterisks s)
- | Odoc_info.Code s -> node "span" ~atts:["class", "code"] [Leaf
(remove_asterisks s)]
+ | Odoc_info.Code s -> node "tt" [Leaf (remove_asterisks s)]
| Odoc_info.CodePre s -> node "span" ~atts:["class", "codepre"] [Leaf
(remove_asterisks s)]
| Odoc_info.Verbatim s -> node "span" ~atts:["class", "verbatim"] [Leaf
(remove_asterisks s)]
| Odoc_info.Bold t -> node "b" (self#t_of_text t)
diff -r db3f4cda7bae ocaml/doc/style.css
--- a/ocaml/doc/style.css Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/doc/style.css Wed Dec 02 15:15:38 2009 +0000
@@ -17,7 +17,7 @@
margin: 0;
border: 0;
font: 80% helvetica, arial, sans-serif;
- font-weight: normal;
+ font-weight: normal;
line-height: 130%;
background: white;
color : black;
@@ -66,6 +66,7 @@
background-color: #ffffdd;
padding: 1.5em 1em;
margin: 0 22em 0 .5em;
+ line-height: 150%;
}
#sidebar {
@@ -206,8 +207,8 @@
background-color: orange;
}
-.code {
- font-family: Courier New, monospace;
+tt {
+ font:1.2em monospace
}
.comment {
@@ -261,3 +262,12 @@
vertical-align: top;
}
+.type {
+// font:1.2em monospace;
+}
+
+.arrow {
+ font-size: 2em;
+ color: #cc6600;
+}
+
diff -r db3f4cda7bae ocaml/xapi/create_networks.ml
--- a/ocaml/xapi/create_networks.ml Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/xapi/create_networks.ml Wed Dec 02 15:15:38 2009 +0000
@@ -10,9 +10,6 @@
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
- *)
-(** Built-in networks.
- * @group Networking
*)
module D=Debug.Debugger(struct let name="xapi" end)
diff -r db3f4cda7bae ocaml/xapi/create_networks.mli
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ocaml/xapi/create_networks.mli Wed Dec 02 15:15:38 2009 +0000
@@ -0,0 +1,19 @@
+(*
+ * Copyright (C) 2006-2009 Citrix Systems Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation; version 2.1 only. with the special
+ * exception on linking described in file LICENSE.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Lesser General Public License for more details.
+ *)
+(** Built-in networks.
+ * @group Networking
+ *)
+
+(** Create a guest installer network (if it does not exist yet). *)
+val create_networks_localhost : unit -> unit
diff -r db3f4cda7bae ocaml/xapi/xapi_bond.mli
--- a/ocaml/xapi/xapi_bond.mli Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/xapi/xapi_bond.mli Wed Dec 02 15:15:38 2009 +0000
@@ -12,8 +12,18 @@
* GNU Lesser General Public License for more details.
*)
(** Module that defines API functions for Bond objects
- * @group XenAPI functions
+ * @group Networking
*)
+
+(**
+A host can have multiple network interfaces. These can be used to physically
separate networks. However, multiple interfaces can also be {i bonded} together
to form a single high-throughput interface.
+{ul
+{- The PIFs that are bonded together are called {i slaves}.}
+{- The datamodel has a {i Bond} object that joins the slaves.}
+{- The bond is used through a {i master} PIF, which is also associated with
the Bond object. The master PIF is a special PIF that does not directly
represent a physical interface. The master PIF is associated with a Network,
and used as a regular PIF.}
+{- Bond slaves should never be used directly: they are not allowed to be
plugged. Hence, they are not connected to bridges and therefore not accessible.}
+}
+*)
(** Create a PIF to represent the bond master and a Bond record to represent
the bond.
* Return a reference to the bond record. The given network must not have any
local
diff -r db3f4cda7bae ocaml/xapi/xapi_mgmt_iface.mli
--- a/ocaml/xapi/xapi_mgmt_iface.mli Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/xapi/xapi_mgmt_iface.mli Wed Dec 02 15:15:38 2009 +0000
@@ -11,8 +11,8 @@
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*)
-(**
- * @group Networking
+(** Controlling the management interface.
+ * @group Networking
*)
(** Block until an IP address appears on the management interface *)
diff -r db3f4cda7bae ocaml/xapi/xapi_network.mli
--- a/ocaml/xapi/xapi_network.mli Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/xapi/xapi_network.mli Wed Dec 02 15:15:38 2009 +0000
@@ -12,8 +12,25 @@
* GNU Lesser General Public License for more details.
*)
(** Module that defines API functions for Network objects
- * @group XenAPI functions
+ * @group Networking
*)
+
+(**
+{i Network} objects are used to interconnect multiple VIFs and PIFs within a
resource pool.
+{ul
+{- PIFs and VIFs can be attached to a Network.}
+{- A Network that spans multiple hosts has physical links (cables +
hub/switch) between the PIFs that are attached to it.}
+{- Two VMs are connected iff: both have a VIF on the same Network AND (they
are on the same host OR their hosts both have a PIF on this Network).}
+{- Within the boundaries of a host, a Network is represented by a bridge if it
is brought up. A Network spanning multiple hosts has a bridge on each host.}
+{- PIFs on a single host are all on different networks, and each PIF is
associated to exactly one network. Hence, all PIFs on a network are on
different hosts.}
+{- A Network is called {i internal} if there are no PIFs associated with it.
VMs that have VIFs on such a network, which is necessarily confined to a single
host to be of use, are still able to communicate with each other.}
+{- A Network is associated with any number of VIFs, and zero or one PIFs per
host.}
+{- Networks for physical interfaces are created automatically (when the PIF is
created). The name of the bridge for such a network is derived from the device
name of the interface. E.g. interface [eth0] is always associated with bridge
[xenbr0].}
+{- When a PIF or a VIF on a network is plugged, also the associated bridge is
ensured to be up.}
+{- There is a special case {i guest installer network}, which is used by the
internal p2v tool. It is not associated with a PIF, but does some "special
magic stuff". It will probably disappear eventually together with the p2v
stuff, which is not really used anyway.}
+}
+Note: It is currently assumed that all PIFs that are associated with a certain
Network are physically connected, but this is not checked or enforced anywhere.
This means that if a system admin connects the cables in a wrong way, things
may be broken. Moreover, if two PIFs are of different Networks, this does not
mean that they are not on the same physical network. Ideally, Networks objects
should be constructed and maintained automatically by xapi based the actual
physical connections.
+*)
(** Instantiate the bridge associated to this network on the localhost, and
bring
up the PIFs on the localhost that are on this network, provided it wouldn't
@@ -34,6 +51,7 @@
val attach :
__context:Context.t -> network:[ `network ] Ref.t -> host:'a -> unit
+(** Detaches all bridges on a host *)
val network_gc_func : unit -> unit
(** Internal fn used by slave to create new network records on master during
pool join operation *)
diff -r db3f4cda7bae ocaml/xapi/xapi_network_attach_helpers.ml
--- a/ocaml/xapi/xapi_network_attach_helpers.ml Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/xapi/xapi_network_attach_helpers.ml Wed Dec 02 15:15:38 2009 +0000
@@ -11,14 +11,10 @@
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*)
-(** Assertion helpers used when attaching a network
- * @group Networking
- *)
module D=Debug.Debugger(struct let name="xapi" end)
open D
-(** Raises an exception if the network has VIFs in use on the host *)
let assert_network_has_no_vifs_in_use_on_me ~__context ~host ~network =
(* Check if there are any active VIFs on VMs resident on me *)
let vifs = Db.Network.get_VIFs ~__context ~self:network in
@@ -34,23 +30,11 @@
end)
vifs
-(** Raises an exception when the [disallow_unplug] flag is set *)
(* nice triple negative ;) *)
let assert_pif_disallow_unplug_not_set ~__context pif =
if (Db.PIF.get_disallow_unplug ~__context ~self:pif) then
raise (Api_errors.Server_error(Api_errors.pif_does_not_allow_unplug, [
Ref.string_of pif ]))
-(** Raises an exception if the network cannot be attached.
- * Returns a list of {i shafted} PIFs and a list of {i local} PIFs.
-
- * Cannot attach this network if it has a PIF AND this PIF 'shafts'
- * some other PIF which is attached to a network which is 'in-use'.
- * Bringing a bond master up, or a VLAN on a bond, shafts the bond slaves;
- * similarly, bringing a bond slave up shafts its master + that master's VLANs;
- * but sibling slaves don't shaft each other.
- *
- * There should be only one local PIF by construction.
- *)
let assert_can_attach_network_on_host ~__context ~self ~host
~overide_management_if_check =
(* Cannot attach this network if it has a PIF AND this PIF 'shafts'
some other PIF which is attached to a network which is 'in-use'.
diff -r db3f4cda7bae ocaml/xapi/xapi_network_attach_helpers.mli
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ocaml/xapi/xapi_network_attach_helpers.mli Wed Dec 02 15:15:38
2009 +0000
@@ -0,0 +1,43 @@
+(*
+ * Copyright (C) 2006-2009 Citrix Systems Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation; version 2.1 only. with the special
+ * exception on linking described in file LICENSE.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Lesser General Public License for more details.
+ *)
+(** Assertion helpers used when attaching a network
+ * @group Networking
+ *)
+
+(** Raises an exception if the network has VIFs in use on the host *)
+val assert_network_has_no_vifs_in_use_on_me :
+ __context:Context.t ->
+ host:[ `host ] Ref.t -> network:[ `network ] Ref.t -> unit
+
+(** Raises an exception when the [disallow_unplug] flag is set *)
+val assert_pif_disallow_unplug_not_set :
+ __context:Context.t -> [ `PIF ] Ref.t -> unit
+
+(** Raises an exception if the network cannot be attached.
+ * Returns a list of {i shafted} PIFs and a list of {i local} PIFs.
+
+ * Cannot attach this network if it has a PIF AND this PIF 'shafts'
+ * some other PIF which is attached to a network which is 'in-use'.
+ * Bringing a bond master up, or a VLAN on a bond, shafts the bond slaves;
+ * similarly, bringing a bond slave up shafts its master + that master's VLANs;
+ * but sibling slaves don't shaft each other.
+ *
+ * There should be only one local PIF by construction.
+ *)
+val assert_can_attach_network_on_host :
+ __context:Context.t ->
+ self:[ `network ] Ref.t ->
+ host:[ `host ] Ref.t ->
+ overide_management_if_check:bool ->
+ [ `PIF ] Ref.t list * [ `PIF ] Ref.t list
diff -r db3f4cda7bae ocaml/xapi/xapi_network_real.ml
--- a/ocaml/xapi/xapi_network_real.ml Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/xapi/xapi_network_real.ml Wed Dec 02 15:15:38 2009 +0000
@@ -10,9 +10,6 @@
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
- *)
-(** 'Real' network backend
- * @group Networking
*)
module D=Debug.Debugger(struct let name="xapi" end)
diff -r db3f4cda7bae ocaml/xapi/xapi_network_real.mli
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ocaml/xapi/xapi_network_real.mli Wed Dec 02 15:15:38 2009 +0000
@@ -0,0 +1,23 @@
+(*
+ * Copyright (C) 2006-2009 Citrix Systems Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation; version 2.1 only. with the special
+ * exception on linking described in file LICENSE.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Lesser General Public License for more details.
+ *)
+(** 'Real' network backend
+ * @group Networking
+ *)
+
+(** Set-up a guest installer network [bridge]. *)
+val setup_guest_installer_network :
+ __context:Context.t -> string -> (string * string) list -> unit
+
+(** Try to shut down the guest installer network [bridge]. *)
+val maybe_shutdown_guest_installer_network : string -> unit
diff -r db3f4cda7bae ocaml/xapi/xapi_network_types.ml
--- a/ocaml/xapi/xapi_network_types.ml Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/xapi/xapi_network_types.ml Wed Dec 02 15:15:38 2009 +0000
@@ -11,16 +11,17 @@
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*)
-(** Common code between the fake and real servers for dealing with Networks
+(** Common code between the fake and real servers for dealing with Networks.
* @group Networking
*)
-module D=Debug.Debugger(struct let name="xapi" end)
-open D
-
+(** Helper type *)
type backend =
{
attach: __context:Context.t -> self:API.ref_network -> unit;
+ (** Function to attach a Network *)
+
detach: string -> unit;
+ (** Function to detach a Network *)
}
diff -r db3f4cda7bae ocaml/xapi/xapi_pif.mli
--- a/ocaml/xapi/xapi_pif.mli Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/xapi/xapi_pif.mli Wed Dec 02 15:15:38 2009 +0000
@@ -12,8 +12,34 @@
* GNU Lesser General Public License for more details.
*)
(** Module that defines API functions for PIF objects
- * @group XenAPI functions
+ * @group Networking
*)
+
+(**
+A {i PIF} object in the datamodel represents a network interface and contains
relevant information about it.
+{ul
+{- There are three types of PIFs. A PIF can represent...
+ {ol
+ {- A network-interface card. For each physical interface there should
be a PIF. Such a PIF has [PIF.physical = true].}
+ {- A bond-master: a higher-level PIF representing the combination of
multiple PIFs. Such a PIF has [PIF.bond_master_of] set to the Bond object.}
+ {- A VLAN interface: a higher-level PIF (called the {i untagged} PIF,
or {i VLAN master} that tags its outgoing traffic before sending it out to the
underlying physical interface (the {i tagged} PIF, or {i VLAN slave}).}
+ }}
+{- PIF objects are typically created automatically on first boot. There is
also a [PIF.scan] API call to automatically discover any new network interfaces
and create the necessary objects in the database.}
+{- A PIF is always accompanied by a Network object (see below) that associates
the interface with a bridge.}
+{- A PIF can be {i plugged} or {i unplugged}, also known as {i attached} or {i
unattached} respectively.
+ {ul
+ {- Plugging a PIF is also referred to as {i bringing up} the PIF, while
unplugging is {i bringing down} a PIF.}
+ {- After plugging a PIF, any underlying network devices (bridges,
bonds, VLANs, physical interfaces) are configured, such that the interface can
be used. Unplugging will clean up any underlying network devices {i that are
not used anymore}.}
+ {- No PIFs are harmed during unplugging, nor does unplugging have
anything to do with pulling out cables.}
+ {- A PIF that is plugged has [PIF.currently_attached] set to [true], a
PIF that is unplugged has this field set to [false].}
+ }}
+{- A PIF can be specialised to be...
+ {ul
+ {- the {i management interface}, which is the interface used by xapi
for communication between hosts in a pool and XenAPI clients; this PIF has
[PIF.management = true]; the inventory file stores the name of the bridge the
the management interface is on (this is where the management interface is
ultimately defined);}
+ {- dedicated to a specific function, especially for storage traffic (in
this case, the [disallow-unplug] field on the PIF is set to [true], and an
other-config flag is set); this does not seem to be enforced, but only used by
XC.}
+ }}
+}
+*)
(** {2 API functions} *)
@@ -196,14 +222,26 @@
(** {2 Assertion Helper Functions} *)
+(** Ensure the PIF is not a bond slave or master. *)
val assert_not_in_bond : __context:Context.t -> self:[ `PIF ] Ref.t -> unit
+
+(** Ensure the PIF is not a VLAN slave or master. *)
val assert_no_vlans : __context:Context.t -> self:[ `PIF ] Ref.t -> unit
+
+(** Ensure the PIF is not the management interface. *)
val assert_not_management_pif :
__context:Context.t -> self:[ `PIF ] Ref.t -> unit
+
+(** Ensure the PIF is not the management interface if the host is a pool
slave. *)
val assert_not_slave_management_pif :
__context:Context.t -> self:[ `PIF ] Ref.t -> unit
+
+(** Ensure neither HA nor the general redo-log are enabled. *)
val assert_no_protection_enabled :
__context:Context.t -> self:[ `PIF ] Ref.t -> unit
+
+(** Ensure the Network attached to the given PIF has not VIFs on it
+ * belonging to VMs that are protected by HA. *)
val abort_if_network_attached_to_protected_vms :
__context:Context.t -> self:[ `PIF ] Ref.t -> unit
diff -r db3f4cda7bae ocaml/xapi/xapi_vif.mli
--- a/ocaml/xapi/xapi_vif.mli Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/xapi/xapi_vif.mli Wed Dec 02 15:15:38 2009 +0000
@@ -12,8 +12,22 @@
* GNU Lesser General Public License for more details.
*)
(** Module that defines API functions for VIF objects
- * @group XenAPI functions
+ * @group Networking
*)
+
+(**
+A {i VIF} object in the datamodel represents a virtual interface.
+{ul
+{- A VIF is used by a VM, and appears to a VM as a real network interface. A
VIF has a MAC address.}
+{- The [VIF.currently_attached] field reflects whether a virtual interface is
currently {i plugged} into its VM, meaning it is visible to the VM.
+ {ul
+ {- A VIF cannot be [currently_attached] when its VM is halted.}
+ {- When a VM starts up, its VIFs are automatically attached; when a VM
shuts down, VIFs become detached.}
+ {- A VIF can be hot-plugged or hot-unplugged if its VM is running {i
and} the VM has PV-drivers installed.}
+ }}
+{- A VIF can be attached to a Network (bridge) to connect it to a PIF
(physical interface).}
+}
+*)
(** {2 API functions} *)
@@ -40,13 +54,13 @@
(** {2 Helper Functions} *)
+(** Throw error if the given operation is not in the list of allowed
operations.
+ * Implemented by {!Xapi_vif_helpers.assert_operation_valid} *)
val assert_operation_valid :
__context:Context.t -> self:[ `VIF ] Ref.t -> op:API.vif_operations -> unit
+
+(** Update the [PIF.allowed_operations] field.
+ * Implemented by {!Xapi_vif_helpers.update_allowed_operations} *)
val update_allowed_operations :
__context:Context.t -> self:[ `VIF ] Ref.t -> unit
-val dynamic_create :
- __context:Context.t -> vif:API.ref_VIF -> Locking_helpers.token -> unit
-val destroy_vif :
- __context:Context.t -> xs:Xs.xsh -> 'a -> [ `VIF ] Ref.t -> 'b -> unit
-val dynamic_destroy :
- __context:Context.t -> vif:[ `VIF ] Ref.t -> Locking_helpers.token -> unit
+
diff -r db3f4cda7bae ocaml/xapi/xapi_vif_helpers.ml
--- a/ocaml/xapi/xapi_vif_helpers.ml Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/xapi/xapi_vif_helpers.ml Wed Dec 02 15:15:38 2009 +0000
@@ -10,9 +10,6 @@
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
- *)
-(** Common code between the fake and real servers for dealing with VIFs
- * @group Networking
*)
open Stringext
@@ -130,7 +127,7 @@
(** Check if the device string has the right form *)
let valid_device dev = try ignore(int_of_string dev); true with _ -> false
-(** Type of a function which does the actual hotplug/ hotunplug *)
+(* Type of a function which does the actual hotplug/ hotunplug *)
type do_hotplug_fn = __context:Context.t -> vif:API.ref_VIF ->
Locking_helpers.token -> unit
let plug (dynamic_create: do_hotplug_fn) ~__context ~self =
@@ -283,3 +280,4 @@
~other_config:all.API.vIF_other_config
~qos_algorithm_type:all.API.vIF_qos_algorithm_type
~qos_algorithm_params:all.API.vIF_qos_algorithm_params
+
diff -r db3f4cda7bae ocaml/xapi/xapi_vif_helpers.mli
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ocaml/xapi/xapi_vif_helpers.mli Wed Dec 02 15:15:38 2009 +0000
@@ -0,0 +1,67 @@
+(*
+ * Copyright (C) 2006-2009 Citrix Systems Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation; version 2.1 only. with the special
+ * exception on linking described in file LICENSE.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Lesser General Public License for more details.
+ *)
+(** Common code between the fake and real servers for dealing with VIFs.
+ * @group Networking
+ *)
+
+(** Throw error if the given operation is not in the list of allowed
operations. *)
+val assert_operation_valid :
+ __context:Context.t -> self:[ `VIF ] Ref.t -> op:API.vif_operations -> unit
+
+(** Update the [PIF.allowed_operations] field. *)
+val update_allowed_operations :
+ __context:Context.t -> self:[ `VIF ] Ref.t -> unit
+
+(** Cancel all current operations. *)
+val cancel_tasks :
+ __context:Context.t ->
+ self:[ `VIF ] Ref.t ->
+ all_tasks_in_db:'a Ref.t list -> task_ids:string list -> unit
+
+(** Empty the [PIF.current_operations] field. *)
+val clear_current_operations :
+ __context:Context.t -> self:[ `VIF ] Ref.t -> unit
+
+(** Type of a function which does the actual hotplug/hotunplug. *)
+type do_hotplug_fn =
+ __context:Context.t -> vif:API.ref_VIF -> Locking_helpers.token -> unit
+
+(** Hotplug the VIF, dynamically attaching it to the running VM. *)
+val plug : do_hotplug_fn -> __context:Context.t -> self:API.ref_VIF -> unit
+
+(** Hot-unplug the VIF, dynamically unattaching it to the running VM. *)
+val unplug : do_hotplug_fn -> __context:Context.t -> self:API.ref_VIF -> unit
+
+(** Create a VIF object in the database. *)
+val create :
+ __context:Context.t ->
+ device:string ->
+ network:[ `network ] Ref.t ->
+ vM:[ `VM ] Ref.t ->
+ mAC:string ->
+ mTU:int64 ->
+ other_config:(string * string) list ->
+ qos_algorithm_type:string ->
+ qos_algorithm_params:(string * string) list ->
+ currently_attached:bool -> API.ref_VIF
+
+(** Destroy a VIF object in the database. *)
+val destroy : __context:Context.t -> self:[ `VIF ] Ref.t -> unit
+
+(** Copy a VIF. *)
+val copy :
+ __context:Context.t ->
+ vm:[ `VM ] Ref.t ->
+ preserve_mac_address:bool -> [ `VIF ] Ref.t -> API.ref_VIF
+
diff -r db3f4cda7bae ocaml/xapi/xapi_vlan.mli
--- a/ocaml/xapi/xapi_vlan.mli Tue Dec 01 22:37:43 2009 +0000
+++ b/ocaml/xapi/xapi_vlan.mli Wed Dec 02 15:15:38 2009 +0000
@@ -12,8 +12,20 @@
* GNU Lesser General Public License for more details.
*)
(** Module that defines API functions for VLANs
- * @group XenAPI functions
+ * @group Networking
*)
+
+(**
+Xapi also supports 802.1Q VLANs, which are used to separate network traffic by
inserting a _tag_ in each packet, thereby creating multiple virtual networks. A
tag is simply a number.
+{ul
+{- A VLAN has a {i VLAN} object in the datamodel, which is associated with a
{i slave} PIF and a {i master} PIF.}
+{- The VLAN slave, or untagged PIF, is used as the base of the VLAN. It can be
any existing PIF (including bond masters).}
+{- The VLAN master, or tagged PIF, is a higher-level PIF (comparable to a bond
master) that is configured with a VLAN tag. Any traffic sent to the VLAN master
(via its network) will be tagged.}
+{- Both the VLAN slave as well as the master may be used directly. The
"pluggedness" of the master and slave is independent: the master may be plugged
while the slave is not and vice versa, and both may be plugged or unplugged at
the same time.}
+{- Multiple VLANs in a pool may share the same tag.}
+}
+Note: Plugging a VLAN master PIF on top of a VLAN slave that is unplugged,
does not set [currently_attached] to [true], while the underlying network
device and bridge of the slave {i is} brought up. In this case,
[currently_attached] therefore does not always reflect the actual state of the
network interface. Unplugging a VLAN slave that is up, while its master is also
up, actually leaves the slave's bridge up. Should this be made more
aligned/consistent?
+*)
(** Create a VLAN with the given [tag] using the [tagged_PIF] as VLAN slave.
* Creates a new PIF object as VLAN master (untagged PIF) and connects it to
the
doc-netw2
Description: Text document
_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/mailman/listinfo/xen-api
|
Home