Stream: Add In and Out stream interfaces and config

These interfaces will be used by USART, USB and I2C
stream drivers to provide a uniform interface for
console mux'ing code.

Signed-off-by: Anton Staaf <robotboy@chromium.org>

BRANCH=None
BUG=None
TEST=make buildall -j

Change-Id: If8938512c29708f7b8c28f6ca1c707aa6b5c1708
Reviewed-on: https://chromium-review.googlesource.com/216001
Reviewed-by: Randall Spangler <rspangler@chromium.org>
Commit-Queue: Anton Staaf <robotboy@chromium.org>
Tested-by: Anton Staaf <robotboy@chromium.org>

common/build.mk

@@ -64,6 +64,7 @@ common-$(CONFIG_SHA1)+=sha1.o
 common-$(CONFIG_SMBUS)+= smbus.o
 common-$(CONFIG_SOFTWARE_CLZ)+=clz.o
 common-$(CONFIG_SPI_FLASH)+=spi_flash.o
+common-$(CONFIG_STREAM)+=in_stream.o out_stream.o
 common-$(CONFIG_SWITCH)+=switch.o
 common-$(CONFIG_SW_CRC)+=crc.o
 common-$(CONFIG_TEMP_SENSOR)+=temp_sensor.o thermal.o throttle_ap.o

common/in_stream.c

@@ -0,0 +1,19 @@
+/* Copyright (c) 2014 The Chromium OS Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#include "in_stream.h"
+
+size_t in_stream_read(struct in_stream const *stream,
+		      uint8_t *buffer,
+		      size_t count)
+{
+	return stream->ops->read(stream, buffer, count);
+}
+
+void in_stream_ready(struct in_stream const *stream)
+{
+	if (stream->ready)
+		stream->ready(stream);
+}

common/out_stream.c

@@ -0,0 +1,24 @@
+/* Copyright (c) 2014 The Chromium OS Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#include "out_stream.h"
+
+size_t out_stream_write(struct out_stream const *stream,
+			uint8_t const *buffer,
+			size_t count)
+{
+	return stream->ops->write(stream, buffer, count);
+}
+
+void out_stream_flush(struct out_stream const *stream)
+{
+	stream->ops->flush(stream);
+}
+
+void out_stream_ready(struct out_stream const *stream)
+{
+	if (stream->ready)
+		stream->ready(stream);
+}

include/config.h

@@ -902,6 +902,15 @@
  */
 #undef CONFIG_TEMP_SENSOR_POWER_GPIO
 
+/*****************************************************************************/
+/* Stream config
+ *
+ * Streams are an abstraction for managing character based IO streams.  Streams
+ * can virtualize USARTs (interrupt, polled, or DMA driven), USB bulk
+ * endpoints, I2C transfers, and more.
+ */
+#undef CONFIG_STREAM
+
 /*****************************************************************************/
 /* UART config */
 

include/in_stream.h

@@ -0,0 +1,54 @@
+/* Copyright (c) 2014 The Chromium OS Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+#ifndef INCLUDE_IN_STREAM_H
+#define INCLUDE_IN_STREAM_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+struct in_stream;
+
+struct in_stream_ops {
+	/*
+	 * Read at most count characters from the input stream into the user
+	 * buffer provided.  Return the number of characters actually read
+	 * into the buffer.
+	 */
+	size_t (*read)(struct in_stream const *stream,
+		       uint8_t *buffer,
+		       size_t count);
+};
+
+struct in_stream {
+	/*
+	 * Ready will be called by the stream every time new characters are
+	 * added to the stream.  This may be called from an interrupt context
+	 * so work done by the ready callback should be minimal.  Likely this
+	 * callback will be used to call task_wake, or some similar signaling
+	 * mechanism.
+	 *
+	 * This callback is part of the user configuration of a stream, and not
+	 * a stream manipulation function (in_stream_ops).  That means that
+	 * each stream can be configured with its own ready callback.
+	 *
+	 * If no callback functionality is required ready can be specified as
+	 * NULL.
+	 */
+	void (*ready)(struct in_stream const *stream);
+
+	struct in_stream_ops const *ops;
+};
+
+/*
+ * Helper functions that call the associated stream operation and pass it the
+ * given stream.  These help prevent mistakes where one stream is passed to
+ * another stream's functions.
+ */
+size_t in_stream_read(struct in_stream const *stream,
+		      uint8_t *buffer,
+		      size_t count);
+void   in_stream_ready(struct in_stream const *stream);
+
+#endif /* INCLUDE_IN_STREAM_H */

include/out_stream.h

@@ -0,0 +1,80 @@
+/* Copyright (c) 2014 The Chromium OS Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+#ifndef INCLUDE_OUT_STREAM_H
+#define INCLUDE_OUT_STREAM_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+struct out_stream;
+
+/*
+ * An out_stream is a generic interface providing operations that can be used
+ * to send a character stream over a USB endpoint, UART, I2C host interface, and
+ * more.  Each realization of an out_stream provides a constant instance of
+ * the out_stream_ops structure that is used to operate on that realizations
+ * out_streams.  For example, the UART driver could provide one out_stream_ops
+ * structure and four UART configs.  Each UART config uses the same
+ * out_stream_ops structure.
+ */
+struct out_stream_ops {
+	/*
+	 * Write at most count characters from buffer into the output stream.
+	 * Return the number of characters actually written.
+	 */
+	size_t (*write)(struct out_stream const *stream,
+			uint8_t const *buffer,
+			size_t count);
+
+	/*
+	 * Flush all outgoing data.  This works if we are in an interrupt
+	 * context, or normal context.  The call blocks until the output
+	 * stream is empty.
+	 */
+	void (*flush)(struct out_stream const *stream);
+
+};
+
+/*
+ * The out_stream structure is embedded in the device configuration structure
+ * that wishes to publish an out_stream capable interface.  Uses of that device
+ * can pass a pointer to the embedded out_stream around and use it like any
+ * other out_stream.
+ */
+struct out_stream {
+	/*
+	 * Ready will be called by the stream every time characters are removed
+	 * from the stream.  This may be called from an interrupt context
+	 * so work done by the ready callback should be minimal.  Likely this
+	 * callback will be used to call task_wake, or some similar signaling
+	 * mechanism.
+	 *
+	 * This callback is part of the user configuration of a stream, and not
+	 * a stream manipulation function (in_stream_ops).  That means that
+	 * each stream can be configured with its own ready callback.
+	 *
+	 * If no callback functionality is required ready can be specified as
+	 * NULL.
+	 */
+	void (*ready)(struct out_stream const *stream);
+
+	struct out_stream_ops const *ops;
+};
+
+/*
+ * Helper functions that call the associated stream operation and pass it the
+ * given stream.  These help prevent mistakes where one stream is passed to
+ * another stream's functions.
+ */
+size_t out_stream_write(struct out_stream const *stream,
+			uint8_t const *buffer,
+			size_t count);
+void   out_stream_flush(struct out_stream const *stream);
+int    out_stream_pause(struct out_stream const *stream);
+int    out_stream_resume(struct out_stream const *stream);
+int    out_stream_is_paused(struct out_stream const *stream);
+void   out_stream_ready(struct out_stream const *stream);
+
+#endif /* INCLUDE_OUT_STREAM_H */