diff options
| -rw-r--r-- | doc/networking/ChangeLog | 5 | ||||
| -rw-r--r-- | doc/networking/networkapp.t | 44 | ||||
| -rw-r--r-- | doc/networking/preface.texi | 14 |
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 |