diff --git a/dox/source/examples.rst.inc b/dox/source/examples.rst.inc index 53c511d..5f778b7 100644 --- a/dox/source/examples.rst.inc +++ b/dox/source/examples.rst.inc @@ -2,5 +2,111 @@ Simplest driver skeleton ======================== +lets review a simplest driver example provided in project repository. + Please see ``barebones/simple`` directory for this example's source code. +----------------- +Driver descriptor +----------------- + + +First we need to provide driver descriptor structure. + +.. code:: c + + pod_driver simple_driver = { + POD_DRIVER_MAGIC, + POD_DRIVER_VERSION, + POD_DRIVER_ARCH_UNKNOWN, + + POD_DEV_CLASS_VIDEO, 0, 0, 0, + + "simple driver skeleton - RENAME ME!", + + { + simple_driver_construct, + simple_driver_destruct, + + + simple_driver_activate, + simple_driver_deactivate, + + + simple_driver_sense + }, + + 0, // no optional entry points + + 0, // no properties + + 0, // Private state does not exist yet + + 0, // Statically linked, no need for kernel entry points struct + + }; + +The only notable things here are: + +* ``POD_DEV_CLASS_VIDEO`` - we declare that this is a video driver. OS might decide to start different + drivers sooner or later, or to group drivers start by classes. + +* ``simple_driver_X`` - entry points to start and stop our driver by OS. + + +----------------- +Device descriptor +----------------- + +Our driver will provide just one and only device, so device descriptor +can be static too. + +.. code:: c + + pod_device simple_device = + { + POD_DEVICE_MAGIC, // magic + + POD_DEV_CLASS_VIDEO, + 0, 0, + 0, // flags + + // Device name, either static or runtime-generated + "simple driver skeleton device name - RENAME ME!", + + &simple_driver, + + &dev_func, // dev io entry points + + 0, // no properties + + 0, // dev class specific interface + 0, // private data + + 0, // default request q + 0, // request we do now + 0, // thread used to run requests + 0, // triggered to run next request + + }; + +Again, we note that dev class is ``POD_DEV_CLASS_VIDEO``. It is critical to be +correct - OS will connect device to its users based on this. + +We provide device entry points for async interface, but all of them are default +ones provided by OpenPOD library. + +.. code:: c + + static pod_dev_f dev_func = + { + pod_default_enqueue, + pod_default_dequeue, + pod_default_fence, + pod_default_raise + }; + +First of them, ``pod_default_enqueue``, will just call syncronous entry point of driver, +three other are no-ops. + + diff --git a/dox/source/index.rst b/dox/source/index.rst index 400f726..57c8e8a 100644 --- a/dox/source/index.rst +++ b/dox/source/index.rst @@ -30,11 +30,16 @@ Source codes for the project (and for this book) can be found in `OpenPOD GitHub .. _PDF format: https://buildmedia.readthedocs.org/media/pdf/phantomdox/latest/phantomdox.pdf +......... +Rationale +......... + + .. include:: introduction.rst.inc -................. -Project structure -................. +.................. +Project navigation +.................. .. include:: directories.rst.inc diff --git a/dox/source/introduction.rst.inc b/dox/source/introduction.rst.inc index c9a68ab..19990ad 100644 --- a/dox/source/introduction.rst.inc +++ b/dox/source/introduction.rst.inc @@ -36,4 +36,4 @@ Goal is to define API and driver structure that is: Current state of specification: It is partially complete and waits for your comments. -The best way to comment is to create an issue in project's GitHub repository: . +The best way to comment is to create an issue in project's `GitHub repository: `_. diff --git a/dox/source/structure.rst.inc b/dox/source/structure.rst.inc index 003a854..db22b4b 100644 --- a/dox/source/structure.rst.inc +++ b/dox/source/structure.rst.inc @@ -5,12 +5,13 @@ OpenPOD driver includes: Driver descriptor is a required part of a driver. -* **Device descriptor.** A structure which describes each device exported by driver. Can be single and -static, or can be dynamically allocated in run time. For example, USB disk driver can create device -descriptors dynamically as devices come and go. -Device descriptor is not a required part - there can be driver which does not export devices at all -or just starts with empty set of devices. But most drivers will provide at least one device at start. +* **Device descriptor.** A structure which describes each device exported by driver. Can be single and + static, or can be dynamically allocated in run time. For example, USB disk driver can create device + descriptors dynamically as devices come and go. + + Device descriptor is not a required part - there can be driver which does not export devices at all + or just starts with empty set of devices. But most drivers will provide at least one device at start. * **Driver and/or device properties.** Set of key=value parameters to control driver or device and request meta information. For example, sound driver can set sampling rate with corresponding