ryu.lib.packet: docstring

Signed-off-by: YAMAMOTO Takashi <yamamoto@valinux.co.jp>
Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>

9 files changed, 275 insertions, 2 deletions

diff --git a/ryu/lib/packet/arp.py b/ryu/lib/packet/arp.py
index 9d0b3f8c..f8be59e2 100644
--- a/ryu/lib/packet/arp.py
+++ b/ryu/lib/packet/arp.py
@@ -28,6 +28,27 @@ ARP_REV_REPLY = 4
 
 
 class arp(packet_base.PacketBase):
+    """ARP (RFC 826) header encoder/decoder class.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    hwtype         ar$hrd
+    proto          ar$pro
+    hlen           ar$hln
+    plen           ar$pln
+    opcode         ar$op
+    src_mac        ar$sha
+    src_ip         ar$spa
+    dst_mac        ar$tha
+    dst_ip         ar$tpa
+    ============== ====================
+    """
+
     _PACK_STR = '!HHBBH6sI6sI'
     _MIN_LEN = struct.calcsize(_PACK_STR)
 
@@ -60,6 +81,13 @@ class arp(packet_base.PacketBase):
 
 
 def arp_ip(opcode, src_mac, src_ip, dst_mac, dst_ip):
+    """A convenient wrapper for IPv4 ARP for Ethernet.
+
+    This is an equivalent of the following code.
+
+        arp(ARP_HW_TYPE_ETHERNET, ether.ETH_TYPE_IP, \
+               6, 4, opcode, src_mac, src_ip, dst_mac, dst_ip)
+    """
     return arp(ARP_HW_TYPE_ETHERNET, ether.ETH_TYPE_IP,
                6,  # ether mac address length
                4,  # ipv4 address length,
diff --git a/ryu/lib/packet/icmp.py b/ryu/lib/packet/icmp.py
index 0e199a6a..e42fa40f 100644
--- a/ryu/lib/packet/icmp.py
+++ b/ryu/lib/packet/icmp.py
@@ -101,7 +101,7 @@ class icmp(packet_base.PacketBase):
 
 @icmp.register_icmp_type(ICMP_ECHO_REPLY, ICMP_ECHO_REQUEST)
 class echo(object):
-    """ICMP sub encoder/decoder class.
+    """ICMP sub encoder/decoder class for Echo and Echo Reply messages.
 
     This is used with ryu.lib.packet.icmp.icmp for
     ICMP Echo and Echo Reply messages.
diff --git a/ryu/lib/packet/icmpv6.py b/ryu/lib/packet/icmpv6.py
index e3bd7814..4352f4a5 100644
--- a/ryu/lib/packet/icmpv6.py
+++ b/ryu/lib/packet/icmpv6.py
@@ -57,6 +57,24 @@ ICMPV6_MAXTYPE = 201
 
 
 class icmpv6(packet_base.PacketBase):
+    """ICMPv6 (RFC 2463) header encoder/decoder class.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    type\_         Type
+    code           Code
+    csum           CheckSum \
+                   (0 means automatically-calculate when encoding)
+    data           Payload. \
+                   ryu.lib.packet.icmpv6.echo object, or \
+                   ryu.lib.packet.icmpv6.nd_neighbor object, or a bytearray.
+    ============== ====================
+    """
     _PACK_STR = '!BBH'
     _MIN_LEN = struct.calcsize(_PACK_STR)
     _ICMPV6_TYPES = {}
@@ -108,6 +126,32 @@ class icmpv6(packet_base.PacketBase):
 
 @icmpv6.register_icmpv6_type(ND_NEIGHBOR_SOLICIT, ND_NEIGHBOR_ADVERT)
 class nd_neighbor(object):
+    """ICMPv6 sub encoder/decoder class for Neighbor Solicitation and
+    Neighbor Advertisement messages. (RFC 4861)
+
+    This is used with ryu.lib.packet.icmpv6.icmpv6.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    res            R,S,O Flags for Neighbor Advertisement. \
+                   The 3 MSBs of "Reserved" field for Neighbor Solicitation.
+    dst            Target Address
+    type\_         "Type" field of the first option.  None if no options. \
+                   NOTE: This implementation doesn't support two or more \
+                   options.
+    length         "Length" field of the first option.  None if no options.
+    data           An object to describe the first option. \
+                   None if no options. \
+                   Either ryu.lib.packet.icmpv6.nd_option_la object \
+                   or a bytearray.
+    ============== ====================
+    """
+
     _PACK_STR = '!I16s'
     _MIN_LEN = struct.calcsize(_PACK_STR)
     _ND_OPTION_TYPES = {}
@@ -166,6 +210,30 @@ class nd_neighbor(object):
 @nd_neighbor.register_nd_option_type(nd_neighbor.ND_OPTION_SLA,
                                      nd_neighbor.ND_OPTION_TLA)
 class nd_option_la(object):
+    """ICMPv6 sub encoder/decoder class for Neighbor discovery
+    Source/Target Link-Layer Address Option. (RFC 4861)
+
+    This is used with ryu.lib.packet.icmpv6.nd_neighbor.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    hw_src         Link-Layer Address. \
+                   NOTE: If the address is longer than 6 octets this contains \
+                   the first 6 octets in the address. \
+                   This implementation assumes the address has at least \
+                   6 octets.
+    data           A bytearray which contains the rest of Link-Layer Address \
+                   and padding.  When encoding a packet, it's user's \
+                   responsibility to provide necessary padding for 8-octets \
+                   alignment required by the protocol.
+    ============== ====================
+    """
+
     _PACK_STR = '!6s'
     _MIN_LEN = struct.calcsize(_PACK_STR)
 
@@ -194,6 +262,25 @@ class nd_option_la(object):
 
 @icmpv6.register_icmpv6_type(ICMPV6_ECHO_REPLY, ICMPV6_ECHO_REQUEST)
 class echo(object):
+    """ICMPv6 sub encoder/decoder class for Echo Request and Echo Reply
+    messages.
+
+    This is used with ryu.lib.packet.icmpv6.icmpv6 for
+    ICMPv6 Echo Request and Echo Reply messages.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    id             Identifier
+    seq            Sequence Number
+    data           Data
+    ============== ====================
+    """
+
     _PACK_STR = '!HH'
     _MIN_LEN = struct.calcsize(_PACK_STR)
 
diff --git a/ryu/lib/packet/ipv4.py b/ryu/lib/packet/ipv4.py
index ef2d58cc..09ed734a 100644
--- a/ryu/lib/packet/ipv4.py
+++ b/ryu/lib/packet/ipv4.py
@@ -29,7 +29,11 @@ IPV4_PSEUDO_HEADER_PACK_STR = '!II2xHH'
 
 
 class ipv4(packet_base.PacketBase):
-    """IPv4 header encoder/decoder class.
+    """IPv4 (RFC 791) header encoder/decoder class.
+
+    NOTE: When decoding, this implementation tries to decode the upper
+    layer protocol even for a fragmented datagram.  It isn't likely
+    what a user would want.
 
     An instance has the following attributes at least.
     Most of them are same to the on-wire counterparts but in host byte order.
diff --git a/ryu/lib/packet/ipv6.py b/ryu/lib/packet/ipv6.py
index f7b8e9bb..a1cb2035 100644
--- a/ryu/lib/packet/ipv6.py
+++ b/ryu/lib/packet/ipv6.py
@@ -28,6 +28,27 @@ IPV6_PSEUDO_HEADER_PACK_STR = '!16s16s3xB'
 
 
 class ipv6(packet_base.PacketBase):
+    """IPv6 (RFC 2460) header encoder/decoder class.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    version        Version
+    traffic_class  Traffic Class
+    flow_label     When decoding, Flow Label. \
+                   When encoding, the most significant 8 bits of Flow Label.
+    payload_length Payload Length
+    nxt            Next Header
+    hop_limit      Hop Limit
+    src            Source Address
+    dst            Destination Address
+    ============== ====================
+    """
+
     _PACK_STR = '!IHBB16s16s'
     _MIN_LEN = struct.calcsize(_PACK_STR)
 
diff --git a/ryu/lib/packet/mpls.py b/ryu/lib/packet/mpls.py
index 3dc42f67..3c0ae4f9 100644
--- a/ryu/lib/packet/mpls.py
+++ b/ryu/lib/packet/mpls.py
@@ -22,6 +22,25 @@ from ryu.ofproto import ether
 
 
 class mpls(packet_base.PacketBase):
+    """MPLS (RFC 3032) header encoder/decoder class.
+
+    NOTE: When decoding, this implementation assumes that the inner protocol
+    is IPv4.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    label          Label Value
+    exp            Experimental Use
+    bsb            Bottom of Stack
+    ttl            Time To Live
+    ============== ====================
+    """
+
     _PACK_STR = '!I'
     _MIN_LEN = struct.calcsize(_PACK_STR)
 
diff --git a/ryu/lib/packet/tcp.py b/ryu/lib/packet/tcp.py
index a7ef178c..5a44e389 100644
--- a/ryu/lib/packet/tcp.py
+++ b/ryu/lib/packet/tcp.py
@@ -20,6 +20,30 @@ from . import packet_utils
 
 
 class tcp(packet_base.PacketBase):
+    """TCP (RFC 793) header encoder/decoder class.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    src_port       Source Port
+    dst_port       Destination Port
+    seq            Sequence Number
+    ack            Acknowledgement Number
+    offset         Data Offset
+    bits           Control Bits
+    window_size    Window
+    csum           Checksum \
+                   (0 means automatically-calculate when encoding)
+    urgent         Urgent Pointer
+    option         An bytearray containing Options and following Padding. \
+                   None if no options.
+    ============== ====================
+    """
+
     _PACK_STR = '!HHIIBBHHH'
     _MIN_LEN = struct.calcsize(_PACK_STR)
 
diff --git a/ryu/lib/packet/udp.py b/ryu/lib/packet/udp.py
index 518f4fc3..c1bb10c8 100644
--- a/ryu/lib/packet/udp.py
+++ b/ryu/lib/packet/udp.py
@@ -20,6 +20,24 @@ from . import packet_utils
 
 
 class udp(packet_base.PacketBase):
+    """UDP (RFC 768) header encoder/decoder class.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    src_port       Source Port
+    dst_port       Destination Port
+    total_length   Length \
+                   (0 means automatically-calculate when encoding)
+    csum           Checksum \
+                   (0 means automatically-calculate when encoding)
+    ============== ====================
+    """
+
     _PACK_STR = '!HHHH'
     _MIN_LEN = struct.calcsize(_PACK_STR)
 
diff --git a/ryu/lib/packet/vrrp.py b/ryu/lib/packet/vrrp.py
index f98d6aeb..6ce81ceb 100644
--- a/ryu/lib/packet/vrrp.py
+++ b/ryu/lib/packet/vrrp.py
@@ -175,6 +175,33 @@ def is_ipv6(ip_address):
 
 
 class vrrp(packet_base.PacketBase):
+    """The base class for VRRPv2 (RFC 3768) and VRRPv3 (RFC 5798)
+    header encoder/decoder classes.
+
+    Unlike other ryu.lib.packet.packet_base.PacketBase derived classes,
+    This class should not be directly instantiated by user.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    version        Version
+    type           Type
+    vrid           Virtual Rtr ID (VRID)
+    priority       Priority
+    count_ip       Count IPvX Addr. \
+                   Calculated automatically when encoding.
+    max_adver_int  Maximum Advertisement Interval (Max Adver Int)
+    checksum       Checksum. \
+                   Calculated automatically when encoding.
+    ip_addresses   IPvX Address(es).  A python list of IP addresses.
+    auth_type      Authentication Type (only for VRRPv2)
+    auth_data      Authentication Data (only for VRRPv2)
+    ============== ====================
+    """
+
     _VERSION_PACK_STR = '!B'
     _IPV4_ADDRESS_PACK_STR_RAW = 'I'
     _IPV4_ADDRESS_PACK_STR = '!' + _IPV4_ADDRESS_PACK_STR_RAW
@@ -289,6 +316,24 @@ class vrrp(packet_base.PacketBase):
         return self.identification
 
     def create_packet(self, primary_ip_address, vlan_id=None):
+        """Prepare a VRRP packet.
+
+        Returns a newly created ryu.lib.packet.packet.Packet object
+        with appropriate protocol header objects added by add_protocol().
+        It's caller's responsibility to serialize().
+        The serialized packet would looks like the ones described in
+        the following sections.
+
+        * RFC 3768 5.1. VRRP Packet Format
+        * RFC 5798 5.1. VRRP Packet Format
+
+        ================== ====================
+        Argument           Description
+        ================== ====================
+        primary_ip_address Source IP address
+        vlan_id            VLAN ID.  None for no VLAN.
+        ================== ====================
+        """
         if self.is_ipv6:
             traffic_class = 0xc0        # set tos to internetwork control
             flow_label = 0
@@ -358,6 +403,12 @@ class vrrp(packet_base.PacketBase):
 # max_adver_int is in seconds
 @vrrp.register_vrrp_version(VRRP_VERSION_V2, 1)
 class vrrpv2(vrrp):
+    """VRRPv2 (RFC 3768) header encoder/decoder class.
+
+    Unlike other ryu.lib.packet.packet_base.PacketBase derived classes,
+    create method should be used to instantiate an object of this class.
+    """
+
     _PACK_STR = '!BBBBBBH'
     _MIN_LEN = struct.calcsize(_PACK_STR)
     _CHECKSUM_PACK_STR = '!H'
@@ -374,6 +425,14 @@ class vrrpv2(vrrp):
 
     @staticmethod
     def create(type_, vrid, priority, max_adver_int, ip_addresses):
+        """Unlike other ryu.lib.packet.packet_base.PacketBase derived classes,
+        this method should be used to instantiate an object of this class.
+
+        This method's arguments are same as ryu.lib.packet.vrrp.vrrp object's
+        attributes of the same name.  (except that *type_* corresponds to
+        *type* attribute.)
+        """
+
         return vrrp.create_version(VRRP_VERSION_V2, type_, vrid, priority,
                                    max_adver_int,
                                    ip_addresses,
@@ -451,6 +510,12 @@ class vrrpv2(vrrp):
 # max_adver_int is in centi seconds: 1 second = 100 centiseconds
 @vrrp.register_vrrp_version(VRRP_VERSION_V3, 100)
 class vrrpv3(vrrp):
+    """VRRPv3 (RFC 5798) header encoder/decoder class.
+
+    Unlike other ryu.lib.packet.packet_base.PacketBase derived classes,
+    create method should be used to instantiate an object of this class.
+    """
+
     _PACK_STR = '!BBBBHH'
     _MIN_LEN = struct.calcsize(_PACK_STR)
     _CHECKSUM_PACK_STR = '!H'
@@ -473,6 +538,13 @@ class vrrpv3(vrrp):
 
     @staticmethod
     def create(type_, vrid, priority, max_adver_int, ip_addresses):
+        """Unlike other ryu.lib.packet.packet_base.PacketBase derived classes,
+        this method should be used to instantiate an object of this class.
+
+        This method's arguments are same as ryu.lib.packet.vrrp.vrrp object's
+        attributes of the same name.  (except that *type_* corresponds to
+        *type* attribute.)
+        """
         return vrrp.create_version(VRRP_VERSION_V3, type_, vrid, priority,
                                    max_adver_int, ip_addresses)