OpenOCD
interface.h
Go to the documentation of this file.
1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 
3 /***************************************************************************
4  * Copyright (C) 2005 by Dominic Rath *
5  * Dominic.Rath@gmx.de *
6  * *
7  * Copyright (C) 2007,2008 Øyvind Harboe *
8  * oyvind.harboe@zylin.com *
9  * *
10  * Copyright (C) 2009 Zachary T Welch *
11  * zw@superlucidity.net *
12  ***************************************************************************/
13 
14 #ifndef OPENOCD_JTAG_INTERFACE_H
15 #define OPENOCD_JTAG_INTERFACE_H
16 
17 #include <jtag/jtag.h>
18 #include <jtag/swim.h>
19 #include <target/arm_tpiu_swo.h>
20 
21 /* @file
22  * The "Cable Helper API" is what the cable drivers can use to help
23  * implement their "Cable API". So a Cable Helper API is a set of
24  * helper functions used by cable drivers, and this is different from a
25  * Cable API. A "Cable API" is what higher level code used to talk to a
26  * cable.
27  */
28 
29 
31 void tap_set_state_impl(tap_state_t new_state);
32 
49 #define tap_set_state(new_state) \
50  do { \
51  LOG_DEBUG_IO("tap_set_state(%s)", tap_state_name(new_state)); \
52  tap_set_state_impl(new_state); \
53  } while (0)
54 
61 
73 void tap_set_end_state(tap_state_t new_end_state);
74 
80 
95 
113 
114 
128 int tap_move_ndx(tap_state_t astate);
129 
134 bool tap_is_state_stable(tap_state_t astate);
135 
143 tap_state_t tap_state_transition(tap_state_t current_state, bool tms);
144 
146 void tap_use_new_tms_table(bool use_new);
148 bool tap_uses_new_tms_table(void);
149 
150 tap_state_t jtag_debug_state_machine_(const void *tms_buf, const void *tdi_buf,
151  unsigned int tap_len, tap_state_t start_tap_state);
152 
161 static inline tap_state_t jtag_debug_state_machine(const void *tms_buf,
162  const void *tdi_buf, unsigned tap_len, tap_state_t start_tap_state)
163 {
165  return jtag_debug_state_machine_(tms_buf, tdi_buf, tap_len, start_tap_state);
166  else
167  return start_tap_state;
168 }
169 
186  unsigned supported;
187 #define DEBUG_CAP_TMS_SEQ (1 << 0)
188 
195  int (*execute_queue)(struct jtag_command *cmd_queue);
196 };
197 
209  const char * const name;
210 
212  const char * const *transports;
213 
219 
231  int (*init)(void);
232 
239  int (*quit)(void);
240 
255  int (*reset)(int srst, int trst);
256 
262  int (*speed)(int speed);
263 
274  int (*khz)(int khz, int *jtag_speed);
275 
283  int (*speed_div)(int speed, int *khz);
284 
297 
311 
326  int (*config_trace)(bool enabled, enum tpiu_pin_protocol pin_protocol,
327  uint32_t port_size, unsigned int *trace_freq,
328  unsigned int traceclkin_freq, uint16_t *prescaler);
329 
339  int (*poll_trace)(uint8_t *buf, size_t *size);
340 
343 
345  const struct swd_driver *swd_ops;
346 
347  /* DAP APIs over JTAG transport */
348  const struct dap_ops *dap_jtag_ops;
349 
350  /* DAP APIs over SWD transport */
351  const struct dap_ops *dap_swd_ops;
352 
353  /* SWIM APIs */
354  const struct swim_driver *swim_ops;
355 };
356 
357 extern const char * const jtag_only[];
358 
359 int adapter_resets(int assert_trst, int assert_srst);
360 int adapter_assert_reset(void);
361 int adapter_deassert_reset(void);
362 int adapter_config_trace(bool enabled, enum tpiu_pin_protocol pin_protocol,
363  uint32_t port_size, unsigned int *trace_freq,
364  unsigned int traceclkin_freq, uint16_t *prescaler);
365 int adapter_poll_trace(uint8_t *buf, size_t *size);
366 
380 extern struct adapter_driver ftdi_adapter_driver;
382 extern struct adapter_driver hl_adapter_driver;
406 
407 #endif /* OPENOCD_JTAG_INTERFACE_H */
tpiu_pin_protocol
Definition: arm_tpiu_swo.h:7
struct adapter_driver imx_gpio_adapter_driver
Definition: imx_gpio.c:427
tap_state_t tap_state_transition(tap_state_t current_state, bool tms)
Function tap_state_transition takes a current TAP state and returns the next state according to the t...
Definition: interface.c:223
struct adapter_driver linuxgpiod_adapter_driver
Definition: linuxgpiod.c:435
static tap_state_t jtag_debug_state_machine(const void *tms_buf, const void *tdi_buf, unsigned tap_len, tap_state_t start_tap_state)
Prints verbose TAP state transitions for the given TMS/TDI buffers.
Definition: interface.h:161
struct adapter_driver dummy_adapter_driver
Definition: dummy.c:141
struct adapter_driver stlink_dap_adapter_driver
Definition: stlink_usb.c:5223
struct adapter_driver amt_jtagaccel_adapter_driver
struct adapter_driver usb_blaster_adapter_driver
Definition: usb_blaster.c:1060
bool tap_is_state_stable(tap_state_t astate)
Function tap_is_state_stable returns true if the astate is stable.
Definition: interface.c:200
struct adapter_driver ft232r_adapter_driver
Definition: ft232r.c:903
const char *const jtag_only[]
Definition: adapter.c:27
struct adapter_driver jtag_vpi_adapter_driver
Definition: jtag_vpi.c:669
int adapter_resets(int assert_trst, int assert_srst)
Definition: jtag/core.c:1833
void tap_set_end_state(tap_state_t new_end_state)
This function sets the state of an "end state follower" which tracks the state that any cable driver ...
Definition: interface.c:48
struct adapter_driver buspirate_adapter_driver
Definition: buspirate.c:543
struct adapter_driver cmsis_dap_adapter_driver
Definition: cmsis_dap.c:2314
struct adapter_driver angie_adapter_driver
Definition: angie.c:2388
struct adapter_driver dmem_dap_adapter_driver
Definition: dmem.c:609
struct adapter_driver osbdm_adapter_driver
Definition: osbdm.c:685
void tap_use_new_tms_table(bool use_new)
Allow switching between old and new TMS tables.
Definition: interface.c:447
struct adapter_driver vdebug_adapter_driver
Definition: vdebug.c:1347
struct adapter_driver ep93xx_adapter_driver
Definition: ep93xx.c:47
tap_state_t tap_get_end_state(void)
For more information,.
Definition: interface.c:56
bool tap_uses_new_tms_table(void)
Definition: interface.c:451
int tap_get_tms_path(tap_state_t from, tap_state_t to)
This function provides a "bit sequence" indicating what has to be done with TMS during a sequence of ...
Definition: interface.c:190
struct adapter_driver opendous_adapter_driver
Definition: opendous.c:230
struct adapter_driver xlnx_pcie_xvc_adapter_driver
struct adapter_driver ftdi_adapter_driver
Definition: ftdi.c:1258
int tap_get_tms_path_len(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 transit...
Definition: interface.c:195
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)
Definition: jtag/core.c:1917
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)
Definition: interface.c:374
int adapter_poll_trace(uint8_t *buf, size_t *size)
Definition: jtag/core.c:1932
int tap_move_ndx(tap_state_t astate)
Function tap_move_ndx when given a stable state, returns an index from 0-5.
Definition: interface.c:61
struct adapter_driver xds110_adapter_driver
Definition: xds110.c:2069
struct adapter_driver bcm2835gpio_adapter_driver
Definition: bcm2835gpio.c:576
struct adapter_driver armjtagew_adapter_driver
Definition: arm-jtag-ew.c:491
struct adapter_driver openjtag_adapter_driver
Definition: openjtag.c:930
struct adapter_driver vsllink_adapter_driver
Definition: vsllink.c:931
struct adapter_driver kitprog_adapter_driver
Definition: kitprog.c:913
void tap_set_state_impl(tap_state_t new_state)
implementation of wrapper function tap_set_state()
Definition: interface.c:31
struct adapter_driver at91rm9200_adapter_driver
Definition: at91rm9200.c:187
struct adapter_driver sysfsgpio_adapter_driver
Definition: sysfsgpio.c:555
struct adapter_driver am335xgpio_adapter_driver
Definition: am335xgpio.c:495
struct adapter_driver presto_adapter_driver
Definition: presto.c:529
struct adapter_driver rshim_dap_adapter_driver
Definition: rshim.c:513
int adapter_deassert_reset(void)
Definition: jtag/core.c:1900
struct adapter_driver rlink_adapter_driver
Definition: rlink.c:1678
struct adapter_driver hl_adapter_driver
struct adapter_driver jlink_adapter_driver
Definition: jlink.c:2269
tap_state_t tap_get_state(void)
This function gets the state of the "state follower" which tracks the state of the TAPs connected to ...
Definition: interface.c:37
struct adapter_driver gw16012_adapter_driver
Definition: gw16012.c:516
struct adapter_driver ulink_adapter_driver
Definition: ulink.c:2271
struct adapter_driver esp_usb_adapter_driver
Definition: esp_usb_jtag.c:785
int adapter_assert_reset(void)
Definition: jtag/core.c:1880
struct adapter_driver usbprog_adapter_driver
Definition: usbprog.c:593
struct adapter_driver parport_adapter_driver
Definition: parport.c:524
struct adapter_driver jtag_dpi_adapter_driver
Definition: jtag_dpi.c:399
struct adapter_driver remote_bitbang_adapter_driver
The JTAG interface can be implemented with a software or hardware fifo.
enum tap_state tap_state_t
Defines JTAG Test Access Port states.
#define LOG_LEVEL_IS(FOO)
Definition: log.h:99
@ LOG_LVL_DEBUG_IO
Definition: log.h:48
size_t size
Size of the control block search area.
Definition: rtt/rtt.c:30
Represents a driver for a debugging interface.
Definition: interface.h:207
struct jtag_interface * jtag_ops
Low-level JTAG APIs.
Definition: interface.h:342
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)
Configure trace parameters for the adapter.
Definition: interface.h:326
int(* speed)(int speed)
Set the interface speed.
Definition: interface.h:262
const struct swim_driver * swim_ops
Definition: interface.h:354
int(* khz)(int khz, int *jtag_speed)
Returns JTAG maximum speed for KHz.
Definition: interface.h:274
const struct command_registration * commands
The interface driver may register additional commands to expose additional features not covered by th...
Definition: interface.h:218
int(* speed_div)(int speed, int *khz)
Calculate the clock frequency (in KHz) for the given speed.
Definition: interface.h:283
int(* init)(void)
Interface driver must initialize any resources and connect to a JTAG device.
Definition: interface.h:231
const struct swd_driver * swd_ops
Low-level SWD APIs.
Definition: interface.h:345
int(* reset)(int srst, int trst)
Control (assert/deassert) the signals SRST and TRST on the interface.
Definition: interface.h:255
const struct dap_ops * dap_swd_ops
Definition: interface.h:351
int(* power_dropout)(int *power_dropout)
Read and clear the power dropout flag.
Definition: interface.h:296
const char *const * transports
transports supported in C code (NULL terminated vector)
Definition: interface.h:212
const struct dap_ops * dap_jtag_ops
Definition: interface.h:348
int(* poll_trace)(uint8_t *buf, size_t *size)
Poll for new trace data.
Definition: interface.h:339
int(* srst_asserted)(int *srst_asserted)
Read and clear the srst asserted detection flag.
Definition: interface.h:310
const char *const name
The name of the interface driver.
Definition: interface.h:209
int(* quit)(void)
Interface driver must tear down all resources and disconnect from the JTAG device.
Definition: interface.h:239
Transport-neutral representation of queued DAP transactions, supporting both JTAG and SWD transports.
Definition: arm_adi_v5.h:446
Represents a driver for a debugging interface.
Definition: interface.h:182
unsigned supported
Bit vector listing capabilities exposed by this driver.
Definition: interface.h:186
int(* execute_queue)(struct jtag_command *cmd_queue)
Execute commands in the supplied queue.
Definition: interface.h:195
This file implements support for STMicroelectronics debug protocol SWIM (Single Wire Interface Module...