sisci_api.h File Reference

Low-level SISCI software functional specification. More...

Functions
SISCI_API_EXPORT void	SCIInitialize (unsigned int flags, sci_error_t *error)
	Initializes the SISCI library.
SISCI_API_EXPORT void	SCITerminate (void)
	Terminates the SISCI library.
SISCI_API_EXPORT void	SCIOpen (sci_desc_t sd, unsigned int flags, sci_error_t error)
	Opens an SISCI virtual device.
SISCI_API_EXPORT void	SCIClose (sci_desc_t sd, unsigned int flags, sci_error_t *error)
	Closes an open SISCI virtual device.
SISCI_API_EXPORT void	SCIConnectSegment (sci_desc_t sd, sci_remote_segment_t segment, unsigned int nodeId, unsigned int segmentId, unsigned int localAdapterNo, sci_cb_remote_segment_t callback, void callbackArg, unsigned int timeout, unsigned int flags, sci_error_t *error)
	Connects an application to a memory segment made available on a remote node.
SISCI_API_EXPORT void	SCIDisconnectSegment (sci_remote_segment_t segment, unsigned int flags, sci_error_t *error)
	SCIDisconnectSegment disconnects from the give mapped shared memory segment.
SISCI_API_EXPORT unsigned int	SCIGetRemoteSegmentSize (sci_remote_segment_t segment)
	SCIGetRemoteSegmentSize returns the size in bytes of a remote segment after it has been connected with SCIConnectSegment or SCIConnectSCISpace.
SISCI_API_EXPORT sci_segment_cb_reason_t	SCIWaitForRemoteSegmentEvent (sci_remote_segment_t segment, sci_error_t status, unsigned int timeout, unsigned int flags, sci_error_t error)
	SCIWaitForRemoteSegmentEvent blocks a program until an event concerning the remote segment has arrived.
SISCI_API_EXPORT volatile void *	SCIMapRemoteSegment (sci_remote_segment_t segment, sci_map_t map, unsigned int offset, unsigned int size, void addr, unsigned int flags, sci_error_t *error)
	SCIMapRemoteSegment maps an area of a remote segment connected with either SCIConnectSegment or SCIConnectSCISpace into the addressable space of the program and returns a pointer to the beginning of the mapped area.
SISCI_API_EXPORT void *	SCIMapLocalSegment (sci_local_segment_t segment, sci_map_t map, unsigned int offset, unsigned int size, void addr, unsigned int flags, sci_error_t *error)
	SCIMapLocalSegment maps an area of a memory segment created with SCICreateSegment into the addressable space of the program and returns a pointer to the beginning of the mapped area.
SISCI_API_EXPORT void	SCIUnmapSegment (sci_map_t map, unsigned int flags, sci_error_t *error)
	SCIUnmapSegment unmaps from the programs address space a segment that was mapped either with SCIMapLocalSegment or with SCIMapRemoteSegment.
SISCI_API_EXPORT void	SCICreateSegment (sci_desc_t sd, sci_local_segment_t segment, unsigned int segmentId, unsigned int size, sci_cb_local_segment_t callback, void callbackArg, unsigned int flags, sci_error_t *error)
	SCICreateSegment allocates a memory segment and creates and initializes a descriptor for a local segment.
SISCI_API_EXPORT sci_segment_cb_reason_t	SCIWaitForLocalSegmentEvent (sci_local_segment_t segment, unsigned int sourcenodeId, unsigned int localAdapterNo, unsigned int timeout, unsigned int flags, sci_error_t *error)
	SCIWaitForLocalSegmentEvent blocks a program until an event concerning the local segment has arrived.
SISCI_API_EXPORT void	SCIPrepareSegment (sci_local_segment_t segment, unsigned int localAdapterNo, unsigned int flags, sci_error_t *error)
	SCIPrepareSegment guarantees that a local segment is accessible by an SCI adapter.
SISCI_API_EXPORT void	SCIRemoveSegment (sci_local_segment_t segment, unsigned int flags, sci_error_t *error)
	SCIRemoveSegment frees the resources used by a local segment.
SISCI_API_EXPORT void	SCISetSegmentAvailable (sci_local_segment_t segment, unsigned int localAdapterNo, unsigned int flags, sci_error_t *error)
	SCISetSegmentAvailable makes a local segment visible to remote nodes, that can then connect to it.
SISCI_API_EXPORT void	SCISetSegmentUnavailable (sci_local_segment_t segment, unsigned int localAdapterNo, unsigned int flags, sci_error_t *error)
	SCISetSegmentUnavailable hides an available segment to remote nodes; no new connections will be accepted on that segment.
SISCI_API_EXPORT void	SCICreateMapSequence (sci_map_t map, sci_sequence_t sequence, unsigned int flags, sci_error_t error)
	SCICreateMapSequence creates and initializes a new sequence descriptor that can be used to check for errors occurring in a transfer of data from or to a mapped segment.
SISCI_API_EXPORT void	SCIRemoveSequence (sci_sequence_t sequence, unsigned int flags, sci_error_t *error)
	SCIRemoveSequence destroys a sequence descriptor.
SISCI_API_EXPORT sci_sequence_status_t	SCIStartSequence (sci_sequence_t sequence, unsigned int flags, sci_error_t *error)
	SCIStartSequence performs the preliminary check of the error flags on the SCI adapter before starting a sequence of read and write operations on the concerned mapped segment.
SISCI_API_EXPORT sci_sequence_status_t	SCICheckSequence (sci_sequence_t sequence, unsigned int flags, sci_error_t *error)
	SCICheckSequence checks if any error has occurred in a data transfer controlled by a sequence since the last check.
SISCI_API_EXPORT void	SCIStoreBarrier (sci_sequence_t sequence, unsigned int flags)
	SCIStoreBarrier synchronizes all the accesses to a mapped segment.
SISCI_API_EXPORT void	SCIFlushReadBuffers (sci_sequence_t sequence)
	SCIFlushReadBuffers flushes the prefetch buffers associated with a sequence.
SISCI_API_EXPORT int	SCIProbeNode (sci_desc_t sd, unsigned int localAdapterNo, unsigned int nodeId, unsigned int flags, sci_error_t *error)
	SCIProbeNode checks if a remote node is reachable.
SISCI_API_EXPORT unsigned int	SCIGetCSRRegister (sci_desc_t sd, unsigned int localAdapterNo, unsigned int SCINodeId, unsigned int CSROffset, unsigned int flags, sci_error_t *error)
	SISCI Priveleged function SCIGetCSRRegister reads the value contained in a location of the CSR space of an SCI node.
SISCI_API_EXPORT void	SCISetCSRRegister (sci_desc_t sd, unsigned int localAdapterNo, unsigned int SCINodeId, unsigned int CSROffset, unsigned int CSRValue, unsigned int flags, sci_error_t *error)
	SISCI Priveleged function SCISetCSRRegister writes a value to a location of the CSR space of an SCI node.
SISCI_API_EXPORT unsigned int	SCIGetLocalCSR (sci_desc_t sd, unsigned int localAdapterNo, unsigned int CSROffset, unsigned int flags, sci_error_t *error)
	SISCI Priveleged function Further function description missing.
SISCI_API_EXPORT void	SCISetLocalCSR (sci_desc_t sd, unsigned int localAdapterNo, unsigned int CSROffset, unsigned int CSRValue, unsigned int flags, sci_error_t *error)
	SISCI Priveleged function Further function description missing.
SISCI_API_EXPORT void	SCIAttachPhysicalMemory (sci_ioaddr_t ioaddress, void address, unsigned int busNo, unsigned int size, sci_local_segment_t segment, unsigned int flags, sci_error_t error)
	SISCI Priveleged function SCIAttachPhysicalMemory enables usage of physical devices and memory regions where the Physical PCI bus address ( and mapped CPU address ) are already known.
SISCI_API_EXPORT void	SCIQuery (unsigned int command, void data, unsigned int flags, sci_error_t error)
	SCIQuery provides some information about the underlying system.
SISCI_API_EXPORT void	SCIGetLocalNodeId (unsigned int adapterNo, unsigned int nodeId, unsigned int flags, sci_error_t error)
	Get local node id.
SISCI_API_EXPORT void	SCIGetNodeIdByAdapterName (char adaptername, dis_nodeId_list_t nodeId, dis_adapter_type_t type, unsigned int flags, sci_error_t error)
	Funtion description missing.
void	SCIGetNodeInfoByAdapterName (char adaptername, unsigned int adapterNo, dis_nodeId_list_t nodeIdlist, dis_adapter_type_t type, unsigned int flags, sci_error_t *error)
	Funtion description missing.
SISCI_API_EXPORT void	SCICreateDMAQueue (sci_desc_t sd, sci_dma_queue_t dq, unsigned int localAdapterNo, unsigned int maxEntries, unsigned int flags, sci_error_t error)
	SCICreateDMAQueue allocates resources for a queue of DMA transfers and creates and initializes a descriptor for the new queue.
SISCI_API_EXPORT void	SCIRemoveDMAQueue (sci_dma_queue_t dq, unsigned int flags, sci_error_t *error)
	SCIRemoveDMAQueue frees the resources allocated for a DMA queue and destroys the corresponding descriptor.
SISCI_API_EXPORT sci_dma_queue_state_t	SCIEnqueueDMATransfer (sci_dma_queue_t dq, sci_local_segment_t localSegment, sci_remote_segment_t remoteSegment, unsigned int localOffset, unsigned int remoteOffset, unsigned int size, unsigned int flags, sci_error_t *error)
	SCIEnqueueDMATransfer adds the specification of a new transfer to a DMA queue.
SISCI_API_EXPORT void	SCIPostDMAQueue (sci_dma_queue_t dq, sci_cb_dma_t callback, void callbackArg, unsigned int flags, sci_error_t error)
	SCIPostDMAQueue starts the execution of a DMA queue.
SISCI_API_EXPORT void	SCIAbortDMAQueue (sci_dma_queue_t dq, unsigned int flags, sci_error_t *error)
	SCIAbortDMAQueue aborts a DMA transfer initiated with SCIPostDMAQueue.
SISCI_API_EXPORT void	SCIResetDMAQueue (sci_dma_queue_t dq, unsigned int flags, sci_error_t *error)
	SCIResetDMAQueue resets a DMA queue (without removing it), so it can be reused for another chain of transfers.
SISCI_API_EXPORT sci_dma_queue_state_t	SCIDMAQueueState (sci_dma_queue_t dq)
	SCIDMAQueueState returns the state of a DMA queue (see sci_dma_queue_state_t).
