src/jtag/adapter.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2 /*
   3  * Copyright (C) 2005 by Dominic Rath <Dominic.Rath@gmx.de>
   4  * Copyright (c) 2018 Pengutronix, Oleksij Rempel <kernel@pengutronix.de>
   5  */
   6
   7 #ifndef OPENOCD_JTAG_ADAPTER_H
   8 #define OPENOCD_JTAG_ADAPTER_H
   9
  10 #include <stdbool.h>
  11 #include <stddef.h>
  12 #include <stdint.h>
  13
  14 /** Supported output drive modes for adaptor GPIO */
  15 enum adapter_gpio_drive_mode {
  16         ADAPTER_GPIO_DRIVE_MODE_PUSH_PULL,
  17         ADAPTER_GPIO_DRIVE_MODE_OPEN_DRAIN,
  18         ADAPTER_GPIO_DRIVE_MODE_OPEN_SOURCE,
  19 };
  20
  21 /** Supported GPIO directions */
  22 enum adapter_gpio_direction {
  23         ADAPTER_GPIO_DIRECTION_INPUT,
  24         ADAPTER_GPIO_DIRECTION_OUTPUT,
  25         ADAPTER_GPIO_DIRECTION_BIDIRECTIONAL,
  26 };
  27
  28 /** Supported initial states for GPIO */
  29 enum adapter_gpio_init_state {
  30         ADAPTER_GPIO_INIT_STATE_INACTIVE, /* Should be zero so it is the default state */
  31         ADAPTER_GPIO_INIT_STATE_ACTIVE,
  32         ADAPTER_GPIO_INIT_STATE_INPUT,
  33 };
  34
  35 /** Supported pull directions for GPIO */
  36 enum adapter_gpio_pull {
  37         ADAPTER_GPIO_PULL_NONE,
  38         ADAPTER_GPIO_PULL_UP,
  39         ADAPTER_GPIO_PULL_DOWN,
  40 };
  41
  42 /** Adapter GPIO */
  43 enum adapter_gpio_config_index {
  44         ADAPTER_GPIO_IDX_TDO,
  45         ADAPTER_GPIO_IDX_TDI,
  46         ADAPTER_GPIO_IDX_TMS,
  47         ADAPTER_GPIO_IDX_TCK,
  48         ADAPTER_GPIO_IDX_TRST,
  49         ADAPTER_GPIO_IDX_SWDIO,
  50         ADAPTER_GPIO_IDX_SWDIO_DIR,
  51         ADAPTER_GPIO_IDX_SWCLK,
  52         ADAPTER_GPIO_IDX_SRST,
  53         ADAPTER_GPIO_IDX_LED,
  54         ADAPTER_GPIO_IDX_NUM, /* must be the last item */
  55 };
  56
  57 /** Configuration options for a single GPIO */
  58 struct adapter_gpio_config {
  59         int gpio_num;
  60         int chip_num;
  61         enum adapter_gpio_drive_mode drive; /* For outputs only */
  62         enum adapter_gpio_init_state init_state;
  63         bool active_low;
  64         enum adapter_gpio_pull pull;
  65 };
  66
  67 struct command_context;
  68
  69 /** Register the adapter's commands */
  70 int adapter_register_commands(struct command_context *ctx);
  71
  72 /** Initialize debug adapter upon startup.  */
  73 int adapter_init(struct command_context *cmd_ctx);
  74
  75 /** Shutdown the debug adapter upon program exit. */
  76 int adapter_quit(void);
  77
  78 /** @returns true if adapter has been initialized */
  79 bool is_adapter_initialized(void);
  80
  81 /** @returns USB location string set with command 'adapter usb location' */
  82 const char *adapter_usb_get_location(void);
  83
  84 /** @returns true if USB location string is "<dev_bus>-<port_path[0]>[.<port_path[1]>[...]]" */
  85 bool adapter_usb_location_equal(uint8_t dev_bus, uint8_t *port_path, size_t path_len);
  86
  87 /** @returns The current adapter speed setting. */
  88 int adapter_get_speed(int *speed);
  89
  90 /**
  91  * Given a @a speed setting, use the interface @c speed_div callback to
  92  * adjust the setting.
  93  * @param speed The speed setting to convert back to readable kHz.
  94  * @returns ERROR_OK if the interface has not been initialized or on success;
  95  *  otherwise, the error code produced by the @c speed_div callback.
  96  */
  97 int adapter_get_speed_readable(int *speed);
  98
  99 /** Attempt to configure the adapter for the specified kHz. */
 100 int adapter_config_khz(unsigned int khz);
 101
 102 /**
 103  * Attempt to enable RTCK/RCLK. If that fails, fallback to the
 104  * specified frequency.
 105  */
 106 int adapter_config_rclk(unsigned int fallback_speed_khz);
 107
 108 /** Retrieves the clock speed of the adapter in kHz. */
 109 unsigned int adapter_get_speed_khz(void);
 110
 111 /** Retrieves the serial number set with command 'adapter serial' */
 112 const char *adapter_get_required_serial(void);
 113
 114 /**
 115  * Retrieves gpio name
 116  */
 117 const char *adapter_gpio_get_name(enum adapter_gpio_config_index idx);
 118
 119 /**
 120  * Retrieves gpio configuration set with command "adapter gpio <signal_name>"
 121  */
 122 const struct adapter_gpio_config *adapter_gpio_get_config(void);
 123
 124 #endif /* OPENOCD_JTAG_ADAPTER_H */