Probe Groups

Status: The proposal below has been implemented in libsigrok as of 11/2013 ("probe groups" are now called "channel groups", though).

Problem

Some settings supported by a device may apply to specific probes, rather than a device instance as a whole. The current sr_config_{get,set,list} API does not define a way to represent this.

A representation of this information is needed in the API so that frontends can provide an appropriate UI to the user, and so that configuration requests can be made unambiguously to devices with probe-specific settings.

Use Cases

Settings that apply for each available individual probe

• The Rigol DS1052E has two analog probes, CH1 and CH2. Volts per division can be set individually for each.

Settings that apply only for probes of a given type

• The Rigol DS1102D has two analog probes, and 16 digital probes. Volts per division can be set only for the analog probes. Threshold voltage can be set only for the digital probes.

Settings that apply only for groups of probes of the same type

• The Pico Technology PicoScope 2205 has 16 digital probes in two groups of 8. Threshold voltage can be set only for each group of 8.
• The IKALOGIC ScanaPLUS logic analyzer has 9 probes.
  • The voltage threshold can be set for two groups of probes individually (first group: probes 1-4, second group: probes 5-9).
  • Additional special cases on this device are that probes 5 and 6 can either be used "normally" as digital logic analyzer inputs, or they can be combined together (by LA user config at runtime, when configuring the LA) to form one differential probe. The same applies to probes 7 and 8, they can be used individually as normal LA probes, or combined together to form a differential probe (e.g. for differential RS485/CAN/other probing). It is possible to only combine probes 5+6, or probes 7+8, or both, or none.

Previous Ideas

1. Use the existing API, but where settings are per-probe, use a GVariant array of the values for each probe, rather than a single GVariant value.
   • This does not address use case 3.
2. Use the existing API, but where settings are per-probe, use a GVariant array of (probes, value) tuples, rather than a single GVariant value.
   • This is possible, but creates a lot of work. Probes could not be specified by pointer in the GVariant, so would have to be passed by name. In a sr_config_set call, the driver would then have to match the names to some internal data structure.
   • It also loads a lot of structure into a GVariant value that was originally conceived as being merely a simple value whose type would vary between configuration settings according to the nature of each setting.
   • Every frontend, driver and binding would have to implement the code required to pack and unpack these GVariant structures.

Proposal

Concept

• Modify the API to include an explicit "probe group" data type, which can be passed to sr_config_{get,set,list} to address a specific group of probes.
• Provide a way for frontends to get the available probe groups for a device.

API

Define the following structure for a probe group:

struct sr_probe_group {
    /** Name of the probe group. */
    char *name;
    /** List of sr_probe structs of the probes belonging to this group. */
    GSList *probes;
    /** Private data for driver use. */
    void *priv;
};

Modify the signatures for sr_config_{get,set,list} as follows:

SR_API int sr_config_get(const struct sr_dev_driver *driver,
     const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group,
     int key, GVariant **data);

SR_API int sr_config_set(const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group,
     int key, GVariant *data);

SR_API int sr_config_list(const struct sr_dev_driver *driver,
     const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group,
     int key, GVariant **data);

Modify the signatures in struct sr_dev_driver as follows:

int (*config_get) (int key, GVariant **data,
     const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group);

int (*config_set) (int key, GVariant *data,
     const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group);

int (*config_list) (int key, GVariant **data,
     const struct sr_dev_inst *sdi,
     const struct sr_probe_group *probe_group);

In all the above functions, passing NULL for probe_group would have the same meaning as the current function without the probe_group parameter. Passing a probe group would implement the function for that specific group of probes.

The available probe groups are defined by the driver.

Initially, it is proposed to add a GSList *probe_groups field to struct sr_dev_inst to list the probe groups for a device. In all current use cases, these groups are static.

In future we may encounter devices in which certain settings are grouped in ways that change dynamically. In this case, we will need to replace this field with a new API call that retrieves the currently applicable groups.