Initial I2S interface defintion

ChangeLog

@@ -5981,4 +5981,7 @@
 	  SAMA5D3x-EK board (2013-11-6).
 	* arch/arm/src/sama5/sam_pwm.c and .h: SAMA5 PWM driver is now
 	  function (2013-11-7).
+	* include/nuttx/audio/i2s.h:  First cut at an I2S interface
+	  definition.  This initial definition is sparse will will
+	  probably evolve significantly (2011-11-7).
 

include/nuttx/audio/i2s.h

@@ -0,0 +1,177 @@
+/****************************************************************************
+ * include/nuttx/audio/i2s.h
+ *
+ *   Copyright(C) 2013 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_AUDIO_I2S_H
+#define __INCLUDE_NUTTX_AUDIO_I2S_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <sys/types.h>
+#include <stdint.h>
+#include <stdbool.h>
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+/* Configuration ************************************************************/
+
+/* Access macros ************************************************************/
+
+/****************************************************************************
+ * Name: I2S_FREQUENCY
+ *
+ * Description:
+ *   Set the I2S frequency. Required.
+ *
+ * Input Parameters:
+ *   dev -       Device-specific state data
+ *   frequency - The I2S frequency requested
+ *
+ * Returned Value:
+ *   Returns the actual frequency selected
+ *
+ ****************************************************************************/
+
+#define I2S_FREQUENCY(d,f) ((d)->ops->frequency(d,f))
+
+/****************************************************************************
+ * Name: I2S_SEND
+ *
+ * Description:
+ *   Send a block of data on I2S. Required.
+ *
+ * Input Parameters:
+ *   dev    - Device-specific state data
+ *   buffer - A pointer to the buffer of data to be sent
+ *   nbytes - the length of data to send from the buffer in number of bytes.
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
+
+#define I2S_SEND(d,b,n) ((d)->ops->send(d,b,n))
+#endif
+
+/****************************************************************************
+ * Name: I2S_RECEIVE
+ *
+ * Description:
+ *   Receive a block of data from I2S. Required.
+ *
+ * Input Parameters:
+ *   dev -    Device-specific state data
+ *   buffer - A pointer to the buffer in which to recieve data
+ *   nbytes - The length of data that can be received in the buffer in number
+ *            of bytes.
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
+
+#define I2S_RECEIVE(d,b,n) ((d)->ops->recvblock(d,b,n))
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+
+/* The I2S vtable */
+
+struct i2s_dev_s;
+struct i2s_ops_s
+{
+  uint32_t (*frequency)(FAR struct i2s_dev_s *dev, uint32_t frequency);
+  void     (*send)(FAR struct i2s_dev_s *dev, FAR const void *buffer,
+                   size_t nbytes);
+  void     (*receive)(FAR struct i2s_dev_s *dev, FAR void *buffer,
+                      size_t nbytes);
+};
+
+/* I2S private data.  This structure only defines the initial fields of the
+ * structure visible to the I2S client.  The specific implementation may 
+ * add additional, device specific fields
+ */
+
+struct i2s_dev_s
+{
+  FAR const struct i2s_ops_s *ops;
+};
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+#undef EXTERN
+#if defined(__cplusplus)
+#define EXTERN extern "C"
+extern "C"
+{
+#else
+#define EXTERN extern
+#endif
+
+/****************************************************************************
+ * Name: up_i2cinitialize
+ *
+ * Description:
+ *   Initialize the selected I2S port.
+ *
+ *   This is a generic prototype for the I2S initialize logic.  Specific
+ *   architectures may support different I2S initialization functions if,
+ *   for example, those architectures support multiple, incompatible I2S
+ *   implementations.  In any event, the prototype of those architecture-
+ *   specific initialization functions should be the same as
+ *   up_i2cinitialize()
+ *
+ * Input Parameter:
+ *   Port number (for hardware that has mutiple I2S interfaces)
+ *
+ * Returned Value:
+ *   Valid I2S device structure reference on succcess; a NULL on failure
+ *
+ ****************************************************************************/
+
+FAR struct i2s_dev_s *up_i2cinitialize(int port);
+
+#undef EXTERN
+#if defined(__cplusplus)
+}
+#endif
+#endif /* __INCLUDE_NUTTX_AUDIO_I2S_H */