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