RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

2003-10-02 Gene Smith <gene.smith@siemens.com>

Browse Source 
* networkapp.t, preface.texi: Improve documentation for SO_RCVWAKEUP
	and SO_SNDWAKEUP and update the references in the preface.
This commit is contained in:
Joel Sherrill
2003-10-02 12:52:38 +00:00
parent 0bad72c920
commit 837ca43b57
3 changed files with 56 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
doc/networking/ChangeLog
View File

@@ -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.

44
doc/networking/networkapp.t
View File

@@ -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:

14
doc/networking/preface.texi
View File

@@ -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