pwn 0.5.621 → 0.5.626

data/lib/pwn/ffi/rtl_sdr.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+PubFFI = ::FFI unless defined?(PubFFI) # rubocop:disable Style/RedundantConstantBase
+
+module PWN
+  module FFI
+    # Thin librtlsdr binding (no -dev headers required — symbols resolved
+    # from the installed shared object). Control-plane + blocking
+    # `read_sync` so PWN::SDR::Decoder::* / Extrospection probe_rf can pull
+    # raw u8 I/Q without shelling out to `rtl_sdr`.
+    #
+    # If librtlsdr is missing `.available?` is false and callers fall back.
+    module RTLSdr
+      extend PubFFI::Library
+
+      @load_error = nil
+      begin
+        ffi_lib %w[rtlsdr librtlsdr.so.0 librtlsdr.so.2 librtlsdr.so]
+      rescue LoadError => e
+        @load_error = e
+      end
+
+      class << self
+        attr_reader :load_error
+      end
+
+      unless @load_error
+        attach_function :rtlsdr_get_device_count, [], :uint32
+        attach_function :rtlsdr_get_device_name, [:uint32], :string
+        attach_function :rtlsdr_get_device_usb_strings,
+                        %i[uint32 pointer pointer pointer],
+                        :int
+        attach_function :rtlsdr_open, %i[pointer uint32], :int
+        attach_function :rtlsdr_close, [:pointer], :int
+        attach_function :rtlsdr_set_center_freq, %i[pointer uint32], :int
+        attach_function :rtlsdr_get_center_freq, [:pointer], :uint32
+        attach_function :rtlsdr_set_sample_rate, %i[pointer uint32], :int
+        attach_function :rtlsdr_get_sample_rate, [:pointer], :uint32
+        attach_function :rtlsdr_set_tuner_gain_mode, %i[pointer int], :int
+        attach_function :rtlsdr_set_tuner_gain, %i[pointer int], :int
+        attach_function :rtlsdr_get_tuner_gains, %i[pointer pointer], :int
+        attach_function :rtlsdr_set_freq_correction, %i[pointer int], :int
+        attach_function :rtlsdr_reset_buffer, [:pointer], :int
+        attach_function :rtlsdr_read_sync,
+                        %i[pointer pointer int pointer],
+                        :int
+        attach_function :rtlsdr_set_agc_mode, %i[pointer int], :int
+      end
+
+      # Supported Method Parameters::
+      # PWN::FFI::RTLSdr.available?
+
+      public_class_method def self.available?
+        !@load_error && respond_to?(:rtlsdr_get_device_count, true)
+      rescue StandardError
+        false
+      end
+
+      # Supported Method Parameters::
+      # devices = PWN::FFI::RTLSdr.list_devices
+      # Returns Array<Hash> of { index:, name:, manufacturer:, product:, serial: }.
+
+      public_class_method def self.list_devices
+        raise 'ERROR: librtlsdr not available' unless available?
+
+        count = rtlsdr_get_device_count
+        Array.new(count) do |i|
+          mfr  = PubFFI::MemoryPointer.new(:char, 256)
+          prod = PubFFI::MemoryPointer.new(:char, 256)
+          ser  = PubFFI::MemoryPointer.new(:char, 256)
+          rtlsdr_get_device_usb_strings(i, mfr, prod, ser)
+          {
+            index: i,
+            name: (rtlsdr_get_device_name(i) || '').to_s,
+            manufacturer: mfr.read_string,
+            product: prod.read_string,
+            serial: ser.read_string
+          }
+        end
+      end
+
+      # Supported Method Parameters::
+      # dev = PWN::FFI::RTLSdr.open(index: 0)
+      # Returns opaque FFI::Pointer (rtlsdr_dev_t*).
+
+      public_class_method def self.open(opts = {})
+        raise 'ERROR: librtlsdr not available' unless available?
+
+        idx = (opts[:index] || 0).to_i
+        dev_ptr = PubFFI::MemoryPointer.new(:pointer)
+        rc = rtlsdr_open(dev_ptr, idx)
+        raise "ERROR: rtlsdr_open rc=#{rc}" unless rc.zero?
+
+        dev_ptr.read_pointer
+      end
+
+      # Supported Method Parameters::
+      # PWN::FFI::RTLSdr.close(device: pointer)
+
+      public_class_method def self.close(opts = {})
+        dev = opts[:device]
+        return unless dev && !dev.null?
+
+        rtlsdr_close(dev)
+        nil
+      end
+
+      # Supported Method Parameters::
+      # PWN::FFI::RTLSdr.configure(
+      #   device:   'required - pointer from .open',
+      #   freq_hz:  'required - center frequency Hz',
+      #   rate_hz:  'optional - sample rate (default 2.048e6)',
+      #   gain_db:  'optional - tenths of dB (e.g. 496 = 49.6 dB). nil = auto',
+      #   ppm:      'optional - freq correction ppm (default 0)'
+      # )
+
+      public_class_method def self.configure(opts = {}) # rubocop:disable Naming/PredicateMethod
+        dev = opts[:device]
+        raise 'ERROR: :device required' if dev.nil? || dev.null?
+
+        freq = opts[:freq_hz].to_i
+        rate = (opts[:rate_hz] || 2_048_000).to_i
+        ppm  = (opts[:ppm] || 0).to_i
+
+        check!(rtlsdr_set_sample_rate(dev, rate), 'set_sample_rate')
+        check!(rtlsdr_set_center_freq(dev, freq), 'set_center_freq')
+        check!(rtlsdr_set_freq_correction(dev, ppm), 'set_freq_correction') if ppm != 0
+
+        if opts.key?(:gain_db) && !opts[:gain_db].nil?
+          check!(rtlsdr_set_tuner_gain_mode(dev, 1), 'gain_mode manual')
+          check!(rtlsdr_set_tuner_gain(dev, opts[:gain_db].to_i), 'set_tuner_gain')
+        else
+          check!(rtlsdr_set_tuner_gain_mode(dev, 0), 'gain_mode auto')
+          rtlsdr_set_agc_mode(dev, 1)
+        end
+        check!(rtlsdr_reset_buffer(dev), 'reset_buffer')
+        true
+      end
+
+      # Supported Method Parameters::
+      # iq_u8 = PWN::FFI::RTLSdr.read_sync(
+      #   device: 'required - pointer from .open',
+      #   bytes:  'optional - number of raw bytes to read (default 262144)'
+      # )
+      # Returns a binary String of unsigned 8-bit interleaved I/Q samples.
+
+      public_class_method def self.read_sync(opts = {})
+        dev = opts[:device]
+        raise 'ERROR: :device required' if dev.nil? || dev.null?
+
+        nbytes = (opts[:bytes] || 262_144).to_i
+        buf = PubFFI::MemoryPointer.new(:uint8, nbytes)
+        n_read = PubFFI::MemoryPointer.new(:int)
+        rc = rtlsdr_read_sync(dev, buf, nbytes, n_read)
+        raise "ERROR: rtlsdr_read_sync rc=#{rc}" unless rc.zero?
+
+        got = n_read.read_int
+        buf.read_string(got)
+      end
+
+      # Supported Method Parameters::
+      # gains = PWN::FFI::RTLSdr.tuner_gains(device: pointer)
+      # Returns Array<Integer> of supported gains in tenths of a dB.
+
+      public_class_method def self.tuner_gains(opts = {})
+        dev = opts[:device]
+        raise 'ERROR: :device required' if dev.nil? || dev.null?
+
+        n = rtlsdr_get_tuner_gains(dev, nil)
+        return [] if n <= 0
+
+        ptr = PubFFI::MemoryPointer.new(:int, n)
+        rtlsdr_get_tuner_gains(dev, ptr)
+        ptr.read_array_of_int(n)
+      end
+
+      # Author(s):: 0day Inc. <support@0dayinc.com>
+
+      public_class_method def self.authors
+        "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+      end
+
+      # Display Usage for this Module
+
+      public_class_method def self.help
+        puts "USAGE:
+          #{self}.available?
+          #{self}.list_devices
+          dev = #{self}.open(index: 0)
+          #{self}.configure(device: dev, freq_hz:, rate_hz: 2_048_000, gain_db: nil, ppm: 0)
+          #{self}.tuner_gains(device: dev)
+          iq = #{self}.read_sync(device: dev, bytes: 262_144)  # u8 I/Q String
+          #{self}.close(device: dev)
+
+          #{self}.authors
+        "
+      end
+
+      class << self
+        private
+
+        def check!(code, what)
+          raise "ERROR: rtlsdr_#{what} rc=#{code}" unless code.zero? || code.positive?
+        end
+      end
+    end
+  end
+end

