libjaylink/target.c

   1 /*
   2  * This file is part of the libjaylink project.
   3  *
   4  * Copyright (C) 2014-2015 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 2 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 #include <stdint.h>
  21 #include <stdbool.h>
  22
  23 #include "libjaylink.h"
  24 #include "libjaylink-internal.h"
  25
  26 /**
  27  * @file
  28  *
  29  * Target related functions.
  30  */
  31
  32 /** @cond PRIVATE */
  33 #define CMD_SET_SPEED           0x05
  34 #define CMD_SET_TARGET_POWER    0x08
  35 #define CMD_GET_SPEEDS          0xc0
  36 #define CMD_SELECT_TIF          0xc7
  37 #define CMD_CLEAR_RESET         0xdc
  38 #define CMD_SET_RESET           0xdd
  39
  40 #define TIF_GET_SELECTED        0xfe
  41 #define TIF_GET_AVAILABLE       0xff
  42 /** @endcond */
  43
  44 /**
  45  * Set the target interface speed.
  46  *
  47  * @param[in,out] devh Device handle.
  48  * @param[in] speed Speed in kHz or #JAYLINK_SPEED_ADAPTIVE_CLOCKING for
  49  *                  adaptive clocking. Speed of 0 kHz is not allowed and
  50  *                  adaptive clocking must only be used if the device has the
  51  *                  #JAYLINK_DEV_CAP_ADAPTIVE_CLOCKING capability.
  52  *
  53  * @retval JAYLINK_OK Success.
  54  * @retval JAYLINK_ERR_ARG Invalid arguments.
  55  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
  56  * @retval JAYLINK_ERR_IO Input/output error.
  57  * @retval JAYLINK_ERR Other error conditions.
  58  *
  59  * @see jaylink_get_speeds()
  60  *
  61  * @since 0.1.0
  62  */
  63 JAYLINK_API int jaylink_set_speed(struct jaylink_device_handle *devh,
  64                 uint16_t speed)
  65 {
  66         int ret;
  67         struct jaylink_context *ctx;
  68         uint8_t buf[3];
  69
  70         if (!devh || !speed)
  71                 return JAYLINK_ERR_ARG;
  72
  73         ctx = devh->dev->ctx;
  74         ret = transport_start_write(devh, 3, true);
  75
  76         if (ret != JAYLINK_OK) {
  77                 log_err(ctx, "transport_start_write() failed: %s",
  78                         jaylink_strerror(ret));
  79                 return ret;
  80         }
  81
  82         buf[0] = CMD_SET_SPEED;
  83         buffer_set_u16(buf, speed, 1);
  84
  85         ret = transport_write(devh, buf, 3);
  86
  87         if (ret != JAYLINK_OK) {
  88                 log_err(ctx, "transport_write() failed: %s",
  89                         jaylink_strerror(ret));
  90                 return ret;
  91         }
  92
  93         return JAYLINK_OK;
  94 }
  95
  96 /**
  97  * Retrieve target interface speeds.
  98  *
  99  * The speeds are applicable for the currently selected target interface only
 100  * and calculated as follows:
 101  *
 102  * @par
 103  * <tt>speeds = @a freq / n</tt> with <tt>n >= @a div</tt>, where @p n is an
 104  * integer
 105  *
 106  * Assuming, for example, a base frequency @a freq of 4 MHz and a minimum
 107  * divider @a div of 4 then the highest possible target interface speed is
 108  * 4 MHz / 4 = 1 MHz. The next highest speed is 800 kHz for a divider of 5, and
 109  * so on.
 110  *
 111  * @note This function must only be used if the device has the
 112  *       #JAYLINK_DEV_CAP_GET_SPEEDS capability.
 113  *
 114  * @param[in,out] devh Device handle.
 115  * @param[out] speed Speed information on success, and undefined on failure.
 116  *
 117  * @retval JAYLINK_OK Success.
 118  * @retval JAYLINK_ERR_ARG Invalid arguments.
 119  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 120  * @retval JAYLINK_ERR_PROTO Protocol violation.
 121  * @retval JAYLINK_ERR_IO Input/output error.
 122  * @retval JAYLINK_ERR Other error conditions.
 123  *
 124  * @see jaylink_select_interface()
 125  *
 126  * @since 0.1.0
 127  */
 128 JAYLINK_API int jaylink_get_speeds(struct jaylink_device_handle *devh,
 129                 struct jaylink_speed *speed)
 130 {
 131         int ret;
 132         struct jaylink_context *ctx;
 133         uint8_t buf[6];
 134         uint16_t div;
 135
 136         if (!devh || !speed)
 137                 return JAYLINK_ERR_ARG;
 138
 139         ctx = devh->dev->ctx;
 140         ret = transport_start_write_read(devh, 1, 6, true);
 141
 142         if (ret != JAYLINK_OK) {
 143                 log_err(ctx, "transport_start_write_read() failed: %s",
 144                         jaylink_strerror(ret));
 145                 return ret;
 146         }
 147
 148         buf[0] = CMD_GET_SPEEDS;
 149
 150         ret = transport_write(devh, buf, 1);
 151
 152         if (ret != JAYLINK_OK) {
 153                 log_err(ctx, "transport_write() failed: %s",
 154                         jaylink_strerror(ret));
 155                 return ret;
 156         }
 157
 158         ret = transport_read(devh, buf, 6);
 159
 160         if (ret != JAYLINK_OK) {
 161                 log_err(ctx, "transport_read() failed: %s",
 162                         jaylink_strerror(ret));
 163                 return ret;
 164         }
 165
 166         div = buffer_get_u16(buf, 4);
 167
 168         if (!div) {
 169                 log_err(ctx, "Minimum frequency divider is zero");
 170                 return JAYLINK_ERR_PROTO;
 171         }
 172
 173         speed->freq = buffer_get_u32(buf, 0);
 174         speed->div = div;
 175
 176         return JAYLINK_OK;
 177 }
 178
 179 /**
 180  * Select the target interface.
 181  *
 182  * @note This function must only be used if the device has the
 183  *       #JAYLINK_DEV_CAP_SELECT_TIF capability.
 184  *
 185  * @warning This function may return a value for @p prev_iface which is not
 186  *          covered by #jaylink_target_interface.
 187  *
 188  * @param[in,out] devh Device handle.
 189  * @param[in] iface Target interface to select.
 190  * @param[out] prev_iface Previously selected target interface on success, and
 191  *                        undefined on failure. Can be NULL.
 192  *
 193  * @retval JAYLINK_OK Success.
 194  * @retval JAYLINK_ERR_ARG Invalid arguments.
 195  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 196  * @retval JAYLINK_ERR_IO Input/output error.
 197  * @retval JAYLINK_ERR Other error conditions.
 198  *
 199  * @see jaylink_get_available_interfaces()
 200  *
 201  * @since 0.1.0
 202  */
 203 JAYLINK_API int jaylink_select_interface(struct jaylink_device_handle *devh,
 204                 enum jaylink_target_interface iface,
 205                 enum jaylink_target_interface *prev_iface)
 206 {
 207         int ret;
 208         struct jaylink_context *ctx;
 209         uint8_t buf[4];
 210
 211         if (!devh)
 212                 return JAYLINK_ERR_ARG;
 213
 214         switch (iface) {
 215         case JAYLINK_TIF_JTAG:
 216         case JAYLINK_TIF_SWD:
 217         case JAYLINK_TIF_BDM3:
 218         case JAYLINK_TIF_FINE:
 219         case JAYLINK_TIF_2W_JTAG_PIC32:
 220         case JAYLINK_TIF_CJTAG:
 221                 break;
 222         default:
 223                 return JAYLINK_ERR_ARG;
 224         }
 225
 226         ctx = devh->dev->ctx;
 227         ret = transport_start_write_read(devh, 2, 4, true);
 228
 229         if (ret != JAYLINK_OK) {
 230                 log_err(ctx, "transport_start_write_read() failed: %s",
 231                         jaylink_strerror(ret));
 232                 return ret;
 233         }
 234
 235         buf[0] = CMD_SELECT_TIF;
 236         buf[1] = iface;
 237
 238         ret = transport_write(devh, buf, 2);
 239
 240         if (ret != JAYLINK_OK) {
 241                 log_err(ctx, "transport_write() failed: %s",
 242                         jaylink_strerror(ret));
 243                 return ret;
 244         }
 245
 246         ret = transport_read(devh, buf, 4);
 247
 248         if (ret != JAYLINK_OK) {
 249                 log_err(ctx, "transport_read() failed: %s",
 250                         jaylink_strerror(ret));
 251                 return ret;
 252         }
 253
 254         if (prev_iface)
 255                 *prev_iface = buffer_get_u32(buf, 0);
 256
 257         return JAYLINK_OK;
 258 }
 259
 260 /**
 261  * Retrieve the available target interfaces.
 262  *
 263  * The target interfaces are stored in a 32-bit bit field where each individual
 264  * bit represents a target interface. A set bit indicates an available target
 265  * interface. See #jaylink_target_interface for a description of the target
 266  * interfaces and their bit positions.
 267  *
 268  * @note This function must only be used if the device has the
 269  *       #JAYLINK_DEV_CAP_SELECT_TIF capability.
 270  *
 271  * @param[in,out] devh Device handle.
 272  * @param[out] ifaces Target interfaces on success, and undefined on failure.
 273  *
 274  * @retval JAYLINK_OK Success.
 275  * @retval JAYLINK_ERR_ARG Invalid arguments.
 276  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 277  * @retval JAYLINK_ERR_IO Input/output error.
 278  * @retval JAYLINK_ERR Other error conditions.
 279  *
 280  * @see jaylink_select_interface()
 281  *
 282  * @since 0.1.0
 283  */
 284 JAYLINK_API int jaylink_get_available_interfaces(
 285                 struct jaylink_device_handle *devh, uint32_t *ifaces)
 286 {
 287         int ret;
 288         struct jaylink_context *ctx;
 289         uint8_t buf[4];
 290
 291         if (!devh || !ifaces)
 292                 return JAYLINK_ERR_ARG;
 293
 294         ctx = devh->dev->ctx;
 295         ret = transport_start_write_read(devh, 2, 4, true);
 296
 297         if (ret != JAYLINK_OK) {
 298                 log_err(ctx, "transport_start_write_read() failed: %s",
 299                         jaylink_strerror(ret));
 300                 return ret;
 301         }
 302
 303         buf[0] = CMD_SELECT_TIF;
 304         buf[1] = TIF_GET_AVAILABLE;
 305
 306         ret = transport_write(devh, buf, 2);
 307
 308         if (ret != JAYLINK_OK) {
 309                 log_err(ctx, "transport_write() failed: %s",
 310                         jaylink_strerror(ret));
 311                 return ret;
 312         }
 313
 314         ret = transport_read(devh, buf, 4);
 315
 316         if (ret != JAYLINK_OK) {
 317                 log_err(ctx, "transport_read() failed: %s",
 318                         jaylink_strerror(ret));
 319                 return ret;
 320         }
 321
 322         *ifaces = buffer_get_u32(buf, 0);
 323
 324         return JAYLINK_OK;
 325 }
 326
 327 /**
 328  * Retrieve the selected target interface.
 329  *
 330  * @note This function must only be used if the device has the
 331  *       #JAYLINK_DEV_CAP_SELECT_TIF capability.
 332  *
 333  * @warning This function may return a value for @p iface which is not covered
 334  *          by #jaylink_target_interface.
 335  *
 336  * @param[in,out] devh Device handle.
 337  * @param[out] iface Selected target interface on success, and undefined on
 338  *                   failure.
 339  *
 340  * @retval JAYLINK_OK Success.
 341  * @retval JAYLINK_ERR_ARG Invalid arguments.
 342  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 343  * @retval JAYLINK_ERR_IO Input/output error.
 344  * @retval JAYLINK_ERR Other error conditions.
 345  *
 346  * @see jaylink_select_interface()
 347  *
 348  * @since 0.1.0
 349  */
 350 JAYLINK_API int jaylink_get_selected_interface(
 351                 struct jaylink_device_handle *devh,
 352                 enum jaylink_target_interface *iface)
 353 {
 354         int ret;
 355         struct jaylink_context *ctx;
 356         uint8_t buf[4];
 357
 358         if (!devh || !iface)
 359                 return JAYLINK_ERR_ARG;
 360
 361         ctx = devh->dev->ctx;
 362         ret = transport_start_write_read(devh, 2, 4, true);
 363
 364         if (ret != JAYLINK_OK) {
 365                 log_err(ctx, "transport_start_write_read() failed: %s",
 366                         jaylink_strerror(ret));
 367                 return ret;
 368         }
 369
 370         buf[0] = CMD_SELECT_TIF;
 371         buf[1] = TIF_GET_SELECTED;
 372
 373         ret = transport_write(devh, buf, 2);
 374
 375         if (ret != JAYLINK_OK) {
 376                 log_err(ctx, "transport_write() failed: %s",
 377                         jaylink_strerror(ret));
 378                 return ret;
 379         }
 380
 381         ret = transport_read(devh, buf, 4);
 382
 383         if (ret != JAYLINK_OK) {
 384                 log_err(ctx, "transport_read() failed: %s",
 385                         jaylink_strerror(ret));
 386                 return ret;
 387         }
 388
 389         *iface = buffer_get_u32(buf, 0);
 390
 391         return JAYLINK_OK;
 392 }
 393
 394 /**
 395  * Clear the target reset signal.
 396  *
 397  * @param[in,out] devh Device handle.
 398  *
 399  * @retval JAYLINK_OK Success.
 400  * @retval JAYLINK_ERR_ARG Invalid arguments.
 401  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 402  * @retval JAYLINK_ERR_IO Input/output error.
 403  * @retval JAYLINK_ERR Other error conditions.
 404  *
 405  * @since 0.1.0
 406  */
 407 JAYLINK_API int jaylink_clear_reset(struct jaylink_device_handle *devh)
 408 {
 409         int ret;
 410         struct jaylink_context *ctx;
 411         uint8_t buf[1];
 412
 413         if (!devh)
 414                 return JAYLINK_ERR_ARG;
 415
 416         ctx = devh->dev->ctx;
 417         ret = transport_start_write(devh, 1, true);
 418
 419         if (ret != JAYLINK_OK) {
 420                 log_err(ctx, "transport_start_write() failed: %s",
 421                         jaylink_strerror(ret));
 422                 return ret;
 423         }
 424
 425         buf[0] = CMD_CLEAR_RESET;
 426
 427         ret = transport_write(devh, buf, 1);
 428
 429         if (ret != JAYLINK_OK) {
 430                 log_err(ctx, "transport_write() failed: %s",
 431                         jaylink_strerror(ret));
 432                 return ret;
 433         }
 434
 435         return JAYLINK_OK;
 436 }
 437
 438 /**
 439  * Set the target reset signal.
 440  *
 441  * @param[in,out] devh Device handle.
 442  *
 443  * @retval JAYLINK_OK Success.
 444  * @retval JAYLINK_ERR_ARG Invalid arguments.
 445  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 446  * @retval JAYLINK_ERR_IO Input/output error.
 447  * @retval JAYLINK_ERR Other error conditions.
 448  *
 449  * @since 0.1.0
 450  */
 451 JAYLINK_API int jaylink_set_reset(struct jaylink_device_handle *devh)
 452 {
 453         int ret;
 454         struct jaylink_context *ctx;
 455         uint8_t buf[1];
 456
 457         if (!devh)
 458                 return JAYLINK_ERR_ARG;
 459
 460         ctx = devh->dev->ctx;
 461         ret = transport_start_write(devh, 1, true);
 462
 463         if (ret != JAYLINK_OK) {
 464                 log_err(ctx, "transport_start_write() failed: %s",
 465                         jaylink_strerror(ret));
 466                 return ret;
 467         }
 468
 469         buf[0] = CMD_SET_RESET;
 470
 471         ret = transport_write(devh, buf, 1);
 472
 473         if (ret != JAYLINK_OK) {
 474                 log_err(ctx, "transport_write() failed: %s",
 475                         jaylink_strerror(ret));
 476                 return ret;
 477         }
 478
 479         return JAYLINK_OK;
 480 }
 481
 482 /**
 483  * Set the target power supply.
 484  *
 485  * If enabled, the target is supplied with 5 V from pin 19 of the 20-pin
 486  * JTAG / SWD connector.
 487  *
 488  * @note This function must only be used if the device has the
 489  *       #JAYLINK_DEV_CAP_SET_TARGET_POWER capability.
 490  *
 491  * @param[in,out] devh Device handle.
 492  * @param[in] enable Determines whether to enable or disable the target power
 493  *                   supply.
 494  *
 495  * @retval JAYLINK_OK Success.
 496  * @retval JAYLINK_ERR_ARG Invalid arguments.
 497  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 498  * @retval JAYLINK_ERR_IO Input/output error.
 499  * @retval JAYLINK_ERR Other error conditions.
 500  *
 501  * @since 0.1.0
 502  */
 503 JAYLINK_API int jaylink_set_target_power(struct jaylink_device_handle *devh,
 504                 bool enable)
 505 {
 506         int ret;
 507         struct jaylink_context *ctx;
 508         uint8_t buf[2];
 509
 510         if (!devh)
 511                 return JAYLINK_ERR_ARG;
 512
 513         ctx = devh->dev->ctx;
 514         ret = transport_start_write(devh, 2, true);
 515
 516         if (ret != JAYLINK_OK) {
 517                 log_err(ctx, "transport_start_wrte() failed: %s",
 518                         jaylink_strerror(ret));
 519                 return ret;
 520         }
 521
 522         buf[0] = CMD_SET_TARGET_POWER;
 523         buf[1] = enable;
 524
 525         ret = transport_write(devh, buf, 2);
 526
 527         if (ret != JAYLINK_OK) {
 528                 log_err(ctx, "transport_write() failed: %s",
 529                         jaylink_strerror(ret));
 530                 return ret;
 531         }
 532
 533         return JAYLINK_OK;
 534 }