--- src/lib/libc/sys/syslink.2 2007/08/25 10:01:34 1.9
+++ src/lib/libc/sys/syslink.2 2007/08/25 10:38:53 1.10
@@ -49,58 +49,82 @@
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
+At the moment the only command implemented is
+.Dv 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.
+between two user processes.
+Other system calls may also indirectly return a
+.Nm
+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.
+System links are not pipes.
+Reads and writes are message based and the kernel carefully checks the
+.Vt 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
+.Nm Syslink
+commands are very similar to high level device operations.
+An out-of-band DMA buffer (<= 128KB) may be specified along with the
+.Nm
+message by placing it in
+.Fa 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
+system call on a
+.Nm
+descriptor.
+The
+.Nm
+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.
+only accounts for
+.Fa 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.
+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
+.Nm
+command, then remap the space for other purposes without waiting for a
+.Nm
+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
+.Fn munmap Ns 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.
+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.
+the target's VM space.
+DMA buffers must be page-aligned and it is best to use
+.Fn 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.
+.Rv -std
.\".Sh SEE ALSO
.Sh HISTORY
The