.\" Copyright (c) 2007 The DragonFly Project. All rights reserved. .\" .\" This code is derived from software contributed to The DragonFly Project .\" by Matthew Dillon .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" 3. Neither the name of The DragonFly Project nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific, prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $DragonFly: src/lib/libc/sys/syslink.2,v 1.8 2007/07/23 23:08:02 dillon Exp $ .\" .Dd March 13, 2007 .Dt SYSLINK 2 .Os .Sh NAME .Nm syslink .Nd low level connect to the cluster mesh .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/syslink.h .In sys/syslink_msg.h .Ft int .Fn syslink "int cmd" "struct syslink_info *info" "size_t bytes" .Sh DESCRIPTION The .Fn 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. .Pp 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. .Pp 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 .Fn readv or .Fn 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 .Fn readv or .Fn writev only accounts for iov[0]. The caller checks message flags to determine if any DMA occured. .Pp 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. .Pp 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. .Pp 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. .Sh RETURN VALUES The value -1 is returned if an error occurs, otherwise 0. The external variable .Va errno indicates the cause of the error. .Sh SEE ALSO .Sh HISTORY The .Fn syslink function first appeared in .Dx 1.9 .