+/* SPDX-License-Identifier: GPL-2.0-or-later */
+
/***************************************************************************
* Copyright (C) 2005 by Dominic Rath *
* Dominic.Rath@gmx.de *
* *
* Copyright (C) 2009 Zachary T Welch *
* zw@superlucidity.net *
- * *
- * This program is free software; you can redistribute it and/or modify *
- * it under the terms of the GNU General Public License as published by *
- * the Free Software Foundation; either version 2 of the License, or *
- * (at your option) any later version. *
- * *
- * This program is distributed in the hope that it will be useful, *
- * but WITHOUT ANY WARRANTY; without even the implied warranty of *
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
- * GNU General Public License for more details. *
- * *
- * You should have received a copy of the GNU General Public License *
- * along with this program; if not, write to the *
- * Free Software Foundation, Inc., *
- * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
***************************************************************************/
+
#ifndef OPENOCD_JTAG_INTERFACE_H
#define OPENOCD_JTAG_INTERFACE_H
-#include "jtag.h"
+#include <jtag/jtag.h>
+#include <jtag/swim.h>
+#include <target/arm_tpiu_swo.h>
/* @file
* The "Cable Helper API" is what the cable drivers can use to help
* expected to traverse, not just end points of a multi-step state path.
*
* @param new_state The state we think the TAPs are currently in (or
- * are about to enter).
+ * are about to enter).
*/
-#if defined(_DEBUG_JTAG_IO_)
#define tap_set_state(new_state) \
do { \
- LOG_DEBUG("tap_set_state(%s)", tap_state_name(new_state) ); \
+ LOG_DEBUG_IO("tap_set_state(%s)", tap_state_name(new_state)); \
tap_set_state_impl(new_state); \
} while (0)
-#else
-static inline void tap_set_state(tap_state_t new_state)
-{
- tap_set_state_impl(new_state);
-}
-#endif
/**
* This function gets the state of the "state follower" which tracks the
* state follower via tap_set_state().
*
* @param new_end_state The state the TAPs should enter at completion of
- * a pending TAP operation.
+ * a pending TAP operation.
*/
void tap_set_end_state(tap_state_t new_end_state);
* @param from The starting state.
* @param to The desired final state.
* @return int The required TMS bit sequence, with the first bit in the
- * sequence at bit 0.
+ * sequence at bit 0.
*/
int tap_get_tms_path(tap_state_t from, tap_state_t to);
-
/**
* Function int tap_get_tms_path_len
* returns the total number of bits that represents a TMS path
*/
tap_state_t tap_state_transition(tap_state_t current_state, bool tms);
-/// Provides user-friendly name lookup of TAP states.
-tap_state_t tap_state_by_name(const char *name);
-
-/// Allow switching between old and new TMS tables. @see tap_get_tms_path
+/** Allow switching between old and new TMS tables. @see tap_get_tms_path */
void tap_use_new_tms_table(bool use_new);
-/// @returns True if new TMS table is active; false otherwise.
+/** @returns True if new TMS table is active; false otherwise. */
bool tap_uses_new_tms_table(void);
-#ifdef _DEBUG_JTAG_IO_
+tap_state_t jtag_debug_state_machine_(const void *tms_buf, const void *tdi_buf,
+ unsigned int tap_len, tap_state_t start_tap_state);
+
/**
* @brief Prints verbose TAP state transitions for the given TMS/TDI buffers.
* @param tms_buf must points to a buffer containing the TMS bitstream.
* @param start_tap_state must specify the current TAP state.
* @returns the final TAP state; pass as @a start_tap_state in following call.
*/
-tap_state_t jtag_debug_state_machine(const void *tms_buf, const void *tdi_buf,
- unsigned tap_len, tap_state_t start_tap_state);
-#else
static inline tap_state_t jtag_debug_state_machine(const void *tms_buf,
const void *tdi_buf, unsigned tap_len, tap_state_t start_tap_state)
{
- return start_tap_state;
+ if (LOG_LEVEL_IS(LOG_LVL_DEBUG_IO))
+ return jtag_debug_state_machine_(tms_buf, tdi_buf, tap_len, start_tap_state);
+ else
+ return start_tap_state;
}
-#endif // _DEBUG_JTAG_IO_
-
-typedef struct jtag_interface_s
-{
- /// The name of the JTAG interface driver.
- char* name;
+/**
+ * Represents a driver for a debugging interface.
+ *
+ * @todo Rename; perhaps "debug_driver". This isn't an interface,
+ * it's a driver! Also, not all drivers support JTAG.
+ *
+ * @todo We need a per-instance structure too, and changes to pass
+ * that structure to the driver. Instances can for example be in
+ * either SWD or JTAG modes. This will help remove globals, and
+ * eventually to cope with systems which have more than one such
+ * debugging interface.
+ */
+struct jtag_interface {
/**
- * Execute queued commands.
- * @returns ERROR_OK on success, or an error code on failure.
+ * Bit vector listing capabilities exposed by this driver.
*/
- int (*execute_queue)(void);
+ unsigned supported;
+#define DEBUG_CAP_TMS_SEQ (1 << 0)
/**
- * Set the interface speed.
- * @param speed The new interface speed setting.
+ * Execute commands in the supplied queue
+ * @param cmd_queue - a linked list of commands to execute
* @returns ERROR_OK on success, or an error code on failure.
*/
- int (*speed)(int speed);
+
+ int (*execute_queue)(struct jtag_command *cmd_queue);
+};
+
+/**
+ * Represents a driver for a debugging interface
+ *
+ * @todo We need a per-instance structure too, and changes to pass
+ * that structure to the driver. Instances can for example be in
+ * either SWD or JTAG modes. This will help remove globals, and
+ * eventually to cope with systems which have more than one such
+ * debugging interface.
+ */
+struct adapter_driver {
+ /** The name of the interface driver. */
+ const char * const name;
+
+ /** transports supported in C code (NULL terminated vector) */
+ const char * const *transports;
/**
* 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);
+ const struct command_registration *commands;
/**
- * Interface driver must initalize any resources and connect to a
+ * Interface driver must initialize any resources and connect to a
* JTAG device.
+ *
+ * quit() is invoked if and only if init() succeeds. quit() is always
+ * invoked if init() succeeds. Same as malloc() + free(). Always
+ * invoke free() if malloc() succeeds and do not invoke free()
+ * otherwise.
+ *
* @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
+ * Control (assert/deassert) the signals SRST and TRST on the interface.
+ * This function is synchronous and should be called after the adapter
+ * queue has been properly flushed.
+ * This function is optional.
+ * Adapters that don't support resets can either not define this function
+ * or return an error code.
+ * Adapters that don't support one of the two reset should ignore the
+ * request to assert the missing signal and eventually log an error.
+ *
+ * @param srst 1 to assert SRST, 0 to deassert SRST.
+ * @param trst 1 to assert TRST, 0 to deassert TRST.
+ * @returns ERROR_OK on success, or an error code on failure.
+ */
+ int (*reset)(int srst, int trst);
+
+ /**
+ * 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);
+
+ /**
+ * Returns JTAG maximum 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
* and use a fallback kHz TCK.
* @returns ERROR_OK on success, or an error code on failure.
*/
- int (*khz)(int khz, int* jtag_speed);
+ int (*khz)(int khz, int *jtag_speed);
/**
* Calculate the clock frequency (in KHz) for the given @a speed.
* @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);
+ int (*speed_div)(int speed, int *khz);
/**
* Read and clear the power dropout flag. Note that a power dropout
*
* @returns ERROR_OK on success, or an error code on failure.
*/
- int (*power_dropout)(int* power_dropout);
+ int (*power_dropout)(int *power_dropout);
/**
* Read and clear the srst asserted detection flag.
* been asserted.
* @returns ERROR_OK on success, or an error code on failure.
*/
- int (*srst_asserted)(int* srst_asserted);
-} jtag_interface_t;
+ int (*srst_asserted)(int *srst_asserted);
+
+ /**
+ * Configure trace parameters for the adapter
+ *
+ * @param enabled Whether to enable trace
+ * @param pin_protocol Configured pin protocol
+ * @param port_size Trace port width for sync mode
+ * @param trace_freq A pointer to the configured trace
+ * frequency; if it points to 0, the adapter driver must write
+ * its maximum supported rate there
+ * @param traceclkin_freq TRACECLKIN frequency provided to the TPIU in Hz
+ * @param prescaler Pointer to the SWO prescaler calculated by the
+ * adapter
+ * @returns ERROR_OK on success, an error code on failure.
+ */
+ int (*config_trace)(bool enabled, enum tpiu_pin_protocol pin_protocol,
+ uint32_t port_size, unsigned int *trace_freq,
+ unsigned int traceclkin_freq, uint16_t *prescaler);
+
+ /**
+ * Poll for new trace data
+ *
+ * @param buf A pointer to buffer to store received data
+ * @param size A pointer to buffer size; must be filled with
+ * the actual amount of bytes written
+ *
+ * @returns ERROR_OK on success, an error code on failure.
+ */
+ int (*poll_trace)(uint8_t *buf, size_t *size);
+
+ /** Low-level JTAG APIs */
+ struct jtag_interface *jtag_ops;
+
+ /** Low-level SWD APIs */
+ const struct swd_driver *swd_ops;
+
+ /* DAP APIs over JTAG transport */
+ const struct dap_ops *dap_jtag_ops;
+
+ /* DAP APIs over SWD transport */
+ const struct dap_ops *dap_swd_ops;
+
+ /* SWIM APIs */
+ const struct swim_driver *swim_ops;
+};
+
+extern const char * const jtag_only[];
+
+int adapter_resets(int assert_trst, int assert_srst);
+int adapter_assert_reset(void);
+int adapter_deassert_reset(void);
+int adapter_config_trace(bool enabled, enum tpiu_pin_protocol pin_protocol,
+ uint32_t port_size, unsigned int *trace_freq,
+ unsigned int traceclkin_freq, uint16_t *prescaler);
+int adapter_poll_trace(uint8_t *buf, size_t *size);
+extern struct adapter_driver am335xgpio_adapter_driver;
+extern struct adapter_driver amt_jtagaccel_adapter_driver;
+extern struct adapter_driver angie_adapter_driver;
+extern struct adapter_driver armjtagew_adapter_driver;
+extern struct adapter_driver at91rm9200_adapter_driver;
+extern struct adapter_driver bcm2835gpio_adapter_driver;
+extern struct adapter_driver buspirate_adapter_driver;
+extern struct adapter_driver cmsis_dap_adapter_driver;
+extern struct adapter_driver dmem_dap_adapter_driver;
+extern struct adapter_driver dummy_adapter_driver;
+extern struct adapter_driver ep93xx_adapter_driver;
+extern struct adapter_driver esp_usb_adapter_driver;
+extern struct adapter_driver ft232r_adapter_driver;
+extern struct adapter_driver ftdi_adapter_driver;
+extern struct adapter_driver gw16012_adapter_driver;
+extern struct adapter_driver hl_adapter_driver;
+extern struct adapter_driver imx_gpio_adapter_driver;
+extern struct adapter_driver jlink_adapter_driver;
+extern struct adapter_driver jtag_dpi_adapter_driver;
+extern struct adapter_driver jtag_vpi_adapter_driver;
+extern struct adapter_driver kitprog_adapter_driver;
+extern struct adapter_driver linuxgpiod_adapter_driver;
+extern struct adapter_driver opendous_adapter_driver;
+extern struct adapter_driver openjtag_adapter_driver;
+extern struct adapter_driver osbdm_adapter_driver;
+extern struct adapter_driver parport_adapter_driver;
+extern struct adapter_driver presto_adapter_driver;
+extern struct adapter_driver remote_bitbang_adapter_driver;
+extern struct adapter_driver rlink_adapter_driver;
+extern struct adapter_driver rshim_dap_adapter_driver;
+extern struct adapter_driver stlink_dap_adapter_driver;
+extern struct adapter_driver sysfsgpio_adapter_driver;
+extern struct adapter_driver ulink_adapter_driver;
+extern struct adapter_driver usb_blaster_adapter_driver;
+extern struct adapter_driver usbprog_adapter_driver;
+extern struct adapter_driver vdebug_adapter_driver;
+extern struct adapter_driver vsllink_adapter_driver;
+extern struct adapter_driver xds110_adapter_driver;
+extern struct adapter_driver xlnx_pcie_xvc_adapter_driver;
-#endif // OPENOCD_JTAG_INTERFACE_H
+#endif /* OPENOCD_JTAG_INTERFACE_H */
Code Review / openocd.git / blobdiff