tribble-control 0.4.4

data/lib/tribble-control/hub/exsys.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+#
+# The ExSYS 16-port managed hub, over the FT232 serial line wired
+# inside it.  The exsys gem speaks the frames; this class says which
+# hub, and answers the Hub interface with it.
+#
+require 'exsys'
+require 'exsys/managed-usb'
+
+require_relative '../hub'
+
+module TribbleControl
+class Hub
+
+class ExSYS < Hub
+    # The gem's class, named once.  Inside this class the bare
+    # constant ExSYS is this class, not the gem's module.
+    GEM = ::ExSYS::ManagedUSB
+
+    # The USB id of a hub's control adapter, for the messages that name
+    # it.  Asked of the gem rather than written out: it is a fact about
+    # the hardware, the gem is what knows it, and a literal here would
+    # go on saying 0403:6001 after the gem had stopped looking for that.
+    CTRL_ID = "#{GEM::CTRL_VENDOR}:#{GEM::CTRL_PRODUCT}".freeze
+
+    # Every FTDI 0403:6001 the host has, as the gem reports them:
+    # { device:, serial:, usb_path: }.  Reports; decides nothing.  The
+    # gem's own errors -- a host it cannot look on -- become ours.
+    def self.available = guard { GEM.available }
+
+    # The hub +named+ names, or the one hub the host has.
+    #
+    # Three shapes of name, told apart by what they look like, no two
+    # of which can be confused:
+    #
+    #   /dev/ttyUSB1   a '/' in it, so a device node, used as given --
+    #                  the same rule --openocd uses to tell a path from
+    #                  a name to look up
+    #   1-1.2.4.4      the USB path shape (GEM::USB_PATH), so the
+    #                  adapter in that socket
+    #   AL03GD7X       anything else, so an FT232 serial number
+    #
+    # The node is the worst of the three to write down.  The number in
+    # /dev/ttyUSB1 is not the hub's, and not the USB device number
+    # either: it is the usbserial layer's own index, and it is the
+    # LOWEST ONE FREE when the adapter is probed (ttyU on FreeBSD,
+    # allocated the same way).  So it depends on what else was attached
+    # first, and it is reused -- unplug the adapter holding ttyUSB0 and
+    # the next thing to attach becomes ttyUSB0.  Two hubs can therefore
+    # swap names across a reboot, or while the machine is up, and every
+    # configuration naming them that way is then pointed at the other bench.
+    #
+    # The other two are both stable, and they answer different
+    # questions.  A serial stays with the ADAPTER: move the hub to
+    # another socket or another machine and its serial goes with it.  A
+    # USB path stays with the SOCKET: whatever is plugged in there
+    # answers to it, a replacement hub included.  Naming one particular
+    # hub is the serial's job and is the usual want.  The path is for
+    # the hub whose EEPROM carries no serial to be named by -- its only
+    # stable name -- and for a bench where the socket is the fixed
+    # thing.  Both platforms report one, but each in its own numbering,
+    # so a path names a socket on the host that reported it and does
+    # not travel to another.
+    #
+    # Auto-detection is a guess, and it is only a safe guess while
+    # there is one candidate.  The gem reports every FTDI 0403:6001 on
+    # the host, which is a hub's control adapter and also every other
+    # FT232 attached -- the gem says so itself, and deliberately
+    # reports rather than decides, because telling them apart means
+    # opening the line and writing to it.  With two, taking one would
+    # be a coin toss decided by enumeration order, on a command that
+    # might then switch somebody else's ports, so it refuses and lists
+    # what it found with the serials to choose between them.
+    def self.open(named, password: nil)
+        if named&.include?(File::SEPARATOR)
+            # A line named outright is used as given, and discovery is
+            # not required to succeed for that to work -- naming it is
+            # the escape hatch for a host discovery cannot answer on.
+            # It is still ASKED, quietly, because a line that IS a
+            # known candidate brings its USB path with it, and that is
+            # what --method usb needs; see #usb_path.
+            return new(named, ctrl: candidate_for(named), password: password)
+        end
+
+        found = available
+        ctrl  = if named
+                then match(named, found)
+                else lone(found)
+                end
+        new(ctrl[:device], ctrl: ctrl, password: password)
+    end
+
+    # The one candidate +named+ names among +found+, or an error.
+    def self.match(named, found)
+        key, what = if GEM::USB_PATH.match?(named)
+                    then [ :usb_path, 'at USB path' ]
+                    else [ :serial,   'with serial'  ]
+                    end
+        match = found.select {|c| c[key] == named }
+        case match.size
+        when 1 then match.first
+        when 0
+            # A path that matched nothing on a host reporting no
+            # paths at all is a different mistake from a path that
+            # is simply not this one, and saying "not found" would
+            # send the reader hunting for a socket.
+            if key == :usb_path && found.none? {|c| c[:usb_path] }
+                raise Error, "no FTDI #{CTRL_ID} at USB path '#{named}':" \
+                             ' this host reports no USB path for any of' \
+                             ' its serial lines, so none can be named' \
+                             ' that way.  Name the hub by the serial of' \
+                             " its FT232 instead (#{seen(found)})"
+            end
+            raise Error, "no FTDI #{CTRL_ID} #{what} '#{named}' on this" \
+                         " host (#{seen(found)}).  A name with a '/' in" \
+                         ' it is taken as the path of a serial line, one' \
+                         ' shaped 1-1.2.4.4 as a USB path, and anything' \
+                         ' else as an FT232 serial number'
+        else
+            raise Error, "#{match.size} FTDI #{CTRL_ID} are #{what}" \
+                         " '#{named}' (#{seen(found)}): name the line by" \
+                         ' path instead'
+        end
+    end
+
+    # The one candidate the host has, when it has exactly one.
+    def self.lone(found)
+        case found.size
+        when 1 then found.first
+        when 0
+            raise Error, 'unable to auto-detect the hub control line:' \
+                         " no FTDI #{CTRL_ID} on this host.  Name it" \
+                         " with -d, or with a 'device =' line in the" \
+                         ' configuration'
+        else
+            raise Error, 'unable to auto-detect the hub control line:' \
+                         " #{found.size} FTDI #{CTRL_ID} adapters on this" \
+                         " host (#{seen(found)}).  Name the one to drive" \
+                         " with -d, or with a 'device =' line in the" \
+                         ' configuration'
+        end
+    end
+
+    # The candidate the host reports for a line named outright, or nil.
+    #
+    # Quietly: naming a line is the escape hatch for a host discovery
+    # cannot answer on -- a pty under test, a node discovery does not
+    # know -- so a discovery that fails here must not take the run with
+    # it.  What is lost when it does is the USB path, and with it
+    # --method usb, which says so at the point it needs one.
+    def self.candidate_for(line)
+        available.find {|c| c[:device] == line }
+    rescue Error
+        nil
+    end
+
+    # What the host has, as a refusal lists it.
+    def self.seen(found)
+        return 'none found' if found.empty?
+        "found: #{found.map {|c| describe(c) }.join(', ')}"
+    end
+
+    # One candidate, as an error message names it.
+    #
+    # The serial leads, that being what the reader is meant to copy
+    # into a configuration, and the USB path follows it in brackets where the
+    # host reports one -- for the adapter with no serial it is the only
+    # stable name there is, and a refusal is where somebody goes
+    # looking for it.
+    def self.describe(ctrl)
+        name = if ctrl[:serial]
+               then "#{ctrl[:serial]} on #{ctrl[:device]}"
+               else "#{ctrl[:device]}, which reports no serial"
+               end
+        ctrl[:usb_path] ? "#{name} [#{ctrl[:usb_path]}]" : name
+    end
+
+    # The gem's errors are the hub layer's to report, not to leak: it
+    # raises both for a hub that refuses a command (E01 on a wrong
+    # password) and for a host it cannot look for a hub on.  Both are
+    # operator errors with nothing to debug, so both become Hub::Error
+    # carrying the same words.
+    def self.guard
+        yield
+    rescue GEM::Error => e
+        raise Error, e.message
+    end
+
+    private_class_method :match, :lone, :seen, :describe
+
+    # +line+ is the serial line; +ctrl+ the candidate it was chosen
+    # from, when discovery knew it, which is where the USB path comes
+    # from.  The line is not opened here: the gem opens it on first
+    # use and locks it for the duration of each call.
+    def initialize(line, ctrl: nil, password: nil)
+        super()
+        @line = line
+        @ctrl = ctrl
+        @gem  = GEM.new(line, password)
+    end
+
+    # The serial line, as it was named or found.
+    attr_reader :line
+
+    def to_s  = @line
+    def ports = GEM::PORTS
+    def state = guard { @gem.get(:ports) }
+
+    def on(*list)     = guard { @gem.on(*selection(list)) }
+    def off(*list)    = guard { @gem.off(*selection(list)) }
+    def toggle(*list) = guard { @gem.toggle(*selection(list)) }
+
+    # One exchange: the gem reads the port word, applies the whole
+    # change and writes it back under a single hold of the line.
+    def set(changes, default = nil) = guard { @gem.set(changes, default) }
+
+    # Four internal banks of four, so a board on +port+ is at
+    # <root>.bank.slot.  The root is the control adapter's own path
+    # less its last two components: the FT232 is wired at the last
+    # position of that internal tree, <root>.4.4, which is also why a
+    # board must never be put on port 16 -- --method usb would compute
+    # the adapter's own path for it.  See THE HUB in the manual.
+    #
+    # nil when there is nothing to work it out from -- a line named
+    # outright that discovery does not know, a host that reports no
+    # USB path for it, or an adapter plugged straight into a root port
+    # and therefore not inside a hub at all.
+    def usb_path(port)
+        return nil unless (root = self.usb_root)
+        bank = ((port - 1) / 4) + 1
+        slot = ((port - 1) % 4) + 1
+        "#{root}.#{bank}.#{slot}"
+    end
+
+  private
+
+    def guard(&) = self.class.guard(&)
+
+    def usb_root
+        parts = @ctrl&.dig(:usb_path)&.split('.')
+        return nil if parts.nil? || parts.size < 3
+        parts[0..-3].join('.')
+    end
+end
+
+end
+end

