From f4980c5e8ea66cca3a0966a35b36ba5932e5dca1 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab <mchehab@redhat.com>
Date: Sun, 13 Sep 2009 20:45:57 -0300
Subject: staging-specs: Add a staging tree for Documentation/DocBook

From: Mauro Carvalho Chehab <mchehab@redhat.com>

This patch basically copies V4L and DVB DocBook specs into a single file,
under a temporary staging tree. This is meant to add the set of V4L/DVB API
specifications at Linux Kernel.

For now, it just renames the *sgml files to *xml and creates a common body
for both API's, dividing them into two parts.

Later patches will add some glue for the two specs, move IR to a common part
(since IR keycodes are common to both API's) and add it into
linux/Documentation/DocBook.

Comments and reviews are welcome.

Priority: normal

Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
---
 staging-specs/v4l/driver.xml | 208 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 208 insertions(+)
 create mode 100644 staging-specs/v4l/driver.xml

(limited to 'staging-specs/v4l/driver.xml')

diff --git a/staging-specs/v4l/driver.xml b/staging-specs/v4l/driver.xml
new file mode 100644
index 000000000..1f7eea5c4
--- /dev/null
+++ b/staging-specs/v4l/driver.xml
@@ -0,0 +1,208 @@
+  <title>V4L2 Driver Programming</title>
+
+  <!-- This part defines the interface between the "videodev"
+    module and individual drivers. -->
+
+  <para>to do</para>
+<!--
+  <para>V4L2 is a two-layer driver system. The top layer is the "videodev"
+kernel module. When videodev initializes it registers as character device
+with major number 81, and it registers a set of file operations. All V4L2
+drivers are really clients of videodev, which calls V4L2 drivers through
+driver method functions. V4L2 drivers are also written as kernel modules.
+After probing the hardware they register one or more devices with
+videodev.</para>
+
+  <section id="driver-modules">
+    <title>Driver Modules</title>
+
+    <para>V4L2 driver modules must have an initialization function which is
+called after the module was loaded into kernel, an exit function whis is
+called before the module is removed.  When the driver is compiled into the
+kernel these functions called at system boot and shutdown time.</para>
+
+    <informalexample>
+      <programlisting>
+#include &lt;linux/module.h&gt;
+
+/* Export information about this module. For details and other useful
+   macros see <filename>linux/module.h</filename>. */
+MODULE_DESCRIPTION("my - driver for my hardware");
+MODULE_AUTHOR("Your name here");
+MODULE_LICENSE("GPL");
+
+static void
+my_module_exit (void)
+{
+	/* Free all resources allocated by my_module_init(). */
+}
+
+static int
+my_module_init (void)
+{
+	/* Bind the driver to the supported hardware, see
+	   <link linkend="driver-pci"> and
+	   <link linkend="driver-usb"> for examples. */
+
+	return 0; /* a negative value on error, 0 on success. */
+}
+
+/* Export module functions. */
+module_init (my_module_init);
+module_exit (my_module_exit);
+</programlisting>
+    </informalexample>
+
+    <para>Users can add parameters when kernel modules are inserted:</para>
+
+    <informalexample>
+      <programlisting>
+include &lt;linux/moduleparam.h&gt;
+
+static int my_option = 123;
+static int my_option_array[47];
+
+/* Export the symbol, an int, with access permissions 0664.
+   See <filename>linux/moduleparam.h</filename> for other types. */
+module_param (my_option, int, 0644);
+module_param_array (my_option_array, int, NULL, 0644);
+
+MODULE_PARM_DESC (my_option, "Does magic things, default 123");
+</programlisting>
+    </informalexample>
+
+    <para>One parameter should be supported by all V4L2 drivers, the minor
+number of the device it will register. Purpose is to predictably link V4L2
+drivers to device nodes if more than one video device is installed. Use the
+name of the device node followed by a "_nr" suffix, for example "video_nr"
+for <filename>/dev/video</filename>.</para>
+
+    <informalexample>
+      <programlisting>
+/* Minor number of the device, -1 to allocate the first unused. */
+static int video_nr = -1;
+
+module_param (video_nr, int, 0444);
+</programlisting>
+    </informalexample>
+  </section>
+
+  <section id="driver-pci">
+    <title>PCI Devices</title>
+
+    <para>PCI devices are initialized like this:</para>
+
+    <informalexample>
+      <programlisting>
+typedef struct {
+	/* State of one physical device. */
+} my_device;
+
+static int
+my_resume               (struct pci_dev *               pci_dev)
+{
+	/* Restore the suspended device to working state. */
+}
+
+static int
+my_suspend              (struct pci_dev *               pci_dev,
+			 pm_message_t                   state)
+{
+	/* This function is called before the system goes to sleep.
+	   Stop all DMAs and disable interrupts, then put the device
+	   into a low power state. For details see the kernel
+	   sources under <filename>Documentation/power</filename>. */
+
+	return 0; /* a negative value on error, 0 on success. */
+}
+
+static void __devexit
+my_remove               (struct pci_dev *               pci_dev)
+{
+	my_device *my = pci_get_drvdata (pci_dev);
+
+	/* Describe me. */
+}
+
+static int __devinit
+my_probe                (struct pci_dev *               pci_dev,
+			 const struct pci_device_id *   pci_id)
+{
+	my_device *my;
+
+	/* Describe me. */
+
+	/* You can allocate per-device data here and store a pointer
+	   to it in the pci_dev structure. */
+	my = ...;
+	pci_set_drvdata (pci_dev, my);
+
+	return 0; /* a negative value on error, 0 on success. */
+}
+
+/* A list of supported PCI devices. */
+static struct pci_device_id
+my_pci_device_ids [] = {
+	{ PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
+	  PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0 },
+	{ 0 } /* end of list */
+};
+
+/* Load our module if supported PCI devices are installed. */
+MODULE_DEVICE_TABLE (pci, my_pci_device_ids);
+
+static struct pci_driver
+my_pci_driver = {
+	.name     = "my",
+	.id_table = my_pci_device_ids,
+
+	.probe    = my_probe,
+	.remove   = __devexit_p (my_remove),
+
+	/* Power management functions. */
+	.suspend  = my_suspend,
+	.resume   = my_resume,
+};
+
+static void
+my_module_exit          (void)
+{
+	pci_unregister_driver (&my_pci_driver);
+}
+
+static int
+my_module_init          (void)
+{
+	return pci_register_driver (&my_pci_driver);
+}
+</programlisting>
+    </informalexample>
+  </section>
+
+  <section id="driver-usb">
+    <title>USB Devices</title>
+    <para>to do</para>
+  </section>
+  <section id="driver-registering">
+    <title>Registering V4L2 Drivers</title>
+
+    <para>After a V4L2 driver probed the hardware it registers one or more
+devices with the videodev module.</para>
+  </section>
+  <section id="driver-file-ops">
+    <title>File Operations</title>
+    <para>to do</para>
+  </section>
+  <section id="driver-internal-api">
+    <title>Internal API</title>
+    <para>to do</para>
+  </section>
+-->
+
+<!--
+Local Variables:
+mode: sgml
+sgml-parent-document: "v4l2.sgml"
+indent-tabs-mode: nil
+End:
+-->
-- 
cgit v1.2.3