From c3c6ad34267afdfa9e94d96732f973816b0381ed Mon Sep 17 00:00:00 2001 From: YAMAMOTO Takashi Date: Fri, 19 Apr 2013 14:10:56 +0900 Subject: ryu.lib.packet: docstring Signed-off-by: YAMAMOTO Takashi Signed-off-by: FUJITA Tomonori --- ryu/lib/packet/arp.py | 28 ++++++++++++++++ ryu/lib/packet/icmp.py | 2 +- ryu/lib/packet/icmpv6.py | 87 ++++++++++++++++++++++++++++++++++++++++++++++++ ryu/lib/packet/ipv4.py | 6 +++- ryu/lib/packet/ipv6.py | 21 ++++++++++++ ryu/lib/packet/mpls.py | 19 +++++++++++ ryu/lib/packet/tcp.py | 24 +++++++++++++ ryu/lib/packet/udp.py | 18 ++++++++++ ryu/lib/packet/vrrp.py | 72 +++++++++++++++++++++++++++++++++++++++ 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) -- cgit v1.2.3