exsys 0.6 → 1.1

data/test/support/fake_hub.rb

@@ -7,8 +7,9 @@
 class FakeHub
     DEFAULT_PASSWORD = 'pass'.ljust(8)
 
-    attr_reader   :log, :opens, :locks, :line, :speed, :mode
-    attr_accessor :password, :silent, :lockable, :garbage
+    attr_reader   :log, :opens, :locks, :line, :speed, :mode, :lock_path
+    attr_accessor :password, :silent, :lockable, :garbage, :lock_error,
+                  :ident
 
     # @param state    [Integer] initial port bitmap
     # @param path     [String]  file backing the state, so that separate
@@ -18,13 +19,19 @@ class FakeHub
     # @param delay    [Float]   pause inside a write, widening the
     #                            window a concurrent process could slip
     #                            into
+    # @param ports [Integer] how many ports this hub has
+    # @param width [Integer] hex digits in its state word.  Real hubs
+    #                         answer wider than their port count: a
+    #                         16-port unit answers eight, and the ports
+    #                         it does not have read as 1.
     def initialize(password: DEFAULT_PASSWORD, state: 0x0000,
+                   ports: 16, width: 8,
                    path: nil, lock: nil, delay: 0)
         @password = password
         @state    = state
         @flash    = state
         @path     = path
-        @lock     = lock
+        @lock_path = lock
         @delay    = delay
         @log      = []
         @opens    = 0
@@ -32,6 +39,10 @@ class FakeHub
         @silent   = false     # hub answers nothing at all
         @lockable = true      # platform allows locking the line
         @garbage  = nil       # hub answers this instead, when set
+        @lock_error = nil     # raised by flock; for the propagation test
+        @ports    = ports
+        @width    = width
+        @ident    = format('CENTOS0005%02dv02', ports)  # nil = refuse ?Q
 
         # Attach to the hub the file already describes, so that a test
         # can inspect what its subprocesses did; seed it otherwise.
@@ -57,9 +68,20 @@ class FakeHub
     # Ports currently powered, as a sorted list -- the oracle the tests
     # compare against.
     def ports_on
-        1.upto(16).select {|p| state & (1 << (p-1)) != 0 }
+        1.upto(@ports).select {|p| state & (1 << (p-1)) != 0 }
     end
 
+    # The power-on state the hub would come back to.
+    def flash_ports
+        1.upto(@ports).select {|p| flash & (1 << (p-1)) != 0 }
+    end
+
+    # Bits for ports this hub does not have.  A real one reports them
+    # set, which is why a client must write back what it read.
+    def absent = ((1 << (@width * 4)) - 1) & ~real
+
+    def real = (1 << @ports) - 1
+
     # Record how the line was opened, so a test can check the library
     # asks for the device and the speed the hub actually needs.
     def opened(line, speed, mode)
@@ -67,18 +89,13 @@ class FakeHub
         @opens += 1
     end
 
-    def flock(mode)
-        raise Errno::ENOTSUP unless @lockable
+    # Called by each opened line before it locks.  The lock handle
+    # itself belongs to the line, not to the hub, so that two threads
+    # hold two of them and genuinely contend.
+    def lock_attempted
+        raise @lock_error            if @lock_error   # must NOT be swallowed
+        raise Errno::ENOTSUP         unless @lockable # platform refusal
         @locks += 1
-        return 0 if @lock.nil?
-
-        @lockfh = File.open(@lock, File::RDWR|File::CREAT, 0o600)
-        @lockfh.flock(mode)
-    end
-
-    def unlock
-        @lockfh&.close
-        @lockfh = nil
     end
 
     # Answer one command, as the hub would.
@@ -99,9 +116,10 @@ class FakeHub
         code = cmd[0, 2]
         args = cmd[2..].to_s
 
-        # GP is the one command the hub answers unauthenticated, with a
-        # bare 8-digit payload rather than a G/E status.
-        return encode(@state) + 'FFFF' if code == 'GP'
+        # GP and ?Q are the two commands the hub answers without a
+        # password, both with a bare payload rather than a G/E status.
+        return encode(@state | absent)  if code == 'GP'
+        return @ident || 'E01'         if code == '?Q'
 
         return 'E01' unless args.start_with?(@password)
         rest = args[@password.size..]