data/lib/pwn/ffi/soapy_sdr.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+PubFFI = ::FFI unless defined?(PubFFI) # rubocop:disable Style/RedundantConstantBase
+
+module PWN
+  module FFI
+    # Thin SoapySDR C-API binding (libSoapySDR). Inventory-focused first —
+    # enumerate devices and report API version so Extrospection `probe_rf`
+    # can list every Soapy-backed front-end (RTL-SDR, HackRF, Airspy,
+    # Pluto, UHD, …) without shelling out to `SoapySDRUtil`.
+    #
+    # Full streaming can be layered later; today this is the discovery
+    # surface. Missing lib → `.available?` false, pure-Ruby / CLI fallbacks.
+    module SoapySDR
+      extend PubFFI::Library
+
+      @load_error = nil
+      begin
+        ffi_lib %w[SoapySDR libSoapySDR.so.0.8 libSoapySDR.so.0 libSoapySDR.so]
+      rescue LoadError => e
+        @load_error = e
+      end
+
+      class << self
+        attr_reader :load_error
+      end
+
+      # SoapySDRKwargs is {size_t size; char** keys; char** vals;}
+      class Kwargs < PubFFI::Struct
+        layout :size, :size_t,
+               :keys, :pointer,
+               :vals, :pointer
+      end
+
+      unless @load_error
+        attach_function :SoapySDR_getAPIVersion, [], :string
+        attach_function :SoapySDR_getABIVersion, [], :string
+        attach_function :SoapySDR_getLibVersion, [], :string
+
+        # SoapySDRKwargs* SoapySDRDevice_enumerate(const SoapySDRKwargs* args, size_t* length)
+        attach_function :SoapySDRDevice_enumerate,
+                        %i[pointer pointer],
+                        :pointer
+
+        # void SoapySDRKwargsList_clear(SoapySDRKwargs *kwargs, size_t length)
+        attach_function :SoapySDRKwargsList_clear,
+                        %i[pointer size_t],
+                        :void
+
+        # SoapySDRDevice* SoapySDRDevice_make(const SoapySDRKwargs* args)
+        attach_function :SoapySDRDevice_make, [:pointer], :pointer
+        # SoapySDRDevice* SoapySDRDevice_makeStrArgs(const char* args)
+        attach_function :SoapySDRDevice_makeStrArgs, [:string], :pointer
+        attach_function :SoapySDRDevice_unmake, [:pointer], :int
+
+        attach_function :SoapySDRDevice_getDriverKey, [:pointer], :string
+        attach_function :SoapySDRDevice_getHardwareKey, [:pointer], :string
+        # char* SoapySDRDevice_getHardwareInfo — returns freeable dict as string? skip
+      end
+
+      # Supported Method Parameters::
+      # PWN::FFI::SoapySDR.available?
+
+      public_class_method def self.available?
+        !@load_error && respond_to?(:SoapySDR_getAPIVersion, true)
+      rescue StandardError
+        false
+      end
+
+      # Supported Method Parameters::
+      # info = PWN::FFI::SoapySDR.info
+      # Returns { available:, api:, abi:, lib: }.
+
+      public_class_method def self.info
+        return { available: false, error: @load_error&.message } unless available?
+
+        {
+          available: true,
+          api: SoapySDR_getAPIVersion().to_s,
+          abi: SoapySDR_getABIVersion().to_s,
+          lib: SoapySDR_getLibVersion().to_s
+        }
+      end
+
+      # Supported Method Parameters::
+      # devices = PWN::FFI::SoapySDR.list_devices
+      # Returns Array<Hash> of keyword→value maps for every enumerated device.
+
+      public_class_method def self.list_devices
+        raise 'ERROR: libSoapySDR not available' unless available?
+
+        len_ptr = PubFFI::MemoryPointer.new(:size_t)
+        # pass NULL args → enumerate everything
+        list_ptr = SoapySDRDevice_enumerate(nil, len_ptr)
+        length = len_ptr.read_ulong
+        return [] if list_ptr.null? || length.zero?
+
+        results = []
+        length.times do |i|
+          kw = Kwargs.new(list_ptr + (i * Kwargs.size))
+          h = {}
+          kw[:size].times do |j|
+            key = kw[:keys].get_pointer(j * PubFFI::Pointer.size)
+            val = kw[:vals].get_pointer(j * PubFFI::Pointer.size)
+            h[key.read_string.to_sym] = val.read_string unless key.null?
+          end
+          results << h
+        end
+        SoapySDRKwargsList_clear(list_ptr, length)
+        results
+      end
+
+      # Supported Method Parameters::
+      # dev = PWN::FFI::SoapySDR.make(args: 'driver=rtlsdr')
+      # Returns opaque pointer (SoapySDRDevice*) or raises.
+      # ALWAYS pair with .unmake.
+
+      public_class_method def self.make(opts = {})
+        raise 'ERROR: libSoapySDR not available' unless available?
+
+        args = opts[:args].to_s
+        dev = SoapySDRDevice_makeStrArgs(args)
+        raise "ERROR: SoapySDRDevice_makeStrArgs(#{args.inspect}) returned NULL" if dev.null?
+
+        dev
+      end
+
+      # Supported Method Parameters::
+      # PWN::FFI::SoapySDR.unmake(device: pointer)
+
+      public_class_method def self.unmake(opts = {})
+        dev = opts[:device]
+        return unless dev && !dev.null?
+
+        SoapySDRDevice_unmake(dev)
+        nil
+      end
+
+      # Supported Method Parameters::
+      # meta = PWN::FFI::SoapySDR.device_keys(device: pointer)
+      # Returns { driver:, hardware: }.
+
+      public_class_method def self.device_keys(opts = {})
+        dev = opts[:device]
+        raise 'ERROR: :device required' if dev.nil? || dev.null?
+
+        {
+          driver: SoapySDRDevice_getDriverKey(dev).to_s,
+          hardware: SoapySDRDevice_getHardwareKey(dev).to_s
+        }
+      end
+
+      # Author(s):: 0day Inc. <support@0dayinc.com>
+
+      public_class_method def self.authors
+        "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+      end
+
+      # Display Usage for this Module
+
+      public_class_method def self.help
+        puts "USAGE:
+          #{self}.available?
+          #{self}.info
+          #{self}.list_devices
+          dev = #{self}.make(args: 'driver=rtlsdr')
+          #{self}.device_keys(device: dev)
+          #{self}.unmake(device: dev)
+
+          #{self}.authors
+        "
+      end
+    end
+  end
+end