data/lib/tribble-control/hub/usb.rb

@@ -0,0 +1,418 @@
+# frozen_string_literal: true
+
+#
+# Any USB hub that switches its own ports, driven through usbconfig(8).
+#
+# Nothing here is an agreement with one manufacturer: what is spoken is
+# USB chapter 11, the hub class, which every hub answers -- the hub
+# descriptor says how many ports there are, GET_STATUS says whether one
+# is powered, and SET_FEATURE/CLEAR_FEATURE(PORT_POWER) switches it.
+# The ExSYS backend needs a gem because the ExSYS hub is switched over
+# a serial line wired beside the bus; this one needs none, because the
+# switching is on the bus itself.
+#
+# FreeBSD only for now: usbconfig(8) is FreeBSD's, and Linux has no
+# command that issues an arbitrary control request to a hub.
+#
+require 'open3'
+require 'rbconfig'
+
+require_relative '../hub'
+require_relative '../platform'
+
+module TribbleControl
+class Hub
+
+class USB < Hub
+    # Both by absolute path: this program switches benches, and what it
+    # runs must not depend on whoever's PATH it was started with.
+    USBCONFIG = '/usr/sbin/usbconfig'
+    SYSCTL    = '/sbin/sysctl'
+
+    # The two names that are not a serial.  A ugen name is what
+    # usbconfig -d takes; a USB path is what the configuration already uses
+    # to place a board.
+    UGEN     = /\Augen\d+\.\d+\z/
+    USB_PATH = /\A\d+-\d+(?:\.\d+)*\z/
+
+    # The hub descriptor, by bDescriptorType: the wValue that asks for
+    # it, how many bytes it is, and -- THE TRAP -- which bit of
+    # wPortStatus then means "powered".  A USB 2 hub (0x29) reports
+    # power in 0x0100; a SuperSpeed hub (0x2a) reports it in 0x0200 and
+    # puts the link state in bits 5-8, so reading a SuperSpeed port
+    # with the USB 2 bit answers "unpowered" for a port that is fine.
+    # Which descriptor the hub ANSWERS is therefore what decides how
+    # its status word is read, and is remembered for that.
+    DESCRIPTORS = {
+        0x29 => { :value => '0x2900', :length => '9',  :power => 0x0100 },
+        0x2a => { :value => '0x2a00', :length => '12', :power => 0x0200 }
+    }.freeze
+
+    # wHubCharacteristics bits 1:0, as the candidate reports them.
+    # Reported and never acted on: a hub that says ganged may still
+    # switch per port (the Genesys part on this bench does), and a hub
+    # that says individual may still switch nothing.  The read-back
+    # after a switch is what knows, so nothing is refused on this.
+    SWITCHING = [ :ganged, :individual, :none, :none ].freeze
+
+    # PORT_POWER, the only port feature this backend touches.
+    PORT_POWER = '0x0008'
+
+    # What 'off' does to the socket, which the hub cannot be asked.
+    # See Hub#vbus?: a plain hub takes the port off the bus, and only
+    # one with a power switch wired to VBUS cuts the supply.
+    SWITCHES = { :link => false, :vbus => true }.freeze
+
+    # A class method so that a test can stand on another host, and
+    # because this is the one fact about the platform the backend has.
+    def self.freebsd? = RbConfig::CONFIG['host_os'].match?(/^freebsd/)
+
+    # How a command is run: a callable (*argv) -> merged stdout+stderr.
+    #
+    # Everything this class runs goes through one of these, so a test
+    # hands it a fake host instead of a real one, and nothing in the
+    # methods below has to know what Open3 is.
+    def self.runner
+        lambda do |*argv|
+            Open3.capture2e(*argv).first
+        rescue Errno::ENOENT
+            raise Error, "cannot run #{argv.first}: it is not installed" \
+                         ' on this host, so no USB hub can be switched here'
+        end
+    end
+
+    # Every hub on this host that is not a root hub, as
+    #
+    #     { device: 'ugen1.4', serial: 'AC0528515619', usb_path: '1-1.1',
+    #       ports: 4, switching: :individual,
+    #       desc: 'vendor 0x0451 product 0x8142' }
+    #
+    # Root hubs are left out because they are the controller: their
+    # %location is empty and their parent is a usbusN, and a port of
+    # theirs has no PORT_POWER to clear.  Offering one as a candidate
+    # would offer a hub every command against it then failed on.
+    #
+    # The descriptor is read per hub rather than guessed, because it is
+    # what says how many ports a candidate has -- and the port count is
+    # half of what a refusal has to print for the reader to tell two
+    # identical hubs apart.  A hub that will not answer one is listed
+    # all the same, with no port count: discovery is a listing, and one
+    # odd hub must not stop the others from being named.  Choosing that
+    # hub is what is refused, in #initialize, where the descriptor is
+    # read for real.
+    def self.available(run: nil)
+        run ||= self.runner
+        tree  = Platform::FreeBSD.parse_usb_tree(run.call(SYSCTL, '-e', 'dev.uhub'))
+        tree.filter_map {|name, dev|
+            next unless name.start_with?('uhub')
+            loc = dev[:'%location']
+            next unless loc.is_a?(Hash) && (ugen = loc[:ugen])
+            desc   = begin
+                self.descriptor(ugen, run)
+            rescue Error
+                { :ports => nil, :switching => :unknown }
+            end
+            serial = dev.dig(:'%pnpinfo', :sernum).to_s
+            { :device    => ugen,
+              :serial    => serial.empty? ? nil : serial,
+              :usb_path  => Platform::FreeBSD.usb_path(dev, tree),
+              :ports     => desc[:ports],
+              :switching => desc[:switching],
+              # The tail of %desc is the class, the revision and the
+              # bus address, and the address changes on every replug:
+              # only the head names the part.
+              :desc      => dev[:'%desc'].to_s.split(',').first }
+        }
+    end
+
+    # The hub +named+ names, or the one switchable hub the host has.
+    #
+    # Three shapes of name, told apart by what they look like, no two
+    # of which can be confused:
+    #
+    #   ugen1.4        the ugen shape, so that device, used as given
+    #   1-1.1          the USB path shape, so the hub in that socket
+    #   AC0528515619   anything else, so the hub's serial number
+    #
+    # The ugen name is the worst of the three to write down, and it is
+    # here for the same reason /dev/ttyUSB1 is in Hub::ExSYS.open: it
+    # is the escape hatch for a hub discovery cannot answer for.  The
+    # number in it is enumeration order -- ugen1.4 is the fourth device
+    # the second controller attached -- so a replug renumbers it, and a
+    # configuration naming a hub that way points at whatever attached in its
+    # place.  The other two are stable: a serial follows the HUB, a USB
+    # path follows the SOCKET, and each names one host's numbering.
+    #
+    # Auto-detection is only safe while there is one candidate.  Two
+    # hubs on a host and no name is a coin toss decided by enumeration
+    # order, and driving the wrong one raises nothing anywhere: the
+    # ports exist, the requests succeed, and the boards that go dark
+    # are on the other bench.  It refuses and lists them instead.
+    def self.open(named, switch: :link, run: nil)
+        unless self.freebsd?
+            raise Error, 'the usb hub backend runs on FreeBSD only for now:' \
+                         ' it switches ports with usbconfig(8) hub-class' \
+                         ' requests, and no other host here has usbconfig'
+        end
+        run ||= self.runner
+        if named && UGEN.match?(named)
+            # Used as given, and discovery is not required to succeed
+            # for that to work.  It is still ASKED, quietly, because a
+            # device that IS a known candidate brings its USB path and
+            # its serial with it, and the path is what --method usb
+            # needs; see #usb_path.
+            return new(named, hub: self.candidate_for(named, run),
+                              switch: switch, run: run)
+        end
+        found = self.available(run: run)
+        hub   = named ? self.match(named, found) : self.lone(found)
+        new(hub[:device], hub: hub, switch: switch, run: run)
+    end
+
+    # The one candidate +named+ names among +found+, or an error.
+    def self.match(named, found)
+        key, what = if USB_PATH.match?(named)
+                    then [ :usb_path, 'at USB path' ]
+                    else [ :serial,   'with serial'  ]
+                    end
+        match = found.select {|c| c[key] == named }
+        case match.size
+        when 1 then match.first
+        when 0
+            raise Error, "no USB hub #{what} '#{named}' on this host" \
+                         " (#{seen(found)}).  A name shaped ugen1.4 is" \
+                         ' taken as a device, one shaped 1-1.1 as a USB' \
+                         ' path, and anything else as a hub serial number'
+        else
+            raise Error, "#{match.size} USB hubs are #{what} '#{named}'" \
+                         " (#{seen(found)}): name the hub by its ugen" \
+                         ' name instead'
+        end
+    end
+
+    # The one switchable hub the host has, when it has exactly one.
+    def self.lone(found)
+        case found.size
+        when 1 then found.first
+        when 0
+            raise Error, 'unable to auto-detect the hub: this host has no' \
+                         ' USB hub below a root hub, and a root hub has no' \
+                         " switchable port.  Name the hub with -d, or with" \
+                         " a 'device =' line in the configuration"
+        else
+            raise Error, 'unable to auto-detect the hub:' \
+                         " #{found.size} USB hubs on this host" \
+                         " (#{seen(found)}).  Name the one to drive with" \
+                         " -d, or with a 'device =' line in the configuration"
+        end
+    end
+
+    # The candidate the host reports for a device named outright, or nil.
+    #
+    # Quietly, as in Hub::ExSYS.candidate_for: naming a device is the
+    # escape hatch for a host discovery cannot answer on, so a
+    # discovery that fails here must not take the run with it.  What is
+    # lost when it does is the USB path, and with it --method usb,
+    # which says so at the point it needs one.
+    def self.candidate_for(device, run)
+        self.available(run: run).find {|c| c[:device] == device }
+    rescue Error
+        nil
+    end
+
+    # What the host has, as a refusal lists it.  Semicolons between
+    # candidates, because each one has commas of its own.
+    def self.seen(found)
+        return 'none found' if found.empty?
+        "found: #{found.map {|c| describe(c) }.join('; ')}"
+    end
+
+    # One candidate, as an error message names it: the serial leads,
+    # being what the reader is meant to copy into a configuration, then the
+    # device, the socket, and the port count -- which is the only thing
+    # that tells two of the same part apart when neither has a serial.
+    def self.describe(hub)
+        name = if hub[:serial]
+               then "#{hub[:serial]} on #{hub[:device]}"
+               else "#{hub[:device]}, which reports no serial"
+               end
+        name += " [#{hub[:usb_path]}]" if hub[:usb_path]
+        "#{name}, #{hub[:ports] || 'an unknown number of'} ports"
+    end
+
+    # The hub descriptor of +device+: which kind of hub it is, how many
+    # ports it has, and what it says about switching them.
+    #
+    # Two requests and not one, because the descriptor TYPE is half the
+    # answer and there is no way to ask which type a hub has: a USB 2
+    # hub answers 0x2900 and refuses 0x2a00, a SuperSpeed hub does the
+    # reverse.  Whichever answered decides how the port status word is
+    # read from then on (see DESCRIPTORS).
+    def self.descriptor(device, run)
+        DESCRIPTORS.each do |type, d|
+            bytes = self.bytes(device,
+                               self.request(device, run, '0xa0', '0x06',
+                                            d[:value], '0', d[:length]))
+            next if bytes.nil?
+            return { :type      => type,
+                     :ports     => bytes[2],
+                     :switching => SWITCHING[bytes[3] & 0x03] }
+        end
+        raise Error, "#{device} answers no hub descriptor, neither USB 2" \
+                     ' nor SuperSpeed, so it is not a hub this tool can' \
+                     ' switch'
+    end
+
+    # One usbconfig request, as the text between its angle brackets:
+    # 'OK', 'ERROR', or the bytes that came back.
+    #
+    # Only the first bracketed group: usbconfig prints the payload
+    # again as ASCII after it, and that copy contains whatever the
+    # bytes happened to spell -- '<0x09 0x29 ...><)>' for a descriptor.
+    # A pattern that reached for the last group would parse that.
+    #
+    # The exit status is not consulted because it is not the answer:
+    # usbconfig exits 0 for a request the hub refused, and 0 for a
+    # device it could not even find.  The printed text is the truth.
+    def self.request(device, run, *args)
+        out = run.call(USBCONFIG, '-d', device, 'do_request', *args)
+        if out.match?(/Permission denied|Operation not permitted/)
+            raise Error, "not allowed to drive #{device}: the ugen nodes" \
+                         ' are root:operator 0660, so switching a port' \
+                         ' needs membership of group operator (pw groupmod' \
+                         ' operator -m <user>, then log in again)'
+        end
+        payload = out[/REQUEST = <([^>]*)>/, 1]
+        if payload.nil?
+            raise Error, "#{device} answered no usbconfig request" \
+                         " (#{out.to_s.lines.first.to_s.strip}): it is not" \
+                         ' a device this host can be asked about'
+        end
+        payload
+    end
+
+    # The bytes of an answer, or nil for a request the hub refused.
+    def self.bytes(device, payload)
+        return nil if payload == 'ERROR'
+        payload.split.map {|b| Integer(b, 16) }
+    rescue ArgumentError
+        raise Error, "#{device} answered '#{payload}' where a usbconfig" \
+                     ' request should have brought bytes back'
+    end
+
+    private_class_method :match, :lone, :seen, :describe
+
+    # +device+ is the ugen name usbconfig is given; +hub+ the candidate
+    # it was chosen from, when discovery knew it, which is where the
+    # USB path comes from.  The descriptor is read here and not per
+    # call: the port count is asked before the hub is opened for real
+    # (the configuration is checked against it) and it cannot change under
+    # us, while the port STATE can and is never remembered.
+    def initialize(device, hub: nil, switch: :link, run: nil)
+        super()
+        @device = device
+        @hub    = hub || {}
+        @run    = run || self.class.runner
+        @vbus   = SWITCHES.fetch(switch) {
+            raise Error, "no such switch #{switch.inspect}: a hub's 'off'" \
+                         ' either takes the port off the bus (:link,' \
+                         " the default) or cuts the socket (:vbus), and" \
+                         ' software cannot tell which this hub is' \
+                         ' wired for'
+        }
+        @desc   = self.class.descriptor(@device, @run)
+        @ports  = (1..@desc[:ports]).to_a
+    end
+
+    # The ugen name, as it was named or found, and the ports the hub's
+    # descriptor says it has.
+    attr_reader :device
+    attr_reader :ports
+
+    def to_s  = @device
+    def vbus? = @vbus
+
+    # One GET_STATUS per port: the hub has no request that reports them
+    # all, so a status of a 16-port hub is 16 exchanges.
+    def state = @ports.to_h {|port| [ port, powered?(port) ] }
+
+    def on(*list)  = apply(selection(list), true)
+    def off(*list) = apply(selection(list), false)
+
+    # Read then invert, port by port, because there is no request that
+    # flips one: a port's own current state is the only thing that says
+    # what toggling it means.
+    def toggle(*list)
+        selection(list).each {|port| apply([ port ], !powered?(port)) }
+    end
+
+    # Where a board on +port+ is in this host's USB tree.  A plain hub
+    # has no internal geometry to account for -- the ExSYS hub's 4-by-4
+    # tree is a fact about that hub and not about hubs -- so a port is
+    # one component below the hub's own path.
+    #
+    # nil when there is nothing to work it out from: a device named
+    # outright that discovery does not know, or a host that reports no
+    # path for it.
+    def usb_path(port)
+        root = @hub[:usb_path]
+        root && "#{root}.#{port}"
+    end
+
+  private
+
+    # Switch every port in +list+, and check that the hub did it.
+    #
+    # The read-back is not belt and braces, it is the only thing that
+    # knows.  A hub that switches nothing -- ganged, or with no switch
+    # wired -- accepts CLEAR_FEATURE(PORT_POWER) and answers OK, and
+    # the port stays up.  Without this, `off` would report success on a
+    # bench it had not touched, and a board would be flashed live.  It
+    # is also why nothing is refused on wHubCharacteristics: the
+    # descriptor is a claim, this is the measurement.
+    def apply(list, powered)
+        list.each do |port|
+            feature(powered ? '0x03' : '0x01', port)
+            next if powered?(port) == powered
+            raise Error, "port #{port} of #{@device} did not switch" \
+                         " #{powered ? 'on' : 'off'}: the hub accepted the" \
+                         ' request and the port still reports itself' \
+                         " #{powered ? 'unpowered' : 'powered'}, so this" \
+                         ' hub does not switch that port'
+        end
+    end
+
+    # SET_FEATURE (0x03) or CLEAR_FEATURE (0x01) of PORT_POWER.
+    def feature(request, port)
+        answer = self.class.request(@device, @run, '0x23', request,
+                                    PORT_POWER, port.to_s, '0')
+        return if answer == 'OK'
+        raise Error, "#{@device} refused to switch port #{port}:" \
+                     " usbconfig answered '#{answer}'"
+    end
+
+    # Is the port powered, by the bit this kind of hub reports it in?
+    def powered?(port)
+        port_status(port).anybits?(DESCRIPTORS.fetch(@desc[:type])[:power])
+    end
+
+    # wPortStatus, the first two of the four bytes GET_STATUS brings
+    # back, little-endian.  The other two are wPortChange, which this
+    # backend never reads: it says what has happened since the last
+    # time somebody cleared it, and nothing here clears it.
+    def port_status(port)
+        bytes = self.class.bytes(@device,
+                                 self.class.request(@device, @run, '0xa3',
+                                                    '0x00', '0x0000',
+                                                    port.to_s, '4'))
+        if bytes.nil? || bytes.size < 2
+            raise Error, "#{@device} reports no status for port #{port}:" \
+                         ' the hub refused the request, which is what it' \
+                         ' answers for a port it has not got'
+        end
+        bytes[0] | (bytes[1] << 8)
+    end
+end
+
+end
+end