[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1959: Documentation for the Timer Driver

[GitBox <gi...@apache.org>]

v01d commented on a change in pull request #1959:
URL: https://github.com/apache/incubator-nuttx/pull/1959#discussion_r503922436



##########
File path: Documentation/components/drivers/character/timer.rst
##########
@@ -16,3 +16,274 @@ locations:
    reside in ``arch/``\ *<architecture>*\ ``/src/``\ *<hardware>*
    directory for the specific processor *<architecture>* and for
    the specific *<chip>* timer peripheral devices.
+   
+There are two ways to enable Timer Support along with the Timer Example. The first is faster and simpler. Just run the following command to use a ready config file with timer support and example included. You need to check if there's a timer config file for your specific chip. You may check it at the specific board's path: ``/boards/<arch>/<chip>/<variant>/config``.
+
+.. code-block:: console
+
+   $ ./tools/configure.sh <variant>:timer
+
+And the second way is creating your own config file. To do so, follow the next instructions.
+
+Enabling the Timer Support and Example in ``menuconfing``
+---------------------------------------------------------
+
+  1. Select Timer Instances
+
+ To select these timers browse in the ``menuconfig`` using the following path:
+
+  Go into menu :menuselection:`System Type --> <Chip> Peripheral Selection` and press :kbd:`Enter`.
+
+  Then select one or more timers according to availability.
+
+  2. Enable the Timer Support
+
+  Go into menu :menuselection:`Device Drivers --> Timer Driver Support` and press :kbd:`Enter`. Then enable:
+
+  - [x] Timer Support
+  - [x] Timer Arch Implementation
+
+  3. Include the Timer Example
+
+  Go into menu :menuselection:`Application Configuration --> Examples` and press :kbd:`Enter`. Then select the Timer Example.
+
+  - [x] Timer example
+
+  Below the option, it is possible to manually configure some parameters as the standard timer device path, the timeout, the sample rate in which the counter will be read, the number of samples to be executed, and other parameters. 
+   
+Timer Example
+--------------
+
+The previously selected example will basically consult the timer status, set a timer alarm interval, set a timer signal handler function to be notified at the alarm, which only increments a variable, and then it will start the timer. The application will periodically consult the timer status at the sample rate previously configured through the ``menuconfig`` to follow the time left until the timer expires. After the samples have been read, the application stops de timer.
+
+The `example code <https://github.com/apache/incubator-nuttx-apps/blob/master/examples/timer/timer_main.c#ref-example>`_  may be explored, its path is at ``/examples/timer/timer_main.c`` in the apps' repository. 
+
+In NuttX, the timer driver is a character driver and when a chip supports multiple timers, each one is accessible through its respective file in ``/dev`` directory. Each timer is registered using a unique numeric identifier (i.e. ``/dev/timer0``, ``/dev/timer1``, ...).  
+
+Use the following command to run the example:
+
+.. code-block:: console
+
+  `nsh> timer`
+ 
+This command will use the timer 0. To use the others, specify it through a parameter (where x is the timer number):
+
+.. code-block:: console
+
+  `nsh> timer -d /dev/timerx` 
+   
+Application Level Interface 
+----------------------------
+
+The first necessary thing to be done in order to use the timer driver in an application is to include the header file for the NuttX timer driver. It contains the Application Level Interface to the timer driver. To do so, include:
+
+.. code-block:: c
+
+  #include <nuttx/timers/timer.h>
+
+
+At an application level, the timer functionalities may be accessed through ``ioctl`` systems calls. The available ``ioctl`` commands are:
+
+* TCIOC_START
+* TCIOC_STOP
+* TCIOC_GETSTATUS
+* TCIOC_SETTIMEOUT 
+* TCIOC_NOTIFICATION
+* TCIOC_MAXTIMEOUT

Review comment:
       you can use `macro` for these




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org