tribble-control 0.4.4

data/lib/tribble-control/hub.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+#
+# The hub, as the rest of the program sees it: switchable ports and
+# nothing about how they are switched.
+#
+module TribbleControl
+
+# What every kind of hub has to answer.
+#
+# The subject of this tool is a USB hub, of more than one kind.  This
+# class is the seam that puts each kind behind the same calls.  A backend
+# is a subclass answering the methods below, and the commands,
+# each_device and the protections talk to nothing else.
+#
+# Ports are Integers numbered as the hub numbers them, from 1.  A list
+# handed to a switching method must be non-empty and name ports the
+# hub has: an empty list never means "every port" anywhere in this
+# program (see DESIGN.md), and the guard here is the last one rather
+# than the first -- every caller checks before it gets this far, and a
+# fourth path into the hub that forgets to is stopped here instead of
+# powering a bench up or down.
+#
+# Reaching for a hub's own methods in a command -- anything a backend
+# can do that this class does not name -- is the thing this class
+# exists to stop.  Add the method here, with a default or as a
+# NotImplementedError, and then to the backends.
+class Hub
+    # Anything the hub layer has to report: a hub that refuses a
+    # command, a host that cannot be looked for one on, a name that
+    # matches nothing or matches two.  CLI.run prints the message and
+    # nothing else, so every one of these must carry one.
+    class Error < StandardError
+    end
+
+    # The kinds of hub there are, by the name a configuration's 'hub =' line
+    # uses, and the class answering for each.  The configuration says what
+    # the hub IS -- an ExSYS managed hub, a standard hub with per-port
+    # power switching -- and not which tool drives it on this host, so
+    # the same line keeps working when another host learns to drive
+    # such a hub.  A backend is required when it is asked for, so a
+    # host that lacks what one of them needs still runs the others.
+    KINDS = { 'exsys' => 'ExSYS', 'usb' => 'USB' }.freeze
+
+    # The class for a kind, loaded.
+    def self.backend(kind)
+        unless (klass = KINDS[kind.to_s])
+            raise Error, "unknown hub kind '#{kind}' (one of" \
+                         " #{KINDS.keys.join(', ')})"
+        end
+        require_relative "hub/#{kind}"
+        const_get(klass)
+    end
+
+    # Every port this hub has, in order.  Static, and asked before the
+    # hub is ever opened: the configuration is checked against it.
+    def ports = raise NotImplementedError, "#{self.class}#ports"
+
+    # The hub's own view of what is powered: { port => true/false },
+    # for every port in #ports.
+    def state = raise NotImplementedError, "#{self.class}#state"
+
+    def on(*)     = raise NotImplementedError, "#{self.class}#on"
+    def off(*)    = raise NotImplementedError, "#{self.class}#off"
+    def toggle(*) = raise NotImplementedError, "#{self.class}#toggle"
+
+    # Apply { port => true/false } and, unless +default+ is nil, put
+    # every port not named to +default+.  A backend that can do the
+    # whole thing in one exchange with the hub overrides this; here it
+    # is an on and an off.
+    def set(changes, default = nil)
+        ons  = changes.select {|_, v| v }.keys
+        offs = changes.reject {|_, v| v }.keys
+        unless default.nil?
+            (default ? ons : offs).concat(self.ports - changes.keys)
+        end
+        self.on(*ons)   unless ons.empty?
+        self.off(*offs) unless offs.empty?
+    end
+
+    # Where a board on +port+ is in this host's USB tree, as a path in
+    # the shape ExSYS::ManagedUSB::USB_PATH describes (1-1.2.4.4), or
+    # nil when the hub cannot be placed in the tree.  --method usb
+    # needs it; the other two methods need no topology at all.
+    def usb_path(port) = raise NotImplementedError, "#{self.class}#usb_path(#{port})"
+
+    # The hub as a message names it.
+    def to_s = raise NotImplementedError, "#{self.class}#to_s"
+
+    # Does 'off' remove power from the socket, or only take the port
+    # off the bus?  Software cannot tell the two apart -- a hub with no
+    # power switch wired still reports the port unpowered and drops the
+    # link, and the device on it vanishes and returns either way -- so
+    # this is a fact a backend is told, or knows about its hardware.
+    # false means a board on a cut port keeps running, which is enough
+    # to select it by ('power' identifies a board by being the only
+    # one visible) and not enough to reboot it.  The default is the
+    # honest one for a hub that was built to switch VBUS.
+    def vbus? = true
+
+  private
+
+    # A list a switching method was handed, vetted: non-empty, and
+    # every port one the hub has.
+    def selection(list)
+        raise Error, 'no port named: refusing to switch nothing' if list.empty?
+        if (bad = list - self.ports).any?
+            raise Error, "no such port on this hub: #{bad.join(' ')}" \
+                         " (it has #{self.ports.first}-#{self.ports.last})"
+        end
+        list
+    end
+end
+
+end