@@ -109,21 +127,29 @@ class FakeHub
         sleep @delay if @delay.positive?
 
         case code
-        when 'SP' then @state = decode(rest)             ; 'G'
-        when 'FP' then @state = @flash = decode(rest)    ; 'G'
+        when 'SP' then @state = decode(rest) & real      ; 'G'
+        when 'FP' then @state = @flash = decode(rest) & real ; 'G'
         when 'WP' then @flash = @state                   ; 'G'
-        when 'RD' then @state = @flash                   ; 'G'
+        when 'RD' then @state = @flash = 0
+                       @password = DEFAULT_PASSWORD            ; 'G'
         when 'RH' then @state = @flash                   ; nil
         when 'CP' then @password = rest                  ; 'G'
         else           'E02'
         end
     end
 
-    # Little-endian 16-bit, spelled out rather than packed.  Upper case
-    # because that is what a real hub answers -- observed on an ExSYS
-    # 16-port unit, which replies to GP with e.g. "C4FFFFFF".
-    def encode(v) = format('%02X%02X', v & 0xff, (v >> 8) & 0xff)
-    def decode(s) = s[0, 2].to_i(16) | (s[2, 2].to_i(16) << 8)
+    # Little-endian, any width, spelled out rather than packed.  Upper
+    # case because that is what a real hub answers -- observed on an
+    # ExSYS 16-port unit, which replies to GP with "C4FFFFFF".
+    def encode(v)
+        (@width / 2).times.map {|i| format('%02X', (v >> (8 * i)) & 0xff) }
+                    .join
+    end
+
+    def decode(str)
+        str.scan(/\h\h/).each_with_index
+           .sum {|byte, i| byte.to_i(16) << (8 * i) }
+    end
 
     def load
         return if @path.nil? || !File.exist?(@path)

data/test/support/uart.rb

@@ -18,12 +18,29 @@ module UART
         def reset! = @hub = nil
     end
 
-    # Stands in for the File that UART.open normally yields.
+    # Stands in for the File that UART.open normally yields.  Each one
+    # carries its own lock handle, as a real open would, so that two of
+    # them contend instead of sharing one.
     class Serial
-        def initialize(hub) = @hub = hub
-        def flock(mode)     = @hub.flock(mode)
-        def write(cmd)      = @reply = @hub.command(cmd.chomp("\r"))
-        def read            = @reply.nil? ? '' : "#{@reply}\r"
+        def initialize(hub)
+            @hub  = hub
+            @lock = hub.lock_path &&
+                    File.open(hub.lock_path, File::RDWR|File::CREAT, 0o600)
+        end
+
+        def flock(mode)
+            @hub.lock_attempted
+            @lock ? @lock.flock(mode) : 0
+        end
+
+        def write(cmd) = @reply = @hub.command(cmd.chomp("\r"))
+
+        # A real hub ends every reply CR LF -- seen in the hex off the
+        # wire -- so a read to the terminator takes the whole line.
+        def gets(_sep = "\n")
+            @reply.nil? ? nil : "#{@reply}\r\n"
+        end
+        def close      = @lock&.close
     end
 
     def self.open(line, speed = 9600, mode = '8N1')
@@ -34,7 +51,7 @@ module UART
         begin
             yield serial
         ensure
-            hub.unlock
+            serial.close
         end
     end
 end

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

data/test/test_exsys_usb.rb

@@ -50,19 +50,104 @@ class TestExsysUsb < Minitest::Test
         assert_equal [ 3 ], hub.ports_on
     end
 
-    def test_commit_and_restore
+    def test_commit_saves_the_power_on_state
         exsys_usb('on', '1')
         exsys_usb('commit')
         exsys_usb('on', '2')
-        exsys_usb('restore')
-        assert_equal [ 1 ], hub.ports_on
+        assert_equal [ 1, 2 ], hub.ports_on
+        assert_equal [ 1 ],    hub.flash_ports
     end
 
     def test_commit_flag_writes_through
         exsys_usb('-c', 'on', '4')
         exsys_usb('on', '5')
