STP(7P)STP(7P)NAMEstp - Scheduled Transfer Protocol
SYNOPSIS
#include <sys/socket.h>
#include <netinet/in.h>
s = socket(AF_STP, SOCK_SEQPACKET, IPPROTO_STP);
DESCRIPTION
STP is a data transfer protocol that uses small control messages to pre-
arrange data movement. Buffers are allocated at the sending and the
receiving end before the data transmission, allowing full-rate, non-
congesting data flow between the end devices. The control and data may
use different physical media, or may share a single physical medium.
The read(2) or recv(2) and write(2) or send(2) system calls should be
used to transfer data over STP sockets. By the very nature of STP, a send
operation on an STP socket must have a corresponding receive at the peer
in order for progress to be made. This is because STP is fundamentally a
``no-copy'' protocol, where transfers are a-priori scheduled to occur
directly from user-space to user-space: there is no intermediate copy of
user-payload into kernel-space. If the user buffer is not aligned on a
double word boundry it may be realigned inside kernel memory resulting in
a bcopy of user data depending on the type of physical NIC.
The sendmsg(2) and recvmsg(2) system calls may be used in a restricted
fashion for scatter-gather operations. The msg_name and msg_namelen
fields in the msghdr structure are ignored. The msg_iov field has the
following restrictions. If the msg_iovlen == 1 then the vector (buffer)
being sent must only meet the device alignment restrictions. If msg_len
is greater than one then the msg_iov[0].iov_base must end on a 2^ST_BUFSZ
boundry. The middle vectors msg_iov[1].iov_base thru msg_iov[msg_iovlen-
2].iov_base must be of length 2^ST_BUFSZ if they exist. The last vector
msg_iov[msg_iovlen-1].iov_base must start on a 2^ST_BUFSZ boundy. The
first, middle and last vector must also meet the device alignment
restrictions. The msghdr may contain zero length vectors which are
removed before sending.
STP supports several socket options which can be tested with
getsockopt(2) and manipulated with setsockopt(2). These options are
defined in <netinet/st.h>.
ST_CTS_OUTSTD
Tells the ST socket how many outstanding clear-to-sends (CTS-es) the
initiator of a write()/send() can handle. Other things remaining
equal, increasing this value pipelines the data transfer, and is
expected to increase bandwidth. The default value for ST sockets is
128. The data type for the {set|get}socketopt is an unsigned short.
Page 1
STP(7P)STP(7P)
ST_BLKSZ
Modifies the BlockSize parameter, as defined in the ST protocol
standard. Other things remaining equal, a larger blocksize is
expected to increase bandwidth. The parameter is specified as a
power of 2. The default block size is 24 (16 MB). The maximum block
size is 24. The data type for the {set|get}socketopt is an unsigned
short.
ST_BUFSZ
The size of buffers to use for the transfer. As explained in the ST
protocol specification, this information is exchanged between the
initiator and the responder of a transfer during connection set-up.
Other things remaining equal, a larger bufsize is expected to
increase bandwidth. Note that setting a bufsize of N bytes makes
sense if and only if the user buffer's physical memory fragments are
each of size at least N bytes. The parameter is specified as a power
of 2. The default bufsize is 14 (16 Kbytes). The data type for the
{set|get}socketopt is an unsigned int.
ST_STUSZ
The default size of the Scheduled Transfer Unit (STU) to be
transmitted. (STU is similar to an MTU - Maximum Transfer Unit - on
most networks.) This can be throttled down by the other end-point
per the STP specification. The parameter is specified as a power of
2. Default size is 24 (16777216 bytes) on GSN and 10 (1024 bytes) on
all versions of ethernet. Also note that the actual STU size is the
minimum of the ST_BLKSZ and ST_STUSZ parameters, per the STP
specification. The data type for the {set|get}socketopt is an
unsigned int.
ST_OUT_VCNUM
The virtual circuit to be used for payload packets -- can be set to
2 or 3. The default VC used for payload packets is 3. [This
parameter makes sense for Gigabyte System Network hardware only.]
The data type for the {set|get}socketopt is an unsigned char.
ST_TX_SPRAY_WIDTH
The size of spray to be used for sending payload. This parameter can
be set to 1, 2, 4, or 8. The default spray size used for a send is 1
("no spray"). [Setting the spray width should be done very
carefully, since it is easy to get garbled data on a transfer if all
parameters of the spray are not exactly right. This parameter makes
sense for the Gigabyte System Network hardware only.] The data type
for the {set|get}socketopt is an unsigned char.
Page 2
STP(7P)STP(7P)
ST_RX_SPRAY_WIDTH
The size of spray to be used for receiving payload. This parameter
can be set to 1, 2, 4, or 8. The default spray size used for a
receive is 1 ("no spray"). [Setting the spray width should be done
very carefully, since it is easy to get garbled data on a transfer
if all parameters of the spray are not exactly right. This
parameter makes sense for the Gigabyte System Network hardware
only.] The data type for the {set|get}socketopt is an unsigned
char.
ST_USE_APPEND_PORT
This allows the user to specify to the STP stack to use an append
data port. This parameter can be 0 to use normal port or 1 to have
it be an append port. [This parameter makes sense for the Gigabyte
System Network hardware only.] The data type for the
{set|get}socketopt is an unsigned char.
ST_MAP_PORT_DIRECT
This allows the user to specify a hardware port to use directly
instead of having the STP stack assign one. This parameter can be 0
to let the STP stack choose a hardware port or 1 to have it user
specified. The user specified value is the port to which the socket
is bound. [This parameter makes sense for the Gigabyte System
Network hardware only.] The data type for the {set|get}socketopt is
an unsigned char.
EXAMPLE
int sd; /* socket file descriptor */
u_char st_port_spray = 1;
uint st_port_stusz = 14;
uint st_port_bufsz = 14;
ushort st_port_blksz = 24;
... OPEN SOCKET ...
if(setsockopt(sd, IPPROTO_STP, ST_TX_SPRAY_WIDTH,
&st_port_spray, sizeof(st_port_spray)) < 0) {
perror("setsockopt ST_TX_SPRAY_WIDTH failed");
exit(-1);
}
if(setsockopt(sd, IPPROTO_STP, ST_RX_SPRAY_WIDTH,
&st_port_spray, sizeof(st_port_spray)) < 0) {
perror("setsockopt ST_RX_SPRAY_WIDTH failed");
exit(-1);
}
if (setsockopt(sd, IPPROTO_STP, ST_STUSZ,
&st_port_stusz, sizeof(st_port_stusz)) < 0) {
Page 3
STP(7P)STP(7P)
perror("setsockopt ST_STUSZ failed");
exit(-1);
}
if (setsockopt(sd, IPPROTO_STP, ST_BUFSZ,
&st_port_bufsz, sizeof(st_port_bufsz)) < 0) {
perror("setsockopt ST_BUFSZ failed");
exit(-1);
}
if (setsockopt(sd, IPPROTO_STP, ST_BLKSZ,
&st_port_blksz, sizeof(st_port_blksz)) < 0) {
perror("setsockopt ST_BLKSZ failed");
exit(-1);
}
DIAGNOSTICS
A socket operation may fail with one of the following errors returned:
[EISCONN] when trying to establish a connection on a socket which
already has one, or when trying to send a datagram with
the destination address specified and the socket is
already connected.
[ENOTCONN] when trying to send a datagram, but no destination address
is specified, and the socket hasn't been connected.
[EHOSTUNREACH] The desination address can not be reached. Check
harp/arp.
[EPIPE] The socket had an error and the connection was torn down.
[ECONNABORTED] The socket had an error and the connection was torn down.
[EADDRNOTAVAIL]
when an attempt is made to create a socket with a network
address for which no network interface exists.
[ETIMEDOUT] A keepalive timer or send/recv timer has expired and the
operation was aborted.
Page 4
STP(7P)STP(7P)
[EINVAL] The page size of buffers passed to send/recv is too large
or small based on the specified blocksize. This can also
be received when an invalid socket option is attempted.
[EPROTONOSUPPORT]
Trying to use STP on a device for which it is not
supported.
[EOPNOTSUPP] Most likely trying to send/recv OOB data which is not
supported.
[ENOBUFS] The system has run out of memory for an internal data
structure.
[ENOMEM] The system has run out of memory for an internal data
structure or the blocksize is greater than the maxdmasz
(maximum DMA size - see systune(1M)).
[EFAULT] Tried to send/recv in a buffer that is not owned by the
application.
SEE ALSOsend(2), recv(2), intro(3), write(2), read(2), systune(1M)
IRIX Network Programming Guide,
ANSI T11.1/Project 1245-D: Scheduled Transfer Protocol specifications at
http://www.hippi.org
Page 5
