[Sound-open-firmware] [PATCH] pipeline: docs: Add some comments to further document the pipeline core

[Liam Girdwood]

Add more descriptive documentation to help document the pipeline core.

Signed-off-by: Liam Girdwood <liam.r.girdwood at linux.intel.com>
---
 src/audio/pipeline.c | 40 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 5 deletions(-)

diff --git a/src/audio/pipeline.c b/src/audio/pipeline.c
index 3cfffb6..94d91b5 100644
--- a/src/audio/pipeline.c
+++ b/src/audio/pipeline.c
@@ -196,6 +196,7 @@ static void disconnect_downstream(struct pipeline *p, struct comp_dev *start,
 static void pipeline_cmd_update(struct pipeline *p, struct comp_dev *comp,
 	int cmd)
 {
+	/* only required by the scheduling component */
 	if (p->sched_comp != comp)
 		return;
 
@@ -345,7 +346,11 @@ int pipeline_buffer_connect(struct pipeline *p,
 	return 0;
 }
 
-/* call op on all downstream components - locks held by caller */
+/* Walk the graph downstream from start component in any pipeline and perform
+ * the operation on each component. Graph walk is stopped on any component
+ * returning an error ( < 0) and returns immediately. Components returning a
+ * positive error code also stop the graph walk on that branch causing the
+ * walk to return to a shallower level in the graph. */
 static int component_op_downstream(struct op_data *op_data,
 	struct comp_dev *start, struct comp_dev *current,
 	struct comp_dev *previous)
@@ -422,7 +427,11 @@ static int component_op_downstream(struct op_data *op_data,
 	return err;
 }
 
-/* call op on all upstream components - locks held by caller */
+/* Walk the graph upstream from start component in any pipeline and perform
+ * the operation on each component. Graph walk is stopped on any component
+ * returning an error ( < 0) and returns immediately. Components returning a
+ * positive error code also stop the graph walk on that branch causing the
+ * walk to return to a shallower level in the graph. */
 static int component_op_upstream(struct op_data *op_data,
 	struct comp_dev *start, struct comp_dev *current,
 	struct comp_dev *previous)
@@ -496,6 +505,8 @@ static int component_op_upstream(struct op_data *op_data,
 	return err;
 }
 
+/* walk the graph upstream from start component in any pipeline and prepare
+ * the buffer context for each inactive component */
 static int component_prepare_buffers_upstream(struct comp_dev *start,
 	struct comp_dev *current, struct comp_buffer *buffer)
 {
@@ -534,6 +545,8 @@ static int component_prepare_buffers_upstream(struct comp_dev *start,
 	return err;
 }
 
+/* walk the graph downstream from start component in any pipeline and prepare
+ * the buffer context for each inactive component */
 static int component_prepare_buffers_downstream(struct comp_dev *start,
 	struct comp_dev *current, struct comp_buffer *buffer)
 {
@@ -725,6 +738,10 @@ int pipeline_reset(struct pipeline *p, struct comp_dev *host)
  * end point(s) to the downstream components in a single operation.
  * i.e. the period data is processed from upstream end points to downstream
  * "comp" recursively in a single call to this function.
+ *
+ * The copy operation is for this pipeline only (as pipelines are scheduled
+ * individually) and it stops at pipeline endpoints (where a component has no
+ * source or sink components) or where this pipeline joins another pipeline.
  */
 static int pipeline_copy_from_upstream(struct comp_dev *start,
 	struct comp_dev *current)
@@ -779,6 +796,10 @@ copy:
  * downstream end point component(s) in a single operation.
  * i.e. the period data is processed from this component to downstream
  * end points recursively in a single call to this function.
+ *
+ * The copy operation is for this pipeline only (as pipelines are scheduled
+ * individually) and it stops at pipeline endpoints (where a component has no
+ * source or sink components) or where this pipeline joins another pipeline.
  */
 static int pipeline_copy_to_downstream(struct comp_dev *start,
 		struct comp_dev *current)
@@ -827,6 +848,10 @@ out:
 	return err;
 }
 
+/* walk the graph to downstream active components in any pipeline to find
+ * the first active DAI and return it's timestamp.
+ * TODO: consider pipeline with multiple DAIs
+ */
 static int timestamp_downstream(struct comp_dev *start,
 		struct comp_dev *current, struct sof_ipc_stream_posn *posn)
 {
@@ -868,7 +893,10 @@ downstream:
 	return res;
 }
 
-
+/* walk the graph to upstream active components in any pipeline to find
+ * the first active DAI and return it's timestamp.
+ * TODO: consider pipeline with multiple DAIs
+ */
 static int timestamp_upstream(struct comp_dev *start,
 		struct comp_dev *current, struct sof_ipc_stream_posn *posn)
 {
@@ -938,7 +966,8 @@ static void xrun(struct comp_dev *dev, void *data)
 }
 
 
-/* travel down stream from start and run func for each component of type */
+/* walk the graph downstream from start component in any pipeline and run
+ * function <func> for each component of type <type> */
 static void pipeline_for_each_downstream(struct pipeline *p,
 	enum sof_comp_type type, struct comp_dev *current,
 	void (*func)(struct comp_dev *, void *), void *data)
@@ -964,7 +993,8 @@ static void pipeline_for_each_downstream(struct pipeline *p,
 	}
 }
 
-/* travel up stream from start and run func for each component of type */
+/* walk the graph upstream from start component in any pipeline and run
+ * function <func> for each component of type <type> */
 static void pipeline_for_each_upstream(struct pipeline *p,
 	enum sof_comp_type type, struct comp_dev *current,
 	void (*func)(struct comp_dev *, void *), void *data)
-- 
2.14.1