DragonFly On-Line Manual Pages

Search: Section:  

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

Search: Section: