summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--src/jtag/interface.h70
1 files changed, 55 insertions, 15 deletions
diff --git a/src/jtag/interface.h b/src/jtag/interface.h
index 79e3a3e9..83ff6fa4 100644
--- a/src/jtag/interface.h
+++ b/src/jtag/interface.h
@@ -189,49 +189,89 @@ static inline tap_state_t jtag_debug_state_machine(const void *tms_buf,
typedef struct jtag_interface_s
{
+ /// The name of the JTAG interface driver.
char* name;
- /* queued command execution
+ /**
+ * Execute queued commands.
+ * @returns ERROR_OK on success, or an error code on failure.
*/
int (*execute_queue)(void);
- /* interface initalization
+ /**
+ * Set the interface speed.
+ * @param speed The new interface speed setting.
+ * @returns ERROR_OK on success, or an error code on failure.
*/
int (*speed)(int speed);
+
+ /**
+ * The interface driver may register additional commands to expose
+ * additional features not covered by the standard command set.
+ * @param cmd_ctx The context in which commands should be registered.
+ * @returns ERROR_OK on success, or an error code on failure.
+ */
int (*register_commands)(struct command_context_s* cmd_ctx);
+
+ /**
+ * Interface driver must initalize any resources and connect to a
+ * JTAG device.
+ * @returns ERROR_OK on success, or an error code on failure.
+ */
int (*init)(void);
+
+ /**
+ * Interface driver must tear down all resources and disconnect from
+ * the JTAG device.
+ * @returns ERROR_OK on success, or an error code on failure.
+ */
int (*quit)(void);
- /* returns JTAG maxium speed for KHz. 0=RTCK. The function returns
+ /**
+ * Returns JTAG maxium speed for KHz. 0=RTCK. The function returns
* a failure if it can't support the KHz/RTCK.
*
* WARNING!!!! if RTCK is *slow* then think carefully about
* whether you actually want to support this in the driver.
* Many target scripts are written to handle the absence of RTCK
* and use a fallback kHz TCK.
+ * @returns ERROR_OK on success, or an error code on failure.
*/
int (*khz)(int khz, int* jtag_speed);
- /* returns the KHz for the provided JTAG speed. 0=RTCK. The function returns
- * a failure if it can't support the KHz/RTCK. */
+ /**
+ * Calculate the clock frequency (in KHz) for the given @a speed.
+ * @param speed The desired interface speed setting.
+ * @param khz On return, contains the speed in KHz (0 for RTCK).
+ * @returns ERROR_OK on success, or an error code if the
+ * interface cannot support the specified speed (KHz or RTCK).
+ */
int (*speed_div)(int speed, int* khz);
- /* Read and clear the power dropout flag. Note that a power dropout
- * can be transitionary, easily much less than a ms.
+ /**
+ * Read and clear the power dropout flag. Note that a power dropout
+ * can be transitionary, easily much less than a ms.
*
- * So to find out if the power is *currently* on, you must invoke
- * this method twice. Once to clear the power dropout flag and a
- * second time to read the current state.
+ * To find out if the power is *currently* on, one must invoke this
+ * method twice. Once to clear the power dropout flag and a second
+ * time to read the current state. The default implementation
+ * never reports power dropouts.
*
- * Currently the default implementation is never to detect power dropout.
+ * @returns ERROR_OK on success, or an error code on failure.
*/
int (*power_dropout)(int* power_dropout);
- /* Read and clear the srst asserted detection flag.
+ /**
+ * Read and clear the srst asserted detection flag.
+ *
+ * Like power_dropout this does *not* read the current
+ * state. SRST assertion is transitionary and may be much
+ * less than 1ms, so the interface driver must watch for these
+ * events until this routine is called.
*
- * NB!!!! like power_dropout this does *not* read the current
- * state. srst assertion is transitionary and *can* be much
- * less than 1ms.
+ * @param srst_asserted On return, indicates whether SRST has
+ * been asserted.
+ * @returns ERROR_OK on success, or an error code on failure.
*/
int (*srst_asserted)(int* srst_asserted);
} jtag_interface_t;