DragonFly On-Line Manual Pages


SYSLINK(2)		 DragonFly System Calls Manual		    SYSLINK(2)

NAME

syslink -- low level connect to the cluster mesh

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <sys/syslink.h> #include <sys/syslink_msg.h> int syslink(int cmd, struct syslink_info *info, size_t bytes);

DESCRIPTION

The syslink() system call manages the system link protocol interface to the kernel. At the moment the only command implemented is SYSLINK_CMD_NEW which establishes a connected pair of file descriptors suitable for communication between two user processes. Other system calls may also indirectly return a syslink descriptor, for example when mounting a user filesystem. System links are not pipes. Reads and writes are message based and the kernel carefully checks the syslink_msg structure for conformance. Every message sent requires a reply to be returned. If the remote end dies, the kernel automatically replies to any unreplied messages. Syslink commands are very similar to high level device operations. An out-of-band DMA buffer (<= 128KB) may be specified along with the syslink message by placing it in iov[1] in a readv() or writev() system call on a syslink descriptor. The syslink message must also have the appropriate flags set for the kernel to recognize the DMA buffer. The return value from readv() or writev() only accounts for iov[0]. The caller checks message flags to determine if any DMA occurred. DMA buffers must be managed carefully. Sending a command along with a DMA buffer does not immediately copy out the buffer. The originator of the command may free the VM space related to the buffer but must leave the storage backing the buffer intact until a reply to that command is received. For example, the originator can memory map a file and supply pointers into the mapping as part of a syslink command, then remap the space for other purposes without waiting for a syslink command to be replied. As long as the contents at the related offsets in the backing store (the file) are not modified, the operation is legal. Anonymous memory can also be used in this manner by munmap()ing it after having sent the command. However, it should be noted that mapping memory can be quite expensive. Since there is no reply to a reply, the target has no way of knowing when the DMA buffer it supplies in a reply will be drained. Because of this, buffers associated with reply messages are always immediately copied by the kernel allowing the target to throw the buffer away and reuse its memory after replying. There are no backing object restrictions for replies. The kernel has the option of mapping the originator's buffer directly into the target's VM space. DMA buffers must be page-aligned and it is best to use mmap() to allocate and manage them. This feature is not yet implemented.

RETURN VALUES

Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

HISTORY

The syslink() function first appeared in DragonFly 1.9. DragonFly 3.5 March 13, 2007 DragonFly 3.5