Descriptors

Working with remote shared memories, DMA transfers and remote interrupts, the major communication features that this API offers, requires the use of logical entities like devices, memory segments, DMA queues. Each of these entities is characterize by a set of properties that should be managed as a unique object in order to avoid inconsistencies. To hide the details of the internal representation and management of such properties to an API user, a number of descriptors have been defined and made opaque: their contents can be referenced with a handle and can be modified only through the functions provided by the API.

The descriptors and their meaning are the following:

• sci_desc_t It represents an SISCI virtual device, that is a communication channel with the driver. Many virtual devices can be opened by the same application. It is initialized by calling the function SCIOpen() and closed with SCIClose().

• sci_local_segment_t It represents a local memory segment and it is initialized when the segment is allocated by calling the function SCICreateSegment().

• sci_remote_segment_t It represents a segment residing on a remote node. It is initialized by calling either the function SCIConnectSegment().

• sci_map_t It represents a memory segment mapped in the process address space. It is initialized by calling either the SCIMapRemoteSegment() or SCIMapLocalSegment() function.

• sci_sequence_t It represents a sequence of operations involving communication with remote nodes. It is used to check if errors have occurred during a data transfer. The descriptor is initialized when the sequence is created by calling the function SCICreateMapSequence().

• sci_dma_queue_t It represents a chain of specifications of data transfers to be performed using the DMA engine available on the adapter. The descriptor is initialized when the chain is created by calling the function SCICreateDMAQueue().

• sci_local_interrupt_t It represents an instance of an interrupt that an application has made available to remote nodes. It is initialized when the interrupt is created by calling the function SCICreateInterrupt().

• sci_remote_interrupt_t It represents an interrupt that can be triggered on a remote node. It is initialized by calling the function SCIConnectInterrupt().

• sci_local_data_interrupt_t It represents an instance of an data interrupt that an application has made available to remote nodes. It is initialized when the interrupt is created by calling the function SCICreateDataInterrupt().

• sci_remote_data_interrupt_t It represents an data interrupt that can be triggered on a remote node. It is initialized by calling the function SCIConnectDataInterrupt().

Each of the above descriptors is an opaque data type and can be referenced only via a handle.

No automatic cleanup of the resources represented by the above descriptors is performed, rather it should be provide by the API client. Resources cannot be released (and the corresponding descriptors deallocated) until all the dependent resources have been previously released. The dependencies between resource classes can be derived by the function specifications.