From c037dd98c5bcc825502147a229f6d048e2d1c7fa Mon Sep 17 00:00:00 2001
From: Federico Vaga <federico.vaga@gmail.com>
Date: Wed, 1 Feb 2012 23:53:42 +0100
Subject: [PATCH] Documentation: explain ti->abort and ti->change_status
Signed-off-by: Federico Vaga <federico.vaga@gmail.com>
Acked-by: Alessandro Rubini <rubini@gnudd.com>
---
Documentation/zio/trigger.txt | 14 ++++++++++++++
include/linux/zio-trigger.h | 7 ++++++-
2 files changed, 20 insertions(+), 1 deletion(-)
diff --git a/Documentation/zio/trigger.txt b/Documentation/zio/trigger.txt
index ccd4aca..02c7f81 100644
--- a/Documentation/zio/trigger.txt
+++ b/Documentation/zio/trigger.txt
@@ -79,6 +79,20 @@ trigger will push blocks to the buffer; for output it will release
the blocks. zio-core offers zio_generic_data_done() for triggers
that don't need special handling.
+ void (*abort)(struct zio_cset *cset);
+
+This function is called to stop a running acquisition before the data_done
+invocation. ZIO calls this function when a trigger is disabled during a
+data transfer.
+
+ void (*change_status)(struct zio_ti *ti, unsigned int status);
+
+ZIO invokes this function each time user enable or disable the trigger. The
+status value is the new status of the trigger: 0 for disable and 1 for enable.
+The function activates or deactivates the trigger depending on status. If the
+trigger is running and the user disable it before the data_done, ZIO calls
+sequentially abort and then change_status.
+
When the trigger fires
======================
diff --git a/include/linux/zio-trigger.h b/include/linux/zio-trigger.h
index 00e227d..57d51cc 100644
--- a/include/linux/zio-trigger.h
+++ b/include/linux/zio-trigger.h
@@ -69,13 +69,18 @@ void zio_fire_trigger(struct zio_ti *ti);
* the data has been transferred for the cset, the device calls back the
* trigger. For output, data_done frees the blocks and prepares new
* blocks if possible; for input, data_done pushes material to the buffers.
+ * If the transfer must be interrupted before the invocation of data_done,
+ * the abort function must be called.
*
* Then, a trigger instance is configured either by sysfs (and this means
* the conf_set callback runs and the instance is notified) or by writing
* a whole control to the control device. In this case the config method
* is called by the write method.
*
- * FIXME describe well abort and change_status
+ * A trigger can be enabled or disabled; each time the trigger status changes,
+ * ZIO invokes change_status. The trigger driver must use change_status to
+ * start and stop the trigger depending on status value.
+ *
*/
struct zio_trigger_operations {
int (*push_block)(struct zio_ti *ti,
--
GitLab