Re: rawsock documentation, checksums

Sam Steingold writes:
 > if you want a more encouraging language for the docs, please send a
 > patch.
I did try to suggest some replacement text.
  Use SOCKET:SOCKET-STREAM instead!
=>See SOCKET:SOCKET-STREAM first!

  This interface is very low-level, and you probably do not need it -
  unless you are doing something very unusual. If you are interested in
  TCP/IP (Internet) stream sockets, you should use
  SOCKET:SOCKET-STREAMs, not this package.
=>For most uses of sockets, the facilities described in [31.5 Socket
  Streams] are adequate and much more convenient than raw sockets.
  You are advised to understand Socket Streams and why they are not
  adequate for your purposes before you use raw sockets. 

 > >   32.13.5. High-Level Functions
 > > In what sense are the functions in this section higher level than
 > > those above?
 > 
 > they do not map directly to a single syscall.

That makes a much better description than "higher level".
Some of those functions map to more than one, some to less.
I think that higher level corresponds to doing more work and
hiding more details, in which case recvfrom is a lot higher
level than sockaddr-family.

 > > checksums - mention that these not only compute the checksum but
 > > store it in the buffer.  Also, looking at the code, these seem
 > > to assume the buffer holds a raw ethernet packet of the expected
 > > type.  In fact, that type seems more seem than you might expect,
 > > e.g. the won't work with such things as vlan tagged packets, even
 > > though you might think of those as IP packets.  In hind sight I
 > > think these should have been written in lisp.
 > 
 > I don't know what those functions do.
 > I have no idea what they compute.
 > I would appreciate a doc for them:
 > like: what is the buffer size? (max? min?)
 > are they destructive?
 > how?
 > where are they checksums specified? (rfc?)

(Note - IP below refers to IPv4 - IPv6 is different...)

RFCs (IP=791,ICMP=792,TCP=793,UDP=768) describe the format of
packets in each protocol, including a 16 bit checksum of certain
data in the packet.  The function IPCSUM, for instance, assumes
that the buffer holds an IP packet, computes the checksum and
puts it into the field where it should go.  Typically if you want
to send, e.g., a TCP packet you'd compute the parts that matter
to you, store them in the buffer, then call IPCSUM to fix the
IP checksum and TCPCSUM to fix the TCP checksum before you send it. 

Destructive: yes, in that they store the checksum in the buffer
(as well as returning it) - this is almost always what you want
before you send a packet.
Buffer size: not really important, as long as it's big enough to
hold the packet.  For instance, an IP packet contains an IP header
which contains the header size, and the checksum covers that header.
More detail on my complaint above:
These functions assume you start with an ethernet packet.  That
starts with 12 bytes for the source and destination mac address,
then two bytes of length or protocol.  For IP packets these bytes
are 8,0.  In that case the IP header follows.  However the header
could be something else, and that thing could contain within it
an IP packet starting not at byte 14 but some place later.
The code currently in rawsock.c assumes the IP header starts at
byte 14.  I suppose if this assumption is not valid you could
pass in a buffer displaced to 14 before the start of the "real" IP
header.
Similar arguments apply to e.g., the tcp header, which is assumed
by the code to follow the IP header, whereas one might want to
checksum a TCP header contained in some further encapsulation,
e.g., IP in IP.

I hope that's helpful to you, though I'm not sure what part of it,
if any, belongs in the doc.

-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl