Add constants for IPv4 device information
[libjaylink.git] / libjaylink / libjaylink.h
bloba542c05c2e4286102f1aa3a078dc4e5ac326e890
1 /*
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
23 #include <stddef.h>
24 #include <stdint.h>
25 #include <stdbool.h>
26 #include <stdarg.h>
27 #ifdef _WIN32
28 #include <ws2tcpip.h>
29 #else
30 #include <arpa/inet.h>
31 #endif
33 /**
34 * @file
36 * Public libjaylink header file to be used by applications.
39 /** Error codes returned by libjaylink functions. */
40 enum jaylink_error {
41 /** No error. */
42 JAYLINK_OK = 0,
43 /** Unspecified error. */
44 JAYLINK_ERR = -1,
45 /** Invalid argument. */
46 JAYLINK_ERR_ARG = -2,
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. */
58 JAYLINK_ERR_IO = -8,
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,
81 /** Output I/O debug messages. */
82 JAYLINK_LOG_LEVEL_DEBUG_IO = 5
85 /** Default libjaylink log domain. */
86 #define JAYLINK_LOG_DOMAIN_DEFAULT "jaylink: "
88 /** Maximum length of a libjaylink log domain in bytes. */
89 #define JAYLINK_LOG_DOMAIN_MAX_LENGTH 32
91 /** libjaylink capabilities. */
92 enum jaylink_capability {
93 /** Library supports USB as host interface. */
94 JAYLINK_CAP_HIF_USB = 0
97 /** Host interfaces. */
98 enum jaylink_host_interface {
99 /** Universal Serial Bus (USB). */
100 JAYLINK_HIF_USB = (1 << 0),
101 /** Transmission Control Protocol (TCP). */
102 JAYLINK_HIF_TCP = (1 << 1)
106 * USB addresses.
108 * The USB address is a way to identify USB devices and is related to the USB
109 * Product ID (PID) of a device.
111 enum jaylink_usb_address {
112 /** USB address 0 (Product ID 0x0101). */
113 JAYLINK_USB_ADDRESS_0 = 0,
114 /** USB address 1 (Product ID 0x0102). */
115 JAYLINK_USB_ADDRESS_1 = 1,
116 /** USB address 2 (Product ID 0x0103). */
117 JAYLINK_USB_ADDRESS_2 = 2,
118 /** USB address 3 (Product ID 0x0104). */
119 JAYLINK_USB_ADDRESS_3 = 3
122 /** Device capabilities. */
123 enum jaylink_device_capability {
124 /** Device supports retrieval of the hardware version. */
125 JAYLINK_DEV_CAP_GET_HW_VERSION = 1,
126 /** Device supports adaptive clocking. */
127 JAYLINK_DEV_CAP_ADAPTIVE_CLOCKING = 3,
128 /** Device supports reading configuration data. */
129 JAYLINK_DEV_CAP_READ_CONFIG = 4,
130 /** Device supports writing configuration data. */
131 JAYLINK_DEV_CAP_WRITE_CONFIG = 5,
132 /** Device supports retrieval of target interface speeds. */
133 JAYLINK_DEV_CAP_GET_SPEEDS = 9,
134 /** Device supports retrieval of free memory size. */
135 JAYLINK_DEV_CAP_GET_FREE_MEMORY = 11,
136 /** Device supports retrieval of hardware information. */
137 JAYLINK_DEV_CAP_GET_HW_INFO = 12,
138 /** Device supports the setting of the target power supply. */
139 JAYLINK_DEV_CAP_SET_TARGET_POWER = 13,
140 /** Device supports target interface selection. */
141 JAYLINK_DEV_CAP_SELECT_TIF = 17,
142 /** Device supports retrieval of counter values. */
143 JAYLINK_DEV_CAP_GET_COUNTERS = 19,
144 /** Device supports capturing of SWO trace data. */
145 JAYLINK_DEV_CAP_SWO = 23,
146 /** Device supports file I/O operations. */
147 JAYLINK_DEV_CAP_FILE_IO = 26,
148 /** Device supports registration of connections. */
149 JAYLINK_DEV_CAP_REGISTER = 27,
150 /** Device supports retrieval of extended capabilities. */
151 JAYLINK_DEV_CAP_GET_EXT_CAPS = 31,
152 /** Device supports EMUCOM. */
153 JAYLINK_DEV_CAP_EMUCOM = 33,
154 /** Device supports ethernet connectivity. */
155 JAYLINK_DEV_CAP_ETHERNET = 38
158 /** Hardware information. */
159 enum jaylink_hardware_info {
161 * Status of the target power supply.
163 * This indicates whether the target power supply on pin 19 of the
164 * 20-pin JTAG / SWD connector is enabled or disabled.
166 * @see jaylink_set_target_power()
168 JAYLINK_HW_INFO_TARGET_POWER = (1 << 0),
169 /** Current consumption of the target in mA. */
170 JAYLINK_HW_INFO_ITARGET = (1 << 2),
171 /** Peak current consumption of the target in mA. */
172 JAYLINK_HW_INFO_ITARGET_PEAK = (1 << 3),
174 * Device's IPv4 address in network byte order.
176 * If the address is 0.0.0.0 and DHCP is enabled, no address is
177 * assigned (yet).
179 * @note The value is valid only if the device is configured in DHCP
180 * mode.
182 JAYLINK_HW_INFO_IPV4_ADDRESS = (1 << 16),
184 * IPv4 netmask in network byte order.
186 * @note The value is valid only if the device is configured in DHCP
187 * mode.
189 JAYLINK_HW_INFO_IPV4_NETMASK = (1 << 17),
191 * Gateway IPv4 address in network byte order.
193 * @note The value is valid only if the device is configured in DHCP
194 * mode.
196 JAYLINK_HW_INFO_IPV4_GATEWAY = (1 << 18),
198 * DNS server IPv4 address in network byte order.
200 * @note The value is valid only if the device is configured in DHCP
201 * mode.
203 JAYLINK_HW_INFO_IPV4_DNS = (1 << 19)
206 /** Device counters. */
207 enum jaylink_counter {
208 /** Time the device is connected to a target in milliseconds. */
209 JAYLINK_COUNTER_TARGET_TIME = (1 << 0),
211 * Number of times the device was connected or disconnected from a
212 * target.
214 JAYLINK_COUNTER_TARGET_CONNECTIONS = (1 << 1)
217 /** Device hardware types. */
218 enum jaylink_hardware_type {
219 /** J-Link. */
220 JAYLINK_HW_TYPE_JLINK = 0,
221 /** Flasher. */
222 JAYLINK_HW_TYPE_FLASHER = 2,
223 /** J-Link Pro. */
224 JAYLINK_HW_TYPE_JLINK_PRO = 3
227 /** Target interfaces. */
228 enum jaylink_target_interface {
229 /** Joint Test Action Group, IEEE 1149.1 (JTAG). */
230 JAYLINK_TIF_JTAG = 0,
231 /** Serial Wire Debug (SWD). */
232 JAYLINK_TIF_SWD = 1,
233 /** Background Debug Mode 3 (BDM3). */
234 JAYLINK_TIF_BDM3 = 2,
235 /** Renesas’ single-wire debug interface (FINE). */
236 JAYLINK_TIF_FINE = 3,
237 /** 2-wire JTAG for PIC32 compliant devices. */
238 JAYLINK_TIF_2W_JTAG_PIC32 = 4,
242 * JTAG command versions.
244 * The JTAG command version only affects the device and the communication
245 * protocol. The behaviour of a JTAG operation is not affected at all.
247 enum jaylink_jtag_version {
249 * JTAG command version 2.
251 * This version is obsolete for major hardware version 5 and above. Use
252 * #JAYLINK_JTAG_VERSION_3 for these versions instead.
254 JAYLINK_JTAG_VERSION_2 = 1,
255 /** JTAG command version 3. */
256 JAYLINK_JTAG_VERSION_3 = 2
259 /** Serial Wire Output (SWO) capture modes. */
260 enum jaylink_swo_mode {
261 /** Universal Asynchronous Receiver Transmitter (UART). */
262 JAYLINK_SWO_MODE_UART = 0
265 /** Target interface speed information. */
266 struct jaylink_speed {
267 /** Base frequency in Hz. */
268 uint32_t freq;
269 /** Minimum frequency divider. */
270 uint16_t div;
273 /** Serial Wire Output (SWO) speed information. */
274 struct jaylink_swo_speed {
275 /** Base frequency in Hz. */
276 uint32_t freq;
277 /** Minimum frequency divider. */
278 uint32_t min_div;
279 /** Maximum frequency divider. */
280 uint32_t max_div;
281 /** Minimum prescaler. */
282 uint32_t min_prescaler;
283 /** Maximum prescaler. */
284 uint32_t max_prescaler;
287 /** Device hardware version. */
288 struct jaylink_hardware_version {
289 /** Hardware type. */
290 enum jaylink_hardware_type type;
291 /** Major version. */
292 uint8_t major;
293 /** Minor version. */
294 uint8_t minor;
295 /** Revision number. */
296 uint8_t revision;
299 /** Device hardware status. */
300 struct jaylink_hardware_status {
301 /** Target reference voltage in mV. */
302 uint16_t target_voltage;
303 /** TCK pin state. */
304 bool tck;
305 /** TDI pin state. */
306 bool tdi;
307 /** TDO pin state. */
308 bool tdo;
309 /** TMS pin state. */
310 bool tms;
311 /** TRES pin state. */
312 bool tres;
313 /** TRST pin state. */
314 bool trst;
317 /** Device connection. */
318 struct jaylink_connection {
319 /** Handle. */
320 uint16_t handle;
322 * Process ID (PID).
324 * Identification of the client process. Usually this is the
325 * Process ID (PID) of the client process in an arbitrary format.
327 uint32_t pid;
329 * Host ID (HID).
331 * IPv4 address string of the client in quad-dotted decimal format
332 * (e.g. 192.0.2.235). The address 0.0.0.0 should be used for the
333 * registration of an USB connection.
335 char hid[INET_ADDRSTRLEN];
336 /** IID. */
337 uint8_t iid;
338 /** CID. */
339 uint8_t cid;
341 * Timestamp of the last registration in milliseconds.
343 * The timestamp is relative to the time the device was powered up.
345 uint32_t timestamp;
348 /** Target interface speed value for adaptive clocking. */
349 #define JAYLINK_SPEED_ADAPTIVE_CLOCKING 0xffff
351 /** Size of the device configuration data in bytes. */
352 #define JAYLINK_DEV_CONFIG_SIZE 256
354 /** Number of bytes required to store device capabilities. */
355 #define JAYLINK_DEV_CAPS_SIZE 4
357 /** Number of bytes required to store extended device capabilities. */
358 #define JAYLINK_DEV_EXT_CAPS_SIZE 32
360 /** Maximum number of connections that can be registered on a device. */
361 #define JAYLINK_MAX_CONNECTIONS 16
363 /** Media Access Control (MAC) address length in bytes. */
364 #define JAYLINK_MAC_ADDRESS_LENGTH 6
367 * Maximum length of a device's nickname including trailing null-terminator in
368 * bytes.
370 #define JAYLINK_NICKNAME_MAX_LENGTH 32
373 * Maximum length of a device's product name including trailing null-terminator
374 * in bytes.
376 #define JAYLINK_PRODUCT_NAME_MAX_LENGTH 32
378 /** Maximum length of a filename in bytes. */
379 #define JAYLINK_FILE_NAME_MAX_LENGTH 255
381 /** Maximum transfer size for a file in bytes. */
382 #define JAYLINK_FILE_MAX_TRANSFER_SIZE 0x100000
385 * EMUCOM channel with the system time of the device in milliseconds.
387 * The channel is read-only and the time is encoded in 4 bytes. The byte order
388 * is little-endian.
390 #define JAYLINK_EMUCOM_CHANNEL_TIME 0x0
393 * Offset of EMUCOM user channels.
395 * User channels are available to implement vendor and/or device specific
396 * functionalities. All channels below are reserved.
398 #define JAYLINK_EMUCOM_CHANNEL_USER 0x10000
401 * @struct jaylink_context
403 * Opaque structure representing a libjaylink context.
405 struct jaylink_context;
408 * @struct jaylink_device
410 * Opaque structure representing a device.
412 struct jaylink_device;
415 * @struct jaylink_device_handle
417 * Opaque structure representing a handle of a device.
419 struct jaylink_device_handle;
421 /** Macro to mark public libjaylink API symbol. */
422 #ifdef _WIN32
423 #define JAYLINK_API
424 #else
425 #define JAYLINK_API __attribute__ ((visibility ("default")))
426 #endif
429 * Log callback function type.
431 * @param[in] ctx libjaylink context.
432 * @param[in] level Log level.
433 * @param[in] format Message format in printf()-style.
434 * @param[in] args Message arguments.
435 * @param[in,out] user_data User data passed to the callback function.
437 * @return Number of characters printed on success, or a negative error code on
438 * failure.
440 typedef int (*jaylink_log_callback)(const struct jaylink_context *ctx,
441 enum jaylink_log_level level, const char *format, va_list args,
442 void *user_data);
444 /*--- core.c ----------------------------------------------------------------*/
446 JAYLINK_API int jaylink_init(struct jaylink_context **ctx);
447 JAYLINK_API int jaylink_exit(struct jaylink_context *ctx);
448 JAYLINK_API bool jaylink_library_has_cap(enum jaylink_capability cap);
450 /*--- device.c --------------------------------------------------------------*/
452 JAYLINK_API int jaylink_get_devices(struct jaylink_context *ctx,
453 struct jaylink_device ***devs, size_t *count);
454 JAYLINK_API void jaylink_free_devices(struct jaylink_device **devs,
455 bool unref);
456 JAYLINK_API int jaylink_device_get_host_interface(
457 const struct jaylink_device *dev,
458 enum jaylink_host_interface *iface);
459 JAYLINK_API int jaylink_device_get_serial_number(
460 const struct jaylink_device *dev, uint32_t *serial_number);
461 JAYLINK_API int jaylink_device_get_usb_address(
462 const struct jaylink_device *dev,
463 enum jaylink_usb_address *address);
464 JAYLINK_API int jaylink_device_get_ipv4_address(
465 const struct jaylink_device *dev, char *address);
466 JAYLINK_API int jaylink_device_get_mac_address(
467 const struct jaylink_device *dev, uint8_t *address);
468 JAYLINK_API int jaylink_device_get_hardware_version(
469 const struct jaylink_device *dev,
470 struct jaylink_hardware_version *version);
471 JAYLINK_API int jaylink_device_get_product_name(
472 const struct jaylink_device *dev, char *name);
473 JAYLINK_API int jaylink_device_get_nickname(const struct jaylink_device *dev,
474 char *nickname);
475 JAYLINK_API struct jaylink_device *jaylink_ref_device(
476 struct jaylink_device *dev);
477 JAYLINK_API void jaylink_unref_device(struct jaylink_device *dev);
478 JAYLINK_API int jaylink_open(struct jaylink_device *dev,
479 struct jaylink_device_handle **devh);
480 JAYLINK_API int jaylink_close(struct jaylink_device_handle *devh);
481 JAYLINK_API struct jaylink_device *jaylink_get_device(
482 struct jaylink_device_handle *devh);
483 JAYLINK_API int jaylink_get_firmware_version(
484 struct jaylink_device_handle *devh, char **version,
485 size_t *length);
486 JAYLINK_API int jaylink_get_hardware_info(struct jaylink_device_handle *devh,
487 uint32_t mask, uint32_t *info);
488 JAYLINK_API int jaylink_get_counters(struct jaylink_device_handle *devh,
489 uint32_t mask, uint32_t *values);
490 JAYLINK_API int jaylink_get_hardware_version(
491 struct jaylink_device_handle *devh,
492 struct jaylink_hardware_version *version);
493 JAYLINK_API int jaylink_get_hardware_status(struct jaylink_device_handle *devh,
494 struct jaylink_hardware_status *status);
495 JAYLINK_API int jaylink_get_caps(struct jaylink_device_handle *devh,
496 uint8_t *caps);
497 JAYLINK_API int jaylink_get_extended_caps(struct jaylink_device_handle *devh,
498 uint8_t *caps);
499 JAYLINK_API int jaylink_get_free_memory(struct jaylink_device_handle *devh,
500 uint32_t *size);
501 JAYLINK_API int jaylink_read_raw_config(struct jaylink_device_handle *devh,
502 uint8_t *config);
503 JAYLINK_API int jaylink_write_raw_config(struct jaylink_device_handle *devh,
504 const uint8_t *config);
505 JAYLINK_API int jaylink_register(struct jaylink_device_handle *devh,
506 struct jaylink_connection *connection,
507 struct jaylink_connection *connections, size_t *count);
508 JAYLINK_API int jaylink_unregister(struct jaylink_device_handle *devh,
509 const struct jaylink_connection *connection,
510 struct jaylink_connection *connections, size_t *count);
512 /*--- discovery.c -----------------------------------------------------------*/
514 JAYLINK_API int jaylink_discovery_scan(struct jaylink_context *ctx,
515 uint32_t ifaces);
517 /*--- emucom.c --------------------------------------------------------------*/
519 JAYLINK_API int jaylink_emucom_read(struct jaylink_device_handle *devh,
520 uint32_t channel, uint8_t *buffer, uint32_t *length);
521 JAYLINK_API int jaylink_emucom_write(struct jaylink_device_handle *devh,
522 uint32_t channel, const uint8_t *buffer, uint32_t *length);
524 /*--- error.c ---------------------------------------------------------------*/
526 JAYLINK_API const char *jaylink_strerror(int error_code);
527 JAYLINK_API const char *jaylink_strerror_name(int error_code);
529 /*--- fileio.c --------------------------------------------------------------*/
531 JAYLINK_API int jaylink_file_read(struct jaylink_device_handle *devh,
532 const char *filename, uint8_t *buffer, uint32_t offset,
533 uint32_t *length);
534 JAYLINK_API int jaylink_file_write(struct jaylink_device_handle *devh,
535 const char *filename, const uint8_t *buffer, uint32_t offset,
536 uint32_t *length);
537 JAYLINK_API int jaylink_file_get_size(struct jaylink_device_handle *devh,
538 const char *filename, uint32_t *size);
539 JAYLINK_API int jaylink_file_delete(struct jaylink_device_handle *devh,
540 const char *filename);
542 /*--- jtag.c ----------------------------------------------------------------*/
544 JAYLINK_API int jaylink_jtag_io(struct jaylink_device_handle *devh,
545 const uint8_t *tms, const uint8_t *tdi, uint8_t *tdo,
546 uint16_t length, enum jaylink_jtag_version version);
547 JAYLINK_API int jaylink_jtag_clear_trst(struct jaylink_device_handle *devh);
548 JAYLINK_API int jaylink_jtag_set_trst(struct jaylink_device_handle *devh);
550 /*--- log.c -----------------------------------------------------------------*/
552 JAYLINK_API int jaylink_log_set_level(struct jaylink_context *ctx,
553 enum jaylink_log_level level);
554 JAYLINK_API int jaylink_log_get_level(const struct jaylink_context *ctx,
555 enum jaylink_log_level *level);
556 JAYLINK_API int jaylink_log_set_callback(struct jaylink_context *ctx,
557 jaylink_log_callback callback, void *user_data);
558 JAYLINK_API int jaylink_log_set_domain(struct jaylink_context *ctx,
559 const char *domain);
560 JAYLINK_API const char *jaylink_log_get_domain(
561 const struct jaylink_context *ctx);
563 /*--- strutil.c -------------------------------------------------------------*/
565 JAYLINK_API int jaylink_parse_serial_number(const char *str,
566 uint32_t *serial_number);
568 /*--- swd.c -----------------------------------------------------------------*/
570 JAYLINK_API int jaylink_swd_io(struct jaylink_device_handle *devh,
571 const uint8_t *direction, const uint8_t *out, uint8_t *in,
572 uint16_t length);
574 /*--- swo.c -----------------------------------------------------------------*/
576 JAYLINK_API int jaylink_swo_start(struct jaylink_device_handle *devh,
577 enum jaylink_swo_mode mode, uint32_t baudrate, uint32_t size);
578 JAYLINK_API int jaylink_swo_stop(struct jaylink_device_handle *devh);
579 JAYLINK_API int jaylink_swo_read(struct jaylink_device_handle *devh,
580 uint8_t *buffer, uint32_t *length);
581 JAYLINK_API int jaylink_swo_get_speeds(struct jaylink_device_handle *devh,
582 enum jaylink_swo_mode mode, struct jaylink_swo_speed *speed);
584 /*--- target.c --------------------------------------------------------------*/
586 JAYLINK_API int jaylink_set_speed(struct jaylink_device_handle *devh,
587 uint16_t speed);
588 JAYLINK_API int jaylink_get_speeds(struct jaylink_device_handle *devh,
589 struct jaylink_speed *speed);
590 JAYLINK_API int jaylink_select_interface(struct jaylink_device_handle *devh,
591 enum jaylink_target_interface iface,
592 enum jaylink_target_interface *prev_iface);
593 JAYLINK_API int jaylink_get_available_interfaces(
594 struct jaylink_device_handle *devh, uint32_t *ifaces);
595 JAYLINK_API int jaylink_get_selected_interface(
596 struct jaylink_device_handle *devh,
597 enum jaylink_target_interface *iface);
598 JAYLINK_API int jaylink_clear_reset(struct jaylink_device_handle *devh);
599 JAYLINK_API int jaylink_set_reset(struct jaylink_device_handle *devh);
600 JAYLINK_API int jaylink_set_target_power(struct jaylink_device_handle *devh,
601 bool enable);
603 /*--- util.c ----------------------------------------------------------------*/
605 JAYLINK_API bool jaylink_has_cap(const uint8_t *caps, uint32_t cap);
607 /*--- version.c -------------------------------------------------------------*/
609 JAYLINK_API int jaylink_version_package_get_major(void);
610 JAYLINK_API int jaylink_version_package_get_minor(void);
611 JAYLINK_API int jaylink_version_package_get_micro(void);
612 JAYLINK_API const char *jaylink_version_package_get_string(void);
613 JAYLINK_API int jaylink_version_library_get_current(void);
614 JAYLINK_API int jaylink_version_library_get_revision(void);
615 JAYLINK_API int jaylink_version_library_get_age(void);
616 JAYLINK_API const char *jaylink_version_library_get_string(void);
618 #include "version.h"
620 #endif /* LIBJAYLINK_LIBJAYLINK_H */