mbuf.9 - OpenGrok cross reference for /freebsd/share/man/man9/mbuf.9

Deleted Added

sdiffudifftextold (238d9c59..)new (0193eb5e..)

mbuf.9 (238d9c5975e5a2706d409575cb0fb1fdd896a2ae)	mbuf.9 (0193eb5ee905fe6a653925bfc5357848bba2c949)
1.\" Copyright (c) 2000 FreeBSD Inc. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. --- 224 unchanged lines hidden (view full) --- 233is added to the 234.Vt mbuf 235header. 236It contains a pointer to the interface 237the packet has been received from 238.Pq Vt struct ifnet Va *rcvif , 239and the total packet length 240.Pq Vt int Va len .	1.\" Copyright (c) 2000 FreeBSD Inc. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. --- 224 unchanged lines hidden (view full) --- 233is added to the 234.Vt mbuf 235header. 236It contains a pointer to the interface 237the packet has been received from 238.Pq Vt struct ifnet Va *rcvif , 239and the total packet length 240.Pq Vt int Va len .
	241Fields used in offloading checksum calculation to the hardware are kept in 242.Va m_pkthdr 243as well. 244See 245.Sx HARDWARE-ASSISTED CHECKSUM CALCULATION 246for details.
241.Pp 242If small enough, data is stored in the internal data buffer of an 243.Vt mbuf . 244If the data is sufficiently large, another 245.Vt mbuf 246may be added to the 247.Vt mbuf chain , 248or external storage may be associated with the --- 506 unchanged lines hidden (view full) --- 755.Fa len 756bytes. 757In case of failure, it returns 758.Dv NULL 759and attempts to restore the 760.Vt mbuf chain 761to its original state. 762.El	247.Pp 248If small enough, data is stored in the internal data buffer of an 249.Vt mbuf . 250If the data is sufficiently large, another 251.Vt mbuf 252may be added to the 253.Vt mbuf chain , 254or external storage may be associated with the --- 506 unchanged lines hidden (view full) --- 761.Fa len 762bytes. 763In case of failure, it returns 764.Dv NULL 765and attempts to restore the 766.Vt mbuf chain 767to its original state. 768.El
	769.Sh HARDWARE-ASSISTED CHECKSUM CALCULATION 770This section currently applies to TCP/IP only. 771In order to save the host CPU resources, computing checksums is 772offloaded to the network interface hardware if possible. 773The 774.Va m_pkthdr 775member of the leading 776.Vt mbuf 777of a packet contains two fields used for that purpose, 778.Vt int Va csum_flags 779and 780.Vt int Va csum_data . 781The meaning of those fields depends on the direction a packet flows in, 782and on whether the packet is fragmented. 783Henceforth, 784.Va csum_flags 785or 786.Va csum_data 787of a packet 788will denote the corresponding field of the 789.Va m_pkthdr 790member of the leading 791.Vt mbuf 792in the 793.Vt mbuf chain 794containing the packet. 795.Pp 796On output, checksum offloading is attempted after the outgoing 797interface has been determined for a packet. 798The interface-specific field 799.Va ifnet.if_data.ifi_hwassist 800(see 801.Xr ifnet 9 ) 802is consulted for the capabilities of the interface to assist in 803computing checksums. 804The 805.Va csum_flags 806field of the packet is set to indicate which actions the interface 807is supposed to perform on it. 808The actions unsupported by the network interface are done in the 809software prior to passing the packet down to the interface driver; 810such actions will never be requested through 811.Va csum_flags . 812.Pp 813The flags demanding a particular action from an interface are as follows: 814.Bl -tag -width ".Dv CSUM_TCP" -offset indent 815.It Dv CSUM_IP 816The IP header checksum is to be computed and stored in the 817corresponding field of the packet. 818The hardware is expected to know the format of an IP header 819to determine the offset of the IP checksum field. 820.It Dv CSUM_TCP 821The TCP checksum is to be computed. (See below.) 822.It Dv CSUM_UDP 823The UDP checksum is to be computed. (See below.) 824.El 825.Pp 826Should the TCP or UDP checksum be calculated in the hardware, 827the field 828.Va csum_data 829will contain the byte offset of the checksum field relative to the 830end of the IP header. 831In this case, the checksum field will be initially 832set by the TCP/IP module to the checksum of the pseudo header 833defined by the protocol specification. 834.Pp 835For outbound packets which have been fragmented 836by the host CPU, the following will also be true, 837regardless of the checksum flag settings: 838.Bl -bullet -offset indent 839.It 840all fragments will have the flag 841.Dv M_FRAG 842set in their 843.Va m_flags 844field; 845.It 846the first and the last fragments in the chain will have 847.Dv M_FIRSTFRAG 848or 849.Dv M_LASTFRAG 850set in their 851.Va m_flags , 852correspondingly; 853.It 854the first fragment in the chain will have the total number 855of fragments contained in its 856.Va csum_data 857field. 858.El 859.Pp 860It is obvious that computing the TCP or UDP checksum cannot 861be offloaded for a packet fragmented by the host CPU. 862Consequently, there is no ambiguity in the meaning of 863.Va csum_data 864for an outgoing packet. 865.Pp 866On input, an interface indicates the actions it has performed 867on a packet by setting one or more of the following flags in 868.Va csum_flags 869associated with the packet: 870.Bl -tag -width ".Dv CSUM_IP_CHECKED" -offset indent 871.It Dv CSUM_IP_CHECKED 872The IP header checksum has been computed. 873.It Dv CSUM_IP_VALID 874The IP header has a valid checksum. 875This flag can appear only in combination with 876.Dv CSUM_IP_CHECKED . 877.It Dv CSUM_DATA_VALID 878The checksum of the data portion of the IP packet has been computed 879and stored in the field 880.Va csum_data 881in network byte order. 882.It Dv CSUM_PSEUDO_HDR 883Can be set only along with 884.Dv CSUM_DATA_VALID 885to indicate that the IP data checksum found in 886.Va csum_data 887allows for the pseudo header. 888Otherwise the checksum of the pseudo header must be calculated by 889the host CPU and added to 890.Va csum_data 891to obtain the final checksum to be used for validation purposes. 892.El 893.Pp 894If a particular network interface just indicates success or 895failure of TCP or UDP checksum validation without returning 896the exact value of the checksum to the host CPU, its driver can mark 897.Dv CSUM_DATA_VALID 898and 899.Dv CSUM_PSEUDO_HDR 900in 901.Va csum_flags , 902and set 903.Va csum_data 904to 905.Li 0xFFFF 906hexadecimal to indicate a valid checksum. 907It's a peculiarity of the algorithm used that the Internet checksum 908calculated over any valid packet will be 909.Li 0xFFFF 910as long as the original checksum field is included. 911.Pp 912For inbound packets which are IP fragments, all 913.Va csum_data 914fields will be summed during reassembly to obtain the final checksum 915value passed to an upper layer in the 916.Va csum_data 917field of the reassembled packet. 918The 919.Va csum_flags 920fields of all fragments will be consolidated using logical AND 921to obtain the final value for 922.Va csum_flags . 923Thus, in order to successfully 924offload checksum computation for fragmented data, 925all fragments should have the same value of 926.Va csum_flags .
