summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>2003-10-02 12:52:38 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>2003-10-02 12:52:38 +0000
commit837ca43b57dac858242cb21ea4aaf2d285ed03da (patch)
treea75b90f93f9f871fba0c0a424bfd2f78c30085cc
parent0bad72c920ce757ef2236da83c57578d8407b2c3 (diff)
downloadrtems-837ca43b57dac858242cb21ea4aaf2d285ed03da.tar.bz2
2003-10-02 Gene Smith <gene.smith@siemens.com>
* networkapp.t, preface.texi: Improve documentation for SO_RCVWAKEUP and SO_SNDWAKEUP and update the references in the preface.
-rw-r--r--doc/networking/ChangeLog5
-rw-r--r--doc/networking/networkapp.t44
-rw-r--r--doc/networking/preface.texi14
3 files changed, 56 insertions, 7 deletions
diff --git a/doc/networking/ChangeLog b/doc/networking/ChangeLog
index 7778f3894c..64aeaf0e0e 100644
--- a/doc/networking/ChangeLog
+++ b/doc/networking/ChangeLog
@@ -1,3 +1,8 @@
+2003-10-02 Gene Smith <gene.smith@siemens.com>
+
+ * networkapp.t, preface.texi: Improve documentation for SO_RCVWAKEUP
+ and SO_SNDWAKEUP and update the references in the preface.
+
2003-09-22 Ralf Corsepius <corsepiu@faw.uni-ulm.de>
* Makefile.am: Merger from rtems-4-6-branch.
diff --git a/doc/networking/networkapp.t b/doc/networking/networkapp.t
index 73dea2ee5f..cf13c42645 100644
--- a/doc/networking/networkapp.t
+++ b/doc/networking/networkapp.t
@@ -393,7 +393,8 @@ structure has the following fields:
@end group
@end example
-These options are used to set a function to be called when there is
+These options are used to set a callback function to be called when, for
+example, there is
data available from the socket (@code{SO_RCVWAKEUP}) and when there is space
available to accept data written to the socket (@code{SO_SNDWAKEUP}).
@@ -412,15 +413,52 @@ the function pointed to by the @code{sw_pfn} field
will be called. The arguments passed to the function will be as with
@code{SO_SNDWAKEUP}.
-When the function is called, the network semaphore will be locked.
+When the function is called, the network semaphore will be locked and
+the callback function runs in the context of the networking task.
The function must be careful not to call any networking functions. It
is OK to call an RTEMS function; for example, it is OK to send an
RTEMS event.
-The purpose of these functions is to permit a more efficient
+The purpose of these callback functions is to permit a more efficient
alternative to the select call when dealing with a large number of
sockets.
+The callbacks are called by the same criteria that the select
+function uses for indicating "ready" sockets. In Stevens @cite{Unix
+Network Programming} on page 153-154 in the section "Under what Conditions
+Is a Descriptor Ready?" you will find the definitive list of conditions
+for readable and writable that also determine when the functions are
+called.
+
+When the number of received bytes equals or exceeds the socket receive
+buffer "low water mark" (default 1 byte) you get a readable callback. If
+there are 100 bytes in the receive buffer and you only read 1, you will
+not immediately get another callback. However, you will get another
+callback after you read the remaining 99 bytes and at least 1 more byte
+arrives. Using a non-blocking socket you should probably read until it
+produces error EWOULDBLOCK and then allow the readable callback to tell
+you when more data has arrived. (Condition 1.a.)
+
+For sending, when the socket is connected and the free space becomes at
+or above the "low water mark" for the send buffer (default 4096 bytes)
+you will receive a writable callback. You don't get continuous callbacks
+if you don't write anything. Using a non-blocking write socket, you can
+then call write until it returns a value less than the amount of data
+requested to be sent or it produces error EWOULDBLOCK (indicating buffer
+full and no longer writable). When this happens you can
+try the write again, but it is often better to go do other things and
+let the writable callback tell you when space is available to send
+again. You only get a writable callback when the free space transitions
+to above the "low water mark" and not every time you
+write to a non-full send buffer. (Condition 2.a.)
+
+The remaining conditions enumerated by Stevens handle the fact that
+sockets become readable and/or writable when connects, disconnects and
+errors occur, not just when data is received or sent. For example, when
+a server "listening" socket becomes readable it indicates that a client
+has connected and accept can be called without blocking, not that
+network data was received (Condition 1.c).
+
@subsection Adding an IP Alias
The following code snippet adds an IP alias:
diff --git a/doc/networking/preface.texi b/doc/networking/preface.texi
index 05f52e0f4e..bd10af6671 100644
--- a/doc/networking/preface.texi
+++ b/doc/networking/preface.texi
@@ -30,10 +30,10 @@ the original 10 Megabit per second (Mbps) system, the 100 Mbps
Fast Ethernet system (802.3u), and the Gigabit Ethernet system (802.3z)."
The URL is:
@ifset use-html
-(@uref{http://wwwhost.ots.utexas.edu/ethernet/index.html,http://wwwhost.ots.utexas.edu/ethernet/index.html})
+(@uref{http://www.ethermanage.com/ethernet/ethernet.html,http://www.ethermanage.com/ethernet/ethernet.html})
@end ifset
@ifclear use-html
-(http://wwwhost.ots.utexas.edu/ethernet/index.html)
+(http://www.ethermanage.com/ethernet/ethernet.html)
@end ifclear
@item @cite{TCP/IP Illustrated, Volume 1 : The Protocols} by
@@ -42,11 +42,17 @@ by W. Richard Stevens (ISBN: 0201633469)
This book provides detailed introduction to TCP/IP and includes diagnostic
programs which are publicly available.
-@item @cite{TCP/IP Illustrated : The Implementation} by W. Richard
+@item @cite{TCP/IP Illustrated, Volume 2 : The Implementation} by W. Richard
Stevens and Gary Wright (ISBN: 020163354X)
This book focuses on implementation issues regarding TCP/IP. The
treat for RTEMS users is that the implementation covered is the BSD
-stack.
+stack with most of the source code described in detail.
+
+@item @cite{UNIX Network Programming, Volume 1 : 2nd Edition} by W. Richard
+Stevens (ISBN: 0-13-490012-X)
+
+This book describes how to write basic TCP/IP applications, again with primary
+focus on the BSD stack.
@end itemize