exsys 1.0 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b64ad35673afb17f7d07e21cd404043cf832637c9247a6697a08148ca781977e
-  data.tar.gz: fd871f3815d45d51731a686cda177a28d1fb8315c72dd9a299da91bfeee1a091
+  metadata.gz: 97086399976474a8e6d5c41ca473a6b2bd385dfe65bc1a1655301510b93ce68d
+  data.tar.gz: f14819b8e580dcec1374b6ea1360628b3980c6dd7a8ea7aeb6f87ee406de312b
 SHA512:
-  metadata.gz: 0ba2590f1165d88b24642f02a27b14ce5855f42c793e46ad1d2a697ebe6c795eeddb34ffb8e0d411988e920740de7bc189839545446107bdc850332c906d19a7
-  data.tar.gz: 6c9f2cdf259a245308884fba34601a3c7040c656659472b99d0c8fed03435bc8233bb5aad21eaf87970eb2503aabdce611a62d37448a2f74e177be15d65b43be
+  metadata.gz: 3f70740de8575d2e1982b890fd33f65bc200181e73f7854435233dc325642cefd9b10103e7edacf936f0fbae6b8de8329ab97a979072713a83f49bc17ea623f6
+  data.tar.gz: 57c4f9a96bb7cf8de062101b72720bc76350ef0098081bb036632a7f3672975630a8d8eb14aee2a1837f9e283dc0e13a1ec31fbc43a71882521ef6daa1851911

data/README.md

@@ -33,6 +33,9 @@ You need read and write access to it: the device is usually owned by a
 group such as `dialout` or `plugdev`, so check `ls -l` on it and add
 yourself to that group rather than reaching for `sudo`.
 
