twib 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: be083ce5e43cdb183a7548ce6ad0b2eabc77e425
-  data.tar.gz: 58e462f9150b324ac65acdaa12dbc1fb10dc4df9
+  metadata.gz: b9015c1f3220bfaeda563a3f8c1cc515b29379dd
+  data.tar.gz: 35e11df95809753993e09f2374e710bdb0459d09
 SHA512:
-  metadata.gz: a58ca6fa102c71854d30b3b2bb4338e6425f59fd05be3392ad660816a617fb82866a5508ff3b50c542b29125ff1c1d76b6a67cee14f8d1e737780304e2835d5a
-  data.tar.gz: f77ef0b936b82b29b2d5e48bc803b85d37e077a7222118ee4d2c6b070f0368331744ce6ef862525b8f7746cb5a1cc75d654f606674959ec9e49cc48906c581a2
+  metadata.gz: 7924978593a63d765464260639f158aa4cc1b3690851635e77b7b2fd1bf367aef5c6d0944453bf195a21a1268fddb5fe246b8e57b038facd5024c5c8f307815a
+  data.tar.gz: def10e5a85b65b522bdd401718c12df4ac01fc37e457a1207b929068dddbe307fe474be82ef1c632575294a254cef8e09737c868065e0586875a6367b2685cb1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    twib (0.1.0)
+    twib (0.1.1)
       msgpack
 
 GEM

data/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2018 misson20000
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -1,4 +1,5 @@
 # ruby-twib
