C H A P T E R 10 |
Transparent Interprocess Communication API |
This chapter describes the Transparent Interprocess Communication (TIPC) API. Topics include:
The Transparent Interprocess Communication (TIPC) protocol is for clustered computer environments. TIPC enables developers to create applications that can communicate quickly and reliably with other applications regardless of their location within the cluster.
The TIPC Ethernet Bearer API can be used to develop Sun Netra DPS TIPC application with TIPC Ethernet bearer support.
Must be implemented by the application developer. The function is used inside the TIPC stack. The function must copy the MAC address of the given Ethernet or vnet port number in the MAC argument.
The sample implementation of this function is found in the TIPC reference application: /opt/SUNWndps/src/apps/tipc/src/app/tipc_eth.c
tipc_eth_get_mac(tipc_dev_type dev_type, int port, uchar_t *mac);
dev_type - DEV_TYPE_ETHERNET for ethernet port.
DEV_TYPE_VNET for vnet port.
port - Ethernet or vnet port number.
mac - Buffer to copy the MAC address of the Ethernet or vnet port.
Returns the TIPC stack receive and transmit fast queue handles for the given Ethernet or vnet port and DMA channel number.
tipc_eth_get_fastq(tipc_dev_type dev_type, int port, int chan, tipc_fastq type);
dev_type - DEV_TYPE_ETHERNET for ethernet port.
DEV_TYPE_VNET for vnet port.
port - Ethernet/vnet port number.
chan - DMA channel number. Must be 0 for vnet port
type - TIPC_FASTQ_RX for receive fast queue.
TIPC_FASTQ_TX for transmit fast queue.
NULL - On invalid Ethernet or vnet port number.
Allocates a message block for outgoing packet data. This function must be implemented by application developer. The function should call the Ethernet alloc API (eth_pbuf_alloc).
The sample implementation of this function is found in the TIPC reference application: /opt/SUNWndps/src/apps/tipc/src/app/tipc_util.c
tipc_eth_pbuf_alloc(void *hook, size_t size, uint16_t mpool_id);
hook - User-provided hook. (See in Note 1.)
size - User-provided buffer size to be allocated. (See Note 2.)
mpool_id - DMA channel pool. (See Note 3.)
Pointer to mblk with b_rptr and b_wptr pointing to the start of a valid data buffer - Success.
Free the message block allocated by eth_pbuf_alloc. This function must be implemented by application developer. The function should call the Ethernet free API (eth_pbuf_free).
The sample implementation of this function is found in the TIPC reference application: /opt/SUNWndps/src/apps/tipc/src/app/tipc_util.c
tipc_eth_pbuf_free(void *hook, pbuf_t *mp, void *arg, uint16_t mpool_id);
hook - User-provided hook. (See in Note 1.)
mp - Pointer to message block to be freed.
arg - Not used (pass in NULL).
mpool_id - DMA channel pool. (See Note 3.)
The following function prototypes can be found in netra_dps/tipc.h in /opt/SUNWndps/lib/tipc/include/.
Must be called from the application initialization function.
tipc_init(int tipc_strandid, int numport, int numchan, int startport);
tipc_strandid - The thread number that runs the TIPC stack.
numport - Number of Ethernet ports the TIPC stack to support.
numchan - Number of DMA channels per port.
startport - First Ethernet port number from which TIPC stack to support.
Initializes the memory pool ID used by the Ethernet driver for given port and DMA channel.
tipc_eth_init_mempool(int port, int chan, uint16_t mpool_id);
port - Port number of the Ethernet interface.
mpool_id - Memory pool ID used by Ethernet driver for the given DMA channel.
Must be implemented by the application developer. The function is used by the TIPC stack to allocate pbuf_t buffers. The buffer returned by the function should be 8-byte aligned.
The sample implementation of this function is found in the TIPC reference application: /opt/SUNWndps/src/apps/tipc/src/app/tipc_util.c
Must be implemented by the application developer. The function is used by the TIPC stack to free pbuf_t buffers.
The sample implementation of this function is found in the TIPC reference application: /opt/SUNWndps/src/apps/tipc/src/app/tipc_util.c
mp - Buffer obtained through tipc_pbuf_alloc.
Must be polled regularly at least in an interval of 1 ms. This function provides the TIPC stack functionality. This function can be called from a dedicated strand or it can be put in the management strand. This function must not be called from the strand where a TIPC application is running, otherwise, the fastq called will cause a dead-lock.
This function is used to register fast queues for sending and receiving tn-tipc-config tool packets between the Sun Netra DPS application and the Sun Netra DPS TIPC stack when Linux tn-tipc-config tool is used. This function is also used to register a packet buffer pool with the TIPC stack. This pool is used by the TIPC stack for allocating tn-tipc-config tool packets.
tipc_vnet_config_register(void *txfq, void *rxfq, int poolid)
txfq - Fast queue on which configuration packets transmitted by the TIPC stack are queued. The application dequeues packets from this fast queue and transmits them over a vnet interface.
rxfq - Fast queue on which application enqueues configuration packets that are received on a vnet interface. The TIPC stack dequeues from this fast queue for processing.
poolid - Relative index for the memory pool from which packets are allocated.
On success, returns 0. On failure, returns a value less than 0.
Must be implemented by the application developer. The function is used by the TIPC stack to allocate message blocks for communicating with Linux tn-tipc-config tool.
tipc_cfgsrv_pbuf_alloc(void *hook, size_t bufsz, uint16_t pool)
hook - Unused. TIPC stack always passes a NULL.
bufsz - Size of the buffer requested.
pool - The relative memory pool index that was provided by the application using tipc_vnet_config_register described above.
NULL on failure. A non-NULL value on success.
Must be implemented by the application developer. The function is used by the TIPC stack to free message blocks that were allocated for communicating with Linux tn-tipc-config tool.
tipc_cfgsrv_pbuf_free(void *hook, pbuf_t *mblkp, void *arg, uint16_t pool)
hook - Unused. TIPC stack always passes a NULL.
mblkp - Message block that needs to be freed.
arg - Unused. TIPC stack always passes a NULL.
pool - The relative memory pool index that was provided by the application using tipc_vnet_config_register described above.
All the Socket APIs adhere to the Solaris standard, but all blocking APIs have been modified to poll instead. The following functions have the same functionality as the Solaris socket API:
The following functions have the same functionality as the Solaris socket API:
Note - poll() is not supported in Sun Netra DPS. |
The following Socket API functions differ from the Solaris standard in functionality.
Creates TIPC socket. The handle that is returned by a successful call to this function must be passed to access the socket using any of the other interface functions.
socket(int family, int type, int protocol)
family - The family must be AF_TIPC to create the TIPC socket.
type - The following socket types are supported:
SOCK_DGRAM
SOCK_STREAM
SOCK_RDM
SOCK_SEQPACKET
protocol - Currently not supported, should be set to 0.
Error number - Error values similar to Solaris socket accept() API.
Nonblocking call that extracts the first connection request on the queue of pending connections, creates a new socket with the same properties of socket, and allocates a new socket handle for the socket.
tipc_accept(int socket_handle, struct sockaddr *addrp, int *addrlenp)
socket_handle - Handle returned by socket() API.
addrp - Result parameter that is filled in with the address of the connecting entity. This should be of type struct sockaddr_tipc.
addrlenp - Address length of the connecting entity.
Error number - Error values similar to Solaris socket accept() API.
Nonblocking implementation of recv(). This function receives a maximum of length bytes of data from the given socket handle. The length of the message is returned. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket from which the message is received.
recv(int socket_handle, char *buffer, int length, int flags)
socket_handle - Handle returned by socket() API.
buffer - Buffer to which the data to be copied.
length - Number of bytes to be read.
Error number - Error values similar to Solaris socket accept() API.
Nonblocking implementation of recvfrom(). This function receives a maximum of length bytes of message from the given socket handle. The length of the message is returned. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket from which the message is received. The from parameter is filled with the address of source from which the message is received.
recvfrom(int socket_handle, char *buffer, int length, int flag, struct sockaddr *from, int *fromlen)
socket_handle - Handle returned by socket() API.
buffer - Buffer to which the data to be copied.
length - Number of bytes to be read.
from - Source address of the message received. This should be of type struct sockaddr_tipc.
fromlen - Length of the source address.
Error number - Error values similar to Solaris socket accept() API.
Nonblocking implementation of send(). This function sends a maximum of length bytes of the message to the socket.
send(int socket_handle, const char *dataptr, int size, int flags)
socket_handle - Handle returned by socket() API.
dataptr - Buffer to which the data to be copied
size - Number of bytes to be send.
Error number - Error values similar to Solaris socket accept() API.
Nonblocking implementation of sendto(). This function sends a maximum of length bytes of message to the socket.
sendto(int socket_handle, const char *dataptr, int size, int flag, const struct sockaddr *to, int tolen)
socket_handle - Handle returned by socket() API.
dataptr - Buffer to which the data is to be copied.
size - Number of bytes to be send.
to - Destination address to which data is to be sent. This parameter should be of type struct sockaddr_tipc.
tolen - Length of the to address.
Error number - Error values similar to Solaris socket accept() API.
TABLE 4-5 lists the TIPC Stack tunables.
To Configure the TIPC Stack With the Linux
|
1. Set the TIPC stack tunable tipc_config_thru_vnet to 1 before calling tipc_init.
2. Create two fast queues: one for dequeueing TIPC configuration packets from the stack and one to enqueue TIPC configuration packets into the stack.
3. Register the fast queues with the Sun Netra DPS TIPC stack using tipc_vnet_config_register.
4. Add the Ethernet multicast address, 33:33:00:00:00:01, to the multicast table of the vnet in the Oracle VX Server for SPARC software that will be used for
tn-tipc-config.
The vnet ioctl ETH_IOC_ADD_MCAST_ADDR must be used.
5. Enqueue all Ethernet frames that have an Ethernet type 0x3c21 in to the TIPC stack using the fast queue created in Step 2.
6. Dequeue packets from the fast queue created in Step 2, and transmit the packet over the vnet used for tn-tipc-config.
Copyright © 2010, Oracle and/or its affiliates. All rights reserved.