Connection Setup

To setup an DSI stream, a send-socket and a receive-socket must be created, which is done at the involved components. Then the sockets must be connected by the application. Both components can reside in separate address spaces, but it is also possible for one or even two of them to be in the applications address space.

See the following sections describing

Todo:: Write about starting the communication, delaying the receiver. We must define how signalling of prework-time at sender-side works.

Normally, the application uses component-specific functions to initiate a connection. These specific functions send socket-create-requests with suited parameters to both sender and receiver components, which are typically unrelated servers. These parameters usually contain a traffic description that can be converted to a jcp-description by the components. In reply to the requests the application gets two DSI component references, one for the sender and one for the receiver. The references allow DSI to locate the components and address the sockets. Function-pointers in the reference allow component-specific connect-, start- and stop-code to be executed. The application creates the stream by passing these references to the dsi_stream_create() function. The created stream can be started, stopped and destroyed using the common DSI interface.

For example, a fileserver could provide an open-function to open a file in read mode having a filename and a bandwidth as arguments. This open-function sends an open-request to the fileserver and returns a component reference together with two memory regions. The component references points to the fileserver and the created socket, and contains the functions to send connect-, start- and stop-messages to the server. The memory regions are passed to the open-function of a server receiving data and will be used for data transfer and synchronisation. The application never deals with buffer size calculation or memory allocation, this is done at the components or its support functions. This fileserver example makes clear why it is out of the scope of DSI to support a socket create function suitable for all possible components. It is more flexible to use specific functions in a first step for connection setup and to switch to a common interface in a second step.

In reaction to receiving a component-specific open-request the component creates a local socket. This requires a data region for storing the data to transmit and a control region for the communication with the peer. Further a work thread that will call the DSI signalling functions and a synchronisation thread are needed for the socket. For details on data transfer see Data Transfer, for details on signalling see Signalling and Synchronisation Issues.

Both the data region and the control region will be shared between the two sockets of a stream. While control regions are always exclusive for one stream, it is possible for data regions to be shared between multiple streams. DSI can allocate both regions automatically on socket creation. Alternatively, a component can create the data region by itself, which is necessary to use the memory on an adapter card instead of onboard main memory. A stream description contains information to calculate the minimum sizes of the data and control regions and the space to be reserved for the scatter-gather lists. It should be calculated from the parameters of the component-specific open function and is always needed for socket creation. It is obvious that the same memory regions used at the first component must be passed to the other component of the stream. Even if unusual, it is possible to create both data region and control region at the application and pass them to the components. On socket deletion, DSI will free automatically allocated regions by itself, but not the regions that were created previously to socket creation.

Synchronisation threads are used exclusively by one socket, so each stream will result in at least two new threads. These threads will be allocated automatically with automatic removal on socket deletion. The work thread is the only thread that will be able to get and commit packets for the socket. It can be shared with other activities and sockets. Automatic creation and deletion is provided for the work thread too.

Todo:: Write somewhere about the callbacks.

Todo:: Write about the flags on socket creation.

To reference to a socket at a component, applications use the structure dsi_component_t. Applications create a stream with dsi_stream_create(), start a stream with dsi_stream_start(), stop it with dsi_stream_stop() and delete it with dsi_stream_delete().

To convert a jitter-constrained periodic stream to a stream-description, use dsi_jcp_2_config(). Components create a socket with dsi_socket_create(). A reference to the local socket can be obtained with dsi_socket_get_ref(). Together with function-pointers for specific message handling this reference forms a component reference. A local socket is connected with a socket reference to a remote socket using dsi_socket_connect(). To retrieve an opened socket from the numerical socket ID of a socket reference, use dsi_socket_get_descriptor(). To set the callback function that is called on every blocking-related IPC, use dsi_socket_set_sync_callback(). The sender can specify a callback function for acknowledge-events at the client using dsi_socket_set_release_callback(). A socket is closed with dsi_socket_close().