data/lib/pwn/ffi/stdio.rb

@@ -2,7 +2,8 @@
 
 require 'ffi'
 
-PubFFI = FFI
+PubFFI = ::FFI unless defined?(PubFFI) # rubocop:disable Style/RedundantConstantBase
+
 module PWN
   module FFI
     # This plugin is a wrapper for the standard I/O functions in libc.
@@ -15,6 +16,13 @@ module PWN
       attach_function(:printf, %i[string varargs], :int, convention: :default)
       attach_function(:scanf, %i[string varargs], :int)
 
+      # Supported Method Parameters::
+      # PWN::FFI::Stdio.available?
+
+      public_class_method def self.available?
+        true
+      end
+
       # Author(s):: 0day Inc. <support@0dayinc.com>
 
       public_class_method def self.authors

data/lib/pwn/ffi/volk.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+PubFFI = ::FFI unless defined?(PubFFI) # rubocop:disable Style/RedundantConstantBase
+
+module PWN
+  module FFI
+    # Thin VOLK (Vector-Optimized Library of Kernels) binding.
+    #
+    # Dispatches to SIMD kernels (SSE/AVX/NEON/…) when the host provides them.
+    # Used by PWN::SDR::Decoder::DSP hot paths so MHz-rate I/Q work stays
+    # off the Ruby GC heap while orchestration remains pure Ruby.
+    #
+    # Nothing here shells out and nothing is compiled at gem-install time —
+    # if libvolk is missing, `.available?` is false and callers fall back.
+    module Volk
+      extend PubFFI::Library
+
+      @load_error = nil
+      begin
+        ffi_lib %w[volk libvolk.so.3.3 libvolk.so.3 libvolk.so]
+      rescue LoadError => e
+        @load_error = e
+      end
+
+      class << self
+        attr_reader :load_error
+      end
+
+      unless @load_error
+        # Memory helpers (always present as T symbols)
+        attach_function :volk_get_alignment, [], :size_t
+        attach_function :volk_malloc, %i[size_t size_t], :pointer
+        attach_function :volk_free, [:pointer], :void
+
+        # VOLK dispatches are *data* symbols (function pointers). Bind them
+        # with attach_variable then wrap in FFI::Function on first use so we
+        # always hit the CPU-tuned kernel selected by the dispatcher.
+        attach_variable :volk_16i_s32f_convert_32f, :pointer
+        attach_variable :volk_32f_accumulator_s32f, :pointer
+        attach_variable :volk_32fc_magnitude_squared_32f, :pointer
+        attach_variable :volk_32f_sqrt_32f, :pointer
+        attach_variable :volk_32f_s32f_multiply_32f, :pointer
+        attach_variable :volk_32f_x2_dot_prod_32f, :pointer
+      end
+
+      # Supported Method Parameters::
+      # PWN::FFI::Volk.available?
+
+      public_class_method def self.available?
+        !@load_error && respond_to?(:volk_get_alignment, true)
+      rescue StandardError
+        false
+      end
+
+      # Supported Method Parameters::
+      # samples = PWN::FFI::Volk.unpack_s16le(
+      #   data: 'required - raw String of little-endian signed 16-bit PCM'
+      # )
+      # Returns Array<Float> normalised to -1.0..1.0 (same contract as
+      # PWN::SDR::Decoder::DSP.unpack_s16le). VOLK treats `scalar` as a
+      # divisor, so pass 32768.0 to get unit-range floats.
+
+      public_class_method def self.unpack_s16le(opts = {})
+        raise 'ERROR: libvolk not available' unless available?
+
+        data = opts[:data].to_s
+        n = data.bytesize / 2
+        return [] if n.zero?
+
+        in_ptr = PubFFI::MemoryPointer.from_string(data)
+        # from_string null-terminates — reclaim only the payload region
+        out_ptr = PubFFI::MemoryPointer.new(:float, n)
+        convert_fn.call(out_ptr, in_ptr, 32_768.0, n)
+        out_ptr.read_array_of_float(n)
+      end
+
+      # Supported Method Parameters::
+      # sum = PWN::FFI::Volk.accumulate(samples: Array<Float>)
+
+      public_class_method def self.accumulate(opts = {})
+        raise 'ERROR: libvolk not available' unless available?
+
+        samples = opts[:samples]
+        n = samples.length
+        return 0.0 if n.zero?
+
+        in_ptr = float_ptr(samples)
+        out_ptr = PubFFI::MemoryPointer.new(:float, 1)
+        accum_fn.call(out_ptr, in_ptr, n)
+        out_ptr.read_float
+      end
+
+      # Supported Method Parameters::
+      # power = PWN::FFI::Volk.magnitude_squared(
+      #   iq: 'required - Array of interleaved I/Q Floats (even length)'
+      # )
+      # Returns Array<Float> of |z|^2 per complex sample.
+
+      public_class_method def self.magnitude_squared(opts = {})
+        raise 'ERROR: libvolk not available' unless available?
+
+        iq = opts[:iq]
+        n_c = iq.length / 2
+        return [] if n_c.zero?
+
+        in_ptr = float_ptr(iq)
+        out_ptr = PubFFI::MemoryPointer.new(:float, n_c)
+        mag2_fn.call(out_ptr, in_ptr, n_c)
+        out_ptr.read_array_of_float(n_c)
+      end
+
+      # Supported Method Parameters::
+      # out = PWN::FFI::Volk.sqrt(samples: Array<Float>)
+
+      public_class_method def self.sqrt(opts = {})
+        raise 'ERROR: libvolk not available' unless available?
+
+        samples = opts[:samples]
+        n = samples.length
+        return [] if n.zero?
+
+        in_ptr = float_ptr(samples)
+        out_ptr = PubFFI::MemoryPointer.new(:float, n)
+        sqrt_fn.call(out_ptr, in_ptr, n)
+        out_ptr.read_array_of_float(n)
+      end
+
+      # Supported Method Parameters::
+      # out = PWN::FFI::Volk.scale(samples: Array<Float>, factor: Float)
+      # Multiplies every sample by factor.
+
+      public_class_method def self.scale(opts = {})
+        raise 'ERROR: libvolk not available' unless available?
+
+        samples = opts[:samples]
+        factor  = opts[:factor].to_f
+        n = samples.length
+        return [] if n.zero?
+
+        in_ptr = float_ptr(samples)
+        out_ptr = PubFFI::MemoryPointer.new(:float, n)
+        scale_fn.call(out_ptr, in_ptr, factor, n)
+        out_ptr.read_array_of_float(n)
+      end
+
+      # Supported Method Parameters::
+      # sum = PWN::FFI::Volk.dot_prod(a: Array<Float>, b: Array<Float>)
+
+      public_class_method def self.dot_prod(opts = {})
+        raise 'ERROR: libvolk not available' unless available?
+
+        a = opts[:a]
+        b = opts[:b]
+        n = [a.length, b.length].min
+        return 0.0 if n.zero?
+
+        a_ptr = float_ptr(a)
+        b_ptr = float_ptr(b)
+        out_ptr = PubFFI::MemoryPointer.new(:float, 1)
+        dot_fn.call(out_ptr, a_ptr, b_ptr, n)
+        out_ptr.read_float
+      end
+
+      # Author(s):: 0day Inc. <support@0dayinc.com>
+
+      public_class_method def self.authors
+        "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+      end
+
+      # Display Usage for this Module
+
+      public_class_method def self.help
+        puts "USAGE:
+          #{self}.available?                           # => true/false
+          #{self}.unpack_s16le(data: raw_bytes)        # s16le → Float[-1,1]
+          #{self}.accumulate(samples:)                 # Σ samples
+          #{self}.magnitude_squared(iq:)               # |z|² per complex pair
+          #{self}.sqrt(samples:)
+          #{self}.scale(samples:, factor:)
+          #{self}.dot_prod(a:, b:)
+
+          #{self}.authors
+        "
+      end
+
+      class << self
+        private
+
+        def float_ptr(arr)
+          ptr = PubFFI::MemoryPointer.new(:float, arr.length)
+          ptr.write_array_of_float(arr.map(&:to_f))
+          ptr
+        end
+
+        def convert_fn
+          @convert_fn ||= PubFFI::Function.new(
+            :void, %i[pointer pointer float uint],
+            volk_16i_s32f_convert_32f
+          )
+        end
+
+        def accum_fn
+          @accum_fn ||= PubFFI::Function.new(
+            :void, %i[pointer pointer uint],
+            volk_32f_accumulator_s32f
+          )
+        end
+
+        def mag2_fn
+          @mag2_fn ||= PubFFI::Function.new(
+            :void, %i[pointer pointer uint],
+            volk_32fc_magnitude_squared_32f
+          )
+        end
+
+        def sqrt_fn
+          @sqrt_fn ||= PubFFI::Function.new(
+            :void, %i[pointer pointer uint],
+            volk_32f_sqrt_32f
+          )
+        end
+
+        def scale_fn
+          @scale_fn ||= PubFFI::Function.new(
+            :void, %i[pointer pointer float uint],
+            volk_32f_s32f_multiply_32f
+          )
+        end
+
+        def dot_fn
+          @dot_fn ||= PubFFI::Function.new(
+            :void, %i[pointer pointer pointer uint],
+            volk_32f_x2_dot_prod_32f
+          )
+        end
+      end
+    end
+  end
+end