Add skeleton file for eventual implementation of aio_read()

7 files changed, 352 insertions, 5 deletions

diff --git a/nuttx/include/aio.h b/nuttx/include/aio.h
index f945cd717..b130f522a 100644
--- a/nuttx/include/aio.h
+++ b/nuttx/include/aio.h
@@ -46,9 +46,37 @@
 #include <signal.h>
 #include <time.h>
 
+#include <nuttx/wqueue.h>
+
 /****************************************************************************
  * Pre-processor Definitions
  ****************************************************************************/
+/* Configuration ************************************************************/
+/* Work queue support is required.  In the flat, embedded build the low-
+ * priority work queue is required so that the asynchronous I/O does not
+ * interfere with high priority driver operations.  In the protected and
+ * kernel mode builds, user-space work queue support is required.  If these
+ * pre-requisites are met, then asynchronous I/O support can be enabled with
+ * CONFIG_LIBC_AIO
+ */
+
+#ifdef CONFIG_LIBC_AIO
+
+#ifndef CONFIG_SCHED_WORKQUEUE
+#  error Asynchronous I/O requiresCONFIG_SCHED_WORKQUEUE
+#else
+#  if defined (CONFIG_BUILD_PROTECTED) || defined(CONFIG_BUILD_KERNEL)
+#    ifndef CONFIG_SCHED_USRWORK
+#      error User-space asynchronous I/O requires CONFIG_SCHED_USRWORK
+#    endif
+#  else
+#    ifndef CONFIG_SCHED_LPWORK
+#      error Flat-build asynchronous I/O requires CONFIG_SCHED_LPWORK
+#    endif
+#  endif
+#endif
+
+/* Standard Definitions *****************************************************/
 /* aio_cancel return values
  *
  * AIO_ALLDONE     - Indicates that none of the requested operations could
@@ -93,6 +121,8 @@
 
 struct aiocb
 {
+  /* Standard fields required by POSIX */
+
   struct sigevent aio_sigevent;  /* Signal number and value */
   FAR volatile void *aio_buf;    /* Location of buffer */
   off_t aio_offset;              /* File offset */
@@ -100,6 +130,10 @@ struct aiocb
   int aio_fildes;                /* File descriptor */
   int aio_reqprio;               /* Request priority offset */
   int aio_lio_opcode;            /* Operation to be performed */
+
+  /* Non-standard, implementation-dependent data */
+
+  struct work_s aio_work;        /* Use to defer I/O to the work thread */
 };
 
 /****************************************************************************
@@ -126,12 +160,16 @@ ssize_t aio_return(FAR struct aiocb *aiocbp);
 int aio_suspend(FAR const struct aiocb *const list[], int nent,
                 FAR const struct timespec *timeout);
 int aio_write(FAR struct aiocb *aiocbp);
+
+#ifndef CONFIG_PTHREAD_DISABLE
 int lio_listio(int mode, FAR struct aiocb *const list[], int nent,
                FAR struct sigevent *sig);
+#endif
 
 #undef EXTERN
 #ifdef __cplusplus
 }
 #endif
 
+#endif  /* CONFIG_LIBC_AIO */
 #endif /* __INCLUDE_AIO_H */
diff --git a/nuttx/libc/Kconfig b/nuttx/libc/Kconfig
index e95cd245a..e425a48d5 100644
--- a/nuttx/libc/Kconfig
+++ b/nuttx/libc/Kconfig
@@ -79,6 +79,14 @@ config EOL_IS_EITHER_CRLF
 
 endchoice
 
+config LIBC_AIO
+	bool "Asynchronous I/O support"
+	default n
+	depends on ((BUILD_PROTECTED || BUILD_KERNEL) && SCHED_USRWORK) || (BUILD_FLAT && SCHED_LPWORK)
+	---help---
+		Enable support for aynchronous I/O.  This selection enabled the
+		interface declared in include/aio.h.
+
 config LIBC_EXECFUNCS
 	bool "Enable exec[l|v] / posix_spawn() Support"
 	default n
diff --git a/nuttx/libc/aio/Make.defs b/nuttx/libc/aio/Make.defs
index df78a66c0..0ad5bbb47 100644
--- a/nuttx/libc/aio/Make.defs
+++ b/nuttx/libc/aio/Make.defs
@@ -33,11 +33,15 @@
 #
 ############################################################################
 
-ifneq ($(CONFIG_DISABLE_PTHREAD),y)
+ifeq ($(CONFIG_LIBC_AIO),y)
 
 # Add the asynchronous I/O C files to the build
 
+CSRCS += aio_read.c
+
+ifneq ($(CONFIG_PTHREAD_DISABLE),y)
 CSRCS += lio_listio.c