+[![Gem Version](https://badge.fury.io/rb/twib.svg)](https://badge.fury.io/rb/twib)
 
 [Twili](https://github.com/misson20000/twili) bridge client for Ruby, providing a way for Ruby applications to send requests to a Twili device via twibd.
 
@@ -22,19 +23,21 @@ Or install it yourself as:
 
 See the instructions on the [Twili repository](https://github.com/misson20000/twili#twili) for how to set up Twili and twibd.
 
-First, create a Twib::TwibConnection. There is a convenience method `Twib::TwibConnection::connect_unix`
+First, create a [Twib::TwibConnection](https://www.rubydoc.info/gems/twib/Twib/TwibConnection). There is a convenience method [Twib::TwibConnection::connect_unix](https://www.rubydoc.info/gems/twib/Twib/TwibConnection#connect_unix-class_method).
 ```ruby
+> require "twib"
+ => true
 > tc = Twib::TwibConnection.connect_unix
  => #<Twib::TwibConnection:...>
 ```
 
-After that, you can list the available devices with `TwibConnection#list_devices`, which returns an array of hashes identifying each device.
+After that, you can list the available devices with [TwibConnection#list_devices](https://www.rubydoc.info/gems/twib/Twib/TwibConnection#list_devices-instance_method), which returns an array of hashes identifying each device.
 ```ruby
 > tc.list_devices
 [{"device_id"=>507914862, ...}, ...]
 ```
 
-Use `TwibConnection#open_device` to get a device's `ITwibDeviceInterface`.
+Use [TwibConnection#open_device](https://www.rubydoc.info/gems/twib/Twib/TwibConnection#open_device-instance_method) to get a device's [ITwibDeviceInterface](https://www.rubydoc.info/gems/twib/Twib/Interfaces/ITwibDeviceInterface).
 ```ruby
 > tc.open_device(507914862)
  => #<Twib::Interfaces::ITwibDeviceInterface:...>
@@ -49,3 +52,13 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/misson20000/ruby-twib.
+
+## License
+
+```
+Copyright 2018 misson20000
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```

data/lib/twib.rb

@@ -8,16 +8,26 @@ require "twib/interfaces/ITwibDeviceInterface"
 module Twib
   class Error < RuntimeError
   end
-  
+
+  # An error originating from either twibd or a remote device.
   class ResultError < Error
     def initialize(code)
-      super("0x#{code.to_s(16)}")
-      @code = code
+      super("0x#{code.to_i.to_s(16)}")
+      @code = code.to_i
     end
+
+    # @return [Integer] the bad result code that caused this error
     attr_reader :code
   end
-  
+
+  # A response from either twibd or a remote device.
   class Response
+    # @param device_id [Integer] ID of the device that this response originated from.
+    # @param object_id [Integer] ID of the bridge object that this response originated from.
+    # @param result_code [Integer] Result code
+    # @param tag [Integer] Tag corresponding to the request that prompted this response.
+    # @param payload [String] Raw data associated with the response
+    # @param object_ids [Array<Integer>] Object IDs sent with the response
     def initialize(device_id, object_id, result_code, tag, payload, object_ids)
       @device_id = device_id
       @object_id = object_id
@@ -28,7 +38,10 @@ module Twib
     end
 
     attr_reader :device_id, :object_id, :result_code, :tag, :payload, :object_ids
-    
+
+    # Raises a {ResultError} if the {#result_code} is not OK.
+    # @raise [ResultError]
+    # @return [self]
     def assert_ok
       if @result_code != 0 then
         raise ResultError.new(@result_code)
@@ -36,7 +49,8 @@ module Twib
       return self
     end
   end
-  
+
+  # A request to be sent to a remote device.
   class ActiveRequest
     def initialize(tc, device_id, object_id, command_id, tag, payload, &block)
       @tc = tc
@@ -50,6 +64,7 @@ module Twib
       @response = nil
     end
 
+    # @api private
     def respond(response) # expects to be synchronized by @tc.mutex
       @response = response
       @condvar.broadcast
@@ -58,6 +73,8 @@ module Twib
       end
     end
 
+    # Waits for this request to receive a response.
+    # @return [Response]
     def wait
       @tc.mutex.synchronize do
         while @response == nil do
@@ -67,16 +84,24 @@ module Twib
       return @response
     end
 
+    # Waits for this request to receive a response, and raises if the response is not OK.
+    # @raise [ResultError]
+    # @return [Response]
     def wait_ok
       wait.assert_ok
     end
   end
-  
+
+  # A connection to twibd.
   class TwibConnection
+    # Connects to twibd using the standard UNIX socket address.
+    # @return [TwibConnection]
     def self.connect_unix
       return self.new(UNIXSocket.new("/var/run/twibd.sock"))
     end
-    
+
+    # Creates a TwibConnection using the specified socket
+    # @param [BasicSocket] socket
     def initialize(socket)
       @socket = socket
       @itmi = Interfaces::ITwibMetaInterface.new(self, 0, 0)
@@ -112,20 +137,29 @@ module Twib
       @cb_thread = Thread.new do # to avoid deadlocks on I/O thread, we execute callbacks here
         while @alive do
           cb, response = @cb_queue.pop
-          cb.call(response)
+          if cb then
+            cb.call(response)
+          end
         end
       end
     end
 
+    # @api private
     attr_reader :mutex
+    # @api private
     attr_reader :cb_queue
-    
+
+    # Closes the socket and stops internal threads
     def close
       @alive = false
       @socket.close
       @thread.join
+      @cb_queue.close
+      @cb_thread.join
     end
 
+    # @api private
+    # @return [ActiveRequest]
     def send(device_id, object_id, command_id, payload, &block)
       tag = rand(0xffffffff)
 
@@ -140,11 +174,21 @@ module Twib
 
       return rq
     end
-    
+
+    # Returns a list of devices connected to twibd.
+    #
+    #   tc.list_devices
+    #   # => [{"device_id"=>507914862, "identification"=>{...}}]
+    #
+    # Use {#open_device} to connect to one.
+    #
+    # @return [Array<Hash>]
     def list_devices
       @itmi.list_devices
     end
 
+    # Opens a device specified by one of the device IDs returned from {#list_devices}.
+    # @return [Interfaces::ITwibDeviceInterface]
     def open_device(device_id)
       return Interfaces::ITwibDeviceInterface.new(self, device_id, 0)
     end

data/lib/twib/interface.rb

@@ -1,21 +1,35 @@
 module Twib
+  # Base class for Ruby bindings to a remote interface.
+  # An instance of this class represents a remote bridge object.
+  #
+  # This class and any subclasses should not typically be instantiated directly.
+  # Rather, instances should be returned from either {TwibConnection#open_device}
+  # or a remote command binding.
   class Interface
+    
+    # @param connection [TwibConnection] Twib connection to use for transport
+    # @param device_id [Integer] ID of the device this object exists on
+    # @param object_id [Integer] ID of the remote object this object is bound to
     def initialize(connection, device_id, object_id)
       @connection = connection
       @device_id = device_id
       @object_id = object_id
-
-      # object id 0 is special
-      #if @object_id != 0 then
-      #  ObjectSpace.define_finalizer(self, self.class.finalize(connection, device_id, object_id))
-      #end
-    end
-
-    def self.finalize(connection, device_id, object_id)
-      # send close request
-      #connection.send_sync(device_id, object_id, 0xffffffff, String.new)
     end
 
+    # Sends a request to the remote object this instance is bound to.
+    #
+    #   object.send(10, [1234].pack("L<")) do |rs|
+    #     puts "got back: " + rs.assert_ok.payload
+    #   end
+    #
+    #   object.send(10, [1234].pack("L<")).wait_ok
+    #   # => #<Twib::TwibConnection::Response>
+    #
+    # @param command_id [Integer] ID of remtoe command to invoke
+    # @param payload [String] Data to send along with the request
+    # @yield [rs] Calls the block (in a separate thread) when a response is received, if present.
+    # @yieldparam rs [Response]
+    # @return [ActiveRequest]
     def send(command_id, payload=String.new, &block)
       @connection.send(@device_id, @object_id, command_id, payload, &block)
     end

data/lib/twib/interfaces/ITwibDebugger.rb

@@ -3,7 +3,9 @@ require "twib/switch/debug.rb"
 
 module Twib
   module Interfaces
+    # Debug interface bound to a specific process.
     class ITwibDebugger < Interface
+      # @api private
       module Command
         QUERY_MEMORY = 10
         READ_MEMORY = 11
@@ -17,51 +19,86 @@ module Twib
         GET_NSO_INFOS = 19
         WAIT_EVENT = 20
       end
-      
+
+      # Queries process segment information at the given address.
+      #
+      #   debug.query_memory(0)
+      #   # => {:base=>0, :size=>62308483072, :memory_type=>0,
+      #   #     :memory_attribute=>0, :permission=>0,
+      #   #     :device_ref_count=>0, :ipc_ref_count=>0}
+      #
+      # @param addr [Integer] Address to query
+      # @return [Hash]
       def query_memory(addr)
         Hash[
           [:base, :size, :memory_type, :memory_attribute,
            :permission, :device_ref_count, :ipc_ref_count].zip(
             send(Command::QUERY_MEMORY, [addr].pack("Q<")).wait_ok.payload.unpack("Q<Q<L<L<L<L<L<"))]
       end
-      
+
+      # Reads from process memory at the given address.
+      # @param addr [Integer] Address to read from
+      # @param size [Integer] How many bytes to read
+      # @return [String]
       def read_memory(addr, size)
         send(Command::READ_MEMORY, [addr, size].pack("Q<Q<")).wait_ok.payload
       end
-      
+
+      # Writes to process memory at the given address.
+      # @param addr [Integer] Address to write to
+      # @param string [String] Data to write
+      # @return [String]
       def write_memory(addr, string)
         send(Command::WRITE_MEMORY, [addr].pack("Q<") + string).wait_ok
+        string
       end
-      
+
+      # Lists threads in the target process.
+      # @return [self]
       def list_threads
         raise "nyi"
       end
-      
+
+      # Gets a debug event from the target process.
+      # @return [Switch::Debug::Event, nil] A debug event, or nil if none were left
       def get_debug_event
         rs = send(Command::GET_DEBUG_EVENT).wait
         if rs.result_code == 0x8c01 then # no debug events left
           return nil
+        else
+          rs.assert_ok
         end
         return Switch::Debug::Event::Event.unpack(rs.payload)
       end
-      
+
+      # Gets a thread's context.
+      # @return [self]
       def get_thread_context(thread_id)
         raise "nyi"
       end
-      
+
+      # Breaks the target process.
+      # @return [self]
       def break_process
         raise "nyi"
       end
-      
+
+      # Continues the target process.
+      # @param flags [Integer] See http://www.switchbrew.org/index.php?title=SVC#ContinueDebugFlagsOld
+      # @return [self]
       def continue_debug_event(flags, thread_ids=[])
         send(Command::CONTINUE_DEBUG_EVENT, ([flags] + thread_ids).pack("L<Q<*")).wait_ok
-        nil
+        self
       end
-      
+
+      # Sets a thread's context.
+      # @return [self]
       def set_thread_context(thread_id)
         raise "nyi"
       end
-      
+
+      # Queries NSO info for the target process.
+      # @return [Array<Hash>]
       def get_nso_infos
         response = send(Command::GET_NSO_INFOS).wait_ok.payload
         count = response.unpack("Q<")[0]
@@ -70,13 +107,19 @@ module Twib
             [:base, :size, :build_id].zip(response[8 + 0x30 * i, 0x30].unpack("Q<Q<a32"))]
         end
       end
-      
+
+      # Yields from a separate thread when a debug event is available.
+      # @return [self]
       def wait_event_async(&block)
         send(Command::WAIT_EVENT, String.new, &block)
+        self
       end
-      
+
+      # Waits for a debug event to become available.
+      # @return [self]
       def wait_event
         send(Command::WAIT_EVENT).wait_ok
+        self
       end
     end
   end

data/lib/twib/interfaces/ITwibDeviceInterface.rb

@@ -4,7 +4,9 @@ require "twib/interfaces/ITwibDebugger.rb"
 
 module Twib
   module Interfaces
+    # Main interface exposed by a device.
     class ITwibDeviceInterface < Interface
+      # @api private
       module Command
         RUN = 10
         REBOOT = 11
@@ -17,6 +19,10 @@ module Twib
         OPEN_NAMED_PIPE = 18
         OPEN_ACTIVE_DEBUGGER = 19
       end
+
+      # Opens an active debugger for the process with the given PID.
+      # @param pid [Integer] Process ID
+      # @return [ITwibDebugger] Debugger interface
       def open_active_debugger(pid)
         ITwibDebugger.new(@connection, @device_id, send(Command::OPEN_ACTIVE_DEBUGGER, [pid].pack("Q<")).wait_ok.object_ids[0])
       end

data/lib/twib/interfaces/ITwibMetaInterface.rb

@@ -4,10 +4,15 @@ require "twib/interface.rb"
 
 module Twib
   module Interfaces
+    # Exposed by twibd
     class ITwibMetaInterface < Interface
+      # @api private
       module Command
         LIST_DEVICES = 10
       end
+
+      # Lists devices known to twibd.
+      # @return [Array<Hash>]
       def list_devices
         MessagePack.unpack(send(Command::LIST_DEVICES).wait_ok.payload)
       end

data/lib/twib/version.rb

@@ -1,3 +1,3 @@
 module Twib
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/twib.gemspec

@@ -18,6 +18,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.license       = 'ISC'
+
   spec.add_development_dependency "bundler", "~> 1.16"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twib
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - misson20000
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-09-02 00:00:00.000000000 Z
+date: 2018-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -78,6 +78,7 @@ files:
 - ".travis.yml"
 - Gemfile
 - Gemfile.lock
+- LICENSE
 - README.md
 - Rakefile
 - bin/console
@@ -91,7 +92,8 @@ files:
 - lib/twib/version.rb
 - twib.gemspec
 homepage: https://github.com/misson20000/ruby-twib/
-licenses: []
+licenses:
+- ISC
 metadata: {}
 post_install_message: 
 rdoc_options: []