data/lib/tribble-control/platform.rb

@@ -0,0 +1,271 @@
+#
+# Host-specific ways of finding the boards: their probes, their
+# consoles, and their place in the USB tree.  Finding the HUB is each
+# Hub backend's own (Hub::ExSYS.open, through the exsys gem), and so is
+# its geometry, which socket a port is (Hub#usb_path).
+#
+require 'rbconfig'
+require 'shellwords'
+
+module TribbleControl
+
+module Platform
+
+# Vendor ids of the debug probes a bench carries: NXP/mbed for DAPLink
+# (as on an nRF52840-MDK), SEGGER for a J-Link OB (as on a DWM1001-DEV).
+# Both present their console as a CDC interface reporting the PROBE's
+# own serial, which is what makes a serial the key to a console.
+PROBE_VENDORS = %w[0d28 1366].freeze
+
+module FreeBSD
+    # The sysctl branches that describe the USB bus.
+    #
+    # Not the whole dev tree: that is 78K of text here against 5K for
+    # these, and it is read afresh on every lookup rather than
+    # remembered, because --method power switches ports off and on
+    # underneath us and a remembered tree would describe a bench that
+    # has since changed.
+    #
+    #   uftdi     the hub's control adapter
+    #   uhub      every hub, which is what the walk up to the bus
+    #             passes through and nothing else
+    #   umodem    a probe's CDC console -- the tty, and the serial
+    #   usbhid    a DAPLink's HID interface, and umass its drive:
+    #   umass     the same device under another driver, carrying the
+    #             same serial, so a probe whose CDC did not attach is
+    #             still answerable for
+    USB_OIDS = %w[dev.uftdi dev.uhub dev.umodem
+                  dev.usbhid dev.umass].freeze
+
+    # Every debug probe's console, keyed by the probe's serial.
+    #
+    # The probe reports its own serial, the configuration already carries
+    # that serial to address the board for flashing, and umodem says
+    # which tty the probe's CDC interface became.  No topology at all,
+    # which is what lets `connect --method serial` work anywhere.
+    def self.probe_consoles
+        self.usb_tree.filter_map {|name, dev|
+            next unless name.start_with?('umodem')
+            next unless self.probe?(dev)
+            # No ttyname, no console.  '/dev/tty' + '' is /dev/tty --
+            # the controlling terminal -- so an entry whose tty is not
+            # named yet would map a probe's serial to the operator's own
+            # screen, for connect to read as if it were a board.
+            next if dev[:ttyname].to_s.empty?
+            [ dev.dig(:'%pnpinfo', :sernum), '/dev/tty' + dev[:ttyname].to_s ]
+        }.to_h
+    end
+
+    # The console of whatever is at that USB path, or nil.
+    #
+    # At the path or below it: an nRF52840-MDK puts its own hub on the
+    # socket and its DAPLink one level down, so the port leads to the
+    # hub and the tty belongs to the child.
+    def self.usb_to_tty(path, tree: nil)
+        raise ArgumentError if path.nil?
+        tree ||= self.usb_tree
+        dev   = self.devices_at(path, tree).find {|_n, d| d[:ttyname] }&.last
+        dev && ('/dev/tty' + dev[:ttyname].to_s)
+    end
+
+    # The probe serial of whatever is at that USB path, or nil.
+    #
+    # Read from the descriptor the kernel already has, as on Linux, so
+    # it needs no SWD session and no powering the rest of the bench
+    # down.  Several drivers may claim one probe -- an MDK's DAPLink is
+    # umodem, usbhid and umass at once -- and all of them report the
+    # device's serial, so the first that is a probe with one answers.
+    #
+    # The limit here that Linux does not have: a device NO driver
+    # claimed has no sysctl node at all, there being no dev.ugen, so it
+    # cannot be seen.  A probe that enumerates and attaches nothing is
+    # invisible rather than serial-less.
+    def self.usb_to_serial(path, tree: nil)
+        raise ArgumentError if path.nil?
+        tree ||= self.usb_tree
+        self.devices_at(path, tree).each do |_name, dev|
+            next unless self.probe?(dev)
+            serial = dev.dig(:'%pnpinfo', :sernum).to_s
+            return serial unless serial.empty?
+        end
+        nil
+    end
+
+    # Is this one of the debug probes a bench carries?
+    private_class_method def self.probe?(dev)
+        vendor = dev.dig(:'%pnpinfo', :vendor).to_s.delete_prefix('0x')
+        PROBE_VENDORS.include?(vendor)
+    end
+
+    # Everything sitting at that USB path, or below it, shallowest
+    # first and then by name so that the answer does not depend on the
+    # order sysctl happened to print.
+    private_class_method def self.devices_at(path, tree)
+        tree.filter_map {|name, dev|
+            p = self.usb_path(dev, tree)
+            next unless p == path || p&.start_with?("#{path}.")
+            [ p, name, dev ]
+        }.sort_by {|p, name, _| [ p.count('.'), p, name ] }
+         .map     {|_p, name, dev| [ name, dev ] }
+    end
+
+    # Where a device sits in the USB tree, as Linux would write it.
+    #
+    # FreeBSD states no such path, but every piece of one is in the
+    # sysctl tree: %location gives the bus and the port the device
+    # occupies on its parent, and %parent names that parent -- always a
+    # uhub, up to the root hub, whose own %location is empty.
+    #
+    # A walk that does not REACH the root answers nil rather than what
+    # it collected on the way: stopping one hub short turns 1-1.2.4.4
+    # into 1-4, which is not a broken string but a different socket.
+    #
+    # The exsys gem walks the same tree for its own device, and this is
+    # deliberately not that code: its walker is a documented internal
+    # of a gem that must stand alone, and a tool reaching into one is a
+    # tool that breaks on the next release.
+    # Public: Hub::USB walks the same tree, for the hub's own path.
+    def self.usb_path(dev, tree)
+        bus    = nil
+        ports  = []
+        rooted = false
+        seen   = {}
+        while dev
+            loc = dev[:'%location']
+            unless loc.is_a?(Hash) && loc[:port]
+                rooted = true          # a root hub occupies no port
+                break
+            end
+            bus ||= loc[:bus]
+            ports.unshift(loc[:port])
+            parent = dev[:'%parent'].to_s
+            # A %parent chain that returns to a device already on the
+            # way up is not a tree.  No kernel prints one, but this
+            # parses whatever it is handed, and without the guard the
+            # answer is not a wrong path but an unbounded loop: a
+            # command that never returns and never says why.
+            break if seen[parent]
+            seen[parent] = true
+            dev = tree[parent]
+        end
+        return nil unless rooted && bus && !ports.empty?
+        "#{bus}-#{ports.join('.')}"
+    end
+
+    # Parse a sysctl -e dump into the shape below.  Split from the
+    # reading of it so that the tests can feed a capture in and run on
+    # a host with no bench, no probe, and no sysctl at all.
+    def self.parse_usb_tree(output)
+        output.lines.reduce({}) {|acc, l|
+            k, v       = l.chomp.split('=', 2)
+            next acc if k.nil?
+            dev, i, sk = k.split('.')[1..]
+            # No unit number in it -- dev.uhub.%parent -- so it
+            # describes the driver and not a device.
+            next acc if sk.nil? || i !~ /\A\d+\z/
+            if [ '%pnpinfo', '%location' ].include?(sk)
+                # Not every token in one of these is a pair: some
+                # drivers write a bare word, and a parser that died on
+                # one of them would take the whole bench with it.
+                v = Shellwords.shellsplit(v.to_s).filter_map {|e|
+                        k2, v2 = e.split('=', 2)
+                        [ k2.to_sym, v2 ] if v2
+                    }.to_h
+            end
+            acc.merge("#{dev}#{i}" => { sk.to_sym => v }) {|_k, o, n|
+                o.merge(n)
+            }
+        }
+    end
+
+    # The USB branches of the sysctl tree, as
+    #
+    #     { 'umodem0' => { :ttyname => 'U0', :'%parent' => 'uhub6',
+    #                      :'%location' => { :bus => '1', ... } } }
+    #
+    # Keyed by device name and not by unit number: several branches are
+    # read at once, %parent names a parent that way, and unit numbers
+    # repeat across drivers.
+    # Public: Hub::USB walks the same tree, to find the hubs in it.
+    def self.usb_tree
+        oids = USB_OIDS.map {|o| Shellwords.escape(o) }.join(' ')
+        self.parse_usb_tree(`/sbin/sysctl -e #{oids} 2>/dev/null`)
+    end
+end
+
+module Linux
+    # See FreeBSD.probe_consoles.  Matched on the probe's vendor, not
+    # on one probe firmware: an MDK's DAPLink and a DWM1001-DEV's
+    # J-Link OB both report a serial and both become a ttyACM.
+    def self.probe_consoles
+        Dir['/sys/class/tty/ttyACM*']
+            .map    {|path| self.udevadm_query(path) }
+            .select {|dev| PROBE_VENDORS.include?(dev[:ID_VENDOR_ID]) }
+            .to_h   {|dev| [ dev[:ID_SERIAL_SHORT], dev[:DEVNAME] ] }
+    end
+
+    def self.usb_to_tty(path)
+        raise ArgumentError if path.nil?
+        if (dev_path = Dir["/sys/bus/usb/devices/#{path}/**/tty/ttyACM*"]&.first)
+            File.join('/dev', File.basename(dev_path))
+        end
+    end
+
+    # The probe's serial, from the USB descriptor the kernel already has.
+    #
+    # Not asked of openocd: 0.12.0, the current release, prints neither
+    # the CMSIS-DAP "Serial# =" line nor a J-Link "S/N", at any debug
+    # level.  Reading the descriptor needs no SWD session, no openocd,
+    # and above all no powering the rest of the bench down to leave one
+    # adapter for openocd to find.
+    #
+    # An MDK puts its own hub in front of its DAPLink, so the probe sits
+    # one level below the hub port there while a J-Link sits on it; look
+    # at both, and take the first that is a probe with a serial.
+    def self.usb_to_serial(path)
+        raise ArgumentError if path.nil?
+        base = "/sys/bus/usb/devices/#{path}"
+        [ base, *Dir["#{base}.*"].sort ].each do |dev|
+            next unless File.file?("#{dev}/idVendor")
+            next unless PROBE_VENDORS.include?(File.read("#{dev}/idVendor").chomp)
+            next unless File.file?("#{dev}/serial")
+            serial = File.read("#{dev}/serial").chomp
+            return serial unless serial.empty?
+        end
+        nil
+    end
+
+    private_class_method def self.udevadm_query(path)
+        `/usr/bin/udevadm info -q property --export #{Shellwords.escape(path)}`
+          .lines.to_h {|l| l.split('=', 2) }
+          .transform_keys(&:to_sym)
+          .transform_values {|v| Shellwords.split(v).join(' ') }
+    end
+end
+
+
+Current = case RbConfig::CONFIG['host_os']
+          when /^linux-/  then Platform::Linux
+          when /^freebsd/ then Platform::FreeBSD
+          else raise 'Unsupported platform'
+          end
+
+
+def self.probe_consoles(...)   = Current.probe_consoles(...)
+
+# The console of the board whose probe carries this serial, or nil.
+#
+# Works on both platforms and needs no USB topology, which is what lets
+# `connect --method serial` reach a console on a host with no
+# /sys/bus/usb.
+def self.serial_to_tty(serial)
+    return nil if serial.nil?
+    self.probe_consoles[serial.to_s]
+end
+
+def self.usb_to_tty(...)       = Current.usb_to_tty(...)
+def self.usb_to_serial(...)    = Current.usb_to_serial(...)
+
+end
+
+end

