Skip to contentSkip to conversation

doc: Added explaination for splice system call

PATCH New Ram Gupta 1 participant 1 message Sep 29, 2006

lore
Share & tools
lore

Ram Gupta

author
#0 lore raw

PATCH 1/1 doc: Added explaination for splice system call

This patch adds documentation for splice system call. Please apply

-------
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<[email protected]>

Thanks
Ram Gupta