SYSLINK(2) BSD System Calls Manual SYSLINK(2)NAMEsyslink — 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.
BSD March 13, 2007 BSD
