exsys 0.6 → 1.1

data/test/test_managed_usb.rb

@@ -11,17 +11,37 @@ class TestManagedUSB < Minitest::Test
 
     ## Switching #########################################################
 
-    def test_on_without_argument_powers_every_port
-        @usb.on
+    def test_all_powers_every_port
+        @usb.on(ExSYS::ManagedUSB::ALL)
         assert_equal ExSYS::ManagedUSB::PORTS, @hub.ports_on
     end
 
-    def test_off_without_argument_powers_nothing
-        @usb.on
-        @usb.off
+    def test_all_unpowers_every_port
+        @usb.on(:all)
+        @usb.off(:all)
         assert_empty @hub.ports_on
     end
 
+    # Regression: an empty list used to mean every port, so a caller
+    # splatting a computed list that came back empty switched all
+    # sixteen.  on(*[]) and on() are the same call, so neither can be
+    # allowed through.
+    def test_an_empty_port_list_is_refused_not_taken_as_every_port
+        @usb.on(:all)
+        [ ->{ @usb.on(*[])     }, ->{ @usb.on        },
+          ->{ @usb.off(*[])    }, ->{ @usb.off       },
+          ->{ @usb.toggle(*[]) }, ->{ @usb.toggle    } ].each do |op|
+            err = assert_raises(ArgumentError, &op)
+            assert_match(/no port given/, err.message)
+        end
+        assert_equal ExSYS::ManagedUSB::PORTS, @hub.ports_on,
+                     'the hub must not have been touched'
+    end
+
+    def test_all_cannot_be_mixed_with_port_numbers
+        assert_raises(ArgumentError) { @usb.on(:all, 3) }
+    end
+
     def test_on_and_off_are_restricted_to_the_named_ports
         @usb.on(1, 2, 16)
         assert_equal [ 1, 2, 16 ], @hub.ports_on
@@ -36,8 +56,8 @@ class TestManagedUSB < Minitest::Test
     end
 
     def test_switching_returns_self_so_calls_chain
-        assert_same @usb, @usb.on
-        @usb.on.off(4, 5, 6)
+        assert_same @usb, @usb.on(:all)
+        @usb.on(:all).off(4, 5, 6)
         assert_equal ExSYS::ManagedUSB::PORTS - [ 4, 5, 6 ], @hub.ports_on
     end
 
@@ -141,7 +161,7 @@ class TestManagedUSB < Minitest::Test
     def test_get_on_off_always_carries_both_keys
         assert_equal({ :on => [], :off => ExSYS::ManagedUSB::PORTS },
                      @usb.get(:on_off))
-        @usb.on
+        @usb.on(:all)
         assert_equal({ :on => ExSYS::ManagedUSB::PORTS, :off => [] },
                      @usb.get(:on_off))
         @usb.off(1)
@@ -151,6 +171,7 @@ class TestManagedUSB < Minitest::Test
     # A real hub answers in upper case; accept either, since the reply
     # is only ever fed to pack('H4'), which does not care.
     def test_a_lower_case_reply_decodes_the_same
+        @usb.port_count              # settle ?Q before garbling every reply
         @hub.garbage = 'c4ffffff'
         assert_equal [ 3, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 ], @usb.get(:on)
         @hub.garbage = 'C4FFFFFF'
@@ -163,24 +184,191 @@ class TestManagedUSB < Minitest::Test
 
     ## Flash and reset ###################################################
 
-    def test_commit_saves_and_restore_brings_back
+    def test_commit_saves_the_state_as_the_power_on_state
         @usb.on(1)
         @usb.commit