SISCI_API_EXPORT sci_dma_queue_state_t	SCIWaitForDMAQueue (sci_dma_queue_t dq, unsigned int timeout, unsigned int flags, sci_error_t *error)
	SCIWaitForDMAQueue blocks a program until a DMA queue has finished (because of the completion of all the transfers or due to an error) or the timeout has expired.
SISCI_API_EXPORT void	SCIphDmaEnqueue (sci_dma_queue_t dmaqueue, unsigned int size, sci_ioaddr_t localBusAddr, unsigned int remote_nodeid, unsigned int remote_highaddr, unsigned int remote_lowaddr, unsigned int flags, sci_error_t *error)
	Funtion description missing.
SISCI_API_EXPORT sci_dma_queue_state_t	SCIphDmaStart (sci_dma_queue_t dmaqueue, sci_cb_dma_t callback, void callbackArg, unsigned int flags, sci_error_t error)
	Funtion description missing.
SISCI_API_EXPORT void	SCICreateInterrupt (sci_desc_t sd, sci_local_interrupt_t interrupt, unsigned int localAdapterNo, unsigned int interruptNo, sci_cb_interrupt_t callback, void callbackArg, unsigned int flags, sci_error_t error)
	SCICreateInterrupt creates an interrupt resource and make it available to remote nodes and initializes a descriptor for the interrupt.
SISCI_API_EXPORT void	SCIRemoveInterrupt (sci_local_interrupt_t interrupt, unsigned int flags, sci_error_t *error)
	SCIRemoveInterrupt deallocates an interrupt resource and destroys the corresponding descriptor.
SISCI_API_EXPORT void	SCIWaitForInterrupt (sci_local_interrupt_t interrupt, unsigned int timeout, unsigned int flags, sci_error_t *error)
	SCIWaitForInterrupt blocks a program until an interrupt is received.
SISCI_API_EXPORT void	SCIConnectInterrupt (sci_desc_t sd, sci_remote_interrupt_t interrupt, unsigned int nodeId, unsigned int localAdapterNo, unsigned int interruptNo, unsigned int timeout, unsigned int flags, sci_error_t error)
	SCIConnectInterrupt connects the caller to an interrupt resource available on a remote node (see SCICreateInterrupt).
SISCI_API_EXPORT void	SCIDisconnectInterrupt (sci_remote_interrupt_t interrupt, unsigned int flags, sci_error_t *error)
	SCIDisconnectInterrupt disconnects an application from a remote interrupt resource and deallocates the corresponding descriptor.
SISCI_API_EXPORT void	SCITriggerInterrupt (sci_remote_interrupt_t interrupt, unsigned int flags, sci_error_t *error)
	SCITriggerInterrupt triggers an interrupt on a remote node, after having connected to it with SCIConnectInterrupt.
SISCI_API_EXPORT void	SCIRegisterInterruptFlag (unsigned int localAdapterNo, sci_local_interrupt_t interrupt, sci_local_segment_t segment, unsigned int offset, sci_cb_interrupt_t callback, void callbackArg, unsigned int flags, sci_error_t *error)
	SCIRegisterInterruptFlag register an "interrupt flag" that is identified as an unique location within a local segment.
SISCI_API_EXPORT void	SCIEnableConditionalInterrupt (sci_local_interrupt_t interrupt, unsigned int flags, sci_error_t *error)
	SCIEnableConditionalInterrupt make sure that another HW interrupt will take place the next time the corresponding interrupt flag is triggered by a "conditional interrupt" operation.
SISCI_API_EXPORT void	SCIDisableConditionalInterrupt (sci_local_interrupt_t interrupt, unsigned int flags, sci_error_t *error)
	SCIDisableConditionalInterrupt prevent subsequent "conditional interrupt"trigger operations for the specified interupt flag from causing HW interrupt and handler invocations.
SISCI_API_EXPORT void	SCIGetConditionalInterruptTrigCounter (sci_local_interrupt_t interrupt, unsigned int interruptTrigCounter, unsigned int flags, sci_error_t error)
	SCIGetConditionalInterruptTrigCounter returns a value that indicates the number of times that this flag has been trigged since the last time it was enabled or disabled.
SISCI_API_EXPORT void	SCIMemWrite (void memAddr, volatile void remoteAddr, unsigned int size, unsigned int flags, sci_error_t *error)
	SCIMemWrite transfers efficiently a block of data from local memory to a mapped segment using the shared memory mode.
SISCI_API_EXPORT void	SCIMemWrite_mcast (void memAddr, volatile void remoteAddr[], unsigned int size, unsigned int dst_num, unsigned int flags, sci_error_t *error)
	Function desription missing.
SISCI_API_EXPORT void	SCIMemWrite_dual (volatile void memAddr, volatile void remoteAddr1, sci_map_t remoteMap1, volatile void remoteAddr2, sci_map_t remoteMap2, unsigned int size, unsigned int flags, sci_error_t error)
	SCIMemWrite_dual transfers efficiently a block of data from local memory to two mapped segments using the shared memory mode.
SISCI_API_EXPORT void	SCIMemCpy (sci_sequence_t sequence, void memAddr, sci_map_t remoteMap, unsigned int remoteOffset, unsigned int size, unsigned int flags, sci_error_t error)
	SCIMemCpy transfers efficiently a block of data from local memory to a mapped segment using the shared memory mode.
SISCI_API_EXPORT void	SCIMemCopy (void memAddr, sci_map_t remoteMap, unsigned int remoteOffset, unsigned int size, unsigned int flags, sci_error_t error)
	SCIMemCopy transfers efficiently a block of data from local memory to a mapped segment using the shared memory mode.
SISCI_API_EXPORT void	SCIMemCpy_dual (sci_sequence_t sequence1, sci_sequence_t sequence2, void memAddr, sci_map_t remoteMap1, sci_map_t remoteMap2, unsigned int remoteOffset, unsigned int size, unsigned int flags, sci_error_t error)
	This function is experimental and subject to change, DO NOT USE.
SISCI_API_EXPORT void	SCIMemCpy_mcast (sci_sequence_t sequence[], void memAddr, sci_map_t remoteMap[], unsigned int remoteOffset[], unsigned int size, unsigned int dst_num, unsigned int flags, sci_error_t error)
	This function is experimental and subject to change, DO NOT USE.
