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_SPI:
 221         case JAYLINK_TIF_C2:
 222         case JAYLINK_TIF_CJTAG:
 223                 break;
 224         default:
 225                 return JAYLINK_ERR_ARG;
 226         }
 227
 228         ctx = devh->dev->ctx;
 229         ret = transport_start_write_read(devh, 2, 4, true);
 230
 231         if (ret != JAYLINK_OK) {
 232                 log_err(ctx, "transport_start_write_read() failed: %s",
 233                         jaylink_strerror(ret));
 234                 return ret;
 235         }
 236
 237         buf[0] = CMD_SELECT_TIF;
 238         buf[1] = iface;
 239
 240         ret = transport_write(devh, buf, 2);
 241
 242         if (ret != JAYLINK_OK) {
 243                 log_err(ctx, "transport_write() failed: %s",
 244                         jaylink_strerror(ret));
 245                 return ret;
 246         }
 247
 248         ret = transport_read(devh, buf, 4);
 249
 250         if (ret != JAYLINK_OK) {
 251                 log_err(ctx, "transport_read() failed: %s",
 252                         jaylink_strerror(ret));
 253                 return ret;
 254         }
 255
 256         if (prev_iface)
 257                 *prev_iface = buffer_get_u32(buf, 0);
 258
 259         return JAYLINK_OK;
 260 }
 261
 262 /**
 263  * Retrieve the available target interfaces.
 264  *
 265  * The target interfaces are stored in a 32-bit bit field where each individual
 266  * bit represents a target interface. A set bit indicates an available target
 267  * interface. See #jaylink_target_interface for a description of the target
 268  * interfaces and their bit positions.
 269  *
 270  * @note This function must only be used if the device has the
 271  *       #JAYLINK_DEV_CAP_SELECT_TIF capability.
 272  *
 273  * @param[in,out] devh Device handle.
 274  * @param[out] ifaces Target interfaces on success, and undefined on failure.
 275  *
 276  * @retval JAYLINK_OK Success.
 277  * @retval JAYLINK_ERR_ARG Invalid arguments.
 278  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 279  * @retval JAYLINK_ERR_IO Input/output error.
 280  * @retval JAYLINK_ERR Other error conditions.
 281  *
 282  * @see jaylink_select_interface()
 283  *
 284  * @since 0.1.0
 285  */
 286 JAYLINK_API int jaylink_get_available_interfaces(
 287                 struct jaylink_device_handle *devh, uint32_t *ifaces)
 288 {
 289         int ret;
 290         struct jaylink_context *ctx;
 291         uint8_t buf[4];
 292
 293         if (!devh || !ifaces)
 294                 return JAYLINK_ERR_ARG;
 295
 296         ctx = devh->dev->ctx;
 297         ret = transport_start_write_read(devh, 2, 4, true);
 298
 299         if (ret != JAYLINK_OK) {
 300                 log_err(ctx, "transport_start_write_read() failed: %s",
 301                         jaylink_strerror(ret));
 302                 return ret;
 303         }
 304
 305         buf[0] = CMD_SELECT_TIF;
 306         buf[1] = TIF_GET_AVAILABLE;
 307
 308         ret = transport_write(devh, buf, 2);
 309
 310         if (ret != JAYLINK_OK) {
 311                 log_err(ctx, "transport_write() failed: %s",
 312                         jaylink_strerror(ret));
 313                 return ret;
 314         }
 315
 316         ret = transport_read(devh, buf, 4);
 317
 318         if (ret != JAYLINK_OK) {
 319                 log_err(ctx, "transport_read() failed: %s",
 320                         jaylink_strerror(ret));
 321                 return ret;
 322         }
 323
 324         *ifaces = buffer_get_u32(buf, 0);
 325
 326         return JAYLINK_OK;
 327 }
 328
 329 /**
 330  * Retrieve the selected target interface.
 331  *
 332  * @note This function must only be used if the device has the
 333  *       #JAYLINK_DEV_CAP_SELECT_TIF capability.
 334  *
 335  * @warning This function may return a value for @p iface which is not covered
 336  *          by #jaylink_target_interface.
 337  *
 338  * @param[in,out] devh Device handle.
 339  * @param[out] iface Selected target interface on success, and undefined on
 340  *                   failure.
 341  *
 342  * @retval JAYLINK_OK Success.
 343  * @retval JAYLINK_ERR_ARG Invalid arguments.
 344  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 345  * @retval JAYLINK_ERR_IO Input/output error.
 346  * @retval JAYLINK_ERR Other error conditions.
 347  *
 348  * @see jaylink_select_interface()
 349  *
 350  * @since 0.1.0
 351  */
 352 JAYLINK_API int jaylink_get_selected_interface(
 353                 struct jaylink_device_handle *devh,
 354                 enum jaylink_target_interface *iface)
 355 {
 356         int ret;
 357         struct jaylink_context *ctx;
 358         uint8_t buf[4];
 359
 360         if (!devh || !iface)
 361                 return JAYLINK_ERR_ARG;
 362
 363         ctx = devh->dev->ctx;
 364         ret = transport_start_write_read(devh, 2, 4, true);
 365
 366         if (ret != JAYLINK_OK) {
 367                 log_err(ctx, "transport_start_write_read() failed: %s",
 368                         jaylink_strerror(ret));
 369                 return ret;
 370         }
 371
 372         buf[0] = CMD_SELECT_TIF;
 373         buf[1] = TIF_GET_SELECTED;
 374
 375         ret = transport_write(devh, buf, 2);
 376
 377         if (ret != JAYLINK_OK) {
 378                 log_err(ctx, "transport_write() failed: %s",
 379                         jaylink_strerror(ret));
 380                 return ret;
 381         }
 382
 383         ret = transport_read(devh, buf, 4);
 384
 385         if (ret != JAYLINK_OK) {
 386                 log_err(ctx, "transport_read() failed: %s",
 387                         jaylink_strerror(ret));
 388                 return ret;
 389         }
 390
 391         *iface = buffer_get_u32(buf, 0);
 392
 393         return JAYLINK_OK;
 394 }
 395
 396 /**
 397  * Clear the target reset signal.
 398  *
 399  * @param[in,out] devh Device handle.
 400  *
 401  * @retval JAYLINK_OK Success.
 402  * @retval JAYLINK_ERR_ARG Invalid arguments.
 403  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 404  * @retval JAYLINK_ERR_IO Input/output error.
 405  * @retval JAYLINK_ERR Other error conditions.
 406  *
 407  * @since 0.1.0
 408  */
 409 JAYLINK_API int jaylink_clear_reset(struct jaylink_device_handle *devh)
 410 {
 411         int ret;
 412         struct jaylink_context *ctx;
 413         uint8_t buf[1];
 414
 415         if (!devh)
 416                 return JAYLINK_ERR_ARG;
 417
 418         ctx = devh->dev->ctx;
 419         ret = transport_start_write(devh, 1, true);
 420
 421         if (ret != JAYLINK_OK) {
 422                 log_err(ctx, "transport_start_write() failed: %s",
 423                         jaylink_strerror(ret));
 424                 return ret;
 425         }
 426
 427         buf[0] = CMD_CLEAR_RESET;
 428
 429         ret = transport_write(devh, buf, 1);
 430
 431         if (ret != JAYLINK_OK) {
 432                 log_err(ctx, "transport_write() failed: %s",
 433                         jaylink_strerror(ret));
 434                 return ret;
 435         }
 436
 437         return JAYLINK_OK;
 438 }
 439
 440 /**
 441  * Set the target reset signal.
 442  *
 443  * @param[in,out] devh Device handle.
 444  *
 445  * @retval JAYLINK_OK Success.
 446  * @retval JAYLINK_ERR_ARG Invalid arguments.
 447  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 448  * @retval JAYLINK_ERR_IO Input/output error.
 449  * @retval JAYLINK_ERR Other error conditions.
 450  *
 451  * @since 0.1.0
 452  */
 453 JAYLINK_API int jaylink_set_reset(struct jaylink_device_handle *devh)
 454 {
 455         int ret;
 456         struct jaylink_context *ctx;
 457         uint8_t buf[1];
 458
 459         if (!devh)
 460                 return JAYLINK_ERR_ARG;
 461
 462         ctx = devh->dev->ctx;
 463         ret = transport_start_write(devh, 1, true);
 464
 465         if (ret != JAYLINK_OK) {
 466                 log_err(ctx, "transport_start_write() failed: %s",
 467                         jaylink_strerror(ret));
 468                 return ret;
 469         }
 470
 471         buf[0] = CMD_SET_RESET;
 472
 473         ret = transport_write(devh, buf, 1);
 474
 475         if (ret != JAYLINK_OK) {
 476                 log_err(ctx, "transport_write() failed: %s",
 477                         jaylink_strerror(ret));
 478                 return ret;
 479         }
 480
 481         return JAYLINK_OK;
 482 }
 483
 484 /**
 485  * Set the target power supply.
 486  *
 487  * If enabled, the target is supplied with 5 V from pin 19 of the 20-pin
 488  * JTAG / SWD connector.
 489  *
 490  * @note This function must only be used if the device has the
 491  *       #JAYLINK_DEV_CAP_SET_TARGET_POWER capability.
 492  *
 493  * @param[in,out] devh Device handle.
 494  * @param[in] enable Determines whether to enable or disable the target power
 495  *                   supply.
 496  *
 497  * @retval JAYLINK_OK Success.
 498  * @retval JAYLINK_ERR_ARG Invalid arguments.
 499  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 500  * @retval JAYLINK_ERR_IO Input/output error.
 501  * @retval JAYLINK_ERR Other error conditions.
 502  *
 503  * @since 0.1.0
 504  */
 505 JAYLINK_API int jaylink_set_target_power(struct jaylink_device_handle *devh,
 506                 bool enable)
 507 {
 508         int ret;
 509         struct jaylink_context *ctx;
 510         uint8_t buf[2];
 511
 512         if (!devh)
 513                 return JAYLINK_ERR_ARG;
 514
 515         ctx = devh->dev->ctx;
 516         ret = transport_start_write(devh, 2, true);
 517
 518         if (ret != JAYLINK_OK) {
 519                 log_err(ctx, "transport_start_wrte() failed: %s",
 520                         jaylink_strerror(ret));
 521                 return ret;
 522         }
 523
 524         buf[0] = CMD_SET_TARGET_POWER;
 525         buf[1] = enable;
 526
 527         ret = transport_write(devh, buf, 2);
 528
 529         if (ret != JAYLINK_OK) {
 530                 log_err(ctx, "transport_write() failed: %s",
 531                         jaylink_strerror(ret));
 532                 return ret;
 533         }
 534
 535         return JAYLINK_OK;
 536 }