|
The QNIX API is a C library providing user interface to the QNIX communication system. It is mainly targeted to high level communication library developers, but can also be directly used by application programmers. All functions return a negative number or a null pointer in case of error, but at the moment no error code is defined. Currently the QNIX API contains the following functions:
void *qx_init(int *proc_name,
int group_name,
int group_size);
Every process in a parallel application must call this function as its first action. This way the process is registered to the network device. The function completes when all processing composing the parallel application have been registered to their corresponding network device, that is when the parallel application has been registered in the cluster.
Here proc_name is a two-element array containing the pair (AI, PI) defined in section 3.2, group_name is AI and group_size is the number of processes composing the parallel application. This function returns the pointer to the HPS (Figure 3).
int qx_buffer_lock(char *buffer,
long buffer_size);
This function simply calls the Linux mlock() system call. It pins down the memory buffer pointed by buffer. Here buffer_size is the length in bytes of the memory buffer to be locked.
int qx_buffer_unlock(char *buffer,
long buffer_size);
This function simply calls the Linux munlock() system call. It unlocks the memory buffer pointed by buffer. Here buffer_size is the length in bytes of the memory buffer to be unlocked.
int qx_buffer_pool(int pool_size);
This function allocates a page aligned memory block of pool_size pages, locks it, translates page virtual addresses and writes physical addresses into the Buffer_Pool structure of the process Virtual Network Interface (Figure 2). This memory block can be used as a pre-locked and memory translated buffer pool. It is locked for the whole process lifetime and its size is limited to 8 MB.
int qx_buffer_translate(char *buffer,
long buffer_size,
unsigned long *phys_addr);
This function translates virtual addresses of the pages composing the buffer pointed by buffer and writes the related physical addresses in the phys_addr array. This has one element more than the number of pages composing the buffer. Such added element stores the number of buffer bytes in the first and last page. Here buffer_size is the buffer length in bytes and cannot be grater than 2 MB.
int qx_send_context(int *receiver_proc_name,
int context_tag,
int doorbell_flag,
int size,
long len,
int buffer_pool_index,
unsigned long *context_reg);
This function searches for the first available Send Context in the process Send Context List (Figure 2) and assigns its argument values to the corresponding Context fields. It returns the Send Context index in the Send Context List array. Here receiver_proc_name is a two-element array containing the pair (AI, PI) (see section 3.2) for the receiver process, context_tag is the message tag, doorbell_flag indicates if the process wants to be notified on send completion, size is message length in packets, len is the message length in bytes, buffer_pool_index is an index in the Buffer Pool (Figure 2) or -1 if the Buffer Pool is not used, context_reg is the pointer to the page table or data to be copied into the corresponding Context Region (Figure 2), or NULL if the Buffer Pool is used.
int qx_recv_context(int *sender_proc_name,
int context_tag,
int doorbell_flag,
int size,
long len,
int buffer_pool_index,
unsigned long *context_reg);
This function searches for the first available Receive Context in the process Receive Context List (Figure 2) and assigns its argument values to the corresponding Context fields. It returns the Receive Context index in the Recieve Context List array. Here sender_proc_name is a two-element array containing the pair (AI, PI) (see section 3.2) for the sender process, context_tag is the message tag, doorbell_flag indicates if the process wants to be notified on receive completion, size is destination buffer length in pages, len is the destination buffer length in bytes, buffer_pool_index is an index in the Buffer Pool (Figure 2) or -1 if the Buffer Pool is not used, context_reg is the pointer to the page table to be copied into the corresponding Context Region (Figure 2), or NULL if the Buffer Pool is used.
int qx_send(int context_index);
This function posts a Send command in the process Command Queue. Here context_index is the Send Context List index for the Send Context associated to the Send operation.
int qx_send_short(int context_index);
This function posts a Send_Short command in the process Command Queue. Here context_index is the Send Context List index for the Send Context associated to the Send_Short operation.
int qx_broadcast(int context_index,
int group_name);
This function posts a Broadcast command in the process Command Queue. Here context_index is the Send Context List index for the Send Context associated to the Broadcast operation and group_name is the identifier of the broadcast target process group.
int qx_broadcast_short(int context_index,
int group_name);
This function posts a Broadcast_Short command in the process Command Queue. Here context_index is the Send Context List index for the Send Context associated to the Broadcast_Short operation and group_name is the identifier of the broadcast target process group.
int qx_multicast(int context_index,
int size,
int **recv_proc_name_list);
This function posts a Multicast command in the process Command Queue. Here context_index is the Send Context List index for the Send Context associated to the Multicast operation, size is the number of receiver processes and recv_proc_name_list is the pointer to a list of two-element arrays containing the pairs (AI, PI) (see section 3.2) for the receiver processes.
int qx_multicast_short(int context_index,
int size,
int **recv_proc_name_list);
This function posts a Multicast_Short command in the process Command Queue. Here context_index is the Send Context List index for the Send Context associated to the Multicast_Short operation, size is the number of receiver processes and recv_proc_name_list is the pointer to a list of two-element arrays containing the pairs (AI, PI) (see section 3.2) for the receiver processes.
int qx_receive(int context_index);
This function posts a Receive command in the process Command Queue. Here context_index is the Receive Context List index for the Receive Context associated to the Receive operation.
int qx_join_group(int context_index,
int group_name,
int group_size);
This function posts a Join_Group command in the process Command Queue. Here context_index is the Send Context List index for the Send Context associated to the Join_Group operation, group_name is the identifier of new process group and group_size is the number of processes composing the new group.
int qx_barrier(int context_index,
int group_name,
int group_size);
This function posts a Barrier command in the process Command Queue. Here context_index is the Send Context List index for the Send Context associated to the Barrier operation, group_name is the identifier of synchronising process group and group_size is the number of processes composing such group.
int qx_poll_for_send(int context_index);
This function makes the process poll its Send_Doorbell (Figure 3) associated to the Send Context referred by context_index. When the corresponding send operation completes, this functions sets the Send_Doorbell to Free.
int qx_poll_for_receive(int context_index);
This function makes the process poll its Receive_Doorbell (Figure 3) associated to the Receive Context referred by context_index. When the corresponding receive operation completes, this functions sets the Receive_Doorbell to Free.
int qx_end(int *proc_name);
This function de-registers the process from the network device. Here proc_name is a two-element array containing the pair (AI, PI) (see section 3.2) for the process to be de-registered.
Share with your friends: |