-        @usb.on(2)
-        assert_equal [ 1, 2 ], @hub.ports_on
-        @usb.restore
-        assert_equal [ 1 ], @hub.ports_on
+        assert_equal [ 1 ], @hub.flash_ports
+    end
+
+    # RD is the hub's "restore factory defaults", not the inverse of
+    # commit: there is no command that reloads the flashed state, the
+    # hub applies it at power-on by itself.  Modelled from the vendor's
+    # own documentation -- running it against hardware would drop every
+    # port on the bench and reset the password.
+    ## Describing the hub ###############################################
+
+    def test_query_reports_id_ports_and_firmware
+        assert_equal({ :id => 'CENTOS', :ports => 16, :firmware => 'v02',
+                       :raw => 'CENTOS000516v02' }, @usb.query)
+    end
+
+    def test_query_needs_no_password
+        usb = ExSYS::ManagedUSB.new('/dev/null', 'wrong')
+        assert_equal 16, usb.query[:ports]
+    end
+
+    # The hub is asked how many ports it has before it is read, not
+    # somewhere in the middle: a trace of any port operation reads the
+    # same way, and an invalid port is refused without touching it.
+    def test_the_query_leads_and_happens_once
+        @usb.on(1)
+        assert_equal %w[?Q GP SP], (@hub.log.map {|c| c[0, 2] })
+
+        @hub.log.clear
+        @usb.off(2)
+        assert_equal %w[GP SP], (@hub.log.map {|c| c[0, 2] })
+    end
+
+    def test_an_invalid_port_is_refused_before_the_hub_is_read
+        assert_raises(ArgumentError) { @usb.on(99) }
+        assert_equal %w[?Q], (@hub.log.map {|c| c[0, 2] })
+    end
+
+    def test_port_count_is_asked_once_and_remembered
+        3.times { @usb.port_count }
+        assert_equal 1, @hub.log.count('?Q')
+    end
+
+    # Firmware that does not know ?Q answers an error, and the count
+    # falls back to what the state word can address.
+    def test_port_count_falls_back_when_the_hub_refuses_the_query
+        @hub.ident = nil                        # answers E01
+        assert_equal ExSYS::ManagedUSB::PORTS.size, @usb.port_count
+        assert_match(/will not answer/, @dbg.string)
+    end
+
+    # A reply that arrives but cannot be read is a different thing from
+    # a refusal, and must not be guessed at: on a wider hub a guess of
+    # sixteen would leave its upper ports untouched while reporting
+    # success.
+    def test_an_unreadable_query_reply_does_not_become_a_guess
+        @hub.ident = 'CENTOS-garbled'
+        assert_raises(ExSYS::ManagedUSB::Error) { @usb.port_count }
+        assert_raises(ExSYS::ManagedUSB::Error) { @usb.on(:all) }
+    end
+
+    # The firmware is whatever follows the count, not a bare number:
+    # a hub reporting v1.02 must not fall back to a guessed count.
+    def test_a_dotted_firmware_version_still_parses
+        @hub.ident = 'CENTOS000532v1.02'
+        assert_equal 32,      @usb.query[:ports]
+        assert_equal 'v1.02', @usb.query[:firmware]
+        assert_equal 32,      @usb.port_count
+    end
+
+    def test_an_unparseable_query_reply_is_an_error
+        @hub.ident = 'wat'
+        err = assert_raises(ExSYS::ManagedUSB::Error) { @usb.query }
+        assert_match(/unexpected query reply/, err.message)
+    end
+
+    # ALL means every port the hub says it has.  Confirmed against the
+    # vendor tool, which reads the same field and reports 4, 8, 16 or
+    # 32 ports from it.
+    def test_all_covers_exactly_the_ports_the_hub_reports
+        @hub.ident = 'CENTOS000504v02'          # a hub with 4 ports
+        @usb.on(:all)
+        assert_equal [ 1, 2, 3, 4 ], @hub.ports_on
+        assert_equal [ 1, 2, 3, 4 ], @usb.ports
+    end
+
+    def test_a_port_the_hub_does_not_have_is_refused
+        @hub.ident = 'CENTOS000504v02'
+        assert_raises(ArgumentError) { @usb.on(5) }
+    end
+
+    ## Hubs that are not sixteen ports ##################################
+
+    # Regression: the state word's upper half was written as a literal
+    # 'ffff' rather than carried back from the read.  On a 16-port hub
+    # those bits are ports that do not exist and it went unnoticed; on
+    # a 32-port hub it powered ports 17..32 on every single operation.
+    def test_a_wider_hub_does_not_have_its_upper_ports_driven
+        UART.hub = wide = FakeHub.new(ports: 32, width: 8)
+        usb = ExSYS::ManagedUSB.new('/dev/null')
+
+        usb.on(1)
+        assert_equal [ 1 ], wide.ports_on
+    end
+
+    def test_a_wider_hub_can_use_all_of_its_ports
+        UART.hub = wide = FakeHub.new(ports: 32, width: 8)
+        usb = ExSYS::ManagedUSB.new('/dev/null')
+
+        assert_equal 32, usb.port_count
+        usb.on(:all)
+        assert_equal (1..32).to_a, wide.ports_on
+        usb.off(20)
+        assert_equal (1..32).to_a - [ 20 ], wide.ports_on
+    end
+
+    def test_a_narrower_hub_reports_only_the_ports_it_has
+        UART.hub = small = FakeHub.new(ports: 4, width: 8)
+        usb = ExSYS::ManagedUSB.new('/dev/null')
+
+        assert_equal [ 1, 2, 3, 4 ], usb.ports
+        usb.on(:all)
+        assert_equal [ 1, 2, 3, 4 ], small.ports_on
+        assert_equal({ 1 => true, 2 => true, 3 => true, 4 => true },
+                     usb.get)
+        assert_raises(ArgumentError) { usb.on(5) }
+    end
+
+    # The ports it does not have read as 1, and must be written back
+    # that way rather than cleared.
+    def test_absent_ports_are_carried_back_untouched
+        UART.hub = small = FakeHub.new(ports: 4, width: 8)
+        usb = ExSYS::ManagedUSB.new('/dev/null')
+
+        usb.on(1)
+        # Little-endian: ports 1..8 in the first byte, so port 1 on with
+        # ports 5..32 absent and reading 1 is F1 FF FF FF.
+        assert_equal 'F1FFFFFF', small.log.last[-8..],
+                     'absent ports written back as read'
+    end
+
+    ## Factory reset #####################################################
+
+    def test_the_old_restore_name_is_a_tombstone
+        err = assert_raises(NoMethodError) { @usb.restore }
+        assert_match(/renamed factory_reset/, err.message)
+        assert_match(/not the inverse of commit/, err.message)
+    end
+
+    def test_factory_reset_refuses_unless_it_is_confirmed
+        @usb.on(:all)
+        err = assert_raises(ArgumentError) { @usb.factory_reset }
+        assert_match(/confirm: true/, err.message)
+        assert_equal ExSYS::ManagedUSB::PORTS, @hub.ports_on,
+                     'the hub must not have been touched'
+    end
+
+    def test_restore_is_a_factory_reset
+        @usb.on(1)
+        @usb.commit
+        @usb.on(:all)
+        @usb.factory_reset(confirm: true)
+        assert_empty @hub.ports_on,  'every port dropped'
+        assert_empty @hub.flash_ports, 'the power-on state went too'
+        assert_equal FakeHub::DEFAULT_PASSWORD, @hub.password
     end
 
     def test_on_with_commit_writes_through_to_flash
         @usb.on(3, commit: true)
         @usb.on(4)
