src/hardware/microchip-pickit2/api.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2018 Gerhard Sittig <gerhard.sittig@gmx.net>
   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 3 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 /*
  21  * TODO
  22  * - Data acquisition works, but triggers either seem to not take effect,
  23  *   or the trigger position is not in the expected spot according to the
  24  *   user provided acquisition parameters. More research is required. The
  25  *   bitmasks for enable/level/edge as well as the magic 16bit values for
  26  *   position may need adjustment.
  27  * - The trigger position logic assumes that capture ratio specs are in
  28  *   the range of 0-6%, which gets mapped to none/10%/50%/90%/+1W/+2W/+3W
  29  *   choices. This avoids issues with applications which lack support for
  30  *   non-contiguous discrete supported values, and values outside of the
  31  *   0-100% range. This is considered acceptable, to avoid the necessity
  32  *   to extend common infrastructure to an unusual feature of a single
  33  *   device of limited popularity. Just needs to get communicated to users.
  34  * - When a formula for the trigger position values in the SETUP packet
  35  *   is found, the driver may accept arbitrary values between 0-100%, but
  36  *   still could not express the "plus N windows" settings. Though that'd
  37  *   be a rather useful feature considering the very short memory depth.
  38  * - The current implementation assumes externally provided Vdd, without
  39  *   which input levels won't get detected. A future implementation could
  40  *   optionally power Vdd from the PICkit2 itself, according to a user
  41  *   provided configuration value.
  42  * - The current implementation silently accepts sample count limits beyond
  43  *   1024, just won't provide more than 1024 samples to the session. A
  44  *   future implementation could cap the settings upon reception. Apps
  45  *   like PulseView may not be able to specify 1024, and pass 1000 or
  46  *   2000 instead (the latter results in 1024 getting used).
  47  * - The manual suggests that users can assign names to devices. The
  48  *   current implementation supports conn= specs with USB VID:PID pairs
  49  *   or bus/address numbers. A future implementation could scan for user
  50  *   assigned names as well (when the opcode to query the name was found).
  51  * - The "attach kernel driver" support code probably should move to a
  52  *   common location, instead of getting repeated across several drivers.
  53  * - Diagnostics may benefit from cleanup.
  54  */
  55
  56 #include <config.h>
  57 #include <libusb.h>
  58 #include <string.h>
  59 #include "protocol.h"
  60
  61 #define PICKIT2_VENDOR_NAME     "Microchip"
  62 #define PICKIT2_PRODUCT_NAME    "PICkit2"
  63
  64 #define PICKIT2_DEFAULT_ADDRESS "04d8.0033"
  65 #define PICKIT2_USB_INTERFACE   0
  66
  67 static struct sr_dev_driver microchip_pickit2_driver_info;
  68
  69 static const char *channel_names[] = {
  70         "pin4", "pin5", "pin6",
  71 };
  72
  73 static const uint32_t scanopts[] = {
  74         SR_CONF_CONN,
  75 };
  76
  77 static const uint32_t drvopts[] = {
  78         SR_CONF_LOGIC_ANALYZER,
  79 };
  80
  81 static const uint32_t devopts[] = {
  82         SR_CONF_CONN | SR_CONF_GET,
  83         SR_CONF_SAMPLERATE | SR_CONF_GET | SR_CONF_SET | SR_CONF_LIST,
  84         SR_CONF_LIMIT_SAMPLES | SR_CONF_GET | SR_CONF_SET,
  85         SR_CONF_TRIGGER_MATCH | SR_CONF_LIST,
  86         SR_CONF_CAPTURE_RATIO | SR_CONF_GET | SR_CONF_SET | SR_CONF_LIST,
  87 };
  88
  89 static const int32_t trigger_matches[] = {
  90         SR_TRIGGER_ZERO,
  91         SR_TRIGGER_ONE,
  92         SR_TRIGGER_RISING,
  93         SR_TRIGGER_FALLING,
  94 };
  95
  96 /*
  97  * Note that a list of 0, 10, 50, 90, 91, 92, 93, would have been nicer
  98  * from a user's perspective, but applications may not support a set of
  99  * discrete supported values, and 91+ is as much of a hack to work around
 100  * the "0-100%" limitation. So let's map those 0-6 "percent" to the vendor
 101  * app's 10/50/90/1W/2W/3W locations.
 102  */
 103 static const uint64_t captureratios[] = {
 104         0, 1, 2, 3, 4, 5, 6,
 105 };
 106
 107 static const uint64_t samplerates[] = {
 108         SR_KHZ(5),
 109         SR_KHZ(10),
 110         SR_KHZ(25),
 111         SR_KHZ(50),
 112         SR_KHZ(100),
 113         SR_KHZ(250),
 114         SR_KHZ(500),
 115         SR_MHZ(1),
 116 };
 117
 118 static GSList *scan(struct sr_dev_driver *di, GSList *options)
 119 {
 120         struct drv_context *drvc;
 121         const char *conn;
 122         GSList *l, *devices, *usb_devices;
 123         struct sr_config *cfg;
 124         struct sr_usb_dev_inst *usb;
 125         struct sr_dev_inst *sdi;
 126         struct sr_channel_group *cg;
 127         size_t ch_count, ch_idx;
 128         struct sr_channel *ch;
 129         struct dev_context *devc;
 130
 131         drvc = di->context;
 132
 133         conn = PICKIT2_DEFAULT_ADDRESS;
 134         for (l = options; l; l = l->next) {
 135                 cfg = l->data;
 136                 switch (cfg->key) {
 137                 case SR_CONF_CONN:
 138                         conn = g_variant_get_string(cfg->data, NULL);
 139                         break;
 140                 }
 141         }
 142
 143         devices = NULL;
 144         usb_devices = sr_usb_find(drvc->sr_ctx->libusb_ctx, conn);
 145         if (!usb_devices)
 146                 return NULL;
 147
 148         for (l = usb_devices; l; l = l->next) {
 149                 usb = l->data;
 150
 151                 /* Create the device instance. */
 152                 sdi = g_malloc0(sizeof(*sdi));
 153                 devices = g_slist_append(devices, sdi);
 154                 sdi->status = SR_ST_INACTIVE;
 155                 sdi->vendor = g_strdup(PICKIT2_VENDOR_NAME);
 156                 sdi->model = g_strdup(PICKIT2_PRODUCT_NAME);
 157                 sdi->inst_type = SR_INST_USB;
 158                 sdi->conn = usb;
 159                 sdi->connection_id = g_strdup(conn);
 160
 161                 /* Create the logic channels group. */
 162                 cg = sr_channel_group_new(sdi, "Logic", NULL);
 163                 ch_count = ARRAY_SIZE(channel_names);
 164                 for (ch_idx = 0; ch_idx < ch_count; ch_idx++) {
 165                         ch = sr_channel_new(sdi, ch_idx, SR_CHANNEL_LOGIC,
 166                                 TRUE, channel_names[ch_idx]);
 167                         cg->channels = g_slist_append(cg->channels, ch);
 168                 }
 169
 170                 /*
 171                  * Create the device context. Pre-select the highest
 172                  * samplerate and the deepest sample count available.
 173                  */
 174                 devc = g_malloc0(sizeof(*devc));
 175                 sdi->priv = devc;
 176                 devc->samplerates = samplerates;
 177                 devc->num_samplerates = ARRAY_SIZE(samplerates);
 178                 devc->curr_samplerate_idx = devc->num_samplerates - 1;
 179                 devc->captureratios = captureratios;
 180                 devc->num_captureratios = ARRAY_SIZE(captureratios);
 181                 devc->curr_captureratio_idx = 0;
 182                 devc->sw_limits.limit_samples = PICKIT2_SAMPLE_COUNT;
 183         }
 184
 185         return std_scan_complete(di, devices);
 186 }
 187
 188 static int dev_open(struct sr_dev_inst *sdi)
 189 {
 190         struct sr_usb_dev_inst *usb;
 191         struct dev_context *devc;
 192         struct sr_dev_driver *di;
 193         struct drv_context *drvc;
 194         int ret;
 195
 196         usb = sdi->conn;
 197         devc = sdi->priv;
 198         di = sdi->driver;
 199         drvc = di->context;
 200
 201         ret = sr_usb_open(drvc->sr_ctx->libusb_ctx, usb);
 202         if (ret < 0)
 203                 return SR_ERR;
 204
 205         if (libusb_kernel_driver_active(usb->devhdl, PICKIT2_USB_INTERFACE) == 1) {
 206                 ret = libusb_detach_kernel_driver(usb->devhdl, PICKIT2_USB_INTERFACE);
 207                 if (ret < 0) {
 208                         sr_err("Canot detach kernel driver: %s.",
 209                                 libusb_error_name(ret));
 210                         return SR_ERR;
 211                 }
 212                 devc->detached_kernel_driver = TRUE;
 213         }
 214
 215         ret = libusb_claim_interface(usb->devhdl, PICKIT2_USB_INTERFACE);
 216         if (ret < 0) {
 217                 sr_err("Cannot claim interface: %s.", libusb_error_name(ret));
 218                 return SR_ERR;
 219         }
 220
 221         return SR_OK;
 222 }
 223
 224 static int dev_close(struct sr_dev_inst *sdi)
 225 {
 226         struct sr_usb_dev_inst *usb;
 227         struct dev_context *devc;
 228         int ret;
 229
 230         usb = sdi->conn;
 231         devc = sdi->priv;
 232
 233         if (!usb)
 234                 return SR_OK;
 235         if (!usb->devhdl)
 236                 return SR_OK;
 237
 238         ret = libusb_release_interface(usb->devhdl, PICKIT2_USB_INTERFACE);
 239         if (ret) {
 240                 sr_err("Cannot release interface: %s.", libusb_error_name(ret));
 241                 return SR_ERR;
 242         }
 243
 244         if (devc->detached_kernel_driver) {
 245                 ret = libusb_attach_kernel_driver(usb->devhdl, PICKIT2_USB_INTERFACE);
 246                 if (ret) {
 247                         sr_err("Cannot attach kernel driver: %s.",
 248                                 libusb_error_name(ret));
 249                         return SR_ERR;
 250                 }
 251                 devc->detached_kernel_driver = FALSE;
 252         }
 253
 254         libusb_close(usb->devhdl);
 255         sdi->conn = NULL;
 256
 257         return SR_OK;
 258 }
 259
 260 static int config_get(uint32_t key, GVariant **data,
 261         const struct sr_dev_inst *sdi, const struct sr_channel_group *cg)
 262 {
 263         struct dev_context *devc;
 264         struct sr_usb_dev_inst *usb;
 265         uint64_t rate, ratio;
 266
 267         (void)cg;
 268
 269         devc = sdi ? sdi->priv : NULL;
 270
 271         switch (key) {
 272         case SR_CONF_CONN:
 273                 if (!sdi->conn)
 274                         return SR_ERR_ARG;
 275                 usb = sdi->conn;
 276                 *data = g_variant_new_printf("%d.%d", usb->bus, usb->address);
 277                 return SR_OK;
 278         case SR_CONF_SAMPLERATE:
 279                 rate = devc->samplerates[devc->curr_samplerate_idx];
 280                 *data = g_variant_new_uint64(rate);
 281                 return SR_OK;
 282         case SR_CONF_LIMIT_SAMPLES:
 283                 return sr_sw_limits_config_get(&devc->sw_limits, key, data);
 284         case SR_CONF_CAPTURE_RATIO:
 285                 ratio = devc->captureratios[devc->curr_captureratio_idx];
 286                 *data = g_variant_new_uint64(ratio);
 287                 return SR_OK;
 288         default:
 289                 return SR_ERR_NA;
 290         }
 291 }
 292
 293 static int config_set(uint32_t key, GVariant *data,
 294         const struct sr_dev_inst *sdi, const struct sr_channel_group *cg)
 295 {
 296         struct dev_context *devc;
 297         int idx;
 298
 299         (void)cg;
 300
 301         devc = sdi ? sdi->priv : NULL;
 302
 303         switch (key) {
 304         case SR_CONF_SAMPLERATE:
 305                 if (!devc)
 306                         return SR_ERR_ARG;
 307                 idx = std_u64_idx(data, devc->samplerates, devc->num_samplerates);
 308                 if (idx < 0)
 309                         return SR_ERR_ARG;
 310                 devc->curr_samplerate_idx = idx;
 311                 return SR_OK;
 312         case SR_CONF_CAPTURE_RATIO:
 313                 if (!devc)
 314                         return SR_ERR_ARG;
 315                 idx = std_u64_idx(data, devc->captureratios, devc->num_captureratios);
 316                 if (idx >= 0)
 317                         devc->curr_captureratio_idx = idx;
 318                 return SR_OK;
 319         case SR_CONF_LIMIT_SAMPLES:
 320                 return sr_sw_limits_config_set(&devc->sw_limits, key, data);
 321         default:
 322                 return SR_ERR_NA;
 323         }
 324 }
 325
 326 static int config_list(uint32_t key, GVariant **data,
 327         const struct sr_dev_inst *sdi, const struct sr_channel_group *cg)
 328 {
 329         struct dev_context *devc;
 330
 331         devc = sdi ? sdi->priv : NULL;
 332
 333         switch (key) {
 334         case SR_CONF_SCAN_OPTIONS:
 335         case SR_CONF_DEVICE_OPTIONS:
 336                 return STD_CONFIG_LIST(key, data, sdi, cg, scanopts, drvopts, devopts);
 337         case SR_CONF_SAMPLERATE:
 338                 if (!devc)
 339                         return SR_ERR_NA;
 340                 *data = std_gvar_samplerates(devc->samplerates, devc->num_samplerates);
 341                 return SR_OK;
 342         case SR_CONF_TRIGGER_MATCH:
 343                 *data = std_gvar_array_i32(ARRAY_AND_SIZE(trigger_matches));
 344                 return SR_OK;
 345         case SR_CONF_CAPTURE_RATIO:
 346                 *data = std_gvar_array_u64(ARRAY_AND_SIZE(captureratios));
 347                 return SR_OK;
 348         default:
 349                 return SR_ERR_NA;
 350         }
 351 }
 352
 353 static int dev_acquisition_start(const struct sr_dev_inst *sdi)
 354 {
 355         struct dev_context *devc;
 356         struct sr_trigger *trigger;
 357         struct sr_trigger_stage *stage;
 358         struct sr_trigger_match *match;
 359         GSList *l;
 360         size_t idx;
 361         int ret;
 362
 363         devc = sdi->priv;
 364
 365         /*
 366          * Query triggers, translate the more complex caller spec to
 367          * "flat" internal variables, to simplify the construction of
 368          * the SETUP packet elsewhere. This driver supports a single
 369          * stage, with match conditions for one or multiple channels.
 370          */
 371         memset(&devc->triggers, 0, sizeof(devc->triggers));
 372         trigger = sr_session_trigger_get(sdi->session);
 373         if (trigger) {
 374                 if (g_slist_length(trigger->stages) > 1)
 375                         return SR_ERR_NA;
 376                 stage = g_slist_nth_data(trigger->stages, 0);
 377                 if (!stage)
 378                         return SR_ERR_ARG;
 379                 for (l = stage->matches; l; l = l->next) {
 380                         match = l->data;
 381                         if (!match->match)
 382                                 continue;
 383                         if (!match->channel->enabled)
 384                                 continue;
 385                         idx = match->channel->index;
 386                         devc->triggers[idx] = match->match;
 387                 }
 388                 sr_dbg("acq start: trigger specs: %x/%x/%x",
 389                         devc->triggers[0], devc->triggers[1],
 390                         devc->triggers[2]);
 391         }
 392         devc->trigpos = trigger ? devc->curr_captureratio_idx : 0;
 393
 394         /* Have the SETUP packet sent, then poll for the status. */
 395         devc->state = STATE_CONF;
 396         ret = microchip_pickit2_setup_trigger(sdi);
 397         if (ret) {
 398                 devc->state = STATE_IDLE;
 399                 return ret;
 400         }
 401         devc->state = STATE_WAIT;
 402
 403         std_session_send_df_header(sdi);
 404         sr_session_source_add(sdi->session, -1, 0, 20,
 405                 microchip_pickit2_receive_data, (void *)sdi);
 406
 407         return SR_OK;
 408 }
 409
 410 static int dev_acquisition_stop(struct sr_dev_inst *sdi)
 411 {
 412         struct dev_context *devc;
 413
 414         devc = sdi->priv;
 415         if (devc->state < STATE_CONF)
 416                 return SR_OK;
 417
 418         /*
 419          * Keep up the acquisition until either data becomes available
 420          * (according to the previously configured trigger condition),
 421          * or until the user cancels the acquisition by pressing the
 422          * device's button. This is a firmware limitation which the
 423          * vendor software "suffers from" as well.
 424          */
 425         if (devc->state == STATE_WAIT) {
 426                 sr_err("Cannot terminate by software, need either data trigger or cancel button.");
 427                 return SR_OK;
 428         }
 429
 430         if (devc->state > STATE_CONF) {
 431                 std_session_send_df_end(sdi);
 432         }
 433         sr_session_source_remove(sdi->session, -1);
 434         devc->state = STATE_IDLE;
 435
 436         return SR_OK;
 437 }
 438
 439 static struct sr_dev_driver microchip_pickit2_driver_info = {
 440         .name = "microchip-pickit2",
 441         .longname = PICKIT2_VENDOR_NAME " " PICKIT2_PRODUCT_NAME,
 442         .api_version = 1,
 443         .init = std_init,
 444         .cleanup = std_cleanup,
 445         .scan = scan,
 446         .dev_list = std_dev_list,
 447         .dev_clear = std_dev_clear,
 448         .config_get = config_get,
 449         .config_set = config_set,
 450         .config_list = config_list,
 451         .dev_open = dev_open,
 452         .dev_close = dev_close,
 453         .dev_acquisition_start = dev_acquisition_start,
 454         .dev_acquisition_stop = dev_acquisition_stop,
 455         .context = NULL,
 456 };
 457 SR_REGISTER_DEV_DRIVER(microchip_pickit2_driver_info);