Add oneshot timer lower half interface

include/nuttx/timers/oneshot.h

@@ -0,0 +1,204 @@
+/****************************************************************************
+ * include/nuttx/timers/oneshot.h
+ *
+ *   Copyright (C) 2016 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ * 3. Neither the name NuttX nor the names of its contributors may be
+ *    used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+ * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ ****************************************************************************/
+
+#ifndef __INCLUDE_NUTTX_TIMERS_ONESHOT_H
+#define __INCLUDE_NUTTX_TIMERS_ONESHOT_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <stdint.h>
+#include <time.h>
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+/* Method access helper macros **********************************************/
+
+/****************************************************************************
+ * Name: ONESHOT_MAX_DELAY
+ *
+ * Description:
+ *   Determine the maximum delay of the one-shot timer (in microseconds)
+ *
+ * Input Parameters:
+ *   lower   An instance of the lower-half oneshot state structure.  This
+ *           structure must have been previously initialized via a call to
+ *           oneshot_initialize();
+ *   usec    The user-provided location in which to return the maxumum delay
+ *           in microseconds.
+ *
+ * Returned Value:
+ *   Zero (OK) is returned on success; a negated errno value is returned
+ *   on failure.
+ *
+ ****************************************************************************/
+
+#define ONESHOT_MAX_DELAY(l,u) ((l)->ops->max_delay(l,u))
+
+/****************************************************************************
+ * Name: ONESHOT_START
+ *
+ * Description:
+ *   Start the oneshot timer
+ *
+ * Input Parameters:
+ *   lower   An instance of the lower-half oneshot state structure.  This
+ *           structure must have been previously initialized via a call to
+ *           oneshot_initialize();
+ *   handler The function to call when when the oneshot timer expires.
+ *   arg     An opaque argument that will accompany the callback.
+ *   ts      Provides the duration of the one shot timer.
+ *
+ * Returned Value:
+ *   Zero (OK) is returned on success; a negated errno value is returned
+ *   on failure.
+ *
+ ****************************************************************************/
+
+#define ONESHOT_START(l,h,a,t) ((l)->ops->start(l,h,a,t))
+
+/****************************************************************************
+ * Name: ONESHOT_CANCEL
+ *
+ * Description:
+ *   Cancel the oneshot timer and return the time remaining on the timer.
+ *
+ *   NOTE: This function may execute at a high rate with no timer running (as
+ *   when pre-emption is enabled and disabled).
+ *
+ * Input Parameters:
+ *   lower   Caller allocated instance of the oneshot state structure.  This
+ *           structure must have been previously initialized via a call to
+ *           oneshot_initialize();
+ *   ts      The location in which to return the time remaining on the
+ *           oneshot timer.  A time of zero is returned if the timer is
+ *           not running.
+ *
+ * Returned Value:
+ *   Zero (OK) is returned on success.  A call to up_timer_cancel() when
+ *   the timer is not active should also return success; a negated errno
+ *   value is returned on any failure.
+ *
+ ****************************************************************************/
+
+#define ONESHOT_CANCEL(l,t) ((l)->ops->cancel(l,t))
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+
+/* This describes the callback function that will be invoked when the oneshot
+ * timer expires.  The oneshot fires, the client will receive:
+ *
+ *   lower - An instance of the lower half driver
+ *   arg   - The opaque argument provided when the interrupt was registered
+ */
+
+typedef void (*oneshot_callback_t)(FAR struct oneshot_dev_s *lower,
+                                   void *arg);
+
+/* The one short operations supported by the lower half driver */
+
+struct oneshot_operations_s
+{
+  CODE int (*max_delay)(FAR struct oneshot_s *lower, uint64_t *usec);
+  CODE int (*start)(FAR struct oneshot_dev_s *lower,
+                    oneshot_callback_t callback, FAR void *arg,
+                    FAR const struct timespec *ts);
+  CODE int (*cancel)(struct oneshot_dev_s *lower, FAR struct timespec *ts);
+};
+
+/* This structure describes the state of the oneshot timer driver */
+
+struct oneshot_dev_s
+{
+  /* This is the part of the lower half driver that is visible to the upper-
+   * half client of the driver.
+   */
+
+  FAR const struct oneshot_operations_s *ops;
+
+  /* Private lower half data may follow */
+};
+
+/****************************************************************************
+ * Public Data
+ ****************************************************************************/
+
+#undef EXTERN
+#if defined(__cplusplus)
+#define EXTERN extern "C"
+extern "C"
+{
+#else
+#define EXTERN extern
+#endif
+
+/****************************************************************************
+ * Public Function Prototypes
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: oneshot_initialize
+ *
+ * Description:
+ *   Initialize the oneshot timer and return a oneshot lower half driver
+ *   instance.
+ *
+ * Input Parameters:
+ *   chan       Timer counter channel to be used.
+ *   resolution The required resolution of the timer in units of
+ *              microseconds.  NOTE that the range is restricted to the
+ *              range of uint16_t (excluding zero).
+ *
+ * Returned Value:
+ *   On success, a non-NULL instance of the oneshot lower-half driver is
+ *   returned.  NULL is return on any failure.
+ *
+ ****************************************************************************/
+
+FAR struct oneshot_dev_s *oneshot_initialize(int chan, uint16_t resolution);
+
+#undef EXTERN
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __INCLUDE_NUTTX_TIMERS_ONESHOT_H */