WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
   
 
 
Xen 
 
Home Products Support Community News
 
   
 

xen-api

[Xen-API] [PATCH] [ocamldoc] Completed docs for all networking modules i

To: xen-api <xen-api@xxxxxxxxxxxxxxxxxxx>
Subject: [Xen-API] [PATCH] [ocamldoc] Completed docs for all networking modules in xapi
From: Rob Hoes <rob.hoes@xxxxxxxxxx>
Date: Wed, 2 Dec 2009 15:27:44 +0000
Delivery-date: Wed, 02 Dec 2009 07:28:11 -0800
Envelope-to: www-data@xxxxxxxxxxxxxxxxxxx
List-help: <mailto:xen-api-request@lists.xensource.com?subject=help>
List-id: Discussion of API issues surrounding Xen <xen-api.lists.xensource.com>
List-post: <mailto:xen-api@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/mailman/listinfo/xen-api>, <mailto:xen-api-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/mailman/listinfo/xen-api>, <mailto:xen-api-request@lists.xensource.com?subject=unsubscribe>
Sender: xen-api-bounces@xxxxxxxxxxxxxxxxxxx
# 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

Attachment: doc-netw2
Description: Text document

_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/mailman/listinfo/xen-api
<Prev in Thread] Current Thread [Next in Thread>
  • [Xen-API] [PATCH] [ocamldoc] Completed docs for all networking modules in xapi, Rob Hoes <=