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 2 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 <stdint.h>
  24 #include <stdbool.h>
  25 #include <stdarg.h>
  26 #include <sys/types.h>
  27
  28 /**
  29  * @file
  30  *
  31  * Public libjaylink header file to be used by applications.
  32  */
  33
  34 /** Error codes returned by libjaylink functions. */
  35 enum jaylink_error {
  36         /** No error. */
  37         JAYLINK_OK = 0,
  38         /** Unspecific error. */
  39         JAYLINK_ERR = -1,
  40         /** Memory allocation error. */
  41         JAYLINK_ERR_MALLOC = -2,
  42         /** Invalid argument. */
  43         JAYLINK_ERR_ARG = -3,
  44         /** Timeout occurred. */
  45         JAYLINK_ERR_TIMEOUT = -4,
  46         /** Protocol violation. */
  47         JAYLINK_ERR_PROTO = -5,
  48         /** Entity not available. */
  49         JAYLINK_ERR_NOT_AVAILABLE = -6,
  50         /** Operation not supported. */
  51         JAYLINK_ERR_NOT_SUPPORTED = -7,
  52         /** Device: unspecified error. */
  53         JAYLINK_ERR_DEV = -1000,
  54         /** Device: operation not supported. */
  55         JAYLINK_ERR_DEV_NOT_SUPPORTED = -1001,
  56         /** Device: entity not available. */
  57         JAYLINK_ERR_DEV_NOT_AVAILABLE = -1002
  58 };
  59
  60 /** libjaylink log levels. */
  61 enum jaylink_log_level {
  62         /** Output no messages. */
  63         JAYLINK_LOG_LEVEL_NONE = 0,
  64         /** Output error messages. */
  65         JAYLINK_LOG_LEVEL_ERROR = 1,
  66         /** Output warnings. */
  67         JAYLINK_LOG_LEVEL_WARNING = 2,
  68         /** Output informational messages. */
  69         JAYLINK_LOG_LEVEL_INFO = 3,
  70         /** Output debug messages. */
  71         JAYLINK_LOG_LEVEL_DEBUG = 4
  72 };
  73
  74 /** Default libjaylink log domain. */
  75 #define JAYLINK_LOG_DOMAIN_DEFAULT      "jaylink: "
  76
  77 /** Maximum length of a libjaylink log domain in bytes. */
  78 #define JAYLINK_LOG_DOMAIN_MAX_LENGTH   32
  79
  80 /** Host interfaces. */
  81 enum jaylink_host_interface {
  82         /** Universal Serial Bus (USB). */
  83         JAYLINK_HIF_USB = (1 << 0)
  84 };
  85
  86 /**
  87  * USB addresses.
  88  *
  89  * The USB address is a way to identify USB devices and is related to the USB
  90  * Product ID (PID) of a device.
  91  */
  92 enum jaylink_usb_address {
  93         /** USB address 0 (Product ID 0x0101). */
  94         JAYLINK_USB_ADDRESS_0 = 0,
  95         /** USB address 1 (Product ID 0x0102). */
  96         JAYLINK_USB_ADDRESS_1 = 1,
  97         /** USB address 2 (Product ID 0x0103). */
  98         JAYLINK_USB_ADDRESS_2 = 2,
  99         /** USB address 3 (Product ID 0x0104). */
 100         JAYLINK_USB_ADDRESS_3 = 3
 101 };
 102
 103 /** Device capabilities. */
 104 enum jaylink_device_capability {
 105         /** Device supports retrieval of the hardware version. */
 106         JAYLINK_DEV_CAP_GET_HW_VERSION = 1,
 107         /** Device supports adaptive clocking. */
 108         JAYLINK_DEV_CAP_ADAPTIVE_CLOCKING = 3,
 109         /** Device supports reading configuration data. */
 110         JAYLINK_DEV_CAP_READ_CONFIG = 4,
 111         /** Device supports writing configuration data. */
 112         JAYLINK_DEV_CAP_WRITE_CONFIG = 5,
 113         /** Device supports retrieval of target interface speeds. */
 114         JAYLINK_DEV_CAP_GET_SPEEDS = 9,
 115         /** Device supports retrieval of free memory size. */
 116         JAYLINK_DEV_CAP_GET_FREE_MEMORY = 11,
 117         /** Device supports retrieval of hardware information. */
 118         JAYLINK_DEV_CAP_GET_HW_INFO = 12,
 119         /** Device supports the setting of the target power supply. */
 120         JAYLINK_DEV_CAP_SET_TARGET_POWER = 13,
 121         /** Device supports target interface selection. */
 122         JAYLINK_DEV_CAP_SELECT_TIF = 17,
 123         /** Device supports capturing of SWO trace data. */
 124         JAYLINK_DEV_CAP_SWO = 23,
 125         /** Device supports file I/O operations. */
 126         JAYLINK_DEV_CAP_FILE_IO = 26,
 127         /** Device supports registration of connections. */
 128         JAYLINK_DEV_CAP_REGISTER = 27,
 129         /** Device supports retrieval of extended capabilities. */
 130         JAYLINK_DEV_CAP_GET_EXT_CAPS = 31,
 131         /** Device supports EMUCOM. */
 132         JAYLINK_DEV_CAP_EMUCOM = 33,
 133         /** Device supports ethernet connectivity. */
 134         JAYLINK_DEV_CAP_ETHERNET = 38
 135 };
 136
 137 /** Hardware information. */
 138 enum jaylink_hardware_info {
 139         /**
 140          * Status of the target power supply.
 141          *
 142          * This indicates whether the target power supply on pin 19 of the
 143          * 20-pin JTAG / SWD connector is enabled or disabled.
 144          *
 145          * @see jaylink_set_target_power() to set the target power supply.
 146          */
 147         JAYLINK_HW_INFO_TARGET_POWER = (1 << 0),
 148         /** Current consumption of the target in mA. */
 149         JAYLINK_HW_INFO_ITARGET = (1 << 2),
 150         /** Peak current consumption of the target in mA. */
 151         JAYLINK_HW_INFO_ITARGET_PEAK = (1 << 3)
 152 };
 153
 154 /** Device hardware types. */
 155 enum jaylink_hardware_type {
 156         /** J-Link BASE. */
 157         JAYLINK_HW_TYPE_BASE = 0
 158 };
 159
 160 /** Target interfaces. */
 161 enum jaylink_target_interface {
 162         /** Joint Test Action Group, IEEE 1149.1 (JTAG). */
 163         JAYLINK_TIF_JTAG = 0,
 164         /** Serial Wire Debug (SWD). */
 165         JAYLINK_TIF_SWD = 1,
 166         /** Background Debug Mode 3 (BDM3). */
 167         JAYLINK_TIF_BDM3 = 2,
 168         /** Renesas’ single-wire debug interface (FINE). */
 169         JAYLINK_TIF_FINE = 3,
 170         /** 2-wire JTAG for PIC32 compliant devices. */
 171         JAYLINK_TIF_2W_JTAG_PIC32 = 4,
 172
 173         /** <i>Helper which must be always the last element</i>. */
 174         __JAYLINK_TIF_MAX
 175 };
 176
 177 /** Maximum valid target interface number. */
 178 #define JAYLINK_TIF_MAX (__JAYLINK_TIF_MAX - 1)
 179
 180 /**
 181  * JTAG command versions.
 182  *
 183  * The JTAG command version only affects the device and the communication
 184  * protocol. The behaviour of a JTAG operation is not affected at all.
 185  */
 186 enum jaylink_jtag_version {
 187         /**
 188          * JTAG command version 2.
 189          *
 190          * This version is obsolete for major hardware version 5 and above. Use
 191          * #JAYLINK_JTAG_V3 for these versions instead.
 192          */
 193         JAYLINK_JTAG_V2 = 1,
 194         /** JTAG command version 3. */
 195         JAYLINK_JTAG_V3 = 2
 196 };
 197
 198 /** Serial Wire Output (SWO) capture modes. */
 199 enum jaylink_swo_mode {
 200         /** UART capture mode. */
 201         JAYLINK_SWO_MODE_UART = 0
 202 };
 203
 204 /** Target interface speed information. */
 205 struct jaylink_speed {
 206         /** Base frequency in Hz. */
 207         uint32_t freq;
 208         /** Minimum frequency divider. */
 209         uint16_t div;
 210 };
 211
 212 /** Serial Wire Output (SWO) speed information. */
 213 struct jaylink_swo_speed {
 214         /** Base frequency in Hz. */
 215         uint32_t freq;
 216         /** Minimum frequency divider. */
 217         uint32_t min_div;
 218         /** Maximum frequency divider. */
 219         uint32_t max_div;
 220         /** Minimum prescaler. */
 221         uint32_t min_prescaler;
 222         /** Maximum prescaler. */
 223         uint32_t max_prescaler;
 224 };
 225
 226 /** Device hardware version. */
 227 struct jaylink_hardware_version {
 228         /** Hardware type. */
 229         enum jaylink_hardware_type type;
 230         /** Major version. */
 231         uint8_t major;
 232         /** Minor version. */
 233         uint8_t minor;
 234         /** Revision number. */
 235         uint8_t revision;
 236 };
 237
 238 /** Device hardware status. */
 239 struct jaylink_hardware_status {
 240         /** Target reference voltage in mV. */
 241         uint16_t target_voltage;
 242         /** TCK pin state. */
 243         bool tck;
 244         /** TDI pin state. */
 245         bool tdi;
 246         /** TDO pin state. */
 247         bool tdo;
 248         /** TMS pin state. */
 249         bool tms;
 250         /** TRES pin state. */
 251         bool tres;
 252         /** TRST pin state. */
 253         bool trst;
 254 };
 255
 256 /** Device connection. */
 257 struct jaylink_connection {
 258         /** Handle. */
 259         uint16_t handle;
 260         /**
 261          * Process ID (PID).
 262          *
 263          * Identification of the client process. Usually this is the
 264          * Process ID (PID) of the client process in an arbitrary format.
 265          */
 266         uint32_t pid;
 267         /**
 268          * Host ID (HID).
 269          *
 270          * IP address of the client in network byte order.
 271          */
 272         uint32_t hid;
 273         /** IID. */
 274         uint8_t iid;
 275         /** CID. */
 276         uint8_t cid;
 277         /**
 278          * Timestamp of the last registration in milliseconds.
 279          *
 280          * The timestamp is relative to the time the device was powered up.
 281          */
 282         uint32_t timestamp;
 283 };
 284
 285 /** Target interface speed value for adaptive clocking. */
 286 #define JAYLINK_SPEED_ADAPTIVE_CLOCKING         0xffff
 287
 288 /** Size of the device configuration data in bytes. */
 289 #define JAYLINK_DEV_CONFIG_SIZE                 256
 290
 291 /** Number of bytes required to store device capabilities. */
 292 #define JAYLINK_DEV_CAPS_SIZE                   4
 293
 294 /** Number of bytes required to store extended device capabilities. */
 295 #define JAYLINK_DEV_EXT_CAPS_SIZE               32
 296
 297 /** Maximum number of connections that can be registered on a device. */
 298 #define JAYLINK_MAX_CONNECTIONS                 16
 299
 300 /** Maximum length of a filename in bytes. */
 301 #define JAYLINK_FILE_NAME_MAX_LENGTH            255
 302
 303 /** Maximum transfer size for a file in bytes. */
 304 #define JAYLINK_FILE_MAX_TRANSFER_SIZE          0x100000
 305
 306 /**
 307  * EMUCOM channel with the system time of the device in milliseconds.
 308  *
 309  * The channel is read-only and the time is encoded in 4 bytes. The byte order
 310  * is little-endian.
 311  */
 312 #define JAYLINK_EMUCOM_CHANNEL_TIME     0x0
 313
 314 /**
 315  * Offset of EMUCOM user channels.
 316  *
 317  * User channels are available to implement vendor and/or device specific
 318  * functionalities. All channels below are reserved.
 319  */
 320 #define JAYLINK_EMUCOM_CHANNEL_USER     0x10000
 321
 322 /**
 323  * @struct jaylink_context
 324  *
 325  * Opaque structure representing a libjaylink context.
 326  */
 327 struct jaylink_context;
 328
 329 /**
 330  * @struct jaylink_device
 331  *
 332  * Opaque structure representing a device.
 333  */
 334 struct jaylink_device;
 335
 336 /**
 337  * @struct jaylink_device_handle
 338  *
 339  * Opaque structure representing a handle of a device.
 340  */
 341 struct jaylink_device_handle;
 342
 343 /** Macro to mark public libjaylink API symbol. */
 344 #ifdef _WIN32
 345 #define JAYLINK_API
 346 #else
 347 #define JAYLINK_API __attribute__ ((visibility ("default")))
 348 #endif
 349
 350 /** Log callback function type. */
 351 typedef int (*jaylink_log_callback)(const struct jaylink_context *ctx,
 352                 enum jaylink_log_level level, const char *format, va_list args,
 353                 void *user_data);
 354
 355 /*--- core.c ----------------------------------------------------------------*/
 356
 357 JAYLINK_API int jaylink_init(struct jaylink_context **ctx);
 358 JAYLINK_API void jaylink_exit(struct jaylink_context *ctx);
 359
 360 /*--- device.c --------------------------------------------------------------*/
 361
 362 JAYLINK_API ssize_t jaylink_get_device_list(struct jaylink_context *ctx,
 363                 struct jaylink_device ***devices);
 364 JAYLINK_API void jaylink_free_device_list(struct jaylink_device **devices,
 365                 bool unref_devices);
 366 JAYLINK_API int jaylink_device_get_host_interface(
 367                 const struct jaylink_device *dev,
 368                 enum jaylink_host_interface *interface);
 369 JAYLINK_API int jaylink_device_get_serial_number(
 370                 const struct jaylink_device *dev, uint32_t *serial_number);
 371 JAYLINK_API int jaylink_device_get_usb_address(const struct jaylink_device *dev,
 372                 enum jaylink_usb_address *address);
 373 JAYLINK_API struct jaylink_device *jaylink_ref_device(
 374                 struct jaylink_device *dev);
 375 JAYLINK_API void jaylink_unref_device(struct jaylink_device *dev);
 376 JAYLINK_API int jaylink_open(struct jaylink_device *dev,
 377                 struct jaylink_device_handle **devh);
 378 JAYLINK_API void jaylink_close(struct jaylink_device_handle *devh);
 379 JAYLINK_API struct jaylink_device *jaylink_get_device(
 380                 struct jaylink_device_handle *devh);
 381 JAYLINK_API int jaylink_get_firmware_version(struct jaylink_device_handle *devh,
 382                 char **version, size_t *length);
 383 JAYLINK_API int jaylink_get_hardware_info(struct jaylink_device_handle *devh,
 384                 uint32_t mask, uint32_t *info);
 385 JAYLINK_API int jaylink_get_hardware_version(struct jaylink_device_handle *devh,
 386                 struct jaylink_hardware_version *version);
 387 JAYLINK_API int jaylink_get_hardware_status(struct jaylink_device_handle *devh,
 388                 struct jaylink_hardware_status *status);
 389 JAYLINK_API int jaylink_get_caps(struct jaylink_device_handle *devh,
 390                 uint8_t *caps);
 391 JAYLINK_API int jaylink_get_extended_caps(struct jaylink_device_handle *devh,
 392                 uint8_t *caps);
 393 JAYLINK_API int jaylink_get_free_memory(struct jaylink_device_handle *devh,
 394                 uint32_t *size);
 395 JAYLINK_API int jaylink_read_raw_config(struct jaylink_device_handle *devh,
 396                 uint8_t *config);
 397 JAYLINK_API int jaylink_write_raw_config(struct jaylink_device_handle *devh,
 398                 const uint8_t *config);
 399 JAYLINK_API int jaylink_register(struct jaylink_device_handle *devh,
 400                 struct jaylink_connection *connection,
 401                 struct jaylink_connection *connections, uint8_t *info,
 402                 uint16_t *info_size);
 403 JAYLINK_API int jaylink_unregister(struct jaylink_device_handle *devh,
 404                 const struct jaylink_connection *connection,
 405                 struct jaylink_connection *connections, uint8_t *info,
 406                 uint16_t *info_size);
 407
 408 /*--- emucom.c --------------------------------------------------------------*/
 409
 410 JAYLINK_API int jaylink_emucom_read(struct jaylink_device_handle *devh,
 411                 uint32_t channel, uint8_t *buffer, uint32_t *length);
 412 JAYLINK_API int jaylink_emucom_write(struct jaylink_device_handle *devh,
 413                 uint32_t channel, const uint8_t *buffer, uint32_t *length);
 414
 415 /*--- error.c ---------------------------------------------------------------*/
 416
 417 JAYLINK_API const char *jaylink_strerror(int error_code);
 418 JAYLINK_API const char *jaylink_strerror_name(int error_code);
 419
 420 /*--- fileio.c --------------------------------------------------------------*/
 421
 422 JAYLINK_API int jaylink_file_read(struct jaylink_device_handle *devh,
 423                 const char *filename, uint8_t *buffer, uint32_t offset,
 424                 uint32_t *length);
 425 JAYLINK_API int jaylink_file_write(struct jaylink_device_handle *devh,
 426                 const char *filename, const uint8_t *buffer, uint32_t offset,
 427                 uint32_t *length);
 428 JAYLINK_API int jaylink_file_get_size(struct jaylink_device_handle *devh,
 429                 const char *filename, uint32_t *size);
 430 JAYLINK_API int jaylink_file_delete(struct jaylink_device_handle *devh,
 431                 const char *filename);
 432
 433 /*--- jtag.c ----------------------------------------------------------------*/
 434
 435 JAYLINK_API int jaylink_jtag_io(struct jaylink_device_handle *devh,
 436                 const uint8_t *tms, const uint8_t *tdi, uint8_t *tdo,
 437                 uint16_t length, enum jaylink_jtag_version version);
 438 JAYLINK_API int jaylink_jtag_clear_trst(struct jaylink_device_handle *devh);
 439 JAYLINK_API int jaylink_jtag_set_trst(struct jaylink_device_handle *devh);
 440
 441 /*--- log.c -----------------------------------------------------------------*/
 442
 443 JAYLINK_API int jaylink_log_set_level(struct jaylink_context *ctx,
 444                 enum jaylink_log_level level);
 445 JAYLINK_API int jaylink_log_get_level(const struct jaylink_context *ctx);
 446 JAYLINK_API int jaylink_log_set_callback(struct jaylink_context *ctx,
 447                 jaylink_log_callback callback, void *user_data);
 448 JAYLINK_API int jaylink_log_set_domain(struct jaylink_context *ctx,
 449                 char *domain);
 450 JAYLINK_API const char *jaylink_log_get_domain(
 451                 const struct jaylink_context *ctx);
 452
 453 /*--- swd.c -----------------------------------------------------------------*/
 454
 455 JAYLINK_API int jaylink_swd_io(struct jaylink_device_handle *devh,
 456                 const uint8_t *direction, const uint8_t *out, uint8_t *in,
 457                 uint16_t length);
 458
 459 /*--- swo.c -----------------------------------------------------------------*/
 460
 461 JAYLINK_API int jaylink_swo_start(struct jaylink_device_handle *devh,
 462                 enum jaylink_swo_mode mode, uint32_t baudrate, uint32_t size);
 463 JAYLINK_API int jaylink_swo_stop(struct jaylink_device_handle *devh);
 464 JAYLINK_API int jaylink_swo_read(struct jaylink_device_handle *devh,
 465                 uint8_t *buffer, uint32_t *length);
 466 JAYLINK_API int jaylink_swo_get_speeds(struct jaylink_device_handle *devh,
 467                 enum jaylink_swo_mode mode, struct jaylink_swo_speed *speed);
 468
 469 /*--- target.c --------------------------------------------------------------*/
 470
 471 JAYLINK_API int jaylink_set_speed(struct jaylink_device_handle *devh,
 472                 uint16_t speed);
 473 JAYLINK_API int jaylink_get_speeds(struct jaylink_device_handle *devh,
 474                 struct jaylink_speed *speed);
 475 JAYLINK_API int jaylink_select_interface(struct jaylink_device_handle *devh,
 476                 enum jaylink_target_interface interface,
 477                 enum jaylink_target_interface *prev_interface);
 478 JAYLINK_API int jaylink_get_available_interfaces(
 479                 struct jaylink_device_handle *devh, uint32_t *interfaces);
 480 JAYLINK_API int jaylink_get_selected_interface(
 481                 struct jaylink_device_handle *devh,
 482                 enum jaylink_target_interface *interface);
 483 JAYLINK_API int jaylink_clear_reset(struct jaylink_device_handle *devh);
 484 JAYLINK_API int jaylink_set_reset(struct jaylink_device_handle *devh);
 485 JAYLINK_API int jaylink_set_target_power(struct jaylink_device_handle *devh,
 486                 bool enable);
 487
 488 /*--- util.c ----------------------------------------------------------------*/
 489
 490 JAYLINK_API bool jaylink_has_cap(const uint8_t *caps, uint32_t cap);
 491
 492 /*--- version.c -------------------------------------------------------------*/
 493
 494 JAYLINK_API int jaylink_version_package_get_major(void);
 495 JAYLINK_API int jaylink_version_package_get_minor(void);
 496 JAYLINK_API int jaylink_version_package_get_micro(void);
 497 JAYLINK_API const char *jaylink_version_package_get_string(void);
 498 JAYLINK_API int jaylink_version_lib_get_current(void);
 499 JAYLINK_API int jaylink_version_lib_get_revision(void);
 500 JAYLINK_API int jaylink_version_lib_get_age(void);
 501 JAYLINK_API const char *jaylink_version_lib_get_string(void);
 502
 503 #include "version.h"
 504
 505 #endif /* LIBJAYLINK_LIBJAYLINK_H */