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