[PATCH]doc: Added explaination for splice system call

This patch adds documentation for splice system call. Please apply

Signed-off-by: Ram Gupta<r.gupta@xxxxxxxxxxxxxxxx>
-------
diff -uprN -X linux-2.6.18-doc/Documentation/dontdiff
linux-2.6.18/Documentation/splice.txt
linux-2.6.18-doc/Documentation/splice.txt
--- linux-2.6.18/Documentation/splice.txt 1969-12-31
19:00:00.000000000 -0500
+++ linux-2.6.18-doc/Documentation/splice.txt 2006-09-29
10:54:11.000000000 -0500
@@ -0,0 +1,57 @@
+ Splice system call
+ ----------------------------
+A splice() is a system call mechanism to do i/o from one file to another file
+in kernel space without doing copying from/to user space.It is a way of
+improving I/O performance. The splice system call avoids all data copy from
+user space to kernel space & vice versa. It reads from the specified offset
+from the input file & writes to a pipe in the kernel space. There is no copying
+of data to user space.Then it can be called to write the data from the pipe
+to the output file at the specified/current offset.
+
+splice() works by using the pipe buffer mechanism to open a file descriptor
+for a data source and another for a data sink then by using splice() it can
+join the two together. In other words, splice() work on a kernel buffer that
+the user has control over and moves data to/from the buffer from/to an
+arbitrary file descriptor. Specifying offset with pipe is an error as usual.
+If no offset is specified with an input/output file descriptor then the
+current offset will be assumed to be the offset specified. Currently one of
+the file descriptor must be pipe otherwise it is an error.
+This system call was added in 2.6.17 kernel
+
+########################################
+Overview of reading from a file to pipe
+########################################
+* It does the read ahead if there is more than one page
+
+* It tries to find the nr_pages from the input file mapping (contiguous
+ if possible)
+
+* If we got less number of contiguous pages than needed then find the other
+ pages or allocate new page.
+
+* If the page is not uptodate then we may need to start io on that page. But
+ the page may be under i/o already.
+
+* If needed start io if we are not in non-block mode.
+
+* Set up the pages in the buffers of the pipe.
+
+################################################
+Overview of writing from pipe to the output file
+#################################################
+
+* Make sure the page is uptodate
+
+* Steal the page from the page cache if the flag SPLICE_F_MOVE is
set & add the
+ page to the page cache of the file mapping.
+
+* Otherwise find the page of the mapping for the offset & make sure that page
+ is uptodate.
+
+* Prepare the page to be written in the file
+
+* balance dirty memory state
+
+* If file or inode is SYNC and we actually wrote some data, sync it.
+
+Ram Gupta<r.gupta@xxxxxxxxxxxxxxxx>

Thanks
Ram Gupta
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/

Relevant Pages

  • Re: [PATCH] tcp: do not promote SPLICE_F_NONBLOCK to socket O_NONBLOCK
    ... added only for choosing to block or not block on the _pipe_, ... If we need to make certain splice ... operations non-blocking for the other file descriptor, ... Lets change the number of packets in the example with 20 ...
    (Linux-Kernel)
  • Re: Linux 2.6.17-rc2
    ... the current 16 entries of the pipe ... DVD burning probably isn't a good splice fit, ... Ideally, on mkisofs side, we'd be able to: ...
    (Linux-Kernel)
  • Re: Make pipe data structure be a circular list of pages, rather than
    ... page that is on a pipe buffer (well, at least not through the pipe buffer ... that a year or two has passed, so that the video drivers have been updated ... - splice from the (mpeg or whatever - let's just assume that the video ...
    (Linux-Kernel)
  • Re: [patch v3] splice: fix race with page invalidation
    ... It seems like the right way to fix this would be to allow the splicing ... refill the pipe with the unread bytes... ... That should certainly work with the splice model. ... data wouldn't eat the invalid data, ...
    (Linux-Kernel)
  • Re: splice() and file offsets
    ... The logic is simple - either you don't give an explicit offset, ... have splice() update the file offset?) I realise there may be ... sendfile() never changes the file offset ...
    (Linux-Kernel)