Mark API layering violations in the helper module with @todo notes.

[openocd.git] / src / jtag / jtag.h

diff --git a/src/jtag/jtag.h b/src/jtag/jtag.h
index 656741f9b36b0cc800842c8f5c3db52f7e008ea0..2ad2024058c5f0c891e76fa7358d1b4f64f9bebe 100644 (file)
--- a/src/jtag/jtag.h
+++ b/src/jtag/jtag.h
@@ -23,12 +23,9 @@
 #ifndef JTAG_H
 #define JTAG_H
 
-#include "types.h"
 #include "binarybuffer.h"
 #include "log.h"
 
-#include "command.h"
-
 
 #ifdef _DEBUG_JTAG_IO_
 #define DEBUG_JTAG_IO(expr ...)                LOG_DEBUG(expr)
@@ -272,11 +269,6 @@ typedef struct scan_field_s
        int         num_bits;           /* number of bits this field specifies (up to 32) */
        u8*         out_value;          /* value to be scanned into the device */
        u8*         in_value;           /* pointer to a 32-bit memory location to take data scanned out */
-       /* in_check_value/mask, in_handler_error_handler, in_handler_priv can be used by the in handler, otherwise they contain garbage  */
-       u8*          in_check_value;    /* deprecated! only used from jtag_set_check_value. used to validate scan results */
-       u8*          in_check_mask;     /* deprecated! only used from jtag_set_check_value.  check specified bits against check_value */
-       in_handler_t in_handler;        /* deprecated! SET TO NULL. DO NOT USE! process received buffer using this handler */
-       void*        in_handler_priv;   /* deprecated! only used by obsolete in_handler implementations */
 } scan_field_t;
 
 enum scan_type {
@@ -573,6 +565,70 @@ extern int  interface_jtag_add_plain_ir_scan(int num_fields, scan_field_t* field
 extern void jtag_add_plain_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
 extern int  interface_jtag_add_plain_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
 
+
+/* Simplest/typical callback - do some conversion on the data clocked in.
+ * This callback is for such conversion that can not fail.
+ * For conversion types or checks that can
+ * fail, use the jtag_callback_t variant */
+typedef void (*jtag_callback1_t)(u8 *in);
+
+#ifndef HAVE_JTAG_MINIDRIVER_H
+/* A simpler version of jtag_add_callback3 */
+extern void jtag_add_callback(jtag_callback1_t, u8 *in);
+#else
+/* implemented by minidriver */
+#endif
+
+/* This type can store an integer safely by a normal cast on 64 and
+ * 32 bit systems. */
+typedef void *jtag_callback_data_t;
+
+/* The generic callback mechanism.
+ *
+ * The callback is invoked with three arguments. The first argument is
+ * the pointer to the data clocked in.
+ */
+typedef int (*jtag_callback_t)(u8 *in, jtag_callback_data_t data1, jtag_callback_data_t data2);
+
+
+/* This callback can be executed immediately the queue has been flushed. Note that
+ * the JTAG queue can either be executed synchronously or asynchronously. Typically
+ * for USB the queue is executed asynchronously. For low latency interfaces, the
+ * queue may be executed synchronously.
+ *
+ * These callbacks are typically executed *after* the *entire* JTAG queue has been
+ * executed for e.g. USB interfaces.
+ *
+ * The callbacks are guaranteeed to be invoked in the order that they were queued.
+ *
+ * The strange name is due to C's lack of overloading using function arguments
+ *
+ * The callback mechansim is very general and does not really make any assumptions
+ * about what the callback does and what the arguments are.
+ *
+ * in - typically used to point to the data to operate on. More often than not
+ * this will be the data clocked in during a shift operation
+ *
+ * data1 - an integer that is big enough to be used either as an 'int' or
+ * cast to/from a pointer
+ *
+ * data2 - an integer that is big enough to be used either as an 'int' or
+ * cast to/from a pointer
+ *
+ * Why stop at 'data2' for arguments? Somewhat historical reasons. This is
+ * sufficient to implement the jtag_check_value_mask(), besides the
+ * line is best drawn somewhere...
+ *
+ * If the execution of the queue fails before the callbacks, then the
+ * callbacks may or may not be invoked depending on driver implementation.
+ */
+#ifndef HAVE_JTAG_MINIDRIVER_H
+extern void jtag_add_callback3(jtag_callback_t, u8 *in, jtag_callback_data_t data1, jtag_callback_data_t data2);
+#else
+/* implemented by minidriver */
+#endif
+
+
 /* run a TAP_RESET reset. End state is TAP_RESET, regardless
  * of start state.
  */
@@ -736,7 +792,6 @@ struct invalidstruct
 
 };
 
-extern void           jtag_set_check_value(scan_field_t* field, u8* value, u8* mask, struct invalidstruct *obsolete);
 /* execute jtag queue and check value and use mask if mask is != NULL. invokes
  * jtag_set_error() with any error. */
 extern void jtag_check_value_mask(scan_field_t *field, u8 *value, u8 *mask);