libjaylink/libjaylink.h

   1 /*
   2  * This file is part of the libjaylink project.
   3  *
   4  * Copyright (C) 2014-2015 Marc Schink <jaylink-dev@marcschink.de>
   5  *
   6  * This program is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #ifndef LIBJAYLINK_LIBJAYLINK_H
  21 #define LIBJAYLINK_LIBJAYLINK_H
  22
  23 #include <stdlib.h>
  24 #include <stdint.h>
  25 #include <sys/types.h>
  26
  27 /**
  28  * @file
  29  *
  30  * Public libjaylink header file to be used by applications.
  31  */
  32
  33 /** Error codes returned by libjaylink functions. */
  34 enum jaylink_error {
  35         /** No error. */
  36         JAYLINK_OK = 0,
  37         /** Unspecific error. */
  38         JAYLINK_ERR = -1,
  39         /** Memory allocation error. */
  40         JAYLINK_ERR_MALLOC = -2,
  41         /** Invalid argument. */
  42         JAYLINK_ERR_ARG = -3,
  43         /** Timeout occurred. */
  44         JAYLINK_ERR_TIMEOUT = -4
  45 };
  46
  47 /** libjaylink log levels. */
  48 enum jaylink_log_level {
  49         /** Output no messages. */
  50         JAYLINK_LOG_LEVEL_NONE = 0,
  51         /** Output error messages. */
  52         JAYLINK_LOG_LEVEL_ERROR = 1,
  53         /** Output warnings. */
  54         JAYLINK_LOG_LEVEL_WARNING = 2,
  55         /** Output informational messages. */
  56         JAYLINK_LOG_LEVEL_INFO = 3,
  57         /** Output debug messages. */
  58         JAYLINK_LOG_LEVEL_DEBUG = 4
  59 };
  60
  61 /**
  62  * USB addresses.
  63  *
  64  * The USB address is a way to identify USB devices and is related to the USB
  65  * Product ID (PID) of a device.
  66  */
  67 enum jaylink_usb_address {
  68         /** USB address 0 (Product ID 0x0101). */
  69         JAYLINK_USB_ADDRESS_0 = 0,
  70         /** USB address 1 (Product ID 0x0102). */
  71         JAYLINK_USB_ADDRESS_1 = 1,
  72         /** USB address 2 (Product ID 0x0103). */
  73         JAYLINK_USB_ADDRESS_2 = 2,
  74         /** USB address 3 (Product ID 0x0104). */
  75         JAYLINK_USB_ADDRESS_3 = 3
  76 };
  77
  78 /** Device capabilities. */
  79 enum jaylink_device_capability {
  80         /** Device supports retrieval of the hardware version. */
  81         JAYLINK_DEV_CAP_GET_HW_VERSION = 1,
  82         /** Device supports adaptive clocking. */
  83         JAYLINK_DEV_CAP_ADAPTIVE_CLOCKING = 3,
  84         /** Device supports reading configuration data. */
  85         JAYLINK_DEV_CAP_READ_CONFIG = 4,
  86         /** Device supports writing configuration data. */
  87         JAYLINK_DEV_CAP_WRITE_CONFIG = 5,
  88         /** Device supports retrieval of free memory size. */
  89         JAYLINK_DEV_CAP_GET_FREE_MEMORY = 11,
  90         /** Device supports the setting of the target power supply. */
  91         JAYLINK_DEV_CAP_SET_TARGET_POWER = 13,
  92         /** Device supports target interface selection. */
  93         JAYLINK_DEV_CAP_SELECT_TIF = 17,
  94         /** Device supports capturing of SWO trace data. */
  95         JAYLINK_DEV_CAP_SWO = 23,
  96         /** Device supports retrieval of extended capabilities. */
  97         JAYLINK_DEV_CAP_GET_EXT_CAPS = 31
  98 };
  99
 100 /** Device hardware types. */
 101 enum jaylink_hardware_type {
 102         /** J-Link BASE. */
 103         JAYLINK_HW_TYPE_BASE = 0
 104 };
 105
 106 /** Target interfaces. */
 107 enum jaylink_target_interface {
 108         /** Joint Test Action Group, IEEE 1149.1 (JTAG). */
 109         JAYLINK_TIF_JTAG = 0,
 110         /** Serial Wire Debug (SWD). */
 111         JAYLINK_TIF_SWD = 1,
 112         /** Background Debug Mode 3 (BDM3). */
 113         JAYLINK_TIF_BDM3 = 2,
 114         /** Renesas’ single-wire debug interface (FINE). */
 115         JAYLINK_TIF_FINE = 3,
 116         /** 2-wire JTAG for PIC32 compliant devices. */
 117         JAYLINK_TIF_2W_JTAG_PIC32 = 4,
 118
 119         /** <i>Helper which must be always the last element</i>. */
 120         __JAYLINK_TIF_MAX
 121 };
 122
 123 /** Maximum valid target interface number. */
 124 #define JAYLINK_TIF_MAX (__JAYLINK_TIF_MAX - 1)
 125
 126 /**
 127  * JTAG command versions.
 128  *
 129  * The JTAG command version only affects the device and the communication
 130  * protocol. The behaviour of a JTAG operation is not affected at all.
 131  */
 132 enum jaylink_jtag_version {
 133         /**
 134          * JTAG command version 2.
 135          *
 136          * This version is obsolete for major hardware version 5 and above. Use
 137          * #JAYLINK_JTAG_V3 for these versions instead.
 138          */
 139         JAYLINK_JTAG_V2 = 1,
 140         /** JTAG command version 3. */
 141         JAYLINK_JTAG_V3 = 2
 142 };
 143
 144 /** Serial Wire Output (SWO) capture modes. */
 145 enum jaylink_swo_mode {
 146         /** UART capture mode. */
 147         JAYLINK_SWO_MODE_UART = 0
 148 };
 149
 150 /** Device hardware version. */
 151 struct jaylink_hardware_version {
 152         /**
 153          * Hardware type.
 154          *
 155          * See #jaylink_hardware_type for a description of the hardware types.
 156          */
 157         uint8_t type;
 158         /** Major version. */
 159         uint8_t major;
 160         /** Minor version. */
 161         uint8_t minor;
 162         /** Revision number. */
 163         uint8_t revision;
 164 };
 165
 166 /** Device hardware status. */
 167 struct jaylink_hardware_status {
 168         /** Target reference voltage in mV. */
 169         uint16_t target_voltage;
 170         /** TCK pin state. */
 171         uint8_t tck;
 172         /** TDI pin state. */
 173         uint8_t tdi;
 174         /** TDO pin state. */
 175         uint8_t tdo;
 176         /** TMS pin state. */
 177         uint8_t tms;
 178         /** TRES pin state. */
 179         uint8_t tres;
 180         /** TRST pin state. */
 181         uint8_t trst;
 182 };
 183
 184 /** Target interface speed value for adaptive clocking. */
 185 #define JAYLINK_SPEED_ADAPTIVE_CLOCKING 0xffff
 186
 187 /** Size of the device configuration data in bytes. */
 188 #define JAYLINK_DEV_CONFIG_SIZE         256
 189
 190 /** Number of bytes required to store device capabilities. */
 191 #define JAYLINK_DEV_CAPS_SIZE           4
 192
 193 /** Number of bytes required to store extended device capabilities. */
 194 #define JAYLINK_DEV_EXT_CAPS_SIZE       32
 195
 196 /**
 197  * @struct jaylink_context
 198  *
 199  * Opaque structure representing a libjaylink context.
 200  */
 201 struct jaylink_context;
 202
 203 /**
 204  * @struct jaylink_device
 205  *
 206  * Opaque structure representing a device.
 207  */
 208 struct jaylink_device;
 209
 210 /**
 211  * @struct jaylink_device_handle
 212  *
 213  * Opaque structure representing a handle of a device.
 214  */
 215 struct jaylink_device_handle;
 216
 217 /** Macro to mark public libjaylink API symbol. */
 218 #ifndef _WIN32
 219 #define JAYLINK_API __attribute__ ((visibility ("default")))
 220 #else
 221 #define JAYLINK_API
 222 #endif
 223
 224 JAYLINK_API int jaylink_init(struct jaylink_context **ctx);
 225 JAYLINK_API void jaylink_exit(struct jaylink_context *ctx);
 226
 227 JAYLINK_API const char *jaylink_strerror(int error_code);
 228 JAYLINK_API const char *jaylink_strerror_name(int error_code);
 229
 230 JAYLINK_API int jaylink_log_set_level(struct jaylink_context *ctx, int level);
 231 JAYLINK_API int jaylink_log_get_level(const struct jaylink_context *ctx);
 232
 233 JAYLINK_API ssize_t jaylink_get_device_list(struct jaylink_context *ctx,
 234                 struct jaylink_device ***devices);
 235
 236 JAYLINK_API void jaylink_free_device_list(struct jaylink_device **devices,
 237                 int unref_devices);
 238
 239 JAYLINK_API int jaylink_device_get_serial_number(
 240                 const struct jaylink_device *dev, uint32_t *serial_number);
 241
 242 JAYLINK_API int jaylink_device_get_usb_address(
 243                 const struct jaylink_device *dev);
 244
 245 JAYLINK_API struct jaylink_device *jaylink_ref_device(
 246                 struct jaylink_device *dev);
 247 JAYLINK_API void jaylink_unref_device(struct jaylink_device *dev);
 248
 249 JAYLINK_API int jaylink_open(struct jaylink_device *dev,
 250                 struct jaylink_device_handle **devh);
 251
 252 JAYLINK_API void jaylink_close(struct jaylink_device_handle *devh);
 253
 254 JAYLINK_API int jaylink_get_firmware_version(struct jaylink_device_handle *devh,
 255                 char **version);
 256
 257 JAYLINK_API int jaylink_get_hardware_version(struct jaylink_device_handle *devh,
 258                 struct jaylink_hardware_version *version);
 259
 260 JAYLINK_API int jaylink_get_hardware_status(struct jaylink_device_handle *devh,
 261                 struct jaylink_hardware_status *status);
 262
 263 JAYLINK_API int jaylink_get_caps(struct jaylink_device_handle *devh,
 264                 uint8_t *caps);
 265 JAYLINK_API int jaylink_get_extended_caps(struct jaylink_device_handle *devh,
 266                 uint8_t *caps);
 267
 268 JAYLINK_API int jaylink_get_free_memory(struct jaylink_device_handle *devh,
 269                 uint32_t *size);
 270
 271 JAYLINK_API int jaylink_set_speed(struct jaylink_device_handle *devh,
 272                 uint16_t speed);
 273
 274 JAYLINK_API int jaylink_select_interface(struct jaylink_device_handle *devh,
 275                 uint8_t interface);
 276 JAYLINK_API int jaylink_get_available_interfaces(
 277                 struct jaylink_device_handle *devh, uint32_t *interfaces);
 278 JAYLINK_API int jaylink_get_selected_interface(
 279                 struct jaylink_device_handle *devh);
 280
 281 JAYLINK_API int jaylink_clear_reset(struct jaylink_device_handle *devh);
 282 JAYLINK_API int jaylink_set_reset(struct jaylink_device_handle *devh);
 283
 284 JAYLINK_API int jaylink_set_target_power(struct jaylink_device_handle *devh,
 285                 int enable);
 286
 287 JAYLINK_API int jaylink_read_raw_config(struct jaylink_device_handle *devh,
 288                 uint8_t *config);
 289 JAYLINK_API int jaylink_write_raw_config(struct jaylink_device_handle *devh,
 290                 const uint8_t *config);
 291
 292 JAYLINK_API int jaylink_jtag_io(struct jaylink_device_handle *devh,
 293                 const uint8_t *tms, const uint8_t *tdi, uint8_t *tdo,
 294                 uint16_t length, int version);
 295 JAYLINK_API int jaylink_jtag_clear_trst(struct jaylink_device_handle *devh);
 296 JAYLINK_API int jaylink_jtag_set_trst(struct jaylink_device_handle *devh);
 297
 298 JAYLINK_API int jaylink_swd_io(struct jaylink_device_handle *devh,
 299                 const uint8_t *direction, const uint8_t *out, uint8_t *in,
 300                 uint16_t length);
 301
 302 JAYLINK_API int jaylink_swo_start(struct jaylink_device_handle *devh,
 303                 enum jaylink_swo_mode mode, uint32_t baudrate, uint32_t size);
 304 JAYLINK_API int jaylink_swo_stop(struct jaylink_device_handle *devh);
 305 JAYLINK_API ssize_t jaylink_swo_read(struct jaylink_device_handle *devh,
 306                 uint8_t *buffer, uint32_t length);
 307 JAYLINK_API int jaylink_swo_get_speed_info(struct jaylink_device_handle *devh,
 308                 enum jaylink_swo_mode mode, uint32_t *freq, uint32_t *div);
 309
 310 JAYLINK_API int jaylink_has_cap(const uint8_t *caps, uint32_t cap);
 311
 312 #endif /* LIBJAYLINK_LIBJAYLINK_H */