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         usb = sdi ? sdi->conn : NULL;
 271
 272         switch (key) {
 273         case SR_CONF_CONN:
 274                 if (!usb)
 275                         return SR_ERR_ARG;
 276                 *data = g_variant_new_printf("%d.%d", usb->bus, usb->address);
 277                 return SR_OK;
 278         case SR_CONF_SAMPLERATE:
 279                 if (!devc)
 280                         return SR_ERR_ARG;
 281                 rate = devc->samplerates[devc->curr_samplerate_idx];
 282                 *data = g_variant_new_uint64(rate);
 283                 return SR_OK;
 284         case SR_CONF_LIMIT_SAMPLES:
 285                 if (!devc)
 286                         return SR_ERR_ARG;
 287                 return sr_sw_limits_config_get(&devc->sw_limits, key, data);
 288         case SR_CONF_CAPTURE_RATIO:
 289                 if (!devc)
 290                         return SR_ERR_ARG;
 291                 ratio = devc->captureratios[devc->curr_captureratio_idx];
 292                 *data = g_variant_new_uint64(ratio);
 293                 return SR_OK;
 294         default:
 295                 return SR_ERR_NA;
 296         }
 297 }
 298
 299 static int config_set(uint32_t key, GVariant *data,
 300         const struct sr_dev_inst *sdi, const struct sr_channel_group *cg)
 301 {
 302         struct dev_context *devc;
 303         int idx;
 304
 305         (void)cg;
 306
 307         devc = sdi ? sdi->priv : NULL;
 308
 309         switch (key) {
 310         case SR_CONF_SAMPLERATE:
 311                 if (!devc)
 312                         return SR_ERR_ARG;
 313                 idx = std_u64_idx(data, devc->samplerates, devc->num_samplerates);
 314                 if (idx < 0)
 315                         return SR_ERR_ARG;
 316                 devc->curr_samplerate_idx = idx;
 317                 return SR_OK;
 318         case SR_CONF_CAPTURE_RATIO:
 319                 if (!devc)
 320                         return SR_ERR_ARG;
 321                 idx = std_u64_idx(data, devc->captureratios, devc->num_captureratios);
 322                 if (idx >= 0)
 323                         devc->curr_captureratio_idx = idx;
 324                 return SR_OK;
 325         case SR_CONF_LIMIT_SAMPLES:
 326                 return sr_sw_limits_config_set(&devc->sw_limits, key, data);
 327         default:
 328                 return SR_ERR_NA;
 329         }
 330 }
 331
 332 static int config_list(uint32_t key, GVariant **data,
 333         const struct sr_dev_inst *sdi, const struct sr_channel_group *cg)
 334 {
 335         struct dev_context *devc;
 336
 337         devc = sdi ? sdi->priv : NULL;
 338
 339         switch (key) {
 340         case SR_CONF_SCAN_OPTIONS:
 341         case SR_CONF_DEVICE_OPTIONS:
 342                 return STD_CONFIG_LIST(key, data, sdi, cg, scanopts, drvopts, devopts);
 343         case SR_CONF_SAMPLERATE:
 344                 if (!devc)
 345                         return SR_ERR_NA;
 346                 *data = std_gvar_samplerates(devc->samplerates, devc->num_samplerates);
 347                 return SR_OK;
 348         case SR_CONF_TRIGGER_MATCH:
 349                 *data = std_gvar_array_i32(ARRAY_AND_SIZE(trigger_matches));
 350                 return SR_OK;
 351         case SR_CONF_CAPTURE_RATIO:
 352                 *data = std_gvar_array_u64(ARRAY_AND_SIZE(captureratios));
 353                 return SR_OK;
 354         default:
 355                 return SR_ERR_NA;
 356         }
 357 }
 358
 359 static int dev_acquisition_start(const struct sr_dev_inst *sdi)
 360 {
 361         struct dev_context *devc;
 362         struct sr_trigger *trigger;
 363         struct sr_trigger_stage *stage;
 364         struct sr_trigger_match *match;
 365         GSList *l;
 366         size_t idx;
 367         int ret;
 368
 369         devc = sdi->priv;
 370
 371         /*
 372          * Query triggers, translate the more complex caller spec to
 373          * "flat" internal variables, to simplify the construction of
 374          * the SETUP packet elsewhere. This driver supports a single
 375          * stage, with match conditions for one or multiple channels.
 376          */
 377         memset(&devc->triggers, 0, sizeof(devc->triggers));
 378         trigger = sr_session_trigger_get(sdi->session);
 379         if (trigger) {
 380                 if (g_slist_length(trigger->stages) > 1)
 381                         return SR_ERR_NA;
 382                 stage = g_slist_nth_data(trigger->stages, 0);
 383                 if (!stage)
 384                         return SR_ERR_ARG;
 385                 for (l = stage->matches; l; l = l->next) {
 386                         match = l->data;
 387                         if (!match->match)
 388                                 continue;
 389                         if (!match->channel->enabled)
 390                                 continue;
 391                         idx = match->channel->index;
 392                         devc->triggers[idx] = match->match;
 393                 }
 394                 sr_dbg("acq start: trigger specs: %x/%x/%x",
 395                         devc->triggers[0], devc->triggers[1],
 396                         devc->triggers[2]);
 397         }
 398         devc->trigpos = trigger ? devc->curr_captureratio_idx : 0;
 399
 400         /* Have the SETUP packet sent, then poll for the status. */
 401         devc->state = STATE_CONF;
 402         ret = microchip_pickit2_setup_trigger(sdi);
 403         if (ret) {
 404                 devc->state = STATE_IDLE;
 405                 return ret;
 406         }
 407         devc->state = STATE_WAIT;
 408
 409         std_session_send_df_header(sdi);
 410         sr_session_source_add(sdi->session, -1, 0, 20,
 411                 microchip_pickit2_receive_data, (void *)sdi);
 412
 413         return SR_OK;
 414 }
 415
 416 static int dev_acquisition_stop(struct sr_dev_inst *sdi)
 417 {
 418         struct dev_context *devc;
 419
 420         devc = sdi->priv;
 421         if (devc->state < STATE_CONF)
 422                 return SR_OK;
 423
 424         /*
 425          * Keep up the acquisition until either data becomes available
 426          * (according to the previously configured trigger condition),
 427          * or until the user cancels the acquisition by pressing the
 428          * device's button. This is a firmware limitation which the
 429          * vendor software "suffers from" as well.
 430          */
 431         if (devc->state == STATE_WAIT) {
 432                 sr_err("Cannot terminate by software, need either data trigger or cancel button.");
 433                 return SR_OK;
 434         }
 435
 436         if (devc->state > STATE_CONF) {
 437                 std_session_send_df_end(sdi);
 438         }
 439         sr_session_source_remove(sdi->session, -1);
 440         devc->state = STATE_IDLE;
 441
 442         return SR_OK;
 443 }
 444
 445 static struct sr_dev_driver microchip_pickit2_driver_info = {
 446         .name = "microchip-pickit2",
 447         .longname = PICKIT2_VENDOR_NAME " " PICKIT2_PRODUCT_NAME,
 448         .api_version = 1,
 449         .init = std_init,
 450         .cleanup = std_cleanup,
 451         .scan = scan,
 452         .dev_list = std_dev_list,
 453         .dev_clear = std_dev_clear,
 454         .config_get = config_get,
 455         .config_set = config_set,
 456         .config_list = config_list,
 457         .dev_open = dev_open,
 458         .dev_close = dev_close,
 459         .dev_acquisition_start = dev_acquisition_start,
 460         .dev_acquisition_stop = dev_acquisition_stop,
 461         .context = NULL,
 462 };
 463 SR_REGISTER_DEV_DRIVER(microchip_pickit2_driver_info);