You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by GitBox <gi...@apache.org> on 2020/10/09 14:19:31 UTC
[GitHub] [incubator-nuttx] saramonteiro opened a new pull request #1959: Documentation for the Timer Driver
saramonteiro opened a new pull request #1959:
URL: https://github.com/apache/incubator-nuttx/pull/1959
## Summary
This PR adds detailed instructions on how to use the Timer Driver.
## Impact
N/A
## Testing
N/A
----------------------------------------------------------------
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
[GitHub] [incubator-nuttx] v01d commented on pull request #1959: Documentation for the Timer Driver
Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #1959:
URL: https://github.com/apache/incubator-nuttx/pull/1959#issuecomment-708597159
I think it is OK to keep that if it clears up the docs.
----------------------------------------------------------------
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
[GitHub] [incubator-nuttx] davids5 commented on pull request #1959: Documentation for the Timer Driver
Posted by GitBox <gi...@apache.org>.
davids5 commented on pull request #1959:
URL: https://github.com/apache/incubator-nuttx/pull/1959#issuecomment-709625583
@v01d - Thank you!
----------------------------------------------------------------
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
[GitHub] [incubator-nuttx] acassis merged pull request #1959: Documentation for the Timer Driver
Posted by GitBox <gi...@apache.org>.
acassis merged pull request #1959:
URL: https://github.com/apache/incubator-nuttx/pull/1959
----------------------------------------------------------------
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
[GitHub] [incubator-nuttx] v01d commented on pull request #1959: Documentation for the Timer Driver
Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #1959:
URL: https://github.com/apache/incubator-nuttx/pull/1959#issuecomment-707716387
Changes look good. I added a few comments. Also, I'm not sure if it is good idea to mention internal functions such as `start`/`stop`. Or do are you refering to the lower-half interface operations? If so, maybe you can mention that explicitly and show the ops struct here
----------------------------------------------------------------
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
[GitHub] [incubator-nuttx] saramonteiro commented on pull request #1959: Documentation for the Timer Driver
Posted by GitBox <gi...@apache.org>.
saramonteiro commented on pull request #1959:
URL: https://github.com/apache/incubator-nuttx/pull/1959#issuecomment-708581994
I applied the macros and yes, I meant operations. I added now the struct, please take a look and let me know what you think. Maybe it is really getting too much into detail. Maybe We can consider deleting the ops related info
----------------------------------------------------------------
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
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1959: Documentation for the Timer Driver
Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #1959:
URL: https://github.com/apache/incubator-nuttx/pull/1959#discussion_r503922645
##########
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
+
+These ``ioctl`` commands internally call lower-half layer functions and the parameters are forwarded to these functions through the ``ioctl`` system call. The return of a system call is the return of a function.
+Since ``ioctl`` system calls expect a file descriptor, before using these commands, it's necessary to open the timer device special file in order to get a file descriptor. The following snippet demonstrates how to do so:
+
+.. code-block:: c
+
+ /* Open the timer device */
+
+ printf("Open %s\n", devname);
+
+ fd = open(devname, O_RDONLY);
+ if (fd < 0)
+ {
+ fprintf(stderr, "ERROR: Failed to open %s: %d\n",
+ devname, errno);
+ return EXIT_FAILURE;
+ }
+
+TCIOC_START
Review comment:
you can use macro (same for every other subsection)
----------------------------------------------------------------
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
[GitHub] [incubator-nuttx] saramonteiro commented on pull request #1959: Documentation for the Timer Driver
Posted by GitBox <gi...@apache.org>.
saramonteiro commented on pull request #1959:
URL: https://github.com/apache/incubator-nuttx/pull/1959#issuecomment-706330796
@v01d Please, take a look. I followed your suggestions in our talking.
----------------------------------------------------------------
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
[GitHub] [incubator-nuttx] davids5 commented on pull request #1959: Documentation for the Timer Driver
Posted by GitBox <gi...@apache.org>.
davids5 commented on pull request #1959:
URL: https://github.com/apache/incubator-nuttx/pull/1959#issuecomment-709624179
Nice! Where is this published too?
----------------------------------------------------------------
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
[GitHub] [incubator-nuttx] v01d commented on pull request #1959: Documentation for the Timer Driver
Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #1959:
URL: https://github.com/apache/incubator-nuttx/pull/1959#issuecomment-709624735
Docs are at: https://nuttx.apache.org/docs/latest/
However they are only updated daily for now, as we lack the proper setup to rebuild the website on pushes to this repo.
----------------------------------------------------------------
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
[GitHub] [incubator-nuttx] v01d commented on a change in pull request #1959: Documentation for the Timer Driver
Posted by 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