+endif
 
 # Add the asynchronous I/O directory to the build
 
diff --git a/nuttx/libc/aio/aio.h b/nuttx/libc/aio/aio.h
new file mode 100644
index 000000000..9a103a420
--- /dev/null
+++ b/nuttx/libc/aio/aio.h
@@ -0,0 +1,80 @@
+/****************************************************************************
+ * libc/aio/aio.h
+ *
+ *   Copyright (C) 2014 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 __LIBC_AIO_AIO_H
+#define __LIBC_AIO_AIO_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <aio.h>
+#include <nuttx/wqueue.h>
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+/* Select the appropriate work queue */
+
+#if defined (CONFIG_BUILD_PROTECTED) || defined(CONFIG_BUILD_KERNEL)
+#  define AIO_QUEUE LPWORK
+#else
+#  define AIO_QUEUE USRWORK
+#endif
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Variables
+ ****************************************************************************/
+
+#undef EXTERN
+#if defined(__cplusplus)
+#define EXTERN extern "C"
+extern "C"
+{
+#else
+#define EXTERN extern
+#endif
+
+/****************************************************************************
+ * Public Function Prototypes
+ ****************************************************************************/
+
+#endif /* __LIBC_AIO_AIO_H */
diff --git a/nuttx/libc/aio/aio_read.c b/nuttx/libc/aio/aio_read.c
new file mode 100644
index 000000000..7e19fb0ed
--- /dev/null
+++ b/nuttx/libc/aio/aio_read.c
@@ -0,0 +1,217 @@
+/****************************************************************************
+ * libc/aio/aio_read.c
+ *
+ *   Copyright (C) 2014 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.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <signal.h>
+#include <aio.h>
+#include <assert.h>
+#include <errno.h>
+
+#include "lib_internal.h"
+#include "aio/aio.h"
+
+#ifndef CONFIG_LIBC_AIO
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+/* Configuration ************************************************************/
+
+/****************************************************************************
+ * Private Types
+ ****************************************************************************/
+
+/****************************************************************************
+ * Private Variables
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Variables
+ ****************************************************************************/
+
+/****************************************************************************
+ * Private Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: aio_read_worker
+ *
+ * Description:
+ *   This function executes on the worker thread and performs the
+ *   asynchronous I/O operation.
+ *
+ * Input Parameters:
+ *   arg - Worker argument.  In this case, a pointer to an instance of
+ *     struct aiocb cast to void *.
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
+
+static void aio_read_worker(FAR void *arg)
+{
+  FAR struct aiocb *aiocbp = (FAR struct aiocb *)arg;
+  DEBASSERT(arg);
+#warning Missing logic
+}
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: aio_read
+ *
+ * Description:
+ *   The aio_read() function reads aiocbp->aio_nbytes from the file
+ *   associated with aiocbp->aio_fildes into the buffer pointed to by
+ *   aiocbp->aio_buf. The function call will return when the read request
+ *   has been initiated or queued to the file or device (even when the data
+ *   cannot be delivered immediately).
+ *
+ *   The aiocbp value may be used as an argument to aio_error() and
+ *   aio_return() in order to determine the error status and return status,
+ *   respectively, of the asynchronous operation while it is proceeding. If
+ *   an error condition is encountered during queuing, the function call
+ *   will return without having initiated or queued the request. The
+ *   requested operation takes place at the absolute position in the file as
+ *   given by aio_offset, as if lseek() were called immediately prior to the
+ *   operation with an offset equal to aio_offset and a whence equal to
+ *   SEEK_SET. After a successful call to enqueue an asynchronous I/O
+ *   operation, the value of the file offset for the file is unspecified.
+ *
+ *   The aiocbp->aio_lio_opcode field will be ignored by aio_read().
+ * 
+ *   The aiocbp argument points to an aiocb structure. If the buffer pointed
+ *   to by aiocbp->aio_buf or the control block pointed to by aiocbp becomes
+ *   an illegal address prior to asynchronous I/O completion, then the
+ *   behavior is undefined.
+ *
+ *   Simultaneous asynchronous operations using the same aiocbp produce
+ *   undefined results.
+ *
+ *   For any system action that changes the process memory space while an 
+ *   synchronous I/O is outstanding to the address range being changed, the
+ *   result of that action is undefined.
+ *
+ * Input Parameters:
+ *   aiocbp - A pointer to an instance of struct aiocb
+ *
+ * Returned Value:
+ *
+ *   The aio_read() function will return the value zero if the I/O operation
+ *   is successfully queued; otherwise, the function will return the value
+ *   -1 and set errno to indicate the error.  The aio_read() function will
+ *   ail if:
+ *
+ *   EAGAIN - The requested asynchronous I/O operation was not queued due to
+ *     system resource limitations.
+ *
+ *   Each of the following conditions may be detected synchronously at the
+ *   time of the call to aio_read(), or asynchronously. If any of the
+ *   conditions below are detected synchronously, the aio_read() function
+ *   will return -1 and set errno to the corresponding value. If any of the
+ *   conditions below are detected asynchronously, the return status of the
+ *   asynchronous operation is set to -1, and the error status of the
+ *   asynchronous operation is set to the corresponding value.
+ *
+ *   EBADF - The aiocbp->aio_fildes argument is not a valid file descriptor
+ *     open for reading.
+ *   EINVAL - The file offset value implied by aiocbp->aio_offset would be
+ *     invalid, aiocbp->aio_reqprio is not a valid value, or
+ *     aiocbp->aio_nbytes is an invalid value.
+ *
+ *   In the case that the aio_read() successfully queues the I/O operation
+ *   but the operation is subsequently cancelled or encounters an error, the
+ *   return status of the asynchronous operation is one of the values
+ *   normally returned by the read() function call. In addition, the error
+ *   status of the asynchronous operation is set to one of the error
+ *   statuses normally set by the read() function call, or one of the
+ *   following values:
+ *
+ *   EBADF - The aiocbp->aio_fildes argument is not a valid file descriptor
+ *     open for reading.
+ *   ECANCELED - The requested I/O was cancelled before the I/O completed
+ *     due to an explicit aio_cancel() request.
+ *   EINVAL - The file offset value implied by aiocbp->aio_offset would be
+ *     invalid.
+ *
+ * The following condition may be detected synchronously or asynchronously:
+ *
+ *   EOVERFLOW - The file is a regular file, aiobcp->aio_nbytes is greater
+ *     than 0, and the starting offset in aiobcp->aio_offset is before the
+ *     end-of-file and is at or beyond the offset maximum in the open file
+ *     description associated with aiocbp->aio_fildes.
+ *
+ * POSIX Compliance:
+ * - The standard requires that if prioritized I/O is supported for this
+ *   file, then the asynchronous operation will be submitted at a priority
+ *   equal to a base scheduling priority minus aiocbp->aio_reqprio. If
+ *   Thread Execution Scheduling is not supported, then the base scheduling
+ *   priority is that of the calling thread.
+ *
+ *   This implementation uses the NuttX work queues that run at a fixed,
+ *   configured priority.
+ *
+ * - Most errors required in the standard are not detected at this point.
+ *   There are no pre-queuing checks for the validity of the operation.
+ *
+ ****************************************************************************/
+
+int aio_read(FAR struct aiocb *aiocbp);
+{
+  int ret;
+
+  DEBUGASSERT(aiocbp);
+
+  /* Defer the work to the worker thread */
+
+  ret = work_queue(AIO_QUEUE, &aiocbp->aio_work, aio_read_worker, aiocbp, 0);
+  if (ret < 0)
+    {
+      set_errno(ret);
+      return ERROR;
+    }
+
+  return OK;
+}
+
+#endif /* CONFIG_LIBC_AIO */
diff --git a/nuttx/libc/aio/lio_listio.c b/nuttx/libc/aio/lio_listio.c
index 529477cd6..2a817c8aa 100644
--- a/nuttx/libc/aio/lio_listio.c
+++ b/nuttx/libc/aio/lio_listio.c
@@ -47,7 +47,7 @@
 
 #include "lib_internal.h"
 
-#ifndef CONFIG_DISABLE_PTHREAD
+#if defined(CONFIG_LIBC_AIO) && !defined(CONFIG_PTHREAD_DISABLE)
 
 /****************************************************************************
  * Pre-processor Definitions
@@ -283,4 +283,4 @@ int lio_listio(int mode, FAR struct aiocb *const list[], int nent,
   return -ENOSYS;
 }
 
-#endif /* !CONFIG_DISABLE_PTHREAD */
+#endif /* CONFIG_LIBC_AIO && !CONFIG_PTHREAD_DISABLE */
diff --git a/nuttx/libc/lib_internal.h b/nuttx/libc/lib_internal.h
index 829ea968e..d5d1700ed 100644
--- a/nuttx/libc/lib_internal.h
+++ b/nuttx/libc/lib_internal.h
@@ -51,7 +51,7 @@
 #include <nuttx/streams.h>
 
 /****************************************************************************
- * Definitions
+ * Pre-processor Definitions
  ****************************************************************************/
 /* This configuration directory is used in environment variable processing
  * when we need to reference the user's home directory.  There are no user
@@ -125,7 +125,7 @@
  ****************************************************************************/
 
 /****************************************************************************
- * Public Variables
+ * Public Data
  ****************************************************************************/
 
 #undef EXTERN