Synchronize the syslink manual page with the system call.
[dragonfly.git] / lib / libc / sys / syslink.2
1 .\" Copyright (c) 2007 The DragonFly Project.  All rights reserved.
2 .\"
3 .\" This code is derived from software contributed to The DragonFly Project
4 .\" by Matthew Dillon <dillon@backplane.com>
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\"
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\"    notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in
14 .\"    the documentation and/or other materials provided with the
15 .\"    distribution.
16 .\" 3. Neither the name of The DragonFly Project nor the names of its
17 .\"    contributors may be used to endorse or promote products derived
18 .\"    from this software without specific, prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
23 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
24 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
26 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
28 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" SUCH DAMAGE.
32 .\"
33 .\" $DragonFly: src/lib/libc/sys/syslink.2,v 1.8 2007/07/23 23:08:02 dillon Exp $
34 .\"
35 .Dd March 13, 2007
36 .Dt SYSLINK 2
37 .Os
38 .Sh NAME
39 .Nm syslink
40 .Nd low level connect to the cluster mesh
41 .Sh LIBRARY
42 .Lb libc
43 .Sh SYNOPSIS
44 .In sys/syslink.h
45 .In sys/syslink_msg.h
46 .Ft int
47 .Fn syslink "int cmd" "struct syslink_info *info" "size_t bytes"
48 .Sh DESCRIPTION
49 The
50 .Fn syslink
51 system call manages the system link protocol interface to the kernel.
52 At the moment the only command implemented is SYSLINK_CMD_NEW which
53 establishes a connected pair of file descriptors suitable for communication
54 between two user processes.  Other system calls may also indirectly return
55 a syslink descriptor, for example when mounting a user filesystem.
56 .Pp
57 System links are not pipes.  Reads and writes are message based and the
58 kernel carefully checks the syslink_msg structure for conformance.  Every
59 message sent requires a reply to be returned.  If the remote end dies, the
60 kernel automatically replies to any unreplied messages.
61 .Pp
62 Syslink commands are very similar to high level device operations.  An
63 out-of-band DMA buffer (<= 128KB) may be specified along with the syslink
64 message by placing it in iov[1] in a
65 .Fn readv
66 or
67 .Fn writev
68 system call on a syslink descriptor.  The syslink message must also have the
69 appropriate flags set for the kernel to recognize the DMA buffer.  The return
70 value from
71 .Fn readv
72 or
73 .Fn writev
74 only accounts for iov[0].  The caller checks message flags to determine if
75 any DMA occured.
76 .Pp
77 DMA buffers must be managed carefully.  Sending a command along with a DMA
78 buffer does not immediately copy out the buffer.  The originator of the
79 command may free the VM space related to the buffer but must leave the
80 storage backing the buffer intact until a reply to that command is
81 received.  For example, the originator can memory map a file and
82 supply pointers into the mapping as part of a syslink command, then remap
83 the space for other purposes without waiting for a syslink command to
84 be replied.  As long as the contents at the related offsets in the backing
85 store (the file) are not modified, the operation is legal.  Anonymous
86 memory can also be used in this manner by munmap()ing it after having
87 sent the command.  However, it should be noted that mapping memory can be
88 quite expensive.
89 .Pp
90 Since there is no reply to a reply, the target has no way of knowing when
91 the DMA buffer it supplies in a reply will be drained.  Because
92 of this, buffers associated with reply messages are always immediately copied
93 by the kernel allowing the target to throw the buffer away and reuse its
94 memory after replying.  There are no backing object restrictions for replies.
95 .Pp
96 The kernel has the option of mapping the originator's buffer directly into
97 the target's VM space.  DMA buffers must be page-aligned and it is best to
98 use mmap() to allocate and manage them.  This feature is not yet implemented.
99 .Sh RETURN VALUES
100 The value -1 is returned if an error occurs, otherwise 0.
101 The external variable
102 .Va errno
103 indicates the cause of the error.
104 .Sh SEE ALSO
105 .Sh HISTORY
106 The
107 .Fn syslink
108 function first appeared in
109 .Dx 1.9 .