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