-        exsys_usb('restore')
-        assert_equal [ 4 ], hub.ports_on
+        assert_equal [ 4, 5 ], hub.ports_on
+        assert_equal [ 4 ],    hub.flash_ports
+    end
+
+    # restore issues RD, the hub's factory reset -- not the inverse of
+    # commit.  Nothing in the protocol reloads the flashed state.
+    def test_restore_is_a_factory_reset
+        exsys_usb('on', '1')
+        exsys_usb('commit')
+        _, err, st = exsys_usb('--yes', 'factory-reset')
+        assert_equal 0, st.exitstatus, err
+        assert_empty hub.ports_on
+        assert_empty hub.flash_ports
+    end
+
+    ## Reading the hub ##################################################
+
+    def test_status_lists_every_port
+        exsys_usb('on', '1', '3')
+        out, _, st = exsys_usb('status')
+        assert_equal 0, st.exitstatus
+        assert_equal 16, out.lines.size
+        assert_includes out.lines, "1 on\n"
+        assert_includes out.lines, "2 off\n"
+        assert_includes out.lines, "3 on\n"
+    end
+
+    def test_status_can_be_asked_about_named_ports
+        exsys_usb('on', '3')
+        out, _, = exsys_usb('status', '3', '4')
+        assert_equal "3 on\n4 off\n", out
+    end
+
+    def test_status_refuses_a_port_the_hub_does_not_have
+        _, err, st = exsys_usb('status', '99')
+        assert_equal 1, st.exitstatus
+        assert_match(/invalid port: 99/, err)
+    end
+
+    def test_query_reports_what_the_hub_says_it_is
+        out, _, st = exsys_usb('query')
+        assert_equal 0, st.exitstatus
+        assert_match(/^id:\s+CENTOS$/,   out)
+        assert_match(/^ports:\s+16$/,    out)
+        assert_match(/^firmware:\s+v02$/, out)
+    end
+
+    ## Verbose ##########################################################
+
+    def test_verbose_reports_the_state_after_a_change
+        out, _, = exsys_usb('-v', 'on', '2')
+        assert_includes out.lines, "2 on\n"
+        assert_equal 16, out.lines.size
+    end
+
+    def test_without_verbose_a_change_says_nothing
+        out, _, st = exsys_usb('on', '2')
+        assert_equal 0, st.exitstatus
+        assert_empty out
+    end
+
+    ## Confirming the irreversible ######################################
+
+    def test_reset_refuses_without_yes
+        _, err, st = exsys_usb('reset')
+        assert_equal 1, st.exitstatus
+        assert_match(/--yes/, err)
+    end
+
+    def test_reset_runs_when_meant
+        _, err, st = exsys_usb('--yes', 'reset')
+        assert_equal 0, st.exitstatus, err
+    end
+
+    def test_factory_reset_refuses_without_yes
+        exsys_usb('on', '1')
+        _, err, st = exsys_usb('factory-reset')
+        assert_equal 1, st.exitstatus
+        assert_match(/--yes/, err)
+        assert_equal [ 1 ], hub.ports_on, 'the hub must not have been touched'
+    end
+
+    def test_factory_reset_runs_when_meant
+        exsys_usb('on', '1')
+        _, err, st = exsys_usb('--yes', 'factory-reset')
+        assert_equal 0, st.exitstatus, err
+        assert_empty hub.ports_on
     end
 
     ## Exit status -- regression.  Every failure used to be printed and
@@ -220,6 +305,16 @@ class TestExsysUsb < Minitest::Test
         assert_equal [ 1, 2 ], hub.ports_on
     end
 
+    # Typing the old name must not silently do nothing, nor quietly do
+    # the reset: it must say what the command actually is.
+    def test_the_old_restore_action_explains_itself
+        _, err, st = exsys_usb('restore')
+        assert_equal 1, st.exitstatus
+        assert_match(/renamed factory-reset/, err)
+        assert_match(/factory defaults/,      err)
+        assert_equal [], hub.ports_on
+    end
+
     ## Packaging #########################################################
 
     # Regression: the file carried a shebang but no execute bit, so a