-        @usb.restore
-        assert_equal [ 3 ], @hub.ports_on
+        assert_equal [ 3, 4 ], @hub.ports_on
+        assert_equal [ 3 ],    @hub.flash_ports
     end
 
     def test_reset_expects_no_reply
-        assert_same @usb, @usb.reset
+        assert_same @usb, @usb.reset(confirm: true)
+    end
+
+    def test_reset_refuses_unless_it_is_confirmed
+        @usb.on(:all)
+        err = assert_raises(ArgumentError) { @usb.reset }
+        assert_match(/confirm: true/, err.message)
+        refute_includes @hub.log.map {|c| c[0, 2] }, 'RH'
     end
 
     ## Password ##########################################################
@@ -257,14 +445,16 @@ class TestManagedUSB < Minitest::Test
     # Regression: a read-modify-write used to close the line between the
     # GP and the SP, letting another process slip in between the two.
     def test_read_modify_write_holds_the_line_open
+        @usb.port_count                        # the one-off ?Q, out of the way
+        @hub.log.clear
         @usb.on(1)
-        assert_equal 1, @hub.opens
         assert_equal 2, @hub.log.size          # GP then SP, one session
+        assert_equal %w[GP SP], (@hub.log.map {|c| c[0, 2] })
     end
 
     def test_set_holds_the_line_open_too
         @usb.set({ 1 => true })
