ALSA: Introduce snd_BUG_ON() macro

[linux-2.6-omap-h63xx.git] / Documentation / sound / alsa / DocBook / writing-an-alsa-driver.tmpl

diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
index b03df4d4795c6767b79bed4125b07bbdf64fc823..df699e4323ef62a3cfe3afce586d5e4d8b225eae 100644 (file)
--- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
+++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
@@ -6127,8 +6127,8 @@ struct _snd_pcm_runtime {
 
       <para>
         <function>snd_printdd()</function> is compiled in only when
-      <constant>CONFIG_SND_DEBUG_DETECT</constant> is set. Please note
-      that <constant>DEBUG_DETECT</constant> is not set as default
+      <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
+      that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
       even if you configure the alsa-driver with
       <option>--with-debug=full</option> option. You need to give
       explicitly <option>--with-debug=detect</option> option instead. 
@@ -6173,6 +6173,47 @@ struct _snd_pcm_runtime {
         When no debug flag is set, this macro is ignored. 
       </para>
     </section>
+
+    <section id="useful-functions-snd-bug-on">
+      <title><function>snd_BUG_ON()</function></title>
+      <para>
+        <function>snd_BUG_ON()</function> macro is similar with
+       <function>WARN_ON()</function> macro. For example,  
+
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  snd_BUG_ON(!pointer);
+]]>
+          </programlisting>
+        </informalexample>
+
+       or it can be used as the condition,
+        <informalexample>
+          <programlisting>
+<![CDATA[
+  if (snd_BUG_ON(non_zero_is_bug))
+          return -EINVAL;
+]]>
+          </programlisting>
+        </informalexample>
+
+      </para>
+
+      <para>
+        The macro takes an conditional expression to evaluate.
+       When <constant>CONFIG_SND_DEBUG</constant>, is set, the
+       expression is actually evaluated. If it's non-zero, it shows
+       the warning message such as
+       <computeroutput>BUG? (xxx)</computeroutput>
+       normally followed by stack trace.  It returns the evaluated
+       value.
+       When no <constant>CONFIG_SND_DEBUG</constant> is set, this
+       macro always returns zero.
+      </para>
+
+    </section>
+
   </chapter>