| Netra Data Plane Software Suite 2.0 Update 2 Reference Manual |    
|
| C H A P T E R 6 |
|
Interprocess Communication API |
This chapter describes the Interprocess Communication (IPC) API. Topics include:
The Interprocess Communication (IPC) mechanism provides a means to communicate between processes that run in a domain under the Netra DPS runtime environment and processes in a domain with a control plane operating system.
This chapter describes the APIs available for such communications. It is divided into the common API that is available in all operating environments, the API needed to manage IPC communications in the Netra DPS runtime, and the API for use by Solaris processes.
The API described in this section is available on all operating environments that support IPC communications with a LWRTE domain. The tnipc.h header located in the src/common/include directory of the SUNWndps package defines the interface and must be included in source files using the API. The header file defines a number of IPC protocol types. User-defined protocols must not be in conflict with these predefined types.
This function registers a consumer with an IPC channel. The opaque handle that is returned by a successful call to this function must be passed to access the channel using any of the other interface functions.
ipc_handle_t
ipc_connect(uint16_t channel, uint16_t ipc_proto)
ipc_proto - Protocol type of IPC messages that are expected
IPC handle otherwise. This handle needs to be passed to the tx/rx/free functions.
This function registers callback functions for the consumer of an IPC channel. When a message is received by the IPC framework, it strips the IPC header from the message and calls the rx_hdlr function with the content of the message.
int
ipc_register_callbacks ipc_hdl,
event_handler_ft evt_hdler,
rx_handler_ft ipc_hdler,
caddr_t arg){
ipc_hdl - Handle for IPC channel, obtained from ipc_register_callbacks().
evt_hdlr - Function to handle link events.
rx_hdlr - Function to handle received messages.
arg - Opaque argument that the framework will pass back to the handler functions.
This function transmits messages over IPC. The message is described by the mblk passed to the function. To make the function as efficient as possible, the function makes some nonstandard assumptions about the messages:
As the memory containing the message is not freed inside the function, the caller must deal with memory management accordingly.
int
ipc_tx(mblk_t *mp, ipc_handle_t ipc_hdl)
mp - Pointer to message block describing the messages.
ipc_hdl - Handle for IPC channel, obtained from ipc_connect().
EIO - The write to the underlying media failed.
At this time, the only way to receive messages is through the callback function. In LWRTE, the callback function is called when the polling context finds a message on the channel. In Solaris user space, the callback is hidden in the framework, it makes the message available to be read by the read() system call.
mblk_t *ipc_rx(ipc_handle_t ipc_hdl)
ipc_hdl - Handle for IPC channel, obtained from ipc_connect().
The IPC framework allocates memory for messages that are received using its available memory pools. The consumer of an IPC message must call this function to return the memory to that pool.
void
ipc_free(mblk_t *mp, ipc_handle_t ipc_hdl)
mp - Pointer to message block describing message to be freed.
ipc_hdl - Handle for IPC channel, obtained from ipc_connect().
In the Netra DPS runtime environment domain, the interfaces described in the section Common Programming Interfaces are used to communicate with other domains using IPC. Before this infrastructure can be utilized, it must be initialized. Once it is initialized, because there are no interrupts, the programmer must ensure that every channel is polled periodically. This section describes the API for these tasks.
To use this function, the lwrte_ipc_if.h header file, which is located in the lib/ipc/include directory of the SUNWndps package, must be included where needed.
This function must be called in the initialization routine. This function must be called after the LDoms framework has been initialized, that is, mach_descrip_init(), lwrte_cnex_init() and lwrte_init_ldc() must be called first.
EFAULT - Too many channels in machine description
ENOENT - Global configuration channel not defined
To receive messages or event notifications for any IPC channel, this function must be called periodically. For example, it may be called as part of the main loop in the statistics thread. When a message is received, this ensures that the callback function registered for the channel and IPC type is called.
This function always returns 0.
Polling through the tnipc_poll() API is adequate for most IPC channels carrying low bandwidth control traffic. For higher throughput channels, the polling can be moved to a separate strand, using the following API functions:
This function removes the channel identified by the handle passed to the function from the pool of channels polled by the tnipc_poll() function. This function returns an opaque handle that must be passed to the tnipc_local_poll() function.
ipc_poll_handle_t
tnipc_register_local_poll(ipc_handle_t ipc_hdl)
ipc_hdl - The channel handle obtained from the ipc_connect() API call.
Opaque handle to be passed to the tnipc_local_poll() call.
This function works the same way as tnipc_poll(), except that only the channel identified by the handle is polled. If there is data on the channel, the rx callback will be called.
int
tnipc_local_poll(ipc_poll_handle_t poll_hdl)
poll_hdl - The handle obtained from the tnipc_register_local_poll() API call
This function always returns 0.
This function reverses the effect of the tnipc_register_local_poll() call and places the channel identified by the handle back into the common pool polled by tnipc_poll().
int
tnipc_unregister_local_poll(ipc_poll_handle_t poll_hdl)
poll_hdl - The handle obtained from the tnipc_register_local_poll() API call
This function always returns 0.
In the Solaris Operating Environment, the IPC mechanism can be used either from user space or from kernel space.
To use an IPC channel from the Solaris user space, the character-driver interfaces are used. A program opens the tnsm device (/devices/pseudo/tnsm@0:tnsm), issues an ioctl() call to connect the device to a particular channel, and then uses read() and write() calls to send and receive messages. To use the ioctl() interface, the tnsm.h header file, which is located in the directory src/solaris/include/sys in the SUNWndps package, must be included.
Before any of the interfaces can be used, the tnsm driver must be installed and loaded. This is done using the pkgadd system administration command to install the SUNWndpsd package on the Solaris domains that use IPC for communication.
The open(), close(), read(), and write() interfaces are described in their respective man pages.
The open() call on the tnsm driver creates a new instance for the specific client program. Before the read() and write() calls can be used, the TNIPC_IOC_CH_CONNECT ioctl must be called. The arguments for this ioctl are the channel ID and IPC type to be used for messages by this instance.
In the kernel, the interfaces described in Common Programming Interfaces are used.
| Netra Data Plane Software Suite 2.0 Update 2 Reference Manual | 820-5212-11 |
|
Copyright © 2008 Sun Microsystems, Inc. All Rights Reserved.