data/lib/tribble-control/tally.rb

@@ -0,0 +1,91 @@
+#
+# What a board's console output means.
+#
+require_relative 'cli'
+
+module TribbleControl
+
+# A running count of what a board printed, and one line saying so.
+#
+# `connect` knows how to open a board's console, prefix its lines and
+# print them.  What a line MEANS -- a completed exchange, a failure, a
+# banner, noise -- is the firmware's business, and firmware is not what
+# this tool is about: the strings to look for change with every build
+# of every project that ever sits on this hub, and none of them belong
+# in a program whose subject is a USB hub.
+#
+# So they are not here.  A tally is the seam: `connect` hands it every
+# line it prints and asks it, once, for a summary.  The one below
+# counts lines, which is all a tool that knows nothing about the
+# firmware can honestly say.  Anything that knows more is a block,
+# registered from a file loaded with -r/--require:
+#
+#     TribbleControl::Tally.register(:twr) do |device|
+#         MyTally.new(device)
+#     end
+#
+# and chosen with `tally = twr` in the configuration, for the whole bench or
+# for one board.  The block is called once per board per run, so a
+# tally may keep whatever state it likes without sharing it.
+class Tally
+    @registry = {}
+
+    class << self
+        # Register a tally builder under +name+.  The block is given a
+        # device name and must return an object answering #<<, which
+        # receives every line, and #summary, which returns the text of
+        # the SUMMARY line or nil for no summary at all.
+        def register(name, &block)
+            raise ArgumentError, 'a tally needs a block' if block.nil?
+            @registry[name.to_s] = block
+        end
+
+        def registered = @registry.keys.sort
+
+        # Build the tally called +name+ for the device +device+.
+        #
+        # An unknown name is an error rather than a silent fallback to
+        # counting lines: a configuration asking for 'twr' on a run that
+        # forgot -r would otherwise capture a whole bench and report
+        # nothing but line counts, which reads as a firmware saying
+        # nothing rather than as a missing file.
+        def build(name, device)
+            builder = @registry[name.to_s]
+            if builder.nil?
+                raise CLI::Error, "unknown tally '#{name}'" \
+                                  " (known: #{self.registered.join(', ')})." \
+                                  ' A tally other than the built-in ones' \
+                                  ' comes from a file given with --require'
+            end
+            builder.call(device)
+        end
+    end
+
+    def initialize(device)
+        @device = device
+        @lines  = 0
+    end
+
+    def <<(_line)
+        @lines += 1
+        self
+    end
+
+    def summary = "lines=#{@lines}"
+end
+
+# The default: a board printed this many lines.
+Tally.register(:lines) {|device| Tally.new(device) }
+
+# Counts nothing, says nothing: for a capture that wants the lines and
+# no SUMMARY at all.  A null object rather than nil, so that `connect`
+# has one kind of thing to talk to.
+class NullTally
+    def initialize(device) ; @device = device ; end
+    def <<(_line)          = self
+    def summary            = nil
+end
+
+Tally.register(:none) {|device| NullTally.new(device) }
+
+end