+`exsys-usb discover` lists the lines that could be a hub, so you do not
+have to guess which one it is.  See [Finding the hub](#finding-the-hub).
+
 The hub answers only to its password, `pass` unless it has been
 changed.  Port numbering starts at 1 and runs to however many ports
 the hub reports having: the gem asks it, rather than assuming sixteen.
@@ -73,6 +76,7 @@ exsys-usb -d ${dev} -c on 1           # Turn on port 1, and save to flash
 | `toggle [PORT...]`  | Invert the listed ports, or every port          |
 | `set PORT:STATE...` | Set the listed ports; `-D` decides the rest     |
 | `status [PORT...]`  | Report the ports, one `N on` / `N off` per line |
+| `discover`          | List the lines that could be a hub              |
 | `query`             | What the hub says it is: id, ports, firmware    |
 | `commit`            | Save the current port state to flash            |
 | `factory-reset`     | Factory reset; refuses without `--yes`          |
@@ -97,7 +101,8 @@ A port state in `set` is written `PORT:STATE`, where `STATE` is one of
 
 | Option                | Meaning                                       |
 | :-------------------- | :-------------------------------------------- |
-| `-d`, `--device=DEV`  | Serial line to the hub (required)             |
+| `-d`, `--device=DEV`  | Serial line to the hub (required, but see      |
+|                       | `discover`)                                   |
 | `-p`, `--password=STR`| Hub password; defaults to `pass`              |
 | `-c`, `--commit`      | Also write the new state to flash             |
 | `-y`, `--yes`         | Mean a destructive action                     |
@@ -132,6 +137,81 @@ exsys-usb -d /dev/ttyU0 off 3 || echo "could not switch port 3 off"
 ~~~
 
 
+## Finding the hub
+
+The management side of the hub is an ordinary FTDI FT232, so the host
+can be asked which serial lines are attached and what their serial
+numbers are:
+
+~~~sh
+exsys-usb discover
+~~~
+
+~~~text
+/dev/ttyUSB0 A50285BI 1-1.2.4.4
+/dev/ttyUSB1 -        1-1.3
+~~~
+
+One line per adapter: the device to pass to `-d`, the FT232's own
+serial number, and where it sits in the USB tree.  A `-` is a name this
+host cannot give — an EEPROM carrying no serial, or a topology that
+could not be established.  The same list from Ruby:
+
+~~~ruby
+ExSYS::ManagedUSB.available
+# => [ { :device => "/dev/ttyUSB0", :serial => "A50285BI",
+#        :usb_path => "1-1.2.4.4" },
+#      { :device => "/dev/ttyUSB1", :serial => nil,
+#        :usb_path => "1-1.3" } ]
+~~~
+
+**A candidate is not a hub.**  That FT232 is not an ExSYS part and
+carries no ExSYS id, so this lists every FT232 on the host — a
+USB-serial cable, a debug probe, a second hub — and nothing short of
+opening the line and asking (`?Q`, the `query` action) tells them
+apart.  Opening an unknown line means writing to somebody else's
+device, which is why this reports rather than decides.  A program that
+switches ports should not pick one silently when there is more than
+one: the ports of an unrelated hub exist, accept the frames, and report
+success.
+
+**Write down a serial or a path, not the line.**  The number in
+`/dev/ttyUSB1` is neither the hub's nor the USB device number: it is
+the usbserial (Linux) or ucom (FreeBSD) layer's own index, and it is
+the lowest one free when that adapter is probed.  So it depends on what
+else attached first, and it is reused — unplug whatever holds
+`ttyUSB0` and the next thing to attach takes `ttyUSB0`.  Two hubs can
+swap lines across a reboot, or while the machine is up.
+
+The other two are stable, in different ways, and which one is wanted
+depends on the question:
+
+| Name       | Stays with          | Answers                          |
+| :--------- | :------------------ | :------------------------------- |
+| `:serial`  | the adapter         | "this particular hub"            |
+| `:usb_path`| the socket          | "whatever is plugged in there"   |
+
+Move a hub to another port and its serial goes with it while its path
+changes; swap in a replacement hub and the path is unchanged while the
+serial is not.  For naming one particular hub the serial is the answer.
+The path is for a hub whose EEPROM carries no serial to be named by,
+and for a bench where the socket is the fixed thing.
+
+Both platforms report a path, by different means.  Linux states it, in
+`/sys`.  FreeBSD states nothing of the kind, so it is walked out of the
+sysctl tree: each device's `%location` gives the port it occupies on
+its parent and `%parent` names that parent, so collecting the ports
+from the adapter up to the root hub builds the same shape.  The
+numbering is each host's own, though — FreeBSD counts buses from 0 and
+Linux from 1 — so a path names a socket on the machine that reported
+it and does not travel to another.
+
+Discovery reads `/sys/class/tty` through `udevadm` on Linux and
+`dev.uftdi` through `sysctl` on FreeBSD; any other platform raises
+rather than answering an empty list, an empty list being a claim that
+nothing is attached.
+
+
 ## Library
 
 ~~~ruby

data/bin/exsys-usb

@@ -94,6 +94,30 @@ begin
     when 'status'
         report.call(ARGV.map(&:to_i))
 
+    # Which line to give -d.  Needs no hub and no password: it asks the
+    # HOST what is attached, so it works before anything is known.
+    #
+    # Three columns, "line serial usb-path", '-' for one the host does
+    # not report -- the same one-record-per-line shape as status, for
+    # the same reason.  What is listed is every FT232 on the host,
+    # which is not the same as every hub: see the library documentation
+    # for ExSYS::ManagedUSB.available.
+    when 'discover'
+        found = ExSYS::ManagedUSB.available
+        found.each do |c|
+            puts [ c[:device], c[:serial] || '-',
+                   c[:usb_path] || '-' ].join(' ')
+        end
+        # On stderr, and not as a row: stdout here is a listing meant
+        # to be read by awk, and a sentence in it would be parsed as an
+        # adapter.  An operator still wants to know the command ran and
+        # found nothing, which is what stderr is for.
+        if found.empty?
+            warn "#{parser.program_name}: no FTDI" \
+                 " #{ExSYS::ManagedUSB::CTRL_VENDOR}:" \
+                 "#{ExSYS::ManagedUSB::CTRL_PRODUCT} on this host"
+        end
+
     when 'query'
         q = $hub.query
         puts "id:       #{q[:id]}"

data/lib/exsys/discovery.rb

@@ -0,0 +1,314 @@
+require 'open3'
+require 'rbconfig'
+require 'shellwords'
+
+require_relative 'managed-usb'
+
+module ExSYS
+
+class ManagedUSB
+
+    # USB vendor and product of the hub's management adapter.
+    #
+    # It is not an ExSYS id.  The management side of the hub is an
+    # ordinary FTDI FT232, so this pair matches the hub AND every other
+    # FT232 attached to the host: a USB-serial cable, a debug probe,
+    # a second hub.  Nothing short of opening the line and asking it
+    # (?Q, see {#query}) tells them apart, and opening an unknown line
+    # means writing to somebody else's device.
+    #
+    # So {available} reports candidates, and choosing between them is
+    # the caller's -- see the note there.
+    CTRL_VENDOR  = '0403'.freeze
+    CTRL_PRODUCT = '6001'.freeze
+
+    # What a USB path looks like: a bus, a dash, and the chain of hub
+    # ports leading to the device -- 1-1.2.4.4.  Published so that a
+    # caller taking a device name from a human or a configuration file
+    # can tell one from a serial number without inventing the pattern
+    # again; the two cannot be confused, a serial never being digits
+    # and dashes in this shape.
+    USB_PATH = /\A\d+-\d+(?:\.\d+)*\z/
+
+    # Every serial line on this host that could be a managed hub.
+    #
+    # Each entry carries the names the host knows the adapter by:
+    #
+    #     [ { :device   => '/dev/ttyUSB0',
+    #         :serial   => 'AL03GD7X',
+    #         :usb_path => '1-1.2.4.4' },
+    #       { :device   => '/dev/ttyUSB1',
+    #         :serial   => nil,
+    #         :usb_path => '1-1.3' } ]
+    #
+    # `:device` is the line, as {#initialize} wants it.
+    #
+    # `:serial` is the FT232's own serial number, from its EEPROM, or
+    # nil for a chip carrying none -- an FT232R ships with one, an
+    # unprogrammed EEPROM is possible.
+    #
+    # `:usb_path` is where the adapter sits in the USB tree ({USB_PATH}),
+    # or nil where one cannot be established.  Linux states it; FreeBSD
+    # does not, and it is walked out of the sysctl tree instead (see
+    # Discovery::FreeBSD.usb_path).
+    #
+    # The shape is the same on both and the NUMBERING is each host's
+    # own: FreeBSD counts buses from 0 and Linux from 1, and neither
+    # orders its controllers for the other's benefit.  A path names a
+    # socket on the host that reported it, and does not travel.
+    #
+    # The two are stable in DIFFERENT ways, and which is wanted depends
+    # on the question.  A serial follows the adapter: move the hub to
+    # another socket, another port, another machine, and its serial goes
+    # with it.  A USB path follows the socket: whatever is plugged in
+    # there answers to it, including a replacement hub.  For naming one
+    # particular hub the serial is the answer; the path is for a hub
+    # with no serial to be named by, and for a bench where the socket is
+    # the thing that is fixed.
+    #
+    # Prefer one of them over the line for anything written down.  The number in
+    # /dev/ttyUSB1 is neither the hub's nor the USB device number: it is
+    # the usbserial (Linux) or ucom (FreeBSD) layer's own index, and it
+    # is the lowest one free when that adapter is probed.  It therefore
+    # depends on what else attached first, and it is reused -- unplug
+    # whatever holds ttyUSB0 and the next thing to attach takes
+    # ttyUSB0.  Two hubs can swap lines across a reboot, or while the
+    # machine is up.  The serial cannot move.
+    #
+    # ONE candidate is not proof that it is a hub, and several are not
+    # a list of hubs: see {CTRL_VENDOR}.  A caller that switches ports
+    # should therefore not pick one silently when there is more than
+    # one -- the ports of an unrelated hub exist, accept the frames,
+    # and report success.
+    #
+    # @return [Array<Hash>] one { :device, :serial } per FT232 found,
+    #                       in whatever order the host lists them
+    # @raise  [Error] if this platform has no way to look, or the tool
+    #                 that does the looking is not installed
+    def self.available = Discovery.available
+
+    # Asking the host what is attached.
+    #
+    # Each platform answers by running the tool that already knows --
+    # udevadm on Linux, sysctl on FreeBSD -- and each keeps the running
+    # and the parsing apart, so that the parsing can be tested against
+    # captured output on a machine with nothing plugged in.
+    module Discovery                                # @!visibility private
+
+        def self.available
+            case RbConfig::CONFIG['host_os']
+            when /^linux/   then Linux.available
+            when /^freebsd/ then FreeBSD.available
+            else raise Error, 'no hub discovery for this platform' \
+                              " (#{RbConfig::CONFIG['host_os']}):" \
+                              ' name the serial line instead'
+            end
+        end
+
+        # An absent USB string descriptor arrives as an empty one, not
+        # as nothing: udevadm prints ID_SERIAL_SHORT='' and uftdi's
+        # pnpinfo sernum="".  Both mean the EEPROM carries no serial,
+        # and nothing may be identified by ''.
+        def self.nonempty(str)
+            s = str.to_s
+            s.empty? ? nil : s
+        end
+
+        # What a platform reader ran, when it is not there at all.
+        # Reported rather than swallowed: an empty list would read as
+        # "no hub attached", which is a different thing and a lie.
+        def self.missing(tool, error)
+            raise Error, "cannot look for a hub: #{tool} (#{error.message})"
+        end
+
+        # Run a reader, and hand back only what it printed.
+        #
+        # Open3 with the arguments given SEPARATELY, and never a
+        # backtick: a backtick takes a single string, and a single
+        # string with a redirection or a metacharacter in it is run by
+        # /bin/sh -- which reports a missing binary ITSELF, as exit
+        # 127 and no output, so Errno::ENOENT never reaches Ruby and
+        # the rescue above becomes dead code.  That is exactly how
+        # this once answered "no hub attached" on a host with no
+        # sysctl.  Passing the arguments apart from the command runs
+        # it directly: no shell, no quoting, and a missing binary
+        # raises.
+        #
+        # stderr is dropped rather than redirected, for one message:
+        # with no FTDI ever attached the uftdi driver is not loaded,
+        # the oid does not exist, and sysctl says so on stderr while
+        # printing nothing.  That is not an error -- it is the answer,
+        # an empty list -- and a library has no business writing it to
+        # the terminal.  The exit status cannot tell the two apart
+        # either: sysctl exits 1 for an unknown oid, and 1 just the
+        # same when only one of several is unknown.
+        def self.run(tool, *args)
+            out, _err, _status = Open3.capture3(tool, *args)
+            out
+        rescue Errno::ENOENT, Errno::EACCES => e
+            self.missing(tool, e)
+        end
+
+
+        module Linux
+            UDEVADM = '/usr/bin/udevadm'
+
+            def self.available
+                Dir['/sys/class/tty/ttyUSB*'].sort.filter_map {|path|
+                    self.candidate(self.properties(path))
+                }
+            end
+
+            # One candidate, or nil for an adapter that is not an FT232.
+            def self.candidate(props)
+                return nil unless props[:ID_VENDOR_ID] == CTRL_VENDOR &&
+                                  props[:ID_MODEL_ID]  == CTRL_PRODUCT
+                { :device   => props[:DEVNAME],
+                  :serial   => Discovery.nonempty(props[:ID_SERIAL_SHORT]),
+                  :usb_path => self.usb_path(props[:DEVPATH]) }
+            end
+
+            # The adapter's own place in the USB tree, out of the sysfs
+            # path the tty hangs off.
+            #
+            # DEVPATH carries the whole chain -- the bus, every hub
+            # between, the device, its interface, then the tty:
+            #
+            #     .../usb1/1-1/1-1.2/1-1.2.4/1-1.2.4.4/1-1.2.4.4:1.0/
+            #         ttyUSB0/tty/ttyUSB0
+            #
+            # Every hub on the way matches {USB_PATH} as well, so it is
+            # the LAST match that is the device itself; the interface
+            # component after it carries a ':' and matches nothing.
+            def self.usb_path(devpath)
+                devpath.to_s.split('/').grep(USB_PATH).last
+            end
+
+            # udevadm's --export format: KEY='value' a line, the value
+            # quoted the way a shell would want it.
+            def self.parse(export)
+                export.lines.to_h {|l| l.split('=', 2) }
+                      .transform_keys(&:to_sym)
+                      .transform_values {|v| Shellwords.split(v).join(' ') }
+            end
+
+            def self.properties(path)
+                self.parse(Discovery.run(UDEVADM, 'info', '-q', 'property',
+                                         '--export', path))
+            end
+        end
+
+
+        module FreeBSD
+            SYSCTL = '/sbin/sysctl'
+
+            # The two branches read together, in one call: the adapters
+            # themselves, and every hub, which is what the walk from an
+            # adapter up to its bus passes through and nothing else.
+            OIDS = %w[dev.uftdi dev.uhub].freeze
+
+            def self.available
+                tree = self.parse(self.read(*OIDS))
+                tree.filter_map {|name, dev|
+                    next unless name.start_with?('uftdi')
+                    self.candidate(dev, tree)
+                }
+            end
+
+            def self.candidate(dev, tree = {})
+                pnp = dev[:'%pnpinfo']
+                return nil unless pnp.is_a?(Hash)
+                return nil unless pnp[:vendor]  == "0x#{CTRL_VENDOR}" &&
+                                  pnp[:product] == "0x#{CTRL_PRODUCT}"
+                { :device   => '/dev/tty' + dev[:ttyname].to_s,
+                  :serial   => Discovery.nonempty(pnp[:sernum]),
+                  :usb_path => self.usb_path(dev, tree) }
+            end
+
+            # The adapter's place in the USB tree, built by walking it.
+            #
+            # There is no /sys/bus/usb here and nothing states a path,
+            # but every piece of one is in the sysctl tree.  A device's
+            # %location gives the bus and the port it occupies on its
+            # parent, and its %parent names that parent -- always a
+            # uhub, up to the root hub, whose own %location is empty
+            # and whose parent is the usbus.  Collecting the ports on
+            # the way up and reversing them is the path:
+            #
+            #     uftdi0  port=4  parent=uhub5 ┐
+            #     uhub5   port=4  parent=uhub4 │  1-1.1.4.4
+            #     uhub4   port=1  parent=uhub2 │
+            #     uhub2   port=1  parent=uhub0 ┘  (root: stop)
+            #
+            # The shape is Linux's, and the numbering is this host's.
+            # FreeBSD counts buses from 0 and Linux from 1, and neither
+            # orders its controllers for the other's benefit, so the
+            # same socket is not the same string on the two systems.  A
+            # path names a socket on THIS host; see {USB_PATH}.
+            # A walk that does not REACH the root hub answers nil.
+            # Running off the end of the tree -- a parent nothing read
+            # describes -- leaves the ports collected so far, which
+            # read as a whole path and are not one: stopping one hub
+            # short of the root turns 1-1.1.4.4 into 1-4, a path that
+            # exists, names a socket, and is the wrong one.
+            def self.usb_path(dev, tree)
+                bus    = nil
+                ports  = []
+                rooted = false
+                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])
+                    dev = tree[dev[:'%parent'].to_s]
+                end
+                return nil unless rooted && bus && !ports.empty?
+                "#{bus}-#{ports.join('.')}"
+            end
+
+            # sysctl -e output, as { "uftdi0" => { key => value } }.
+            #
+            # Keyed by the device's name and not by its unit number:
+            # two branches are read at once, %parent names a parent
+            # that way, and unit numbers repeat across drivers.
+            #
+            # The two keys holding a list of their own -- %pnpinfo and
+            # %location -- are split into a hash of their own, since
+            # what is wanted is inside them.
+            def self.parse(output)
+                output.lines.map(&:chomp).reduce({}) {|acc, l|
+                    k, v     = l.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:
+                        # dev.acpi_timer.0.%pnpinfo is the bare word
+                        # 'unknown'.  Nothing outside a USB branch is
+                        # read today, but a parser that dies on one
+                        # driver's wording would take the hub 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
+
+            def self.read(*keys)
+                Discovery.run(SYSCTL, '-e', *keys)
+            end
+        end
+    end
+end
+
+end

data/lib/exsys/version.rb

@@ -1,3 +1,3 @@
 module ExSYS
-    VERSION = '1.0'  # Version
+    VERSION = '1.1'  # Version
 end

data/lib/exsys.rb

@@ -3,3 +3,4 @@ end
 
 require_relative 'exsys/version'
 require_relative 'exsys/managed-usb'
+require_relative 'exsys/discovery'

data/test/test_discovery.rb

@@ -0,0 +1,241 @@
+require_relative 'helper'
+
+# Finding the hub's serial line, per platform.
+#
+# The reading and the parsing are kept apart in Discovery precisely so
+# that this runs on a machine with nothing attached: what is asserted
+# here is the parsing, against the output the two tools produce, and
+# not that this host has a hub on it.
+class TestDiscovery < Minitest::Test
+    D = ExSYS::ManagedUSB::Discovery
+
+    # sysctl -e dev.uftdi dev.uhub.
+    #
+    # The uhub half is captured verbatim from a real FreeBSD host --
+    # two controllers, a Genesys hub on one and a chain of two TI hubs
+    # on the other -- because the walk that builds a USB path out of it
+    # is the part worth testing against something nobody invented.
+    #
+    # The uftdi half is written: three adapters, one hanging off the
+    # deepest hub, one whose EEPROM carries no serial, and an FT230X,
+    # which uftdi drives too and which is not what is wanted.
+    UHUB = <<~'SYSCTL'
+        dev.uhub.%parent=
+        dev.uhub.0.%location=
+        dev.uhub.0.%parent=usbus1
+        dev.uhub.1.%location=
+        dev.uhub.1.%parent=usbus0
+        dev.uhub.2.%location=bus=1 hubaddr=1 port=1 devaddr=3 interface=0 ugen=ugen1.3
+        dev.uhub.2.%parent=uhub0
+        dev.uhub.3.%location=bus=0 hubaddr=1 port=2 devaddr=2 interface=0 ugen=ugen0.2
+        dev.uhub.3.%parent=uhub1
+        dev.uhub.4.%location=bus=1 hubaddr=3 port=1 devaddr=4 interface=0 ugen=ugen1.4
+        dev.uhub.4.%parent=uhub2
+        dev.uhub.5.%location=bus=1 hubaddr=4 port=4 devaddr=5 interface=0 ugen=ugen1.5
+        dev.uhub.5.%parent=uhub4
+    SYSCTL
+
+    UFTDI = <<~'SYSCTL'
+        dev.uftdi.0.%desc=FTDI FT232R USB UART
+        dev.uftdi.0.%driver=uftdi
+        dev.uftdi.0.%location=bus=1 hubaddr=5 port=4 devaddr=9 interface=0 ugen=ugen1.9
+        dev.uftdi.0.%pnpinfo=vendor=0x0403 product=0x6001 devclass=0x00 devsubclass=0x00 devproto=0x00 sernum="AL03GD7X" release=0x0600 mode=host intclass=0xff intsubclass=0xff intprotocol=0xff
+        dev.uftdi.0.%parent=uhub5
+        dev.uftdi.0.ttyname=U0
+        dev.uftdi.0.ttyports=1
+        dev.uftdi.1.%desc=FTDI FT232R USB UART
+        dev.uftdi.1.%driver=uftdi
+        dev.uftdi.1.%location=bus=0 hubaddr=2 port=3 devaddr=7 interface=0 ugen=ugen0.7
+        dev.uftdi.1.%pnpinfo=vendor=0x0403 product=0x6001 devclass=0x00 devsubclass=0x00 devproto=0x00 sernum="" release=0x0600 mode=host intclass=0xff intsubclass=0xff intprotocol=0xff
+        dev.uftdi.1.%parent=uhub3
+        dev.uftdi.1.ttyname=U1
+        dev.uftdi.1.ttyports=1
+        dev.uftdi.2.%desc=FTDI FT230X Basic UART
+        dev.uftdi.2.%driver=uftdi
+        dev.uftdi.2.%pnpinfo=vendor=0x0403 product=0x6015 devclass=0x00 devsubclass=0x00 devproto=0x00 sernum="DT04H6789" release=0x1000 mode=host intclass=0xff intsubclass=0xff intprotocol=0xff
+        dev.uftdi.2.%parent=uhub3
+        dev.uftdi.2.ttyname=U2
+        dev.uftdi.2.ttyports=1
+    SYSCTL
+
+    # udevadm info -q property --export, for one FT232R.
+    UDEVADM = <<~'UDEV'
+        DEVNAME='/dev/ttyUSB0'
+        DEVPATH='/devices/pci0000:00/0000:00:14.0/usb1/1-1/1-1.2/1-1.2.4/1-1.2.4.4/1-1.2.4.4:1.0/ttyUSB0/tty/ttyUSB0'
+        ID_BUS='usb'
+        ID_MODEL='FT232R_USB_UART'
+        ID_MODEL_ID='6001'
+        ID_SERIAL_SHORT='A50285BI'
+        ID_VENDOR_ID='0403'
+        MAJOR='188'
+        SUBSYSTEM='tty'
+    UDEV
+
+    def freebsd(text = UFTDI + UHUB)
+        tree = D::FreeBSD.parse(text)
+        tree.filter_map {|name, dev|
+            next unless name.start_with?('uftdi')
+            D::FreeBSD.candidate(dev, tree)
+        }
+    end
+
+    def test_freebsd_reports_the_line_the_serial_and_the_path
+        assert_equal({ :device   => '/dev/ttyU0',
+                       :serial   => 'AL03GD7X',
+                       :usb_path => '1-1.1.4.4' }, freebsd.first)
+    end
+
+    # Nothing on FreeBSD states a path: it is walked, %parent by
+    # %parent, and the ports collected on the way up.  uftdi0 sits on
+    # port 4 of uhub5, which is on port 4 of uhub4, which is on port 1
+    # of uhub2, which is on port 1 of the root hub of bus 1.
+    def test_the_path_is_walked_up_to_the_root_hub
+        tree = D::FreeBSD.parse(UFTDI + UHUB)
+        assert_equal '1-1.1.4', D::FreeBSD.usb_path(tree['uhub5'], tree)
+        assert_equal '1-1.1',   D::FreeBSD.usb_path(tree['uhub4'], tree)
+        assert_equal '0-2',     D::FreeBSD.usb_path(tree['uhub3'], tree)
+    end
+
+    # A root hub occupies no port on anything: its %location is empty.
+    def test_a_root_hub_has_no_path_of_its_own
+        tree = D::FreeBSD.parse(UFTDI + UHUB)
+        assert_nil D::FreeBSD.usb_path(tree['uhub0'], tree)
+    end
+
+    # Without the hubs there is nothing to walk.  The half-built
+    # answer is the dangerous one: the adapter's own port alone reads
+    # as a whole path -- 1-4 rather than 1-1.1.4.4 -- and names a real
+    # socket that is not this one.
+    def test_a_walk_that_never_reaches_the_root_is_nil
+        assert_nil freebsd(UFTDI).first[:usb_path]
+    end
+
+    # An unprogrammed EEPROM answers sernum="", and nothing may be
+    # identified by an empty string.
+    # The case the path exists for: no serial to be named by, and the
+    # socket is then the only stable name it has.
+    def test_an_empty_serial_is_nil_and_the_path_is_still_there
+        assert_equal({ :device   => '/dev/ttyU1',
+                       :serial   => nil,
+                       :usb_path => '0-2.3' }, freebsd[1])
+    end
+
+    # uftdi drives every FTDI part, not only the one the hub uses.
+    def test_another_ftdi_part_is_not_a_candidate
+        refute_includes freebsd.map {|c| c[:device] }, '/dev/ttyU2'
+        assert_equal 2, freebsd.size
+    end
+
+    # dev.uhub.%parent has no unit number in it and must not become a
+    # device.  Two branches are read at once, so the key is the name.
+    def test_the_driver_wide_key_is_not_taken_for_a_device
+        keys = D::FreeBSD.parse(UFTDI + UHUB).keys
+        assert_includes keys, 'uftdi0'
+        assert_includes keys, 'uhub5'
+        refute_includes keys, 'uhub'
+        assert_equal 9, keys.size
+    end
+
+    # Not every token in a %pnpinfo is a key=value pair --
+    # dev.acpi_timer.0.%pnpinfo is the bare word 'unknown' -- and a
+    # parser that died on one driver's wording would take the hub
+    # with it.
+    def test_a_field_that_is_not_a_pair_does_not_stop_the_parse
+        tree = D::FreeBSD.parse(<<~'SYSCTL')
+            dev.uftdi.0.%pnpinfo=unknown vendor=0x0403 product=0x6001 sernum="AL03GD7X"
+            dev.uftdi.0.ttyname=U0
+        SYSCTL
+        assert_equal '0x0403', tree['uftdi0'][:'%pnpinfo'][:vendor]
+    end
+
+    def test_nothing_attached_is_an_empty_list_not_an_error
+        assert_empty freebsd('')
+    end
+
+    def test_linux_reports_the_line_the_serial_and_the_path
+        assert_equal({ :device   => '/dev/ttyUSB0',
+                       :serial   => 'A50285BI',
+                       :usb_path => '1-1.2.4.4' },
+                     D::Linux.candidate(D::Linux.parse(UDEVADM)))
+    end
+
+    # Every hub on the way to the device matches the shape too, so it
+    # is the last match that is the adapter -- not 1-1, not 1-1.2.
+    def test_the_usb_path_is_the_device_not_a_hub_above_it
+        assert_equal '1-1.2.4.4', D::Linux.usb_path(
+            '/devices/pci0000:00/usb1/1-1/1-1.2/1-1.2.4/1-1.2.4.4/' \
+            '1-1.2.4.4:1.0/ttyUSB0/tty/ttyUSB0')
+    end
+
+    def test_a_devpath_with_no_usb_component_has_no_path
+        assert_nil D::Linux.usb_path('/devices/platform/serial8250/ttyS0')
+    end
+
+    # The published shape, so that a caller can tell a path typed by a
+    # human from a serial number.
+    def test_what_a_usb_path_looks_like
+        assert_match     ExSYS::ManagedUSB::USB_PATH, '1-1.2.4.4'
+        assert_match     ExSYS::ManagedUSB::USB_PATH, '2-3'
+        refute_match     ExSYS::ManagedUSB::USB_PATH, 'AL03GD7X'
+        refute_match     ExSYS::ManagedUSB::USB_PATH, '1-1.2.4.4:1.0'
+        refute_match     ExSYS::ManagedUSB::USB_PATH, '/dev/ttyUSB0'
+    end
+
+    def test_linux_skips_an_adapter_that_is_not_the_right_part
+        props = D::Linux.parse(UDEVADM.sub("'6001'", "'6015'"))
+        assert_nil D::Linux.candidate(props)
+    end
+
+    def test_linux_unquotes_the_export_format
+        assert_equal '/dev/ttyUSB0', D::Linux.parse(UDEVADM)[:DEVNAME]
+    end
+
+    # The public name delegates, so that a caller has one thing to call.
+    def test_available_is_what_the_platform_answered
+        found = [ { :device   => '/dev/ttyU0', :serial => 'AL03GD7X',
+                    :usb_path => nil } ]
+        D.stub(:available, found) do
+            assert_equal found, ExSYS::ManagedUSB.available
+        end
+    end
+
+    # A platform with no way to look says so.  An empty list would read
+    # as "no hub attached", which is a different thing and a lie.
+    def test_a_platform_we_cannot_look_on_is_an_error
+        RbConfig::CONFIG.stub(:[], 'solaris2.11') do
+            e = assert_raises(ExSYS::ManagedUSB::Error) { D.available }
+            assert_match(/no hub discovery for this platform/, e.message)
+            assert_match(/solaris2\.11/,                       e.message)
+        end
+    end
+
+    def test_a_missing_tool_is_an_error_too
+        e = assert_raises(ExSYS::ManagedUSB::Error) {
+            D.missing('/sbin/sysctl', Errno::ENOENT.new('/sbin/sysctl'))
+        }
+        assert_match(%r{cannot look for a hub: /sbin/sysctl}, e.message)
+    end
+
+    # Regression, and the reason Discovery.run exists.  This reader
+    # once ran `sysctl ... 2>/dev/null` in a backtick; the redirection
+    # made Ruby hand the string to /bin/sh, which reports a missing
+    # binary itself as exit 127 with no output, so Errno::ENOENT never
+    # reached the rescue and a host with no sysctl answered "no hub
+    # attached" -- the exact lie the comment there warns against.
+    #
+    # The status cannot stand in for it either: sysctl exits 1 for an
+    # unknown oid, which is the legitimate empty answer.
+    def test_a_reader_that_is_not_installed_raises_rather_than_answering_none
+        e = assert_raises(ExSYS::ManagedUSB::Error) {
+            D.run('/nonexistent/sysctl', '-e', 'dev.uftdi')
+        }
+        assert_match(%r{cannot look for a hub: /nonexistent/sysctl},
+                     e.message)
+    end
+
+    # ... and a reader that IS installed, asked for an oid this host
+    # has not got, answers nothing at all rather than raising.
+    def test_an_oid_that_does_not_exist_is_an_empty_answer
+        assert_empty D.run('/usr/bin/env', 'true')
+    end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exsys
 version: !ruby/object:Gem::Version
-  version: '1.0'
+  version: '1.1'
 platform: ruby
 authors:
 - Stéphane D'Alu
@@ -81,11 +81,13 @@ files:
 - bin/exsys-usb
 - exsys.gemspec
 - lib/exsys.rb
+- lib/exsys/discovery.rb
 - lib/exsys/managed-usb.rb
 - lib/exsys/version.rb
 - test/helper.rb
 - test/support/fake_hub.rb
 - test/support/uart.rb
+- test/test_discovery.rb
 - test/test_exsys_usb.rb
 - test/test_managed_usb.rb
 - test/test_readme.rb