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.11 2007/12/23 15:31:28 swildner 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
  53 .Dv SYSLINK_CMD_NEW
  54 which
  55 establishes a connected pair of file descriptors suitable for communication
  56 between two user processes.
  57 Other system calls may also indirectly return a
  58 .Nm
  59 descriptor, for example when mounting a user filesystem.
  60 .Pp
  61 System links are not pipes.
  62 Reads and writes are message based and the kernel carefully checks the
  63 .Vt syslink_msg
  64 structure for conformance.
  65 Every message sent requires a reply to be returned.
  66 If the remote end dies, the kernel automatically replies to any unreplied
  67 messages.
  68 .Pp
  69 .Nm Syslink
  70 commands are very similar to high level device operations.
  71 An out-of-band DMA buffer (<= 128KB) may be specified along with the
  72 .Nm
  73 message by placing it in
  74 .Fa iov[1]
  75 in a
  76 .Fn readv
  77 or
  78 .Fn writev
  79 system call on a
  80 .Nm
  81 descriptor.
  82 The
  83 .Nm
  84 message must also have the appropriate flags set for the kernel to
  85 recognize the DMA buffer.
  86 The return value from
  87 .Fn readv
  88 or
  89 .Fn writev
  90 only accounts for
  91 .Fa iov[0] .
  92 The caller checks message flags to determine if any DMA occurred.
  93 .Pp
  94 DMA buffers must be managed carefully.
  95 Sending a command along with a DMA buffer does not immediately copy out
  96 the buffer.
  97 The originator of the command may free the VM space related to the buffer
  98 but must leave the storage backing the buffer intact until a reply to that
  99 command is received.
 100 For example, the originator can memory map a file and supply pointers into
 101 the mapping as part of a
 102 .Nm
 103 command, then remap the space for other purposes without waiting for a
 104 .Nm
 105 command to be replied.
 106 As long as the contents at the related offsets in the backing
 107 store (the file) are not modified, the operation is legal.
 108 Anonymous memory can also be used in this manner by
 109 .Fn munmap Ns ing
 110 it after having sent the command.
 111 However, it should be noted that mapping memory can be quite expensive.
 112 .Pp
 113 Since there is no reply to a reply, the target has no way of knowing when
 114 the DMA buffer it supplies in a reply will be drained.
 115 Because of this, buffers associated with reply messages are always
 116 immediately copied by the kernel allowing the target to throw the buffer
 117 away and reuse its memory after replying.
 118 There are no backing object restrictions for replies.
 119 .Pp
 120 The kernel has the option of mapping the originator's buffer directly into
 121 the target's VM space.
 122 DMA buffers must be page-aligned and it is best to use
 123 .Fn mmap
 124 to allocate and manage them.
 125 This feature is not yet implemented.
 126 .Sh RETURN VALUES
 127 .Rv -std
 128 .\".Sh SEE ALSO
 129 .Sh HISTORY
 130 The
 131 .Fn syslink
 132 function first appeared in
 133 .Dx 1.9 .