data/lib/tribble-control/version.rb

@@ -0,0 +1,8 @@
+module TribbleControl
+
+# Bumped by hand.  The version lives here alone: the gemspec reads it
+# from this file, and `tribble-control --version` prints the same
+# constant, so a release cannot have two numbers.
+VERSION = '0.4.4'.freeze
+
+end

data/lib/tribble-control.rb

@@ -0,0 +1,32 @@
+#
+# tribble-control -- power, flash and monitor the boards plugged into a
+# switchable USB hub: an ExSYS 16-port managed hub, or any hub that
+# switches its own ports.
+#
+#     tribble-control -C tribble.conf flash zephyr.hex A1 A3
+#     tribble-control -C tribble.conf connect --off C2 B2 | tee twr.log
+#
+# A hub port may feed something that must never lose power, so
+# tribble-control refuses to switch off any port its 'protect' block
+# names, and by default any port the configuration does not declare;
+# -F/--force lifts both rules.
+#
+# Full documentation -- port map, device selection, recipes and traps --
+# is in man/man1/tribble-control.1, and is displayed by
+# `tribble-control --man`.
+#
+require_relative 'tribble-control/version'
+require_relative 'tribble-control/platform'
+require_relative 'tribble-control/hub'
+require_relative 'tribble-control/hub/exsys'
+require_relative 'tribble-control/cli'
+require_relative 'tribble-control/tally'
+
+# The commands, loaded for their side effect: CLI.commands finds them by
+# asking CLI::Command for its subclasses, so a command file that is
+# never required is a command the tool does not have.
+require_relative 'tribble-control/cli/usb'
+require_relative 'tribble-control/cli/serial'
+require_relative 'tribble-control/cli/flash'
+require_relative 'tribble-control/cli/reset'
+require_relative 'tribble-control/cli/connect'