libjaylink.h

Go to the documentation of this file.

/*
 * This file is part of the libjaylink project.
 *
 * Copyright (C) 2014-2016 Marc Schink <jaylink-dev@marcschink.de>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#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
};

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)
};

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,
};

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

enum jaylink_swo_mode {
    JAYLINK_SWO_MODE_UART = 0
};

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

struct jaylink_context;

struct jaylink_device;

struct jaylink_device_handle;

#ifdef _WIN32
#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);

/*--- 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);

/*--- 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);

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

JAYLINK_API int jaylink_parse_serial_number(const char *str,
        uint32_t *serial_number);

/*--- 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 */