libjaylink/libjaylink.h

   1 /*
   2  * This file is part of the libjaylink project.
   3  *
   4  * Copyright (C) 2014 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
  26 enum jaylink_error {
  27         JAYLINK_OK = 0,
  28         JAYLINK_ERR = -1,
  29         JAYLINK_ERR_MALLOC = -2,
  30         JAYLINK_ERR_ARG = -3,
  31         JAYLINK_ERR_TIMEOUT = -4
  32 };
  33
  34 enum jaylink_log_level {
  35         JAYLINK_LOG_LEVEL_NONE = 0,
  36         JAYLINK_LOG_LEVEL_ERROR = 1,
  37         JAYLINK_LOG_LEVEL_WARNING = 2,
  38         JAYLINK_LOG_LEVEL_INFO = 3,
  39         JAYLINK_LOG_LEVEL_DEBUG = 4
  40 };
  41
  42 /**
  43  * USB addresses.
  44  *
  45  * The USB address is a way to identify USB devices and is related to the USB
  46  * Product ID (PID) of a device.
  47  */
  48 enum jaylink_usb_address {
  49         /** USB address 0 (Product ID 0x0101). */
  50         JAYLINK_USB_ADDRESS_0 = 0,
  51         /** USB address 1 (Product ID 0x0102). */
  52         JAYLINK_USB_ADDRESS_1 = 1,
  53         /** USB address 2 (Product ID 0x0103). */
  54         JAYLINK_USB_ADDRESS_2 = 2,
  55         /** USB address 3 (Product ID 0x0104). */
  56         JAYLINK_USB_ADDRESS_3 = 3
  57 };
  58
  59 /** Device capabilities. */
  60 enum jaylink_device_capability {
  61         /** Device supports retrieval of the hardware version. */
  62         JAYLINK_DEV_CAP_GET_HW_VERSION = 1,
  63         /** Device supports adaptive clocking. */
  64         JAYLINK_DEV_CAP_ADAPTIVE_CLOCKING = 3,
  65         /** Device supports reading configuration data. */
  66         JAYLINK_DEV_CAP_READ_CONFIG = 4,
  67         /** Device supports writing configuration data. */
  68         JAYLINK_DEV_CAP_WRITE_CONFIG = 5,
  69         /** Device supports retrieval of free memory size. */
  70         JAYLINK_DEV_CAP_GET_FREE_MEMORY = 11,
  71         /** Device supports the setting of the target power supply. */
  72         JAYLINK_DEV_CAP_SET_TARGET_POWER = 13,
  73         /** Device supports target interface selection. */
  74         JAYLINK_DEV_CAP_SELECT_TIF = 17,
  75         /** Device supports retrieval of extended capabilities. */
  76         JAYLINK_DEV_CAP_GET_EXT_CAPS = 31
  77 };
  78
  79 /** Device hardware types. */
  80 enum jaylink_hardware_type {
  81         /** J-Link BASE. */
  82         JAYLINK_HW_TYPE_BASE = 0
  83 };
  84
  85 /** Target interfaces. */
  86 enum jaylink_target_interface {
  87         /** Joint Test Action Group, IEEE 1149.1 (JTAG). */
  88         JAYLINK_TIF_JTAG = 0,
  89         /** Serial Wire Debug (SWD). */
  90         JAYLINK_TIF_SWD = 1,
  91         /** Background Debug Mode 3 (BDM3). */
  92         JAYLINK_TIF_BDM3 = 2,
  93         /** Renesas’ single-wire debug interface (FINE). */
  94         JAYLINK_TIF_FINE = 3,
  95         /** 2-wire JTAG for PIC32 compliant devices. */
  96         JAYLINK_TIF_2W_JTAG_PIC32 = 4,
  97
  98         /** <i>Helper which must be always the last element</i>. */
  99         __JAYLINK_TIF_MAX
 100 };
 101
 102 /** Maximum valid target interface number. */
 103 #define JAYLINK_TIF_MAX (__JAYLINK_TIF_MAX - 1)
 104
 105 /** Device hardware version. */
 106 struct jaylink_hardware_version {
 107         /**
 108          * Hardware type.
 109          *
 110          * See #jaylink_hardware_type for a description of the hardware types.
 111          */
 112         uint8_t type;
 113         /** Major version. */
 114         uint8_t major;
 115         /** Minor version. */
 116         uint8_t minor;
 117         /** Revision number. */
 118         uint8_t revision;
 119 };
 120
 121 /** Device hardware status. */
 122 struct jaylink_hardware_status {
 123         /** Target reference voltage in mV. */
 124         uint16_t target_voltage;
 125         /** TCK pin state. */
 126         uint8_t tck;
 127         /** TDI pin state. */
 128         uint8_t tdi;
 129         /** TDO pin state. */
 130         uint8_t tdo;
 131         /** TMS pin state. */
 132         uint8_t tms;
 133         /** TRES pin state. */
 134         uint8_t tres;
 135         /** TRST pin state. */
 136         uint8_t trst;
 137 };
 138
 139 /** Target interface speed value for adaptive clocking. */
 140 #define JAYLINK_SPEED_ADAPTIVE_CLOCKING 0xffff
 141
 142 /** Size of the device configuration data in bytes. */
 143 #define JAYLINK_DEV_CONFIG_SIZE         256
 144
 145 /** Number of bytes required to store device capabilities. */
 146 #define JAYLINK_DEV_CAPS_SIZE           4
 147
 148 /** Number of bytes required to store extended device capabilities. */
 149 #define JAYLINK_DEV_EXT_CAPS_SIZE       32
 150
 151 struct jaylink_context;
 152 struct jaylink_device;
 153 struct jaylink_device_handle;
 154
 155 int jaylink_init(struct jaylink_context **ctx);
 156 void jaylink_exit(struct jaylink_context *ctx);
 157
 158 const char *jaylink_strerror(int error_code);
 159 const char *jaylink_strerror_name(int error_code);
 160
 161 int jaylink_log_set_level(struct jaylink_context *ctx, int level);
 162 int jaylink_log_get_level(const struct jaylink_context *ctx);
 163
 164 ssize_t jaylink_get_device_list(struct jaylink_context *ctx,
 165                 struct jaylink_device ***list);
 166
 167 void jaylink_free_device_list(struct jaylink_device **list, int unref_devices);
 168
 169 int jaylink_device_get_serial_number(const struct jaylink_device *dev,
 170                 uint32_t *serial_number);
 171
 172 int jaylink_device_get_usb_address(const struct jaylink_device *dev);
 173
 174 struct jaylink_device *jaylink_ref_device(struct jaylink_device *dev);
 175 void jaylink_unref_device(struct jaylink_device *dev);
 176
 177 int jaylink_open(struct jaylink_device *dev,
 178                 struct jaylink_device_handle **devh);
 179
 180 void jaylink_close(struct jaylink_device_handle *devh);
 181
 182 int jaylink_get_firmware_version(struct jaylink_device_handle *devh,
 183                 char **version);
 184
 185 int jaylink_get_hardware_version(struct jaylink_device_handle *devh,
 186                 struct jaylink_hardware_version *version);
 187
 188 int jaylink_get_hardware_status(struct jaylink_device_handle *devh,
 189                 struct jaylink_hardware_status *status);
 190
 191 int jaylink_get_caps(struct jaylink_device_handle *devh, uint8_t *caps);
 192 int jaylink_get_extended_caps(struct jaylink_device_handle *devh,
 193                 uint8_t *caps);
 194
 195 int jaylink_get_free_memory(struct jaylink_device_handle *devh, uint32_t *size);
 196
 197 int jaylink_set_speed(struct jaylink_device_handle *devh, uint16_t speed);
 198
 199 int jaylink_select_interface(struct jaylink_device_handle *devh,
 200                 uint8_t interface);
 201 int jaylink_get_available_interfaces(struct jaylink_device_handle *devh,
 202                 uint32_t *interfaces);
 203 int jaylink_get_selected_interface(struct jaylink_device_handle *devh);
 204
 205 int jaylink_clear_reset(struct jaylink_device_handle *devh);
 206 int jaylink_set_reset(struct jaylink_device_handle *devh);
 207
 208 int jaylink_set_target_power(struct jaylink_device_handle *devh, int enable);
 209
 210 int jaylink_read_raw_config(struct jaylink_device_handle *devh,
 211                 uint8_t *config);
 212 int jaylink_write_raw_config(struct jaylink_device_handle *devh,
 213                 const uint8_t *config);
 214
 215 int jaylink_has_cap(const uint8_t *caps, uint32_t cap);
 216
 217 #endif /* LIBJAYLINK_LIBJAYLINK_H */