763.Sh STRESS TESTING 764When running a kernel compiled with the option 765.Dv MBUF_STRESS_TEST , 766the following 767.Xr sysctl 8 Ns 768-controlled options may be used to create 769various failure/extreme cases for testing of network drivers 770and other parts of the kernel that rely on --- 15 unchanged lines hidden (view full) --- 786to randomly fail, returning 787.Dv NULL . 788Any piece of code which uses 789.Fn m_defrag 790should be tested with this feature. 791.El 792.Sh RETURN VALUES 793See above.	927.Sh STRESS TESTING 928When running a kernel compiled with the option 929.Dv MBUF_STRESS_TEST , 930the following 931.Xr sysctl 8 Ns 932-controlled options may be used to create 933various failure/extreme cases for testing of network drivers 934and other parts of the kernel that rely on --- 15 unchanged lines hidden (view full) --- 950to randomly fail, returning 951.Dv NULL . 952Any piece of code which uses 953.Fn m_defrag 954should be tested with this feature. 955.El 956.Sh RETURN VALUES 957See above.
	958.Sh SEE ALSO 959.Xr ifnet 9 .
794.Sh HISTORY 795.\" Please correct me if I'm wrong 796.Vt Mbufs 797appeared in an early version of 798.Bx . 799Besides being used for network packets, they were used 800to store various dynamic structures, such as routing table 801entries, interface addresses, protocol control blocks, etc. 802.Sh AUTHORS 803The original 804.Nm 805man page was written by Yar Tikhiy.	960.Sh HISTORY 961.\" Please correct me if I'm wrong 962.Vt Mbufs 963appeared in an early version of 964.Bx . 965Besides being used for network packets, they were used 966to store various dynamic structures, such as routing table 967entries, interface addresses, protocol control blocks, etc. 968.Sh AUTHORS 969The original 970.Nm 971man page was written by Yar Tikhiy.