ALSA: Update the documentation for changes of proc files

Signed-off-by: Takashi Iwai <tiwai@suse.de>

ALSA: Update the documentation for changes of proc files
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Takashi Iwai
1 parent 02f4865fa4
Showing 1 changed file with 17 additions and 10 deletions Side-by-side Diff
Documentation/DocBook/writing-an-alsa-driver.tmpl
@@ -5518,34 +5518,41 @@
 ]]>
         </programlisting>
       </informalexample>
+
+      For the raw data, <structfield>size</structfield> field must be
+      set properly.  This specifies the maximum size of the proc file access.
     </para>
  
     <para>
-      The callback is much more complicated than the text-file
-      version. You need to use a low-level I/O functions such as
+      The read/write callbacks of raw mode are more direct than the text mode.
+      You need to use a low-level I/O functions such as
       <function>copy_from/to_user()</function> to transfer the
       data.
  
       <informalexample>
         <programlisting>
 <![CDATA[
-  static long my_file_io_read(struct snd_info_entry *entry,
+  static ssize_t my_file_io_read(struct snd_info_entry *entry,
                               void *file_private_data,
                               struct file *file,
                               char *buf,
-                              unsigned long count,
-                              unsigned long pos)
+                              size_t count,
+                              loff_t pos)
   {
-          long size = count;
-          if (pos + size > local_max_size)
-                  size = local_max_size - pos;
-          if (copy_to_user(buf, local_data + pos, size))
+          if (copy_to_user(buf, local_data + pos, count))
                   return -EFAULT;
-          return size;
+          return count;
   }
 ]]>
         </programlisting>
       </informalexample>
+
+      If the size of the info entry has been set up properly,
+      <structfield>count</structfield> and <structfield>pos</structfield> are
+      guaranteed to fit within 0 and the given size.
+      You don't have to check the range in the callbacks unless any
+      other condition is required.
+
     </para>
  
   </chapter>
...	...	@@ -5518,34 +5518,41 @@
5518	5518	]]>
5519	5519	</programlisting>
5520	5520	</informalexample>
	5521	+
	5522	+ For the raw data, <structfield>size</structfield> field must be
	5523	+ set properly. This specifies the maximum size of the proc file access.
5521	5524	</para>
5522	5525
5523	5526	<para>
5524		- The callback is much more complicated than the text-file
5525		- version. You need to use a low-level I/O functions such as
	5527	+ The read/write callbacks of raw mode are more direct than the text mode.
	5528	+ You need to use a low-level I/O functions such as
5526	5529	<function>copy_from/to_user()</function> to transfer the
5527	5530	data.
5528	5531
5529	5532	<informalexample>
5530	5533	<programlisting>
5531	5534	<![CDATA[
5532		- static long my_file_io_read(struct snd_info_entry *entry,
	5535	+ static ssize_t my_file_io_read(struct snd_info_entry *entry,
5533	5536	void *file_private_data,
5534	5537	struct file *file,
5535	5538	char *buf,
5536		- unsigned long count,
5537		- unsigned long pos)
	5539	+ size_t count,
	5540	+ loff_t pos)
5538	5541	{
5539		- long size = count;
5540		- if (pos + size > local_max_size)
5541		- size = local_max_size - pos;
5542		- if (copy_to_user(buf, local_data + pos, size))
	5542	+ if (copy_to_user(buf, local_data + pos, count))
5543	5543	return -EFAULT;
5544		- return size;
	5544	+ return count;
5545	5545	}
5546	5546	]]>
5547	5547	</programlisting>
5548	5548	</informalexample>
	5549	+
	5550	+ If the size of the info entry has been set up properly,
	5551	+ <structfield>count</structfield> and <structfield>pos</structfield> are
	5552	+ guaranteed to fit within 0 and the given size.
	5553	+ You don't have to check the range in the callbacks unless any
	5554	+ other condition is required.
	5555	+
5549	5556	</para>
5550	5557
5551	5558	</chapter>