-        assert_equal 1, @hub.opens
+        assert_equal 1, @hub.opens             # ?Q, GP and SP all inside it
     end
 
     def test_the_line_is_opened_as_the_hub_expects
@@ -280,6 +470,66 @@ class TestManagedUSB < Minitest::Test
         assert_equal 1, @hub.locks
     end
 
+    # Regression: EBADF and EINVAL were swallowed alongside the genuine
+    # "this platform will not lock this" errors.  Both mean a bug here,
+    # and swallowing one runs unlocked while reporting success.
+    def test_an_unexpected_lock_error_is_not_swallowed
+        @hub.lock_error = Errno::EBADF
+        assert_raises(Errno::EBADF) { @usb.on(1) }
+    end
+
+    ## Sessions #########################################################
+
+    def test_session_yields_the_hub_and_returns_the_block_value
+        result = @usb.session {|h| assert_same @usb, h; :done }
+        assert_equal :done, result
+    end
+
+    def test_one_session_holds_one_line_for_every_call_inside_it
+        @usb.session do
+            @usb.get
+            @usb.on(1)
+            @usb.off(1)
+        end
+        assert_equal 1, @hub.opens
+        assert_equal 1, @hub.locks
+    end
+
+    def test_without_a_session_each_call_opens_its_own_line
+        @usb.get
+        @usb.on(1)
+        assert_equal 2, @hub.opens
+    end
+
+    def test_a_session_releases_the_line_even_when_the_block_raises
+        assert_raises(RuntimeError) { @usb.session { raise 'boom' } }
+        @usb.on(1)                       # must open afresh, not reuse
+        assert_equal 2, @hub.opens
+        assert_equal [ 1 ], @hub.ports_on
+    end
+
+    # Regression: the open line was plain instance state, so a second
+    # thread either borrowed a line it held no lock on -- losing one
+    # thread's change -- or had it closed underneath it by the first
+    # thread's ensure, which surfaced as a NoMethodError on nil.
+    def test_two_threads_never_share_one_line
+        Dir.mktmpdir('exsys-threads') do |dir|
+            fake = FakeHub.new(path: File.join(dir, 'hub'),
+                               lock: File.join(dir, 'lock'), delay: 0.2)
+            UART.hub = fake
+            usb = ExSYS::ManagedUSB.new('/dev/null')
+
+            a = Thread.new { usb.on(1) }
+            sleep 0.1                    # B enters while A holds the line
+            b = Thread.new { usb.on(2) }
+            [ a, b ].each(&:join)
+
+            assert_equal 2, fake.opens, 'each thread opens its own line'
+            assert_equal 2, fake.locks, 'each thread takes its own lock'
+            assert_equal [ 1, 2 ], fake.ports_on
+        end
+    end
+
     # A platform that will not lock a character device must not make the
     # tool unusable; it degrades to unlocked and says so.
     def test_an_unlockable_line_degrades_rather_than_failing

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exsys
 version: !ruby/object:Gem::Version
-  version: '0.6'
+  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