UIO: Add name attributes for mappings and port regions
[linux-2.6.git] / Documentation / DocBook / procfs-guide.tmpl
index 45cad23..9eba4b7 100644 (file)
        <othername>(J.A.K.)</othername>
        <surname>Mouw</surname>
        <affiliation>
-         <orgname>Delft University of Technology</orgname>
-         <orgdiv>Faculty of Information Technology and Systems</orgdiv>
          <address>
-            <email>J.A.K.Mouw@its.tudelft.nl</email>
-            <pob>PO BOX 5031</pob>
-            <postcode>2600 GA</postcode>
-            <city>Delft</city>
-            <country>The Netherlands</country>
+            <email>mouw@nl.linux.org</email>
           </address>
        </affiliation>
       </author>
+      <othercredit>
+       <contrib>
+       This software and documentation were written while working on the
+       LART computing board
+       (<ulink url="http://www.lartmaker.nl/">http://www.lartmaker.nl/</ulink>),
+       which was sponsored by the Delt University of Technology projects
+       Mobile Multi-media Communications and Ubiquitous Communications.
+       </contrib>
+      </othercredit>
     </authorgroup>
 
     <revhistory>
       <revision>
-       <revnumber>1.0&nbsp;</revnumber>
+       <revnumber>1.0</revnumber>
        <date>May 30, 2001</date>
        <revremark>Initial revision posted to linux-kernel</revremark>
       </revision>
       <revision>
-       <revnumber>1.1&nbsp;</revnumber>
+       <revnumber>1.1</revnumber>
        <date>June 3, 2001</date>
        <revremark>Revised after comments from linux-kernel</revremark>
       </revision>
@@ -85,7 +88,7 @@
 
 
 
-  <preface>
+  <preface id="Preface">
     <title>Preface</title>
 
     <para>
     </para>
 
     <para>
-      This documentation was written while working on the LART
-      computing board (<ulink
-      url="http://www.lart.tudelft.nl/">http://www.lart.tudelft.nl/</ulink>),
-      which is sponsored by the Mobile Multi-media Communications
-      (<ulink
-      url="http://www.mmc.tudelft.nl/">http://www.mmc.tudelft.nl/</ulink>)
-      and Ubiquitous Communications (<ulink
-      url="http://www.ubicom.tudelft.nl/">http://www.ubicom.tudelft.nl/</ulink>)
-      projects.
-    </para>
-
-    <para>
       Erik
     </para>
   </preface>
 
 
 
-    <sect1>
+    <sect1 id="Creating_a_symlink">
       <title>Creating a symlink</title>
 
       <funcsynopsis>
       </para>
     </sect1>
 
-    <sect1>
+    <sect1 id="Creating_a_directory">
       <title>Creating a directory</title>
       
       <funcsynopsis>
 
 
 
-    <sect1>
+    <sect1 id="Removing_an_entry">
       <title>Removing an entry</title>
       
       <funcsynopsis>
@@ -340,7 +331,7 @@ entry->write_proc = write_proc_foo;
 
 
 
-    <sect1>
+    <sect1 id="Reading_data">
       <title>Reading data</title>
 
       <para>
@@ -352,49 +343,93 @@ entry->write_proc = write_proc_foo;
       <funcsynopsis>
        <funcprototype>
          <funcdef>int <function>read_func</function></funcdef>
-         <paramdef>char* <parameter>page</parameter></paramdef>
+         <paramdef>char* <parameter>buffer</parameter></paramdef>
          <paramdef>char** <parameter>start</parameter></paramdef>
          <paramdef>off_t <parameter>off</parameter></paramdef>
          <paramdef>int <parameter>count</parameter></paramdef>
-         <paramdef>int* <parameter>eof</parameter></paramdef>
+         <paramdef>int* <parameter>peof</parameter></paramdef>
          <paramdef>void* <parameter>data</parameter></paramdef>
        </funcprototype>
       </funcsynopsis>
 
       <para>
         The read function should write its information into the
-        <parameter>page</parameter>. For proper use, the function
-        should start writing at an offset of
-        <parameter>off</parameter> in <parameter>page</parameter> and
-        write at most <parameter>count</parameter> bytes, but because
-        most read functions are quite simple and only return a small
-        amount of information, these two parameters are usually
-        ignored (it breaks pagers like <literal>more</literal> and
-        <literal>less</literal>, but <literal>cat</literal> still
-        works).
+        <parameter>buffer</parameter>, which will be exactly
+        <literal>PAGE_SIZE</literal> bytes long.
       </para>
 
       <para>
-        If the <parameter>off</parameter> and
-        <parameter>count</parameter> parameters are properly used,
-        <parameter>eof</parameter> should be used to signal that the
+        The parameter
+        <parameter>peof</parameter> should be used to signal that the
         end of the file has been reached by writing
         <literal>1</literal> to the memory location
-        <parameter>eof</parameter> points to.
+        <parameter>peof</parameter> points to.
       </para>
 
       <para>
-        The parameter <parameter>start</parameter> doesn't seem to be
-        used anywhere in the kernel. The <parameter>data</parameter>
+        The <parameter>data</parameter>
         parameter can be used to create a single call back function for
         several files, see <xref linkend="usingdata"/>.
       </para>
 
       <para>
-        The <function>read_func</function> function must return the
-        number of bytes written into the <parameter>page</parameter>.
+        The rest of the parameters and the return value are described
+       by a comment in <filename>fs/proc/generic.c</filename> as follows:
       </para>
 
+      <blockquote>
+        <para>
+       You have three ways to return data:
+               </para>
+        <orderedlist>
+          <listitem>
+            <para>
+             Leave <literal>*start = NULL</literal>.  (This is the default.)
+             Put the data of the requested offset at that
+             offset within the buffer.  Return the number (<literal>n</literal>)
+             of bytes there are from the beginning of the
+             buffer up to the last byte of data.  If the
+             number of supplied bytes (<literal>= n - offset</literal>) is
+             greater than zero and you didn't signal eof
+             and the reader is prepared to take more data
+             you will be called again with the requested
+             offset advanced by the number of bytes
+             absorbed.  This interface is useful for files
+             no larger than the buffer.
+           </para>
+         </listitem>
+         <listitem>
+            <para>
+             Set <literal>*start</literal> to an unsigned long value less than
+             the buffer address but greater than zero.
+             Put the data of the requested offset at the
+             beginning of the buffer.  Return the number of
+             bytes of data placed there.  If this number is
+             greater than zero and you didn't signal eof
+             and the reader is prepared to take more data
+             you will be called again with the requested
+             offset advanced by <literal>*start</literal>.  This interface is
+             useful when you have a large file consisting
+             of a series of blocks which you want to count
+             and return as wholes.
+             (Hack by Paul.Russell@rustcorp.com.au)
+           </para>
+         </listitem>
+         <listitem>
+            <para>
+             Set <literal>*start</literal> to an address within the buffer.
+             Put the data of the requested offset at <literal>*start</literal>.
+             Return the number of bytes of data placed there.
+             If this number is greater than zero and you
+             didn't signal eof and the reader is prepared to
+             take more data you will be called again with the
+             requested offset advanced by the number of bytes
+             absorbed.
+           </para>
+         </listitem>
+       </orderedlist>
+      </blockquote>
+
       <para>
         <xref linkend="example"/> shows how to use a read call back
         function.
@@ -404,7 +439,7 @@ entry->write_proc = write_proc_foo;
 
 
 
-    <sect1>
+    <sect1 id="Writing_data">
       <title>Writing data</title>
 
       <para>
@@ -535,7 +570,7 @@ int foo_read_func(char *page, char **start, off_t off,
 
 
 
-    <sect1>
+    <sect1 id="Modules">
       <title>Modules</title>
 
       <para>
@@ -555,7 +590,7 @@ entry->owner = THIS_MODULE;
 
 
 
-    <sect1>
+    <sect1 id="Mode_and_ownership">
       <title>Mode and ownership</title>
 
       <para>