2 * This file is part of the libjaylink project.
4 * Copyright (C) 2014-2016 Marc Schink <jaylink-dev@marcschink.de>
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.
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.
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/>.
20 #ifndef LIBJAYLINK_LIBJAYLINK_H
21 #define LIBJAYLINK_LIBJAYLINK_H
30 #include <arpa/inet.h>
36 * Public libjaylink header file to be used by applications.
39 /** Error codes returned by libjaylink functions. */
43 /** Unspecified error. */
45 /** Invalid argument. */
47 /** Memory allocation error. */
48 JAYLINK_ERR_MALLOC
= -3,
49 /** Timeout occurred. */
50 JAYLINK_ERR_TIMEOUT
= -4,
51 /** Protocol violation. */
52 JAYLINK_ERR_PROTO
= -5,
53 /** Entity not available. */
54 JAYLINK_ERR_NOT_AVAILABLE
= -6,
55 /** Operation not supported. */
56 JAYLINK_ERR_NOT_SUPPORTED
= -7,
57 /** Input/output error. */
59 /** Device: unspecified error. */
60 JAYLINK_ERR_DEV
= -1000,
61 /** Device: operation not supported. */
62 JAYLINK_ERR_DEV_NOT_SUPPORTED
= -1001,
63 /** Device: entity not available. */
64 JAYLINK_ERR_DEV_NOT_AVAILABLE
= -1002,
65 /** Device: not enough memory to perform operation. */
66 JAYLINK_ERR_DEV_NO_MEMORY
= -1003
69 /** libjaylink log levels. */
70 enum jaylink_log_level
{
71 /** Output no messages. */
72 JAYLINK_LOG_LEVEL_NONE
= 0,
73 /** Output error messages. */
74 JAYLINK_LOG_LEVEL_ERROR
= 1,
75 /** Output warnings. */
76 JAYLINK_LOG_LEVEL_WARNING
= 2,
77 /** Output informational messages. */
78 JAYLINK_LOG_LEVEL_INFO
= 3,
79 /** Output debug messages. */
80 JAYLINK_LOG_LEVEL_DEBUG
= 4
83 /** Default libjaylink log domain. */
84 #define JAYLINK_LOG_DOMAIN_DEFAULT "jaylink: "
86 /** Maximum length of a libjaylink log domain in bytes. */
87 #define JAYLINK_LOG_DOMAIN_MAX_LENGTH 32
89 /** libjaylink capabilities. */
90 enum jaylink_capability
{
91 /** Library supports USB as host interface. */
92 JAYLINK_CAP_HIF_USB
= 0
95 /** Host interfaces. */
96 enum jaylink_host_interface
{
97 /** Universal Serial Bus (USB). */
98 JAYLINK_HIF_USB
= (1 << 0)
104 * The USB address is a way to identify USB devices and is related to the USB
105 * Product ID (PID) of a device.
107 enum jaylink_usb_address
{
108 /** USB address 0 (Product ID 0x0101). */
109 JAYLINK_USB_ADDRESS_0
= 0,
110 /** USB address 1 (Product ID 0x0102). */
111 JAYLINK_USB_ADDRESS_1
= 1,
112 /** USB address 2 (Product ID 0x0103). */
113 JAYLINK_USB_ADDRESS_2
= 2,
114 /** USB address 3 (Product ID 0x0104). */
115 JAYLINK_USB_ADDRESS_3
= 3
118 /** Device capabilities. */
119 enum jaylink_device_capability
{
120 /** Device supports retrieval of the hardware version. */
121 JAYLINK_DEV_CAP_GET_HW_VERSION
= 1,
122 /** Device supports adaptive clocking. */
123 JAYLINK_DEV_CAP_ADAPTIVE_CLOCKING
= 3,
124 /** Device supports reading configuration data. */
125 JAYLINK_DEV_CAP_READ_CONFIG
= 4,
126 /** Device supports writing configuration data. */
127 JAYLINK_DEV_CAP_WRITE_CONFIG
= 5,
128 /** Device supports retrieval of target interface speeds. */
129 JAYLINK_DEV_CAP_GET_SPEEDS
= 9,
130 /** Device supports retrieval of free memory size. */
131 JAYLINK_DEV_CAP_GET_FREE_MEMORY
= 11,
132 /** Device supports retrieval of hardware information. */
133 JAYLINK_DEV_CAP_GET_HW_INFO
= 12,
134 /** Device supports the setting of the target power supply. */
135 JAYLINK_DEV_CAP_SET_TARGET_POWER
= 13,
136 /** Device supports target interface selection. */
137 JAYLINK_DEV_CAP_SELECT_TIF
= 17,
138 /** Device supports retrieval of counter values. */
139 JAYLINK_DEV_CAP_GET_COUNTERS
= 19,
140 /** Device supports capturing of SWO trace data. */
141 JAYLINK_DEV_CAP_SWO
= 23,
142 /** Device supports file I/O operations. */
143 JAYLINK_DEV_CAP_FILE_IO
= 26,
144 /** Device supports registration of connections. */
145 JAYLINK_DEV_CAP_REGISTER
= 27,
146 /** Device supports retrieval of extended capabilities. */
147 JAYLINK_DEV_CAP_GET_EXT_CAPS
= 31,
148 /** Device supports EMUCOM. */
149 JAYLINK_DEV_CAP_EMUCOM
= 33,
150 /** Device supports ethernet connectivity. */
151 JAYLINK_DEV_CAP_ETHERNET
= 38
154 /** Hardware information. */
155 enum jaylink_hardware_info
{
157 * Status of the target power supply.
159 * This indicates whether the target power supply on pin 19 of the
160 * 20-pin JTAG / SWD connector is enabled or disabled.
162 * @see jaylink_set_target_power()
164 JAYLINK_HW_INFO_TARGET_POWER
= (1 << 0),
165 /** Current consumption of the target in mA. */
166 JAYLINK_HW_INFO_ITARGET
= (1 << 2),
167 /** Peak current consumption of the target in mA. */
168 JAYLINK_HW_INFO_ITARGET_PEAK
= (1 << 3)
171 /** Device counters. */
172 enum jaylink_counter
{
173 /** Time the device is connected to a target in milliseconds. */
174 JAYLINK_COUNTER_TARGET_TIME
= (1 << 0),
176 * Number of times the device was connected or disconnected from a
179 JAYLINK_COUNTER_TARGET_CONNECTIONS
= (1 << 1)
182 /** Device hardware types. */
183 enum jaylink_hardware_type
{
185 JAYLINK_HW_TYPE_JLINK
= 0,
187 JAYLINK_HW_TYPE_FLASHER
= 2,
189 JAYLINK_HW_TYPE_JLINK_PRO
= 3
192 /** Target interfaces. */
193 enum jaylink_target_interface
{
194 /** Joint Test Action Group, IEEE 1149.1 (JTAG). */
195 JAYLINK_TIF_JTAG
= 0,
196 /** Serial Wire Debug (SWD). */
198 /** Background Debug Mode 3 (BDM3). */
199 JAYLINK_TIF_BDM3
= 2,
200 /** Renesas’ single-wire debug interface (FINE). */
201 JAYLINK_TIF_FINE
= 3,
202 /** 2-wire JTAG for PIC32 compliant devices. */
203 JAYLINK_TIF_2W_JTAG_PIC32
= 4,
207 * JTAG command versions.
209 * The JTAG command version only affects the device and the communication
210 * protocol. The behaviour of a JTAG operation is not affected at all.
212 enum jaylink_jtag_version
{
214 * JTAG command version 2.
216 * This version is obsolete for major hardware version 5 and above. Use
217 * #JAYLINK_JTAG_VERSION_3 for these versions instead.
219 JAYLINK_JTAG_VERSION_2
= 1,
220 /** JTAG command version 3. */
221 JAYLINK_JTAG_VERSION_3
= 2
224 /** Serial Wire Output (SWO) capture modes. */
225 enum jaylink_swo_mode
{
226 /** Universal Asynchronous Receiver Transmitter (UART). */
227 JAYLINK_SWO_MODE_UART
= 0
230 /** Target interface speed information. */
231 struct jaylink_speed
{
232 /** Base frequency in Hz. */
234 /** Minimum frequency divider. */
238 /** Serial Wire Output (SWO) speed information. */
239 struct jaylink_swo_speed
{
240 /** Base frequency in Hz. */
242 /** Minimum frequency divider. */
244 /** Maximum frequency divider. */
246 /** Minimum prescaler. */
247 uint32_t min_prescaler
;
248 /** Maximum prescaler. */
249 uint32_t max_prescaler
;
252 /** Device hardware version. */
253 struct jaylink_hardware_version
{
254 /** Hardware type. */
255 enum jaylink_hardware_type type
;
256 /** Major version. */
258 /** Minor version. */
260 /** Revision number. */
264 /** Device hardware status. */
265 struct jaylink_hardware_status
{
266 /** Target reference voltage in mV. */
267 uint16_t target_voltage
;
268 /** TCK pin state. */
270 /** TDI pin state. */
272 /** TDO pin state. */
274 /** TMS pin state. */
276 /** TRES pin state. */
278 /** TRST pin state. */
282 /** Device connection. */
283 struct jaylink_connection
{
289 * Identification of the client process. Usually this is the
290 * Process ID (PID) of the client process in an arbitrary format.
296 * IPv4 address string of the client in quad-dotted decimal format
297 * (e.g. 192.0.2.235). The address 0.0.0.0 should be used for the
298 * registration of an USB connection.
300 char hid
[INET_ADDRSTRLEN
];
306 * Timestamp of the last registration in milliseconds.
308 * The timestamp is relative to the time the device was powered up.
313 /** Target interface speed value for adaptive clocking. */
314 #define JAYLINK_SPEED_ADAPTIVE_CLOCKING 0xffff
316 /** Size of the device configuration data in bytes. */
317 #define JAYLINK_DEV_CONFIG_SIZE 256
319 /** Number of bytes required to store device capabilities. */
320 #define JAYLINK_DEV_CAPS_SIZE 4
322 /** Number of bytes required to store extended device capabilities. */
323 #define JAYLINK_DEV_EXT_CAPS_SIZE 32
325 /** Maximum number of connections that can be registered on a device. */
326 #define JAYLINK_MAX_CONNECTIONS 16
328 /** Maximum length of a filename in bytes. */
329 #define JAYLINK_FILE_NAME_MAX_LENGTH 255
331 /** Maximum transfer size for a file in bytes. */
332 #define JAYLINK_FILE_MAX_TRANSFER_SIZE 0x100000
335 * EMUCOM channel with the system time of the device in milliseconds.
337 * The channel is read-only and the time is encoded in 4 bytes. The byte order
340 #define JAYLINK_EMUCOM_CHANNEL_TIME 0x0
343 * Offset of EMUCOM user channels.
345 * User channels are available to implement vendor and/or device specific
346 * functionalities. All channels below are reserved.
348 #define JAYLINK_EMUCOM_CHANNEL_USER 0x10000
351 * @struct jaylink_context
353 * Opaque structure representing a libjaylink context.
355 struct jaylink_context
;
358 * @struct jaylink_device
360 * Opaque structure representing a device.
362 struct jaylink_device
;
365 * @struct jaylink_device_handle
367 * Opaque structure representing a handle of a device.
369 struct jaylink_device_handle
;
371 /** Macro to mark public libjaylink API symbol. */
375 #define JAYLINK_API __attribute__ ((visibility ("default")))
379 * Log callback function type.
381 * @param[in] ctx libjaylink context.
382 * @param[in] level Log level.
383 * @param[in] format Message format in printf()-style.
384 * @param[in] args Message arguments.
385 * @param[in,out] user_data User data passed to the callback function.
387 * @return Number of characters printed on success, or a negative error code on
390 typedef int (*jaylink_log_callback
)(const struct jaylink_context
*ctx
,
391 enum jaylink_log_level level
, const char *format
, va_list args
,
394 /*--- core.c ----------------------------------------------------------------*/
396 JAYLINK_API
int jaylink_init(struct jaylink_context
**ctx
);
397 JAYLINK_API
int jaylink_exit(struct jaylink_context
*ctx
);
398 JAYLINK_API
bool jaylink_library_has_cap(enum jaylink_capability cap
);
400 /*--- device.c --------------------------------------------------------------*/
402 JAYLINK_API
int jaylink_get_devices(struct jaylink_context
*ctx
,
403 struct jaylink_device
***devs
, size_t *count
);
404 JAYLINK_API
void jaylink_free_devices(struct jaylink_device
**devs
,
406 JAYLINK_API
int jaylink_device_get_host_interface(
407 const struct jaylink_device
*dev
,
408 enum jaylink_host_interface
*iface
);
409 JAYLINK_API
int jaylink_device_get_serial_number(
410 const struct jaylink_device
*dev
, uint32_t *serial_number
);
411 JAYLINK_API
int jaylink_device_get_usb_address(
412 const struct jaylink_device
*dev
,
413 enum jaylink_usb_address
*address
);
414 JAYLINK_API
struct jaylink_device
*jaylink_ref_device(
415 struct jaylink_device
*dev
);
416 JAYLINK_API
void jaylink_unref_device(struct jaylink_device
*dev
);
417 JAYLINK_API
int jaylink_open(struct jaylink_device
*dev
,
418 struct jaylink_device_handle
**devh
);
419 JAYLINK_API
int jaylink_close(struct jaylink_device_handle
*devh
);
420 JAYLINK_API
struct jaylink_device
*jaylink_get_device(
421 struct jaylink_device_handle
*devh
);
422 JAYLINK_API
int jaylink_get_firmware_version(
423 struct jaylink_device_handle
*devh
, char **version
,
425 JAYLINK_API
int jaylink_get_hardware_info(struct jaylink_device_handle
*devh
,
426 uint32_t mask
, uint32_t *info
);
427 JAYLINK_API
int jaylink_get_counters(struct jaylink_device_handle
*devh
,
428 uint32_t mask
, uint32_t *values
);
429 JAYLINK_API
int jaylink_get_hardware_version(
430 struct jaylink_device_handle
*devh
,
431 struct jaylink_hardware_version
*version
);
432 JAYLINK_API
int jaylink_get_hardware_status(struct jaylink_device_handle
*devh
,
433 struct jaylink_hardware_status
*status
);
434 JAYLINK_API
int jaylink_get_caps(struct jaylink_device_handle
*devh
,
436 JAYLINK_API
int jaylink_get_extended_caps(struct jaylink_device_handle
*devh
,
438 JAYLINK_API
int jaylink_get_free_memory(struct jaylink_device_handle
*devh
,
440 JAYLINK_API
int jaylink_read_raw_config(struct jaylink_device_handle
*devh
,
442 JAYLINK_API
int jaylink_write_raw_config(struct jaylink_device_handle
*devh
,
443 const uint8_t *config
);
444 JAYLINK_API
int jaylink_register(struct jaylink_device_handle
*devh
,
445 struct jaylink_connection
*connection
,
446 struct jaylink_connection
*connections
, size_t *count
);
447 JAYLINK_API
int jaylink_unregister(struct jaylink_device_handle
*devh
,
448 const struct jaylink_connection
*connection
,
449 struct jaylink_connection
*connections
, size_t *count
);
451 /*--- discovery.c -----------------------------------------------------------*/
453 JAYLINK_API
int jaylink_discovery_scan(struct jaylink_context
*ctx
,
456 /*--- emucom.c --------------------------------------------------------------*/
458 JAYLINK_API
int jaylink_emucom_read(struct jaylink_device_handle
*devh
,
459 uint32_t channel
, uint8_t *buffer
, uint32_t *length
);
460 JAYLINK_API
int jaylink_emucom_write(struct jaylink_device_handle
*devh
,
461 uint32_t channel
, const uint8_t *buffer
, uint32_t *length
);
463 /*--- error.c ---------------------------------------------------------------*/
465 JAYLINK_API
const char *jaylink_strerror(int error_code
);
466 JAYLINK_API
const char *jaylink_strerror_name(int error_code
);
468 /*--- fileio.c --------------------------------------------------------------*/
470 JAYLINK_API
int jaylink_file_read(struct jaylink_device_handle
*devh
,
471 const char *filename
, uint8_t *buffer
, uint32_t offset
,
473 JAYLINK_API
int jaylink_file_write(struct jaylink_device_handle
*devh
,
474 const char *filename
, const uint8_t *buffer
, uint32_t offset
,
476 JAYLINK_API
int jaylink_file_get_size(struct jaylink_device_handle
*devh
,
477 const char *filename
, uint32_t *size
);
478 JAYLINK_API
int jaylink_file_delete(struct jaylink_device_handle
*devh
,
479 const char *filename
);
481 /*--- jtag.c ----------------------------------------------------------------*/
483 JAYLINK_API
int jaylink_jtag_io(struct jaylink_device_handle
*devh
,
484 const uint8_t *tms
, const uint8_t *tdi
, uint8_t *tdo
,
485 uint16_t length
, enum jaylink_jtag_version version
);
486 JAYLINK_API
int jaylink_jtag_clear_trst(struct jaylink_device_handle
*devh
);
487 JAYLINK_API
int jaylink_jtag_set_trst(struct jaylink_device_handle
*devh
);
489 /*--- log.c -----------------------------------------------------------------*/
491 JAYLINK_API
int jaylink_log_set_level(struct jaylink_context
*ctx
,
492 enum jaylink_log_level level
);
493 JAYLINK_API
int jaylink_log_get_level(const struct jaylink_context
*ctx
,
494 enum jaylink_log_level
*level
);
495 JAYLINK_API
int jaylink_log_set_callback(struct jaylink_context
*ctx
,
496 jaylink_log_callback callback
, void *user_data
);
497 JAYLINK_API
int jaylink_log_set_domain(struct jaylink_context
*ctx
,
499 JAYLINK_API
const char *jaylink_log_get_domain(
500 const struct jaylink_context
*ctx
);
502 /*--- strutil.c -------------------------------------------------------------*/
504 JAYLINK_API
int jaylink_parse_serial_number(const char *str
,
505 uint32_t *serial_number
);
507 /*--- swd.c -----------------------------------------------------------------*/
509 JAYLINK_API
int jaylink_swd_io(struct jaylink_device_handle
*devh
,
510 const uint8_t *direction
, const uint8_t *out
, uint8_t *in
,
513 /*--- swo.c -----------------------------------------------------------------*/
515 JAYLINK_API
int jaylink_swo_start(struct jaylink_device_handle
*devh
,
516 enum jaylink_swo_mode mode
, uint32_t baudrate
, uint32_t size
);
517 JAYLINK_API
int jaylink_swo_stop(struct jaylink_device_handle
*devh
);
518 JAYLINK_API
int jaylink_swo_read(struct jaylink_device_handle
*devh
,
519 uint8_t *buffer
, uint32_t *length
);
520 JAYLINK_API
int jaylink_swo_get_speeds(struct jaylink_device_handle
*devh
,
521 enum jaylink_swo_mode mode
, struct jaylink_swo_speed
*speed
);
523 /*--- target.c --------------------------------------------------------------*/
525 JAYLINK_API
int jaylink_set_speed(struct jaylink_device_handle
*devh
,
527 JAYLINK_API
int jaylink_get_speeds(struct jaylink_device_handle
*devh
,
528 struct jaylink_speed
*speed
);
529 JAYLINK_API
int jaylink_select_interface(struct jaylink_device_handle
*devh
,
530 enum jaylink_target_interface iface
,
531 enum jaylink_target_interface
*prev_iface
);
532 JAYLINK_API
int jaylink_get_available_interfaces(
533 struct jaylink_device_handle
*devh
, uint32_t *ifaces
);
534 JAYLINK_API
int jaylink_get_selected_interface(
535 struct jaylink_device_handle
*devh
,
536 enum jaylink_target_interface
*iface
);
537 JAYLINK_API
int jaylink_clear_reset(struct jaylink_device_handle
*devh
);
538 JAYLINK_API
int jaylink_set_reset(struct jaylink_device_handle
*devh
);
539 JAYLINK_API
int jaylink_set_target_power(struct jaylink_device_handle
*devh
,
542 /*--- util.c ----------------------------------------------------------------*/
544 JAYLINK_API
bool jaylink_has_cap(const uint8_t *caps
, uint32_t cap
);
546 /*--- version.c -------------------------------------------------------------*/
548 JAYLINK_API
int jaylink_version_package_get_major(void);
549 JAYLINK_API
int jaylink_version_package_get_minor(void);
550 JAYLINK_API
int jaylink_version_package_get_micro(void);
551 JAYLINK_API
const char *jaylink_version_package_get_string(void);
552 JAYLINK_API
int jaylink_version_library_get_current(void);
553 JAYLINK_API
int jaylink_version_library_get_revision(void);
554 JAYLINK_API
int jaylink_version_library_get_age(void);
555 JAYLINK_API
const char *jaylink_version_library_get_string(void);
559 #endif /* LIBJAYLINK_LIBJAYLINK_H */