libjaylink.h

Go to the documentation of this file.

// SPDX-License-Identifier: LGPL-2.1-or-later

#ifndef LIBJAYLINK_LIBJAYLINK_H
#define LIBJAYLINK_LIBJAYLINK_H

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <stdarg.h>
#ifdef _WIN32
#include <ws2tcpip.h>
#else
#include <arpa/inet.h>
#endif

#ifdef __cplusplus
extern "C" {
#endif

enum jaylink_error {
        JAYLINK_OK = 0,
        JAYLINK_ERR = -1,
        JAYLINK_ERR_ARG = -2,
        JAYLINK_ERR_MALLOC = -3,
        JAYLINK_ERR_TIMEOUT = -4,
        JAYLINK_ERR_PROTO = -5,
        JAYLINK_ERR_NOT_AVAILABLE = -6,
        JAYLINK_ERR_NOT_SUPPORTED = -7,
        JAYLINK_ERR_IO = -8,
        JAYLINK_ERR_DEV = -1000,
        JAYLINK_ERR_DEV_NOT_SUPPORTED = -1001,
        JAYLINK_ERR_DEV_NOT_AVAILABLE = -1002,
        JAYLINK_ERR_DEV_NO_MEMORY = -1003
};

enum jaylink_log_level {
        JAYLINK_LOG_LEVEL_NONE = 0,
        JAYLINK_LOG_LEVEL_ERROR = 1,
        JAYLINK_LOG_LEVEL_WARNING = 2,
        JAYLINK_LOG_LEVEL_INFO = 3,
        JAYLINK_LOG_LEVEL_DEBUG = 4,
        JAYLINK_LOG_LEVEL_DEBUG_IO = 5
};

#define JAYLINK_LOG_DOMAIN_DEFAULT      "jaylink: "

#define JAYLINK_LOG_DOMAIN_MAX_LENGTH   32

enum jaylink_capability {
        JAYLINK_CAP_HIF_USB = 0
};

enum jaylink_host_interface {
        JAYLINK_HIF_USB = (1 << 0),
        JAYLINK_HIF_TCP = (1 << 1)
};

enum jaylink_usb_address {
        JAYLINK_USB_ADDRESS_0 = 0,
        JAYLINK_USB_ADDRESS_1 = 1,
        JAYLINK_USB_ADDRESS_2 = 2,
        JAYLINK_USB_ADDRESS_3 = 3
};

enum jaylink_device_capability {
        JAYLINK_DEV_CAP_GET_HW_VERSION = 1,
        JAYLINK_DEV_CAP_ADAPTIVE_CLOCKING = 3,
        JAYLINK_DEV_CAP_READ_CONFIG = 4,
        JAYLINK_DEV_CAP_WRITE_CONFIG = 5,
        JAYLINK_DEV_CAP_GET_SPEEDS = 9,
        JAYLINK_DEV_CAP_GET_FREE_MEMORY = 11,
        JAYLINK_DEV_CAP_GET_HW_INFO = 12,
        JAYLINK_DEV_CAP_SET_TARGET_POWER = 13,
        JAYLINK_DEV_CAP_SELECT_TIF = 17,
        JAYLINK_DEV_CAP_GET_COUNTERS = 19,
        JAYLINK_DEV_CAP_SWO = 23,
        JAYLINK_DEV_CAP_FILE_IO = 26,
        JAYLINK_DEV_CAP_REGISTER = 27,
        JAYLINK_DEV_CAP_GET_EXT_CAPS = 31,
        JAYLINK_DEV_CAP_EMUCOM = 33,
        JAYLINK_DEV_CAP_ETHERNET = 38,
        JAYLINK_DEV_CAP_VCOM = 48,
        JAYLINK_DEV_CAP_SPI = 56,
};

enum jaylink_hardware_info {
        JAYLINK_HW_INFO_TARGET_POWER = (1 << 0),
        JAYLINK_HW_INFO_ITARGET = (1 << 2),
        JAYLINK_HW_INFO_ITARGET_PEAK = (1 << 3),
        JAYLINK_HW_INFO_IPV4_ADDRESS = (1 << 16),
        JAYLINK_HW_INFO_IPV4_NETMASK = (1 << 17),
        JAYLINK_HW_INFO_IPV4_GATEWAY = (1 << 18),
        JAYLINK_HW_INFO_IPV4_DNS = (1 << 19),
        JAYLINK_HW_INFO_VUSB = (1 << 23),
};

enum jaylink_counter {
        JAYLINK_COUNTER_TARGET_TIME = (1 << 0),
        JAYLINK_COUNTER_TARGET_CONNECTIONS = (1 << 1)
};

enum jaylink_hardware_type {
        JAYLINK_HW_TYPE_JLINK = 0,
        JAYLINK_HW_TYPE_FLASHER = 2,
        JAYLINK_HW_TYPE_JLINK_PRO = 3
};

enum jaylink_target_interface {
        JAYLINK_TIF_JTAG = 0,
        JAYLINK_TIF_SWD = 1,
        JAYLINK_TIF_BDM3 = 2,
        JAYLINK_TIF_FINE = 3,
        JAYLINK_TIF_2W_JTAG_PIC32 = 4,
        JAYLINK_TIF_SPI = 5,
        JAYLINK_TIF_C2 = 6,
        JAYLINK_TIF_CJTAG = 7,
};

enum jaylink_jtag_version {
        JAYLINK_JTAG_VERSION_2 = 1,
        JAYLINK_JTAG_VERSION_3 = 2
};

enum jaylink_swo_mode {
        JAYLINK_SWO_MODE_UART = 0
};

enum jaylink_spi_flag {
        JAYLINK_SPI_FLAG_CS_START_U = 0x00,
        JAYLINK_SPI_FLAG_CS_START_0 = 0x02,
        JAYLINK_SPI_FLAG_CS_START_1 = 0x03,
        JAYLINK_SPI_FLAG_CS_END_U = 0x00,
        JAYLINK_SPI_FLAG_CS_END_0 = 0x08,
        JAYLINK_SPI_FLAG_CS_END_1 = 0x0c,
};

struct jaylink_speed {
        uint32_t freq;
        uint16_t div;
};

struct jaylink_swo_speed {
        uint32_t freq;
        uint32_t min_div;
        uint32_t max_div;
        uint32_t min_prescaler;
        uint32_t max_prescaler;
};

struct jaylink_hardware_version {
        enum jaylink_hardware_type type;
        uint8_t major;
        uint8_t minor;
        uint8_t revision;
};

struct jaylink_hardware_status {
        uint16_t target_voltage;
        bool tck;
        bool tdi;
        bool tdo;
        bool tms;
        bool tres;
        bool trst;
};

struct jaylink_connection {
        uint16_t handle;
        uint32_t pid;
        char hid[INET_ADDRSTRLEN];
        uint8_t iid;
        uint8_t cid;
        uint32_t timestamp;
};

#define JAYLINK_SPEED_ADAPTIVE_CLOCKING         0xffff

#define JAYLINK_DEV_CONFIG_SIZE                 256

#define JAYLINK_DEV_CAPS_SIZE                   4

#define JAYLINK_DEV_EXT_CAPS_SIZE               32

#define JAYLINK_MAX_CONNECTIONS                 16

#define JAYLINK_MAC_ADDRESS_LENGTH              6

#define JAYLINK_NICKNAME_MAX_LENGTH             32

#define JAYLINK_PRODUCT_NAME_MAX_LENGTH         32

#define JAYLINK_FILE_NAME_MAX_LENGTH            255

#define JAYLINK_FILE_MAX_TRANSFER_SIZE          0x100000

#define JAYLINK_EMUCOM_CHANNEL_TIME     0x0

#define JAYLINK_EMUCOM_CHANNEL_USER     0x10000

#define JAYLINK_C2_MAX_LENGTH           64

struct jaylink_context;

struct jaylink_device;

struct jaylink_device_handle;

#if defined(_WIN32) || defined(__MSYS__) || defined(__CYGWIN__)
#define JAYLINK_API
#else
#define JAYLINK_API __attribute__ ((visibility ("default")))
#endif

typedef int (*jaylink_log_callback)(const struct jaylink_context *ctx,
                enum jaylink_log_level level, const char *format, va_list args,
                void *user_data);

/*--- core.c ----------------------------------------------------------------*/

JAYLINK_API int jaylink_init(struct jaylink_context **ctx);
JAYLINK_API int jaylink_exit(struct jaylink_context *ctx);
JAYLINK_API bool jaylink_library_has_cap(enum jaylink_capability cap);

/*--- c2.c ------------------------------------------------------------------*/

JAYLINK_API int jaylink_c2_read_address(struct jaylink_device_handle *devh,
                uint8_t *address);
JAYLINK_API int jaylink_c2_write_address(struct jaylink_device_handle *devh,
                uint8_t address);
JAYLINK_API int jaylink_c2_read_data(struct jaylink_device_handle *devh,
                uint8_t *data, uint8_t length);
JAYLINK_API int jaylink_c2_write_data(struct jaylink_device_handle *devh,
                const uint8_t *data, uint8_t length);

/*--- device.c --------------------------------------------------------------*/

JAYLINK_API int jaylink_get_devices(struct jaylink_context *ctx,
                struct jaylink_device ***devs, size_t *count);
JAYLINK_API void jaylink_free_devices(struct jaylink_device **devs,
                bool unref);
JAYLINK_API int jaylink_device_get_host_interface(
                const struct jaylink_device *dev,
                enum jaylink_host_interface *iface);
JAYLINK_API int jaylink_device_get_serial_number(
                const struct jaylink_device *dev, uint32_t *serial_number);
JAYLINK_API int jaylink_device_get_usb_address(
                const struct jaylink_device *dev,
                enum jaylink_usb_address *address);
JAYLINK_API int jaylink_device_get_usb_bus_ports(
                const struct jaylink_device *dev, uint8_t *bus,
                uint8_t **ports, size_t *length);
JAYLINK_API int jaylink_device_get_ipv4_address(
                const struct jaylink_device *dev, char *address);
JAYLINK_API int jaylink_device_get_mac_address(
                const struct jaylink_device *dev, uint8_t *address);
JAYLINK_API int jaylink_device_get_hardware_version(
                const struct jaylink_device *dev,
                struct jaylink_hardware_version *version);
JAYLINK_API int jaylink_device_get_product_name(
                const struct jaylink_device *dev, char *name);
JAYLINK_API int jaylink_device_get_nickname(const struct jaylink_device *dev,
                char *nickname);
JAYLINK_API struct jaylink_device *jaylink_ref_device(
                struct jaylink_device *dev);
JAYLINK_API void jaylink_unref_device(struct jaylink_device *dev);
JAYLINK_API int jaylink_open(struct jaylink_device *dev,
                struct jaylink_device_handle **devh);
JAYLINK_API int jaylink_close(struct jaylink_device_handle *devh);
JAYLINK_API struct jaylink_device *jaylink_get_device(
                struct jaylink_device_handle *devh);
JAYLINK_API int jaylink_get_firmware_version(
                struct jaylink_device_handle *devh, char **version,
                size_t *length);
JAYLINK_API int jaylink_get_hardware_info(struct jaylink_device_handle *devh,
                uint32_t mask, uint32_t *info);
JAYLINK_API int jaylink_get_counters(struct jaylink_device_handle *devh,
                uint32_t mask, uint32_t *values);
JAYLINK_API int jaylink_get_hardware_version(
                struct jaylink_device_handle *devh,
                struct jaylink_hardware_version *version);
JAYLINK_API int jaylink_get_hardware_status(struct jaylink_device_handle *devh,
                struct jaylink_hardware_status *status);
JAYLINK_API int jaylink_get_caps(struct jaylink_device_handle *devh,
                uint8_t *caps);
JAYLINK_API int jaylink_get_extended_caps(struct jaylink_device_handle *devh,
                uint8_t *caps);
JAYLINK_API int jaylink_get_free_memory(struct jaylink_device_handle *devh,
                uint32_t *size);
JAYLINK_API int jaylink_read_raw_config(struct jaylink_device_handle *devh,
                uint8_t *config);
JAYLINK_API int jaylink_write_raw_config(struct jaylink_device_handle *devh,
                const uint8_t *config);
JAYLINK_API int jaylink_register(struct jaylink_device_handle *devh,
                struct jaylink_connection *connection,
                struct jaylink_connection *connections, size_t *count);
JAYLINK_API int jaylink_unregister(struct jaylink_device_handle *devh,
                const struct jaylink_connection *connection,
                struct jaylink_connection *connections, size_t *count);

/*--- discovery.c -----------------------------------------------------------*/

JAYLINK_API int jaylink_discovery_scan(struct jaylink_context *ctx,
                uint32_t ifaces);

/*--- emucom.c --------------------------------------------------------------*/

JAYLINK_API int jaylink_emucom_read(struct jaylink_device_handle *devh,
                uint32_t channel, uint8_t *buffer, uint32_t *length);
JAYLINK_API int jaylink_emucom_write(struct jaylink_device_handle *devh,
                uint32_t channel, const uint8_t *buffer, uint32_t *length);

/*--- error.c ---------------------------------------------------------------*/

JAYLINK_API const char *jaylink_strerror(int error_code);
JAYLINK_API const char *jaylink_strerror_name(int error_code);

/*--- fileio.c --------------------------------------------------------------*/

JAYLINK_API int jaylink_file_read(struct jaylink_device_handle *devh,
                const char *filename, uint8_t *buffer, uint32_t offset,
                uint32_t *length);
JAYLINK_API int jaylink_file_write(struct jaylink_device_handle *devh,
                const char *filename, const uint8_t *buffer, uint32_t offset,
                uint32_t *length);
JAYLINK_API int jaylink_file_get_size(struct jaylink_device_handle *devh,
                const char *filename, uint32_t *size);
JAYLINK_API int jaylink_file_delete(struct jaylink_device_handle *devh,
                const char *filename);

/*--- jtag.c ----------------------------------------------------------------*/

JAYLINK_API int jaylink_jtag_io(struct jaylink_device_handle *devh,
                const uint8_t *tms, const uint8_t *tdi, uint8_t *tdo,
                uint16_t length, enum jaylink_jtag_version version);
JAYLINK_API int jaylink_jtag_clear_trst(struct jaylink_device_handle *devh);
JAYLINK_API int jaylink_jtag_set_trst(struct jaylink_device_handle *devh);
JAYLINK_API int jaylink_jtag_clear_tms(struct jaylink_device_handle *devh);
JAYLINK_API int jaylink_jtag_set_tms(struct jaylink_device_handle *devh);
JAYLINK_API int jaylink_jtag_clear_tck(struct jaylink_device_handle *devh);
JAYLINK_API int jaylink_jtag_set_tck(struct jaylink_device_handle *devh);

/*--- log.c -----------------------------------------------------------------*/

JAYLINK_API int jaylink_log_set_level(struct jaylink_context *ctx,
                enum jaylink_log_level level);
JAYLINK_API int jaylink_log_get_level(const struct jaylink_context *ctx,
                enum jaylink_log_level *level);
JAYLINK_API int jaylink_log_set_callback(struct jaylink_context *ctx,
                jaylink_log_callback callback, void *user_data);
JAYLINK_API int jaylink_log_set_domain(struct jaylink_context *ctx,
                const char *domain);
JAYLINK_API const char *jaylink_log_get_domain(
                const struct jaylink_context *ctx);

/*--- spi.c -----------------------------------------------------------------*/

JAYLINK_API int jaylink_spi_io(struct jaylink_device_handle *devh,
                const uint8_t *mosi, uint8_t *miso, uint32_t length,
                uint32_t flags);

/*--- strutil.c -------------------------------------------------------------*/

JAYLINK_API int jaylink_parse_serial_number(const char *str,
                uint32_t *serial_number);
JAYLINK_API const char *jaylink_hardware_type_string(
                enum jaylink_hardware_type type);
JAYLINK_API const char *jaylink_target_interface_string(
                enum jaylink_target_interface iface);

/*--- swd.c -----------------------------------------------------------------*/

JAYLINK_API int jaylink_swd_io(struct jaylink_device_handle *devh,
                const uint8_t *direction, const uint8_t *out, uint8_t *in,
                uint16_t length);

/*--- swo.c -----------------------------------------------------------------*/

JAYLINK_API int jaylink_swo_start(struct jaylink_device_handle *devh,
                enum jaylink_swo_mode mode, uint32_t baudrate, uint32_t size);
JAYLINK_API int jaylink_swo_stop(struct jaylink_device_handle *devh);
JAYLINK_API int jaylink_swo_read(struct jaylink_device_handle *devh,
                uint8_t *buffer, uint32_t *length);
JAYLINK_API int jaylink_swo_get_speeds(struct jaylink_device_handle *devh,
                enum jaylink_swo_mode mode, struct jaylink_swo_speed *speed);

/*--- target.c --------------------------------------------------------------*/

JAYLINK_API int jaylink_set_speed(struct jaylink_device_handle *devh,
                uint16_t speed);
JAYLINK_API int jaylink_get_speeds(struct jaylink_device_handle *devh,
                struct jaylink_speed *speed);
JAYLINK_API int jaylink_select_interface(struct jaylink_device_handle *devh,
                enum jaylink_target_interface iface,
                enum jaylink_target_interface *prev_iface);
JAYLINK_API int jaylink_get_available_interfaces(
                struct jaylink_device_handle *devh, uint32_t *ifaces);
JAYLINK_API int jaylink_get_selected_interface(
                struct jaylink_device_handle *devh,
                enum jaylink_target_interface *iface);
JAYLINK_API int jaylink_clear_reset(struct jaylink_device_handle *devh);
JAYLINK_API int jaylink_set_reset(struct jaylink_device_handle *devh);
JAYLINK_API int jaylink_set_target_power(struct jaylink_device_handle *devh,
                bool enable);

/*--- util.c ----------------------------------------------------------------*/

JAYLINK_API bool jaylink_has_cap(const uint8_t *caps, uint32_t cap);

/*--- version.c -------------------------------------------------------------*/

JAYLINK_API int jaylink_version_package_get_major(void);
JAYLINK_API int jaylink_version_package_get_minor(void);
JAYLINK_API int jaylink_version_package_get_micro(void);
JAYLINK_API const char *jaylink_version_package_get_string(void);
JAYLINK_API int jaylink_version_library_get_current(void);
JAYLINK_API int jaylink_version_library_get_revision(void);
JAYLINK_API int jaylink_version_library_get_age(void);
JAYLINK_API const char *jaylink_version_library_get_string(void);

#ifdef __cplusplus
}
#endif

#include "version.h"

#endif /* LIBJAYLINK_LIBJAYLINK_H */