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:
us...@infra.apache.org
