libjaylink/libjaylink.h

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