stp(7P)
stp - Scheduled Transfer Protocol
As shipped in IRIX 6.5.22. Last changed in IRIX 6.5.15.
NAME stp - 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. 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. 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) { 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. [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 ALSO send(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