SISCI_API_EXPORT void	SCIRegisterSegmentMemory (void address, unsigned int size, sci_local_segment_t segment, unsigned int flags, sci_error_t error)
	SCIRegisterSegmentMemory associates an area memory allocated by the program (e.g.
SISCI_API_EXPORT void	SCIConnectSCISpace (sci_desc_t sd, unsigned int localAdapterNo, sci_remote_segment_t segment, sci_address_t address, unsigned int size, unsigned int flags, sci_error_t error)
	SISCI Priveleged function SCIConnectSCISpace connects an application directly to a memory window in the adapter address space, defined by its base address and its size, without any restriction.
SISCI_API_EXPORT void	SCIAttachLocalSegment (sci_desc_t sd, sci_local_segment_t segment, unsigned int segmentId, unsigned int size, sci_cb_local_segment_t callback, void callbackArg, unsigned int flags, sci_error_t error)
	SCIAttachLocalSegment() permits an application to "attach" to an already existing local segment, implying that two or more application want share the same local segment.
SISCI_API_EXPORT void	SCIShareSegment (sci_local_segment_t segment, unsigned int flags, sci_error_t *error)
	SCIShareSegment() permits other application to "attach" to an already existing local segment, implying that two or more application want share the same local segment.
SISCI_API_EXPORT void	SCIFlush (sci_sequence_t sequence, unsigned int flags)
	SCIFlush flushes the CPU buffers and the PSB buffers.
SISCI_API_EXPORT void	DISStartDmaTransfer (sci_dma_queue_t dq, sci_local_segment_t localSegment, sci_remote_segment_t remoteSegment, unsigned int localOffset, unsigned int size, unsigned int remoteOffset, sci_cb_dma_t callback, void callbackArg, unsigned int flags, sci_error_t error)
	DISStartDmaTransfer starts the execution of a DMA queue.
SISCI_API_EXPORT void	DISStartDmaTransferVec (sci_dma_queue_t dq, sci_local_segment_t localSegment, sci_remote_segment_t remoteSegment, unsigned int vecLength, dis_dma_vec_t disDmaVec, sci_cb_dma_t callback, void callbackArg, unsigned int flags, sci_error_t *error)
	DISStartDmaTransferVec starts the execution of a DMA queue.

Detailed Description

Low-level SISCI software functional specification.

Remarks:: This document is valid for Dolphin Express SCI and Dolphin Express DX products. Some extensions, e.g. Reflective Memory is only available for Dolphin Express DX. Please read the manual carefully and consult the available SISCI example code found in the distribution.

Function Documentation

SISCI_API_EXPORT void SCIInitialize	(	unsigned int	flags,
		sci_error_t *	error
	)

Initializes the SISCI library.

SCIInitialize must be called before SCIOpen().

Parameters:

	flags	see below
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific error codes for this function.

SISCI_API_EXPORT void SCITerminate ( void )

Terminates the SISCI library.

SCITerminate must be called after SCIClose().

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific error codes for this function.

SISCI_API_EXPORT void SCIOpen	(	sci_desc_t *	sd,
		unsigned int	flags,
		sci_error_t *	error
	)

Opens an SISCI virtual device.

SCIOpen opens an SISCI virtual device, that is a channel to the driver. It creates and initializes a new descriptor for an SISCI virtual device, to be used in subsequent calls to API functions. A single virtual device can be used for all API functions, but only one of each. E.g. if you want to do multiple connections, multiple virtual devices needs to be opened.

If the flag SCI_FLAG_THREAD_SAFE is specified, operations on resources depending on the virtual device are executed in a thread-safe manner.

Parameters:

	sd	handle to the new SISCI virtual device descriptor
	flags	see below
	error	error information

Flags:

SCI_FLAG_THREAD_SAFE
Operations on resources associated with this descriptor will be performed in a thread-safe manner.

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.
Note:
The virtual device handle can handle one connection only I.e., one local segment and one remote segment

SISCI_API_EXPORT void SCIClose	(	sci_desc_t	sd,
		unsigned int	flags,
		sci_error_t *	error
	)

Closes an open SISCI virtual device.

SCIClose closes an open SISCI virtual device, destroying its descriptor. After this call the handle to the descriptor becomes invalid and should not be used. SCIClose does not deallocate possible resources that are still in use, rather it fails if some of them exist.

Parameters:

	sd	handle to an open SISCI virtual device descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise:
SCI_ERR_BUSY
some resources depending on this virtual device are still in use

SISCI_API_EXPORT void SCIConnectSegment	(	sci_desc_t	sd,
		sci_remote_segment_t *	segment,
		unsigned int	nodeId,
		unsigned int	segmentId,
		unsigned int	localAdapterNo,
		sci_cb_remote_segment_t	callback,
		void *	callbackArg,
		unsigned int	timeout,
		unsigned int	flags,
		sci_error_t *	error
	)

Connects an application to a memory segment made available on a remote node.

SCIConnectSegment() connects an application to a memory segment made available on a remote node (see SCISetSegmentAvailable()) and creates and initializes a descriptor for the connected segment. A call to this function enters the state diagram for a remote segment shown in Figure 2.3. If a timeout different from SCI_INFINITE_TIMEOUT is passes to the function, the attempt to connect gives up after the specified number of milliseconds.

The connection operation is by default synchronous: the function returns only when the operation has completed; a failure exits the state diagram and gives back a handle that is not valid and that should not be used. If the flag SCI_FLAG_ASYNCHRONOUS_CONNECT is specified the connection is instead asynchronous: the function returns immediately with a valid handle. In case of failure, the descriptor has to be explicitly destroyed calling SCIDisconnectSegment().

A callback function can be specified to be invoked when an event concerning the segment happens; the intention to use the callback has to be explicitly declared with the flag SCI_FLAG_USE_CALLBACK. Alternatively, interesting events can be caught using the function SCIWaitForRemoteSegmentEvent.

Once a memory segment has been connected, it can either be mapped in the address space of the program (see SCIMapRemoteSegment()) or be used directly for DMA transfers (see SCIEnqueueDMATransfer). A successful connection also generates an SCI_CB_CONNECT event directed to the application that created the segment (see SCICreateSegment and sci_cb_local_segment_t).

Parameters:

	sd	handle to an open SISCI virtual device descriptor
	segment	handle to the new connected segment descriptor
	nodeId	identifier of the node where the segment is allocated
	segmentId	identifier of the segment to connect
	localAdapterNo	number of the local adapter used for the connection
	callback	function called when an asynchronous event affecting the segment occurs
	callbackArg	user-defined parameter passed to the callback function
	timeout	time in milliseconds to wait for the connection to complete
	flags	see below
	error	error information

Flags:

SCI_FLAG_USE_CALLBACK
The specified callback is active
SCI_FLAG_ASYNCHRONOUS_CONNECT
The connection is asynchronous
SCI_FLAG_BROADCAST
This flag must be set to enable the use of DX broadcast and the reflected memory mechanism. This function connects to all available remote broadcast segments with the same segmentId. The remote segments must be created with the function SCICreateSegment() and with the SCI_FLAG_BROADCAST flag specified. SCICreateSegment(..,SCI_FLAG_BROADCAST). This functionality is only available for DX products.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following.
SCI_ERR_NO_SUCH_SEGMENT
The remote segment to connect could not be found
SCI_ERR_CONNECTION_REFUSED
The connection attempt has been refused by the remote node
SCI_ERR_TIMEOUT
The function timed out
SCI_ERR_NO_LINK_ACCESS
It was not possible to communicate via the local adapter
SCI_ERR_NO_REMOTE_LINK_ACCESS
it was not possible to communicate via a remote switch port
SCI_ERR_SYSTEM
The callback thread could not be created

SISCI_API_EXPORT void SCIDisconnectSegment	(	sci_remote_segment_t	segment,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIDisconnectSegment disconnects from the give mapped shared memory segment.

SCIDisconnectSegment() disconnects from a remote segment connected by calling SCIConnectSegment() or SCIConnectSCISpace() and deallocates the corresponding descriptor. After this call the handle to the descriptor becomes invalid and should not be used.

If the segment was connected using SCIConnectSegment() the execution of SCIDisconnectSegment also generates an SCI_CB_DISCONNECT event directed to the application that created the segment (see SCICreateSegment() and sci_cb_local_segment_t).

Parameters:

	segment	handle to the connected segment descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise:
SCI_ERR_BUSY
The segment is currently mapped or in use

SISCI_API_EXPORT unsigned int SCIGetRemoteSegmentSize ( sci_remote_segment_t segment )

SCIGetRemoteSegmentSize returns the size in bytes of a remote segment after it has been connected with SCIConnectSegment or SCIConnectSCISpace.

Parameters:

segment

handle to the connected segment descriptor

Returns:

The function returns the size in bytes of the remote segment.

Errors:

No error information is provided by the function.

SISCI_API_EXPORT sci_segment_cb_reason_t SCIWaitForRemoteSegmentEvent	(	sci_remote_segment_t	segment,
		sci_error_t *	status,
		unsigned int	timeout,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIWaitForRemoteSegmentEvent blocks a program until an event concerning the remote segment has arrived.

If a timeout different from SCI_INFINITE_TIMOUT is specified the function gives up when the timeout expires. SCIWaitForRemoteSegmentEvent cannot be used if a callback associated with the remote segment is active (see SCIConnectSegment).

Parameters:

	segment	handle to the connected segment descriptor
	status	istatus information
	timeout	time in milliseconds to wait before giving up
	flags	not used
	error	error information

Returns:

If successful, the function returns the reason that generated the received event.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_TIMEOUT
The function timed out after specified timeout value.
SCI_ERR_ILLEGAL_OPERATION
Illegal operation.
SCI_ERR_CANCELLED
The segment has been disconnected. The handle is invalid when this error is returned

SISCI_API_EXPORT volatile void* SCIMapRemoteSegment	(	sci_remote_segment_t	segment,
		sci_map_t *	map,
		unsigned int	offset,
		unsigned int	size,
		void *	addr,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIMapRemoteSegment maps an area of a remote segment connected with either SCIConnectSegment or SCIConnectSCISpace into the addressable space of the program and returns a pointer to the beginning of the mapped area.

The function also creates and initializes a descriptor for the mapped segment. If a virtual address is suggested, together with the flag SCI_FLAG_FIXED_MAP_ADDR, the function tries first to map the segment at that address. If the flag SCI_FLAG_READONLY_MAP is specified, the remote segment is mapped in read-only more.

Flags:

SCI_FLAG_BROADCAST
This flag must be set to enable the use of DX broadcast and the reflected memory mechanism. Maps the remote segment into the addressable space of the program and returns a pointer to the beginning of the mapped remote broadcast segments. All remote segments are accessable through this pointer. This functionality is only available for DX products.

SCI_FLAG_EXACT_MAP_RESOURCE
The low level physical map will be occupying exact number of att entries. With this flag, only those att pages that are requested by the size parameter are marked as occupied. Previously, the number of ATTs used was as large as the remote segment.

SCI_FLAG_SHARED_MAP
The low level physical map may be shared by other applications.

SCI_FLAG_FIXED_MAP_ADDR
Map at the suggested virtual address

SCI_FLAG_READONLY_MAP
The segment is mapped in read-only mode

SCI_FLAG_LOCK_OPERATION
Enable Lock operations (fetch and add)

SCI_FLAG_READ_PREFETCH_AGGR_HOLD_MAP
Enable aggressive prefetch with speculative hold.

SCI_FLAG_READ_PREFETCH_HOLD_MAP
The PSB66 will prefetch 128 bytes. The PSB64 will prefetch 64 bytes. The stream will keep the prefetched data until all bytes have been read. As soon as some bytes have been read, the stream mey be used by another request.

SCI_FLAG_READ_PREFETCH_NO_HOLD_MAP
The PSB66 will prefetch 128 bytes. The PSB64 will prefetch 64 bytes. As soon as the PCI read retry has been accepted, the stream will change state to FREE, even if less than 128 bytes were actually read.

SCI_FLAG_IO_MAP_IOSPACE
Mapping using non-prefetch space (iospace) No prefetching, or speculative hold enabled.

SCI_FLAG_WRITES_ENABLE_GATHER_MAP
Enable write gathering in non-prefetch space (iospace)

SCI_FLAG_DMOVE_MAP
Enable DMOVE packet type. The stream will be set into FREE state immediately.

SCI_FLAG_WRITES_DISABLE_GATHER_MAP
Disable use of gather.

SCI_FLAG_DISABLE_128_BYTES_PACKETS
Disable use of 128-Byte packets

SCI_FLAG_CONDITIONAL_INTERRUPT_MAP
Write operations through this map will cause an atomic "fetch-and-add-one" operation on remote memory, but in addition an interrupt will be generated if the target memory location contained a "null value" before the add operation was carried out. The conditional interrupt flag must also be specified in the SCIRegisterInterruptFlag() function.

SCI_FLAG_UNCONDITIONAL_INTERRUPT_MAP
Write operations through this map will cause an interrupt for the remote adapter "in addition to" updating the corresponding remote memory location with the data being written. The unconditional interrupt flag must also be specified in the SCIRegisterInterruptFlag() function.

SCI_FLAG_WRITE_BACK_CACHE_MAP
Enable cacheing of the mapped region. Writes through this map will be written to a write back cache, hence no remote updates until the cache line is flushed. The application is responsible for the cache flush operation. The SCImemCpy() function will handle this correctly by doing cache flushes internally. If this flag has been used for SciMapRemoteSegment it has to be set for SciMemWrite. This feature is architechture dependent and not be available on all plattforms.

SCI_FLAG_NO_MEMORY_LOOPBACK_MAP
Forces a map to a remote segment located in the local machine to be mapped using adapter loopback. This is useful i.e. if you want to use a regular map access to be serialized with lock operations. The default behaviour is to access a remte segment located in the local machine as a local MMU operation.

SCI_FLAG_READ_ORDERING_MAP
Forces all outstanding SCI requests to be completed before a read operation is accepted.

SCI_FLAG_WRITE_ORDERING_MAP
Forces all outstanding SCI requests to be completed before a write operation is accepted.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_NOT_CONNECTED
The links between local and remote node are not active.
SCI_ERR_OUT_OF_RANGE
The sum of the offset and size is larger than the segment size.
SCI_ERR_SIZE_ALIGNMENT Size is not correctly aligned as required by the implementation.
SCI_ERR_OFFSET_ALIGNMENT
Offset is not correctly aligned as required by the implementation.
SCI_ERR_BUSY
SCI_FLAG_EXACT_MAP_RESOURCE was called on the first or the second SCIMapRemoteSegment for the same remote_segment_t pointer.

SISCI_API_EXPORT void* SCIMapLocalSegment	(	sci_local_segment_t	segment,
		sci_map_t *	map,
		unsigned int	offset,
		unsigned int	size,
		void *	addr,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIMapLocalSegment maps an area of a memory segment created with SCICreateSegment into the addressable space of the program and returns a pointer to the beginning of the mapped area.

The function also creates and initializes a descriptor for the mapped segment. If a virtual address is suggested, together with the flag SCI_FLAG_FIXED_MAP_ADDR, the function tries first to map the segment at that address. If the flag SCI_FLAG_READONLY_MAP is specified, the local segment is mapped in read-only more.

Parameters:

	segment	handle to the descriptor of the local segment to be mapped
	map	handle to the new mapped segment descriptor
	offset	offset inside the local segment where the mapping should start
	size	size of the area of the local segment to be mapped, starting from offset
	addr	suggested virtual address where the segment should be mapped
	flags	see below
	error	error information

Flags::

SCI_FLAG_FIXED_MAP_ADDR
The function should try first to map at the suggested virtual address
SCI_FLAG_READONLY_MAP
The segment is mapped in read-only mode

Returns:

If successful, the function returns a pointer to the beginning of the mapped area. In case of error it returns 0.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_OUT_OF_RANGE
The sum of the offset and size is larger than the segment size.
SCI_ERR_SIZE_ALIGNMENT
Size is not correctly aligned as required by the implementation.
SCI_ERR_OFFSET_ALIGNMENT
Offset is not correctly aligned as required by the implementation.

SISCI_API_EXPORT void SCIUnmapSegment	(	sci_map_t	map,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIUnmapSegment unmaps from the programs address space a segment that was mapped either with SCIMapLocalSegment or with SCIMapRemoteSegment.

It also destroys the corresponding descriptor, therefore after this call the handle to the descriptor becomes invalid and should not be used.

Parameters:

	map	handle to the mapped segment descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_BUSY
The map is currently in use.

SISCI_API_EXPORT void SCICreateSegment	(	sci_desc_t	sd,
		sci_local_segment_t *	segment,
		unsigned int	segmentId,
		unsigned int	size,
		sci_cb_local_segment_t	callback,
		void *	callbackArg,
		unsigned int	flags,
		sci_error_t *	error
	)

SCICreateSegment allocates a memory segment and creates and initializes a descriptor for a local segment.

A host-wide unique identifier is associated to the new segment. This function causes a local segment to enter its state diagram, shown in Figure 2.2. A callback function can be specified to be invoked when an event concerning the segment happens (see sci_segment_cb_reason_t); the intention to use the callback has to be explicitly declared with the flag SCI_FLAG_USE_CALLBACK. Alternatively, interesting events can be caught using the function SCIWaitForLocalSegmentEvent. If the flag SCI_FLAG_EMPTY is specified, no memory is allocated for the segment and only the descriptor is initialized. Using the flag SCI_FLAG_PRIVATE declares that the segment will never be made available for external connections (see SCISetSegmentAvailable); in this case the specified segment identifier is meaningless, avoiding the internal check for its uniqueness. These two flags are useful to transform a user-allocated piece of memory (e.g. via malloc) into a mapped segment to be used in a block transfer (see SCITransferBlock and SCITransferBlockAsync): an empty and private segment is first created and then associated to the user-allocated memory (see SCIRegisterSegmentMemory); the segment can then be transformed in a mapped segment (see SCIMapLocalSegment) and possibly prepared for a DMA transfer (see SCIPrepareSegment).

Parameters:

	sd	handle to an open SISCI virtual device descriptor
	segment	handle to the new local segment descriptor
	segmentId	segment identifier
	size	segment size; if SCI_FLAG_EMPTY is specified, size means the maximum size of the memory area that can be associated with this local segment
	callback	callback function called when an asynchronous event affecting the local segment occurs
	callbackArg	user-defined argument passed to the callback function
	flags	not used
	error	error information

Flags:

SCI_FLAG_USE_CALLBACK The callback function will be invoked for events on this segment.
SCI_FLAG_EMPTY No memory will be allocated for the segment.
SCI_FLAG_PRIVATE The segment will be private meaning it will never be any connections to it.
SCI_FLAG_BROADCAST
This flag must be set to enable use of the DX broadcast and the reflected memory mechanism. Creates a segment for broadcast/reflected memory capabilities. All segments in a broadcast group must have the same segmentId. This functionality is only available for DX products.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_SEGMENTID_USED
The segment with this segmentId is already used
SCI_ERR_SIZE_ALIGNMENT
Size is not correctly aligned as required by the implementation.
SCI_ERR_SYSTEM
The callback thread could not be created

SISCI_API_EXPORT sci_segment_cb_reason_t SCIWaitForLocalSegmentEvent	(	sci_local_segment_t	segment,
		unsigned int *	sourcenodeId,
		unsigned int *	localAdapterNo,
		unsigned int	timeout,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIWaitForLocalSegmentEvent blocks a program until an event concerning the local segment has arrived.

If a timeout different from SCI_INFINITE_TIMOUT is specified the function gives up when the timeout expires. SCIWaitForLocalSegmentEvent cannot be used if a callback associated with the local segment is active (see SCICreateSegment).

Parameters:

	segment	handle to local segment descriptor
	sourcenodeId	identifier of the node that have generated the event
	localAdapterNo	number of the local adapter that receive the event
	timeout	time in milliseconds to wait before giving up
	flags	not used
	error	error information

Returns:

If successful, the function returns the reason corresponding to the received event.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_TIMEOUT
The function timed out after specified timeout value.
SCI_ERR_CANCELLED
The wait operation has been cancelled du to a SCIRemoveSegment() on the same handle. The handle is invalid when this error is returned.

SISCI_API_EXPORT void SCIPrepareSegment	(	sci_local_segment_t	segment,
		unsigned int	localAdapterNo,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIPrepareSegment guarantees that a local segment is accessible by an SCI adapter.

Parameters:

	segment	handle to the local segment descriptor
	localAdapterNo	number of the adapter for which the segment is prepared
	flags	not used
	error	error information

Flags:

SCI_FLAG_DMA_SOURCE_ONLY
The segment will be used as a source segment for DMA operations. On some system types this will enable the SISCI driver to use performance improving features.

SCI_FLAG_BROADCAST
This flag must be set to enable use of the DX broadcast and the reflected memory mechanism. This function prepares the segment for broadcast/reflected memory capabilities. This functionality is only available for DX products.

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT void SCIRemoveSegment	(	sci_local_segment_t	segment,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIRemoveSegment frees the resources used by a local segment.

The physical memory is deallocated only if it was allocated when the segment was created with SCICreateSegment. The function also destroys the descriptor associated with the local segment; after this call the handle to the descriptor becomes invalid and should not be used. SCIRemoveSegment fails if other resources, either locally or remotely, depend on it (see Figure 2.1). Before calling this function, the program should consider the use of SCISetSegmentUnavailable with the flags NOTIFY or FORCE_DISCONNECT.

Parameters:

	segment	handle to local segment descriptor
	flags	see below
	error	error information

Flags:

SCI_FLAG_FORCE_REMOVE Force the removal of the segment even if there still exists active connections.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise:
SCI_ERR_BUSY
Unable to remove the segment. The segment is currently in use.

Warning:: The `SCI_FLAG_FORCE_REMOVE' is _NOT_ intended for general use. Use with caution and preferably only after consulting with Dolphin. Incorrect use may cause uncontrolled remote access to unintended memory and may have severe impact on system security and stability. If `SCI_FLAG_FORCE_REMOVE' is used on segments with attached physical memory, it's the responsiblity of the user to assure proper management of that memory and to assure that all remote connections is closed prior to (possibly) releasing that memory.

SISCI_API_EXPORT void SCISetSegmentAvailable	(	sci_local_segment_t	segment,
		unsigned int	localAdapterNo,
		unsigned int	flags,
		sci_error_t *	error
	)

SCISetSegmentAvailable makes a local segment visible to remote nodes, that can then connect to it.

According to the state diagram shown in Figure 2.2 a local segment can be made available only after it has been prepared (see SCIPrepareSegment).

Parameters:

	segment	handle to local segment descriptor
	localAdapterNo	number of the local adapter where the local segment is made available for connections
	flags	not used.
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_SEGMENT_NOT_PREPARED
The segment has not been prepared for access from this adapter.
SCI_ERR_ILLEGAL_OPERATION
The segment is created with the SCI_FLAG_PRIVATE flag specified and therefore has no segmentId.

SISCI_API_EXPORT void SCISetSegmentUnavailable	(	sci_local_segment_t	segment,
		unsigned int	localAdapterNo,
		unsigned int	flags,
		sci_error_t *	error
	)

SCISetSegmentUnavailable hides an available segment to remote nodes; no new connections will be accepted on that segment.

If the flag SCI_FLAG_NOTIFY is specified, the operation is notified to the remote nodes connected to the local segment. The notification should be interpreted as an invitation to disconnect. If the flag SCI_FLAG_FORCE_DISCONNECT is specified, the remote nodes are forced to disconnect. These two flags can be used to implement a smooth removal of a local segment (see SCIRemoveSegment).

Parameters:

	segment	handle to the local segment descriptor
	localAdapterNo	number of the local adapter where the local segment was made available
	flags	see below
	error	error information

Flags:

SCI_FLAG_FORCE_DISCONNECT
The connected nodes are forced to disconnect
SCI_FLAG_NOTIFY
The connected nodes receive a notification of the operation

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise:
SCI_ERR_ILLEGAL_OPERATION
The operation is illegal in the current state of the segment

SISCI_API_EXPORT void SCICreateMapSequence	(	sci_map_t	map,
		sci_sequence_t *	sequence,
		unsigned int	flags,
		sci_error_t *	error
	)

SCICreateMapSequence creates and initializes a new sequence descriptor that can be used to check for errors occurring in a transfer of data from or to a mapped segment.

If the flag SCI_FLAG_FAST_BARRIER is specified, when a store barrier operation is applied to the sequence, it is executed in the fastest possible way allowed by the SCI adapter. There could be a limited number of fast store barrier resources available, therefore SCICreateMapSequence fails if none are left.

Parameters:

	map	handle to a valid mapped segment descriptor
	sequence	handle to the new sequence descriptor
	flags	see below
	error	error information

Flags:

SCI_FLAG_FAST_BARRIER
Use the fast store barrier

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT void SCIRemoveSequence	(	sci_sequence_t	sequence,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIRemoveSequence destroys a sequence descriptor.

After this call the handle to the descriptor becomes invalid and should not be used.

Parameters:

	sequence	handle to the sequence descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT sci_sequence_status_t SCIStartSequence	(	sci_sequence_t	sequence,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIStartSequence performs the preliminary check of the error flags on the SCI adapter before starting a sequence of read and write operations on the concerned mapped segment.

Subsequent checks are done calling SCICheckSequence, as far as no errors occur, in which case SCIStartSequence shall be called again until it returns SCI_SEQ_OK. If the return value is SCI_SEQ_PENDING there is a pending error and the program is required to call SCIStartSequence until it succeeds, before doing other transfer operations on the segment.

Parameters:

	sequence	handle to the sequence descriptor
	flags	not used
	error	error information

Returns:

The function returns the status of the sequence.

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT sci_sequence_status_t SCICheckSequence	(	sci_sequence_t	sequence,
		unsigned int	flags,
		sci_error_t *	error
	)

SCICheckSequence checks if any error has occurred in a data transfer controlled by a sequence since the last check.

The previous check can have been done by calling either SCIStartSequence, that also initiates the sequence, or SCICheckSequence itself. SCICheckSequence can be invoked several times in a row without calling SCIStartSequence, as far as it does not fail, returning SCI_SEQ_OK (i.e. there were no transmission errors in the sequence). If the return value is SCI_SEQ_RETRIABLE the operation can be immediately retried. A return value SCI_SEQ_NOT_RETRIABLE means that there have been a fatal error, probably also notified via callbacks to the corresponding mapped segment; it is not legal to execute other read or write operations on the segment until a call to SCIStartSequence does not fail. As well, if the return value is SCI_SEQ_PENDING it is not legal to perform read or write operations on the segment until a call to SCIStartSequence does not fail. The default behaviour of SCICheckSequence is to flush the write buffers of the adapter and to wait for all the outstanding write requests to be completed. To prevent this actions the caller has to use specific flags.

Parameters:

	sequence	handle to a sequence descriptor
	flags	see below
	error	error information

Flags:

SCI_FLAG_NO_FLUSH
Do not flush the write buffers
SCI_FLAG_NO_STORE_BARRIER
Do not wait for outstanding write requests

Returns:

The function returns the status of the sequence.

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific error values for this function.

SISCI_API_EXPORT void SCIStoreBarrier	(	sci_sequence_t	sequence,
		unsigned int	flags
	)

SCIStoreBarrier synchronizes all the accesses to a mapped segment.

When the function returns the write buffers have been flushed and all outstanding SCI transactions related to the mapped segment have completed.

Parameters:

	sequence	handle to the mapped segment descriptor
	flags	not used

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT void SCIFlushReadBuffers ( sci_sequence_t sequence )

SCIFlushReadBuffers flushes the prefetch buffers associated with a sequence.

Parameters:

sequence

handle to the sequence descriptor.

Errors:

On successful completion, error points to the SCI_ERR_OK value. No information error is provided by the function.

SISCI_API_EXPORT int SCIProbeNode	(	sci_desc_t	sd,
		unsigned int	localAdapterNo,
		unsigned int	nodeId,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIProbeNode checks if a remote node is reachable.

Parameters:

	sd	handle to an open SISCI virtual device descriptor
	localAdapterNo	number of the local adapter used for the check
	nodeId	identifier of the remote node
	flags	not used
	error	error information

Returns:

The function returns 1 when the remote node can be reached, otherwise returns 0.

Errors:

Errors If the function returns 1, the error value points to SCI_ERR_OK; otherwise it points to one of the following:
SCI_ERR_NO_LINK_ACCESS
It was not possible to communicate via the local adapter.
SCI_ERR_NO_REMOTE_LINK_ACCESS
It was not possible to communicate via a remote switch port.

SISCI_API_EXPORT unsigned int SCIGetCSRRegister	(	sci_desc_t	sd,
		unsigned int	localAdapterNo,
		unsigned int	SCINodeId,
		unsigned int	CSROffset,
		unsigned int	flags,
		sci_error_t *	error
	)

SISCI Priveleged function SCIGetCSRRegister reads the value contained in a location of the CSR space of an SCI node.

A node is specified using its physical node identifier. The location is determined by an offset from the base address of the CSR space.

Parameters:

	sd	handle to an open SISCI virtual device descriptor
	localAdapterNo	number of the local adapter used for the communication
	SCINodeId	physical identifier of the remote node where the CSR space resides
	CSROffset	offset in the CSR space
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise:
SCI_ERR_NO_LINK_ACCESS
It was not possible to communicate via the local adapter.
SCI_ERR_NO_REMOTE_LINK_ACCESS
It was not possible to communicate via a remote switch port.

SISCI_API_EXPORT void SCISetCSRRegister	(	sci_desc_t	sd,
		unsigned int	localAdapterNo,
		unsigned int	SCINodeId,
		unsigned int	CSROffset,
		unsigned int	CSRValue,
		unsigned int	flags,
		sci_error_t *	error
	)

SISCI Priveleged function SCISetCSRRegister writes a value to a location of the CSR space of an SCI node.

A node is specified using its physical node identifier. The location is determined by an offset from the base address of the CSR space.

Parameters:

	sd	handle to an open SISCI virtual device descriptor
	localAdapterNo	number of the local adapter used for the communication
	SCINodeId	physical identifier of the remote node where the CSR space resides
	CSROffset	location offset in the CSR space
	CSRValue	value to write in the location
	flags	not used
	error	error information

Flags:

SCI_ERR_NO_LINK_ACCESS
It was not possible to communicate via the local adapter.
SCI_ERR_NO_REMOTE_LINK_ACCESS
It was not possible to communicate via a remote switch port.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_NO_LINK_ACCESS
It was not possible to communicate via the local adapter
SCI_ERR_NO_REMOTE_LINK_ACCESS
It was not possible to communicate via a remote switch port

SISCI_API_EXPORT unsigned int SCIGetLocalCSR	(	sci_desc_t	sd,
		unsigned int	localAdapterNo,
		unsigned int	CSROffset,
		unsigned int	flags,
		sci_error_t *	error
	)

SISCI Priveleged function Further function description missing.

Parameters:

	sd	handle to an open SISCI virtual device descriptor
	localAdapterNo	number of the local adapter used for CSR
	CSROffset	location offset in the CSR space
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT void SCISetLocalCSR	(	sci_desc_t	sd,
		unsigned int	localAdapterNo,
		unsigned int	CSROffset,
		unsigned int	CSRValue,
		unsigned int	flags,
		sci_error_t *	error
	)

SISCI Priveleged function Further function description missing.

Parameters:

	sd	handle to an open SCI virtual device descriptor
	localAdapterNo	number of the local adapter used for CSR
	CSROffset	location offset in the CSR space
	CSRValue
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT void SCIAttachPhysicalMemory	(	sci_ioaddr_t	ioaddress,
		void *	address,
		unsigned int	busNo,
		unsigned int	size,
		sci_local_segment_t	segment,
		unsigned int	flags,
		sci_error_t *	error
	)

SISCI Priveleged function SCIAttachPhysicalMemory enables usage of physical devices and memory regions where the Physical PCI bus address ( and mapped CPU address ) are already known.

The function will register the physical memory as a SISCI segment which can be connected and mapped as a regular SISCI segment.

Requirements: SCICreateSegment() with flag SCI_FLAG_EMPTY must have been called in advance

Parameters:

	ioaddress	This is the address on the PCI bus that a PCI bus master has to use to write to the specified memory
	address	This is the (mapped) virtual address that the application has to use to access the device. This means that the device has to be mapped in advance bye the devices own driver. If the device is not to be accessed by the local CPU, the address pointer shold be set to NULL.
	busNo	TBD
	size	TBD
	segment	TBD
	flags	TBD
	error	TBD

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT void SCIQuery	(	unsigned int	command,
		void *	data,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIQuery provides some information about the underlying system.

The information can be vendor dependent, but some requests are specified in the API and shall be satisfied: the vendor identifier, the version of the API implemented, some adapter characteristics. Each request defines its own data structure to be used as input and output to SCIQuery. The memory management (allocation and deallocation) of the data structures has to be performed by the caller.

Parameters:

	command	type of information required
	data	generic data structure for possible sub-commands and output information
	flags	not used
	error	error information

Commands

Three major commands are as below:
SCI_Q_VENDORID
The vendor identifier is returned in a data structure of type sci_query_string
SCI_Q_API
The version of the API implemented is returned in a data structure of type sci_query_string
SCI_Q_ADAPTER
Certain adapter information, depending on the sub-command (see below), is returned in a data structure of type

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise:
SCI_ERR_ILLEGAL_QUERY
Unrecognized command.

SISCI_API_EXPORT void SCIGetLocalNodeId	(	unsigned int	adapterNo,
		unsigned int *	nodeId,
		unsigned int	flags,
		sci_error_t *	error
	)

Get local node id.

Parameters:

	adapterNo	number of the local adapter to get node id
	nodeId	identifier of the local node
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value, no specific errors for this function.

SISCI_API_EXPORT void SCIGetNodeIdByAdapterName	(	char *	adaptername,
		dis_nodeId_list_t *	nodeId,
		dis_adapter_type_t *	type,
		unsigned int	flags,
		sci_error_t *	error
	)

Funtion description missing.

Parameters:

	adaptername	name of the adapter to query node id
	nodeId
	type
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value, no specific errors for this function.

void SCIGetNodeInfoByAdapterName	(	char *	adaptername,
		unsigned int *	adapterNo,
		dis_nodeId_list_t *	nodeIdlist,
		dis_adapter_type_t *	type,
		unsigned int	flags,
		sci_error_t *	error
	)

Funtion description missing.

Parameters:

	adaptername	names of the adapters to query node ids
	adapterNo	number of local adapter with the given adapter name
	nodeIdlist
	type
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value, no specific errors for this function.

SISCI_API_EXPORT void SCICreateDMAQueue	(	sci_desc_t	sd,
		sci_dma_queue_t *	dq,
		unsigned int	localAdapterNo,
		unsigned int	maxEntries,
		unsigned int	flags,
		sci_error_t *	error
	)

SCICreateDMAQueue allocates resources for a queue of DMA transfers and creates and initializes a descriptor for the new queue.

After the creation the state of the queue is IDLE (see sci_dma_queue_state_t). All the segments involved in the transfers included in the same DMA queue must use the same adapter, which is specified as a parameter in this function. If a handle to an existing queue is passed to this function it is overwritten with the handle to a new queue. The old queue is not affected but it may not be accessible any more.

Parameters:

	sd	handle to an open SISCI virtual device descriptor
	dq	handle to the new DMA queue descriptor
	localAdapterNo	number of the adapter whoseDMAengine will be used for the transfers
	maxEntries	maximum number of entries allowed in the DMA queue
	flags	not used
	error	error information

Flags:

SCI_FLAG_DMA_PHDMA
Create physical DMA queue. Please note that this is an priveleged operation.

Errors:

On successful completion, error points to the SCI_ERR_OK value, no specific errors for this function.

SISCI_API_EXPORT void SCIRemoveDMAQueue	(	sci_dma_queue_t	dq,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIRemoveDMAQueue frees the resources allocated for a DMA queue and destroys the corresponding descriptor.

After this call the handle to the DMA queue descriptor becomes invalid and should not be used. As shown in the state diagram in Figure 2.4, this function can be called only if the queue is either in the initial (IDLE) or in a final (DONE, ERROR or ABORTED) state, otherwise the operation is illegal and the error is detected (see sci_dma_queue_state_t).

Parameters:

	dq	handle to the DMA queue descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise:
SCI_ERR_ILLEGAL_OPERATION
Not allowed in this queue state.

Note:

This function is only available with SCI adapter cards.

SISCI_API_EXPORT sci_dma_queue_state_t SCIEnqueueDMATransfer	(	sci_dma_queue_t	dq,
		sci_local_segment_t	localSegment,
		sci_remote_segment_t	remoteSegment,
		unsigned int	localOffset,
		unsigned int	remoteOffset,
		unsigned int	size,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIEnqueueDMATransfer adds the specification of a new transfer to a DMA queue.

Either the source or the destination of the transfer must be a local segment. By default the transfer is from the local segment to the remote one; if the transfer is in the opposite direction, the flag SCI_FLAG_DMA_READ has to be specified. As shown in Figure 2.4, this function can be called only if the queue is either in the IDLE or in the GATHER states, otherwise the operation is illegal and the error is detected. If the function is successful the final state is GATHER (see sci_dma_queue_state_t). The local adapter used by the local and the remote segments must be the same than the one specified when the queue was created (see SCICreateDMAQueue).

Parameters:

	dq	handle to the DMA queue descriptor
	localSegment	handle to the local segment descriptor
	remoteSegment	handle to the remote segment descriptor
	localOffset	base address inside the local segment where data reside (or where data are transferred to, if the transfer is from the remote segment to the local one)
	remoteOffset	base address inside the remote segment where data are transferred to (or where data reside, if the transfer is from the remote segment to the local one)
	size	size of the data to be transferred
	flags	see below
	error	error information

Flags:

SCI_FLAG_DMA_READ
The DMA will be remote --> local (default is local --> remote)

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_OUT_OF_RANGE
The sum of the offset and size is larger than the segment size or larger than max DMA size.
SCI_ERR_MAX_ENTRIES
The DMA queue is full
SCI_ERR_ILLEGAL_OPERATION
Illegal operation
SCI_ERR_SIZE_ALIGNMENT
Size is not correctly aligned as required by the implementation.
SCI_ERR_OFFSET_ALIGNMENT
Offset is not correctly aligned as required by the implementation.
SCI_ERR_SEGMENT_NOT_PREPARED
The local segment has not been prepared for access from the adapter associated with the queue.
SCI_ERR_SEGMENT_NOT_CONNECTED
The remote segment is not connected through the adapter associated with the queue.

Note:

This function is only available with SCI adapter cards.

SISCI_API_EXPORT void SCIPostDMAQueue	(	sci_dma_queue_t	dq,
		sci_cb_dma_t	callback,
		void *	callbackArg,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIPostDMAQueue starts the execution of a DMA queue.

The function returns as soon as the transfer specifications contained in the queue are passed to the DMA engine of the adapter. If a callback function is specified and explicitly activated using the flag SCI_FLAG_USE_CALLBACK, it is asynchronously invoked when all the transfers have completed or if an error occurs during a transfer. Alternatively, an application can block waiting for the queue completion calling SCIWaitForDMAQueue. As shown in Figure 2.4, SCIPostDMAQueue can be called only if the queue is in the GATHER state, otherwise the operation is illegal and the error is detected. If the function is successful the final state is POSTED (see sci_dma_queue_state_t).

Parameters:

	dq	handle to the DMA queue descriptor
	callback	callback function to be invoked when all the DMA transfers have completed or in case an error occurs during a transfer
	callbackArg	user-defined parameter passed to the callback function
	flags	see below
	error	error information

Flags:

SCI_FLAG_USE_CALLBACK
The end of the transfer will cause the callback function to be invoked.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_ILLEGAL_OPERATION
Illegal operation
SCI_ERR_SYSTEM
The callback thread could not be created

Note:

This function is only available with SCI adapter cards.

SISCI_API_EXPORT void SCIAbortDMAQueue	(	sci_dma_queue_t	dq,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIAbortDMAQueue aborts a DMA transfer initiated with SCIPostDMAQueue.

Calling this function is really meaningful only if the queue is in the POSTED state. If the function is successful the final state is ABORTED (see sci_dma_queue_state_t). If the state is already ABORTED or if it is DONE or ERROR, the call is equivalent to a no-op. In all the other cases the call is illegal and the error is detected. There is a potential race condition if the call happens when the state is already changing from POSTED to either DONE or ERROR because the transfer has completed or an error has occurred. To check what happened the program should call SCIDMAQueueState.

Parameters:

	dq	handle to the DMA queue descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise:
SCI_ERR_ILLEGAL_OPERATION
Illegal operation

Note:

This function is only available with SCI adapter cards.

SISCI_API_EXPORT void SCIResetDMAQueue	(	sci_dma_queue_t	dq,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIResetDMAQueue resets a DMA queue (without removing it), so it can be reused for another chain of transfers.

According to the state diagram in Figure 2.4, this function can be called when the queue is in any state other than the POSTED state. If the function is successful the final state is IDLE (see sci_dma_queue_state_t).

Parameters:

	dq	handle to the DMA queue descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value, otherwise:
SCI_ERR_ILLEGAL_OPERATION
The state transition implied by this operation is not allowed in the current state of the queue.

Note:

This function is only available with SCI adapter cards.

SISCI_API_EXPORT sci_dma_queue_state_t SCIDMAQueueState ( sci_dma_queue_t dq )

SCIDMAQueueState returns the state of a DMA queue (see sci_dma_queue_state_t).

The call does not affect the state of the queue

Parameters:

dq

handle to the DMA queue descriptor

Returns:

The function returns the state of the DMA queue.

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

Note:

This function is only available with SCI adapter cards.

SISCI_API_EXPORT sci_dma_queue_state_t SCIWaitForDMAQueue	(	sci_dma_queue_t	dq,
		unsigned int	timeout,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIWaitForDMAQueue blocks a program until a DMA queue has finished (because of the completion of all the transfers or due to an error) or the timeout has expired.

If timeout is SCI_INFINITE_TIMOUT the function blocks until a relevant event arrives. The function returns the current state of the queue. According to the state diagram shown in Figure 2.4, calling this function is really meaningful only if the queue is in the POSTED state. If the state is in the ABORTED, DONE or ERROR states, the call is equivalent to a no-op. In all the other cases the call is illegal and the error is detected (see sci_dma_queue_state_t). SCIWaitForDMAQueue cannot be used if a callback associated with the DMA queue is active.

Parameters:

	dq	handle to a DMA queue descriptor
	timeout	timeout in milliseconds to wait before giving up
	flags	not used
	error	error information

Returns:

On successful completion, the function returns the current state of the DMA queue. In case of error the returned value is undefined.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the followings:
SCI_ERR_ILLEGAL_OPERATION
Illegal operation
SCI_ERR_TIMEOUT
The function timed out after specified timeout value.
SCI_ERR_CANCELLED
The wait was interrupted, due to arrival of signal.

Note:

This function is only available with SCI adapter cards.

SISCI_API_EXPORT void SCIphDmaEnqueue	(	sci_dma_queue_t	dmaqueue,
		unsigned int	size,
		sci_ioaddr_t	localBusAddr,
		unsigned int	remote_nodeid,
		unsigned int	remote_highaddr,
		unsigned int	remote_lowaddr,
		unsigned int	flags,
		sci_error_t *	error
	)

Funtion description missing.

Parameters:

	dmaqueue
	size	size size of the transfer
	localBusAddr
	remote_nodeid	identifier of the remote node which ...(*)
	remote_highaddr
	remote_lowaddr
	flags	see below
	error	error informations

Flags:

SCI_FLAG_DMA_READ

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

Note:

This function is only available with SCI adapter cards.

SISCI_API_EXPORT sci_dma_queue_state_t SCIphDmaStart	(	sci_dma_queue_t	dmaqueue,
		sci_cb_dma_t	callback,
		void *	callbackArg,
		unsigned int	flags,
		sci_error_t *	error
	)

Funtion description missing.

Parameters:

	dmaqueue
	callback	function called when an asynchronous event affecting the segment occurs.
	callbackArg	user-defined parameter passed to the callback function.
	flags	see below
	error	error information

Flags:

SCI_FLAG_DMA_WAIT

SCI_FLAG_USE_CALLBACK

SCI_FLAG_DMA_RESET

Errors:

On successful completion, error points to the SCI_ERR_OK value,otherwise:
SCI_ERR_SYSTEM
The callback thread could not be created

Note:

This function is only available with SCI adapter cards.

SISCI_API_EXPORT void SCICreateInterrupt	(	sci_desc_t	sd,
		sci_local_interrupt_t *	interrupt,
		unsigned int	localAdapterNo,
		unsigned int *	interruptNo,
		sci_cb_interrupt_t	callback,
		void *	callbackArg,
		unsigned int	flags,
		sci_error_t *	error
	)

SCICreateInterrupt creates an interrupt resource and make it available to remote nodes and initializes a descriptor for the interrupt.

An interrupt is associated by the driver with a unique number. If the flag SCI_FLAG_FIXED_INTNO is specified, the function tries to use the number passed by the caller.

Parameters:

	sd	handle to an open SISCI virtual device descriptor
	interrupt	handle to the new interrupt descriptor
	localAdapterNo	number of the local adapter used to make the interrupt
	interruptNo	number assigned to the interrupt
	callback	function called when the interrupt is triggered
	callbackArg	user-defined parameter passed to the callback function
	flags	see below
	error	error information

Flags:

SCI_FLAG_USE_CALLBACK
The specified callback is active
SCI_FLAG_FIXED_INTNO
The interrupt number is specified by the caller
SCI_FLAG_SHARED_INT

SCI_FLAG_COUNTING_INT
This flag will enable counting interrupts. This means that the number of trigged interrupts is equal to the number of received interrupts.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_INTNO_USED
This interrupt number is already used
SCI_ERR_SYSTEM
The callback thread could not be created

SISCI_API_EXPORT void SCIRemoveInterrupt	(	sci_local_interrupt_t	interrupt,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIRemoveInterrupt deallocates an interrupt resource and destroys the corresponding descriptor.

After this call the handle to the descriptor becomes invalid and should not be used.

Parameters:

	interrupt	handle to the local interrupt descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value,otherwise:
ECI_ERR_BUSY
The resource is used by a remote node. SCIRemoveInterrupt() should be called again to clean up the resource if the application wants to reuse the interrupt. If not, the driver will clean up when the application terminates.

SISCI_API_EXPORT void SCIWaitForInterrupt	(	sci_local_interrupt_t	interrupt,
		unsigned int	timeout,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIWaitForInterrupt blocks a program until an interrupt is received.

If a timeout different from SCI_INFINITE_TIMOUT is specified the function gives up when the timeout expires. SCIWaitForInterrupt cannot be used if a callback associated with the interrupt is active (see SCICreateInterrupt).

Parameters:

	interrupt	handle to the local interrupt descriptor
	timeout	time in milliseconds to wait before giving up
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value, otherwise to one of the followings:
SCI_ERR_TIMEOUT
The function timed out after specified timeout value.
SCI_ERR_CANCELLED
The wait was interrupted by a call to SCIRemoveInterrupt or by the arrival of a signal. The handle is invalid when this error code is returned.

SISCI_API_EXPORT void SCIConnectInterrupt	(	sci_desc_t	sd,
		sci_remote_interrupt_t *	interrupt,
		unsigned int	nodeId,
		unsigned int	localAdapterNo,
		unsigned int	interruptNo,
		unsigned int	timeout,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIConnectInterrupt connects the caller to an interrupt resource available on a remote node (see SCICreateInterrupt).

The function creates and initializes a descriptor for the connected interrupt.

Parameters:

	sd	handle to an open SISCI virtual device descriptor
	interrupt	handle to a new remote interrupt descriptor
	nodeId	identifier of the remote node where the interrupt has been created
	localAdapterNo	number of the local adapter used for the connection
	interruptNo	number assigned to the interrupt
	timeout	time in milliseconds to wait before giving up
	flags	see below
	error	error information

Flags:

SCI_FLAG_COUNTING_INT
This flag will enable counting interrupts. This means that the number of trigged interrupts is equal to the number of received interrupts. if SCI_FLAG_COUNTING_INT is not used, the interface guarentees that there always will be an remote interrupt generated after the first and after the last trigger. If interupts is triggered faster than the remote interrupt handler can handle, interrupts may be lost.

Errors:

On successful completion, error points to the SCI_ERR_OK value,otherwise to one of the followings:
SCI_ERR_NO_SUCH_INTNO
No such interrupt number.
SCI_ERR_CONNECTION_REFUSED
Connection attempt refused by remote node.
SCI_ERR_TIMEOUT
The function timed out after specified timeout value.

SISCI_API_EXPORT void SCIDisconnectInterrupt	(	sci_remote_interrupt_t	interrupt,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIDisconnectInterrupt disconnects an application from a remote interrupt resource and deallocates the corresponding descriptor.

After this call the handle to the descriptor becomes invalid and should not be used.

Parameters:

	interrupt	handle to the remote interrupt descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT void SCITriggerInterrupt	(	sci_remote_interrupt_t	interrupt,
		unsigned int	flags,
		sci_error_t *	error
	)

SCITriggerInterrupt triggers an interrupt on a remote node, after having connected to it with SCIConnectInterrupt.

What happens to the remote application that made the interrupt resource available depends on what it specified at the time it called SCICreateInterrupt.

Parameters:

	interrupt	handle to the remote interrupt descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT void SCIRegisterInterruptFlag	(	unsigned int	localAdapterNo,
		sci_local_interrupt_t *	interrupt,
		sci_local_segment_t	segment,
		unsigned int	offset,
		sci_cb_interrupt_t	callback,
		void *	callbackArg,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIRegisterInterruptFlag register an "interrupt flag" that is identified as an unique location within a local segment.

If successful, the resulting interrupt handle will have been associated with the specified local segment.

It is up to the (remote) client(s) to set up an "interrupt mapping" for the corresponding segment offset using either the

SCI_FLAG_CONDITIONAL_INTERRUPT_MAP

or the

SCI_FLAG_UNCONDITIONAL_DATA_INTERRUPT_MAP

option to "SCIMapRemoteSegment()". - I.e. after having established a connection to the corresponding segment. A trigger operation can then be implemented using a store operation via the relevant "interrupt map".

Parameters:

	localAdapterNo	number of the local adapter used for the interrupt.
	interrupt	handle to the local interrupt descriptor
	segment	handle to the local segment descriptor
	offset
	callback	function called when the interrupt is triggered (*)
	callbackArg	user-defined parameter passed to the callback function
	flags	see below
	error	error information

Flags:

SCI_FLAG_CONDITIONAL_INTERRUPT
Triggering is to take place using "conditional interrupts".

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT void SCIEnableConditionalInterrupt	(	sci_local_interrupt_t	interrupt,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIEnableConditionalInterrupt make sure that another HW interrupt will take place the next time the corresponding interrupt flag is triggered by a "conditional interrupt" operation.

Default semantics:

When successful, the client can rely on that the first subsequent trigger operation will cause a HW interrupt and subsequently cause the client handler function to be invoked.

If an interrupt was triggered in parallell with the enable operation, then the operation will fail (SCI_ERR_COND_INT_RACE_PROBLEM), and the client can not rely on another trigger operation will lead to handler invocation. Hence, any state checking normally associated with handling the corresponding interrupt should take place before attempting to enable again.

Parameters:

	interrupt	handle to the local interrupt descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value, otherwise:
SCI_ERR_COND_INT_RACE_PROBLEM
The enable operation failed because an incomming trigger operation happened concurrently.

SISCI_API_EXPORT void SCIDisableConditionalInterrupt	(	sci_local_interrupt_t	interrupt,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIDisableConditionalInterrupt prevent subsequent "conditional interrupt"trigger operations for the specified interupt flag from causing HW interrupt and handler invocations.

Default semantics:

If successful, no subsequent HW interrupts will take place, but handler invocations that have already been scheduled may still take place.

Parameters:

	interrupt	handle to the local interrupt descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific errors for this function.

SISCI_API_EXPORT void SCIGetConditionalInterruptTrigCounter	(	sci_local_interrupt_t	interrupt,
		unsigned int *	interruptTrigCounter,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIGetConditionalInterruptTrigCounter returns a value that indicates the number of times that this flag has been trigged since the last time it was enabled or disabled.

Calling the SCIEnableConditionalInterrupt / SCIDisableConditionalInterrupt functions will reset the counter value.

Default semantics:

If successful, no subsequent HW interrupts will take place, but handler invocations that have already been scheduled may still take place.

Errors:

On successful completion, error points to the SCI_ERR_OK value, otherwise:
SCI_ERR_OVERFLOW
The number of trig operations have exceeded the range that can be counted.

SISCI_API_EXPORT void SCIMemWrite	(	void *	memAddr,
		volatile void *	remoteAddr,
		unsigned int	size,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIMemWrite transfers efficiently a block of data from local memory to a mapped segment using the shared memory mode.

Parameters:

	memAddr	base address in virtual memory of the source
	remoteAddr	offset inside the mapped segment where the transfer should start
	size	size of the transfer
	flags	see below
	error	error informaiton

Flags:

SCI_FLAG_WRITE_BACK_CACHE_MAP
Only implemented for PowerPC (see documentation.for SciMapRemoteSegment)

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_SIZE_ALIGNMENT
Size is not correctly aligned as required by the implementation.
SCI_ERR_OFFSET_ALIGNMENT
Offset is not correctly aligned as required

SISCI_API_EXPORT void SCIMemWrite_mcast	(	void *	memAddr,
		volatile void *	remoteAddr[],
		unsigned int	size,
		unsigned int	dst_num,
		unsigned int	flags,
		sci_error_t *	error
	)

Function desription missing.

Parameters:

	memAddr	base address in virtual memory of the source
	remoteAddr	offset inside the mapped segment where the transfer should start
	size	size of the transfer
	dst_num
	flags	see below
	error	error information

Flags:

SCI_FLAG_WRITE_BACK_CACHE_MAP
Only implemented for PowerPC (see doc for SciMapRemoteSegment)

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_SIZE_ALIGNMENT
Size is not correctly aligned as required by the implementation.
SCI_ERR_OFFSET_ALIGNMENT
Offset is not correctly aligned as required

SISCI_API_EXPORT void SCIMemWrite_dual	(	volatile void *	memAddr,
		volatile void *	remoteAddr1,
		sci_map_t	remoteMap1,
		volatile void *	remoteAddr2,
		sci_map_t	remoteMap2,
		unsigned int	size,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIMemWrite_dual transfers efficiently a block of data from local memory to two mapped segments using the shared memory mode.

If the flag SCI_FLAG_ERROR_CHECK is specified the function also checks if errors have occurred during the data transfer.

Parameters:

	memAddr	base address in virtual memory of the source
	remoteAddr1
	remoteMap1
	remoteAddr2
	remoteMap2
	size	size of the transfer
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value.

SISCI_API_EXPORT void SCIMemCpy	(	sci_sequence_t	sequence,
		void *	memAddr,
		sci_map_t	remoteMap,
		unsigned int	remoteOffset,
		unsigned int	size,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIMemCpy transfers efficiently a block of data from local memory to a mapped segment using the shared memory mode.

If the flag SCI_FLAG_ERROR_CHECK is specified the function also checks if errors have occurred during the data transfer. If the flag SCI_FLAG_BLOCK_READ is specified, the transfer is from the mapped segment to the local memory.

Parameters:

	sequence	TBD
	memAddr	base address in virtual memory of the source
	remoteMap	handle to the descriptor of the mapped segment that is the destination of the transfer
	remoteOffset	offset inside the mapped segment where the transfer should start
	size	size of the transfer
	flags	see below
	error	error information

Flags:

SCI_FLAG_BLOCK_READ
The data transfer is from the remote segment to the local memory
SCI_FLAG_ERROR_CHECK
Perform error checking

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_OUT_OF_RANGE
The sum of the size and offset is larger than the corresponding map size.
SCI_ERR_SIZE_ALIGNMENT
Size is not correctly aligned as required by the implementation.
SCI_ERR_OFFSET_ALIGNMENT
Offset is not correctly aligned as required by the implementation.
SCI_ERR_TRANSFER_FAILED
The data transfer failed.

SISCI_API_EXPORT void SCIMemCopy	(	void *	memAddr,
		sci_map_t	remoteMap,
		unsigned int	remoteOffset,
		unsigned int	size,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIMemCopy transfers efficiently a block of data from local memory to a mapped segment using the shared memory mode.

SCIMemCopy is normally not recommened for perfomance reasons. Please use SCIMemCpy() where possible.

If the flag SCI_FLAG_ERROR_CHECK is specified the function also checks if errors have occurred during the data transfer. If the flag SCI_FLAG_BLOCK_READ is specified, the transfer is from the mapped segment to the local memory.

Parameters:

	memAddr	base address in virtual memory of the source
	remoteMap	handle to the descriptor of the mapped segment that is the destination of the transfer
	remoteOffset	offset inside the mapped segment where the transfer should start
	size	size of the transfer
	flags	see below
	error	error information

Flags:

SCI_FLAG_BLOCK_READ
The data transfer is from the remote segment to the local memory
SCI_FLAG_ERROR_CHECK
Perform error checking

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_OUT_OF_RANGE
The sum of the size and offset is larger than the corresponding map size.
SCI_ERR_SIZE_ALIGNMENT
Size is not correctly aligned as required by the implementation.
SCI_ERR_OFFSET_ALIGNMENT
Offset is not correctly aligned as required by the implementation.
SCI_ERR_TRANSFER_FAILED
The data transfer failed.

SISCI_API_EXPORT void SCIMemCpy_dual	(	sci_sequence_t	sequence1,
		sci_sequence_t	sequence2,
		void *	memAddr,
		sci_map_t	remoteMap1,
		sci_map_t	remoteMap2,
		unsigned int	remoteOffset,
		unsigned int	size,
		unsigned int	flags,
		sci_error_t *	error
	)

This function is experimental and subject to change, DO NOT USE.

SCIMemCpy_dual transfers efficiently a block of data from local memory to two mapped segments using the shared memory mode. If the flag SCI_FLAG_ERROR_CHECK is specified the function also checks if errors have occurred during the data transfer.

Parameters:

	sequence1
	sequence2
	memAddr	base address in virtual memory of the source
	remoteMap1
	remoteMap2
	remoteOffset	offset inside the mapped segment where the transfer
	size	size of the transfer
	flags	see below
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value.

SISCI_API_EXPORT void SCIMemCpy_mcast	(	sci_sequence_t	sequence[],
		void *	memAddr,
		sci_map_t	remoteMap[],
		unsigned int	remoteOffset[],
		unsigned int	size,
		unsigned int	dst_num,
		unsigned int	flags,
		sci_error_t *	error
	)

This function is experimental and subject to change, DO NOT USE.

Parameters:

	sequence	handle to the sequence descriptor
	memAddr	base address in virtual memory of the source
	remoteMap	handle to the descriptor of the mapped segment that is the destination of the transfer
	remoteOffset	offset inside the mapped segment where the transfer
	size	size of the transfer
	dst_num
	flags	see below
	error	error information

Flags:

SCI_FLAG_BLOCK_READ

SCI_FLAG_ERROR_CHECK

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_OUT_OF_RANGE
The sum of the size and offset is larger than the corresponding map size.
SCI_ERR_SIZE_ALIGNMENT
Size is not correctly aligned as required by the implementation.
SCI_ERR_OFFSET_ALIGNMENT
Offset is not correctly aligned as required by the implementation.
SCI_ERR_TRANSFER_FAILED
The data transfer failed.

SISCI_API_EXPORT void SCIRegisterSegmentMemory	(	void *	address,
		unsigned int	size,
		sci_local_segment_t	segment,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIRegisterSegmentMemory associates an area memory allocated by the program (e.g.

using malloc) with a local segment created passing the flag SCI_FLAG_EMPTY to SCICreateSegment. The memory area is identified by its base address in virtual address space and its size. It is illegal to use the same local segment to register different memory areas. The function can try to determine if the specified address is legal or not, but this highly depends on the underlying platform.

Parameters:

	address	base address of the user-allocated memory in the programs virtual address space
	size	size of the user-allocated memory to be associated with the local segment
	segment	handle to local segment descriptor
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_SIZE_ALIGNMENT
Size is not correctly aligned as required by the implementation.
SCI_ERR_ILLEGAL_ADDRESS
Illegal address.
SCI_ERR_OUT_OF_RANGE
Size is larger than the maximum size for the local segment.

SISCI_API_EXPORT void SCIConnectSCISpace	(	sci_desc_t	sd,
		unsigned int	localAdapterNo,
		sci_remote_segment_t *	segment,
		sci_address_t	address,
		unsigned int	size,
		unsigned int	flags,
		sci_error_t *	error
	)

SISCI Priveleged function SCIConnectSCISpace connects an application directly to a memory window in the adapter address space, defined by its base address and its size, without any restriction.

The function creates and initializes a descriptor for the connected segment. The whole responsibility of handling the segment is left to the programmer: no state diagram is defined, no callbacks can be specified, no callbacks are invoked on the node where the memory actually resides. The function has only the synchronous version; if the connection fails the returned handle is not valid and should not be used; in this case the related descriptor need not be destroyed with SCIDisconnectSegment. Once the address window has been connected, it can either be mapped in the address space of the program (see SCIMapRemoteSegment) or be used directly for DMA transfers (see SCIEnqueueDMATransfer).

Parameters:

	sd	handle to an open SISCI virtual device descriptor
	localAdapterNo	number of the local adapter used for the connection
	segment	handle to the new connected segment descriptor
	address	base address of the memory window
	size	size of the memory window
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_SIZE_ALIGNMENT
Size is not correctly aligned as required by the implementation.
SCI_ERR_CONNECTION_REFUSED
Connection attempt refused by remote node.

Note:

This function is only available with SCI adapter cards.

SISCI_API_EXPORT void SCIAttachLocalSegment	(	sci_desc_t	sd,
		sci_local_segment_t *	segment,
		unsigned int	segmentId,
		unsigned int *	size,
		sci_cb_local_segment_t	callback,
		void *	callbackArg,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIAttachLocalSegment() permits an application to "attach" to an already existing local segment, implying that two or more application want share the same local segment.

The prerequest, is that the application which originally created the segment ("owner") has preformed a SCIShareSegment() in order to mark the segment "shareable". To detach from an attached segment use the SCIRemoveSegment() call.

Flags:

SCI_FLAG_USE_CALLBACK
The callback function will be invoked for events on this segment.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_ACCESS
No such shared segment
SCI_ERR_NO_SUCH_SEGMENT
No such segment
SCI_ERR_SYSTEM
The callback thread could not be created.

Note:

There are no difference in "ownership" of the shared segment between the original creator and the attached applications. If the original creator performs a remove segment with other applications attached to the segment, this becomes equal to a "detach". On global level, the segment wont be removed until all attached processes as well as the original creator has performed SCIRemoveSegment.
Current implenentation will return SCI_ERR_ACCESS for both cases. This will change from next release. Application should handle both cases.

SISCI_API_EXPORT void SCIShareSegment	(	sci_local_segment_t	segment,
		unsigned int	flags,
		sci_error_t *	error
	)

SCIShareSegment() permits other application to "attach" to an already existing local segment, implying that two or more application want share the same local segment.

The prerequest, is that the application which originally created the segment ("owner") has preformed a SCIShareSegment() in order to mark the segment "shareable".

Parameters:

	segment	handle to the descriptor of local segment.
	flags	not used
	error	error information

Errors:

On successful completion, error points to the SCI_ERR_OK value. No specific error information provided.

SISCI_API_EXPORT void SCIFlush	(	sci_sequence_t	sequence,
		unsigned int	flags
	)

SCIFlush flushes the CPU buffers and the PSB buffers.

Parameters:

	sequence	handle to the sequence descriptor
	flags	see below

Flags:

SCI_FLAG_FLUSH_CPU_BUFFERS_ONLY
Only flush CPU buffers (Write combining etc buffers).

Errors:

No error information provided by this function.

SISCI_API_EXPORT void DISStartDmaTransfer	(	sci_dma_queue_t	dq,
		sci_local_segment_t	localSegment,
		sci_remote_segment_t	remoteSegment,
		unsigned int	localOffset,
		unsigned int	size,
		unsigned int	remoteOffset,
		sci_cb_dma_t	callback,
		void *	callbackArg,
		unsigned int	flags,
		sci_error_t *	error
	)

DISStartDmaTransfer starts the execution of a DMA queue.

The function returns as soon as the transfer specifications contained in the queue are passed to the DMA engine of the DX adapter. If a callback function is specified and explicitly activated using the flag SCI_FLAG_USE_CALLBACK, it is asynchronously invoked when all the transfers have completed or if an error occurs during a transfer. Alternatively, an application can block waiting for the queue completion calling SCIWaitForDMAQueue.

Only for DX technology. This function might change in the future. This function is not a part of the official SISCI API interface.

Parameters:

	dq	handle to the DMA queue descriptor
	localSegment	handle to the local segment descriptor
	remoteSegment	handle to the remote segment descriptor
	localOffset	base address inside the local segment where data reside (or where data are transferred to, if the transfer is from the remote segment to the local one)
	size	size of the data to be transferred
	remoteOffset	base address inside the remote segment where data are transferred to (or where data reside, if the transfer is from the remote segment to the local one)
	callback	callback function to be invoked when all the DMA transfers have completed or in case an error occurs during a transfer
	callbackArg	user-defined parameter passed to the callback function
	flags	see below
	error	error information

Flags:

SCI_FLAG_USE_CALLBACK
The end of the transfer will cause the callback function to be invoked.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_ILLEGAL_OPERATION
Illegal operation
SCI_ERR_SYSTEM
The callback thread could not be created

SISCI_API_EXPORT void DISStartDmaTransferVec	(	sci_dma_queue_t	dq,
		sci_local_segment_t	localSegment,
		sci_remote_segment_t	remoteSegment,
		unsigned int	vecLength,
		dis_dma_vec_t *	disDmaVec,
		sci_cb_dma_t	callback,
		void *	callbackArg,
		unsigned int	flags,
		sci_error_t *	error
	)

DISStartDmaTransferVec starts the execution of a DMA queue.

The function returns as soon as the transfer specifications contained in the queue are passed to the DMA engine of the DX adapter. If a callback function is specified and explicitly activated using the flag SCI_FLAG_USE_CALLBACK, it is asynchronously invoked when all the transfers have completed or if an error occurs during a transfer. Alternatively, an application can block waiting for the queue completion calling SCIWaitForDMAQueue.

Only for DX technology. This function might change in the future. This function is not a part of the official SISCI API interface.

Parameters:

	dq	handle to the DMA queue descriptor
	localSegment	handle to the local segment descriptor
	remoteSegment	handle to the remote segment descriptor
	vecLength	lenght of the DMA vector queue.
	disDmaVec	handle to the DMA vector queue.
	callback	callback function to be invoked when all the DMA transfers have completed or in case an error occurs during a transfer
	callbackArg	user-defined parameter passed to the callback function
	flags	see below
	error	error information

Flags:

SCI_FLAG_USE_CALLBACK
The end of the transfer will cause the callback function to be invoked.

Errors:

On successful completion, error points to the SCI_ERR_OK value; otherwise to one of the following:
SCI_ERR_ILLEGAL_OPERATION
Illegal operation
SCI_ERR_SYSTEM
The callback thread could not be created

sisci_api.h File Reference

Functions

Detailed Description

Function Documentation