pwn 0.5.621 → 0.5.626

data/lib/pwn/ffi/fftw.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+PubFFI = ::FFI unless defined?(PubFFI) # rubocop:disable Style/RedundantConstantBase
+
+module PWN
+  module FFI
+    # Thin single-precision FFTW3 binding (`libfftw3f`).
+    #
+    # Used by PWN::SDR::* spectrum work (GQRX FFT snapshots, wideband energy
+    # detectors) when MHz-rate FFTs outgrow pure-Ruby DFT. Missing library
+    # degrades cleanly via `.available?` — callers keep pure-Ruby fallbacks.
+    #
+    # No compile step at gem install; no shells. Plans are built with
+    # FFTW_ESTIMATE so first-call latency stays acceptable for REPL use.
+    module FFTW
+      extend PubFFI::Library
+
+      FFTW_ESTIMATE = (1 << 6)
+      FFTW_MEASURE  = 0
+      FFTW_FORWARD  = -1
+      FFTW_BACKWARD = 1
+
+      @load_error = nil
+      begin
+        ffi_lib %w[fftw3f libfftw3f.so.3 libfftw3f.so]
+      rescue LoadError => e
+        @load_error = e
+      end
+
+      class << self
+        attr_reader :load_error
+      end
+
+      unless @load_error
+        # fftwf_complex is float[2] (re, im) under the C ABI we target.
+        attach_function :fftwf_malloc, [:size_t], :pointer
+        attach_function :fftwf_free, [:pointer], :void
+        attach_function :fftwf_destroy_plan, [:pointer], :void
+        attach_function :fftwf_cleanup, [], :void
+        attach_function :fftwf_execute, [:pointer], :void
+
+        # Real → complex 1-D (out has n/2+1 complex bins = 2*(n/2+1) floats)
+        attach_function :fftwf_plan_dft_r2c_1d,
+                        %i[int pointer pointer uint],
+                        :pointer
+
+        # Complex → real 1-D
+        attach_function :fftwf_plan_dft_c2r_1d,
+                        %i[int pointer pointer uint],
+                        :pointer
+
+        # Complex ↔ complex 1-D
+        attach_function :fftwf_plan_dft_1d,
+                        %i[int pointer pointer int uint],
+                        :pointer
+      end
+
+      # Supported Method Parameters::
+      # PWN::FFI::FFTW.available?
+
+      public_class_method def self.available?
+        !@load_error && respond_to?(:fftwf_malloc, true)
+      rescue StandardError
+        false
+      end
+
+      # Supported Method Parameters::
+      # spectrum = PWN::FFI::FFTW.rfft(
+      #   samples: 'required - Array<Float> real input (length = n)',
+      #   n:       'optional - FFT size (default samples.length; zero-pads/truncates)'
+      # )
+      # Returns Array of [re, im] pairs, length n/2+1 (DC .. Nyquist).
+
+      public_class_method def self.rfft(opts = {})
+        raise 'ERROR: libfftw3f not available' unless available?
+
+        samples = opts[:samples]
+        n = (opts[:n] || samples.length).to_i
+        raise 'ERROR: n must be >= 1' if n < 1
+
+        in_ptr = fftwf_malloc(n * 4)
+        out_bins = (n / 2) + 1
+        out_ptr = fftwf_malloc(out_bins * 2 * 4)
+        raise 'ERROR: fftwf_malloc failed' if in_ptr.null? || out_ptr.null?
+
+        # zero + copy
+        in_ptr.write_array_of_float(Array.new(n, 0.0))
+        src = samples.first([n, samples.length].min).map(&:to_f)
+        in_ptr.write_array_of_float(src + Array.new(n - src.length, 0.0)) if src.length < n
+        in_ptr.write_array_of_float(src) if src.length == n
+
+        plan = fftwf_plan_dft_r2c_1d(n, in_ptr, out_ptr, FFTW_ESTIMATE)
+        raise 'ERROR: fftwf_plan_dft_r2c_1d failed' if plan.null?
+
+        fftwf_execute(plan)
+        flat = out_ptr.read_array_of_float(out_bins * 2)
+        result = Array.new(out_bins) { |i| [flat[2 * i], flat[(2 * i) + 1]] }
+
+        fftwf_destroy_plan(plan)
+        fftwf_free(in_ptr)
+        fftwf_free(out_ptr)
+        result
+      end
+
+      # Supported Method Parameters::
+      # mag = PWN::FFI::FFTW.rfft_magnitude(
+      #   samples: 'required - Array<Float>',
+      #   n:       'optional - FFT size'
+      # )
+      # Returns Array<Float> of |X[k]| for k=0..n/2.
+
+      public_class_method def self.rfft_magnitude(opts = {})
+        rfft(opts).map { |re, im| Math.sqrt((re * re) + (im * im)) }
+      end
+
+      # Supported Method Parameters::
+      # power_db = PWN::FFI::FFTW.rfft_power_db(
+      #   samples: 'required - Array<Float>',
+      #   n:       'optional - FFT size',
+      #   floor:   'optional - dB floor for zeros (default -120.0)'
+      # )
+      # Returns Array<Float> of 20*log10(|X[k]|) with a noise floor.
+
+      public_class_method def self.rfft_power_db(opts = {})
+        floor = (opts[:floor] || -120.0).to_f
+        rfft_magnitude(opts).map do |m|
+          m.positive? ? (20.0 * Math.log10(m)) : floor
+        end
+      end
+
+      # Supported Method Parameters::
+      # spectrum = PWN::FFI::FFTW.cfft(
+      #   iq:   'required - interleaved Array<Float> I/Q (even length)',
+      #   n:    'optional - number of complex samples (default iq.length/2)',
+      #   sign: 'optional - :forward (default) or :backward'
+      # )
+      # Returns Array of [re, im] pairs length n.
+
+      public_class_method def self.cfft(opts = {})
+        raise 'ERROR: libfftw3f not available' unless available?
+
+        iq = opts[:iq]
+        n = (opts[:n] || (iq.length / 2)).to_i
+        raise 'ERROR: n must be >= 1' if n < 1
+
+        sign = opts[:sign] == :backward ? FFTW_BACKWARD : FFTW_FORWARD
+        bytes = n * 2 * 4
+        in_ptr = fftwf_malloc(bytes)
+        out_ptr = fftwf_malloc(bytes)
+        raise 'ERROR: fftwf_malloc failed' if in_ptr.null? || out_ptr.null?
+
+        src = iq.first([2 * n, iq.length].min).map(&:to_f)
+        padded = src + Array.new((2 * n) - src.length, 0.0)
+        in_ptr.write_array_of_float(padded)
+
+        plan = fftwf_plan_dft_1d(n, in_ptr, out_ptr, sign, FFTW_ESTIMATE)
+        raise 'ERROR: fftwf_plan_dft_1d failed' if plan.null?
+
+        fftwf_execute(plan)
+        flat = out_ptr.read_array_of_float(n * 2)
+        result = Array.new(n) { |i| [flat[2 * i], flat[(2 * i) + 1]] }
+
+        fftwf_destroy_plan(plan)
+        fftwf_free(in_ptr)
+        fftwf_free(out_ptr)
+        result
+      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}.rfft(samples:, n: nil)             # real→complex, [[re,im],…]
+          #{self}.rfft_magnitude(samples:, n: nil)   # |X[k]|
+          #{self}.rfft_power_db(samples:, n:, floor: -120.0)
+          #{self}.cfft(iq:, n: nil, sign: :forward)  # complex FFT
+
+          #{self}.authors
+        "
+      end
+    end
+  end
+end

data/lib/pwn/ffi/hack_rf.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+PubFFI = ::FFI unless defined?(PubFFI) # rubocop:disable Style/RedundantConstantBase
+
+module PWN
+  module FFI
+    # Thin libhackrf binding for inventory / RX of raw I/Q.
+    #
+    # Intentionally control-plane first: init/open/tune/rate/gains + one-shot
+    # sync-style helpers used by Extrospection `probe_rf` and by wideband
+    # PWN::SDR::Decoder::* modules that need real I/Q (not GQRX audio).
+    # Streaming callbacks stay opt-in — Ruby GC must not run on the
+    # libusb transfer thread, so call sites that need continuous RX should
+    # buffer into a Queue from a dedicated thread.
+    module HackRF
+      extend PubFFI::Library
+
+      HACKRF_SUCCESS = 0
+
+      @load_error = nil
+      begin
+        ffi_lib %w[hackrf libhackrf.so.0 libhackrf.so]
+      rescue LoadError => e
+        @load_error = e
+      end
+
+      class << self
+        attr_reader :load_error
+      end
+
+      unless @load_error
+        attach_function :hackrf_init, [], :int
+        attach_function :hackrf_exit, [], :int
+        attach_function :hackrf_library_version, [], :string
+        attach_function :hackrf_library_release, [], :string
+        attach_function :hackrf_error_name, [:int], :string
+
+        attach_function :hackrf_open, [:pointer], :int
+        attach_function :hackrf_open_by_serial, %i[string pointer], :int
+        attach_function :hackrf_close, [:pointer], :int
+
+        attach_function :hackrf_set_freq, %i[pointer uint64], :int
+        attach_function :hackrf_set_sample_rate, %i[pointer double], :int
+        attach_function :hackrf_set_baseband_filter_bandwidth, %i[pointer uint32], :int
+        attach_function :hackrf_set_vga_gain, %i[pointer uint32], :int
+        attach_function :hackrf_set_lna_gain, %i[pointer uint32], :int
+        attach_function :hackrf_set_amp_enable, %i[pointer uint8], :int
+        attach_function :hackrf_is_streaming, [:pointer], :int
+        attach_function :hackrf_board_id_read, %i[pointer pointer], :int
+        attach_function :hackrf_board_id_name, [:uint8], :string
+        attach_function :hackrf_version_string_read, %i[pointer pointer uint8], :int
+      end
+
+      # Supported Method Parameters::
+      # PWN::FFI::HackRF.available?
+
+      public_class_method def self.available?
+        !@load_error && respond_to?(:hackrf_init, true)
+      rescue StandardError
+        false
+      end
+
+      # Supported Method Parameters::
+      # info = PWN::FFI::HackRF.info
+      # Returns Hash with library_version / library_release / available.
+
+      public_class_method def self.info
+        return { available: false, error: @load_error&.message } unless available?
+
+        {
+          available: true,
+          library_version: hackrf_library_version.to_s,
+          library_release: hackrf_library_release.to_s
+        }
+      end
+
+      # Supported Method Parameters::
+      # dev = PWN::FFI::HackRF.open(serial: nil)
+      # Returns FFI::Pointer (opaque hackrf_device*) or raises.
+
+      public_class_method def self.open(opts = {})
+        raise 'ERROR: libhackrf not available' unless available?
+
+        check!(hackrf_init)
+        dev_ptr = PubFFI::MemoryPointer.new(:pointer)
+        serial = opts[:serial]
+        rc = if serial
+               hackrf_open_by_serial(serial.to_s, dev_ptr)
+             else
+               hackrf_open(dev_ptr)
+             end
+        check!(rc)
+        dev_ptr.read_pointer
+      end
+
+      # Supported Method Parameters::
+      # PWN::FFI::HackRF.close(device: pointer)
+
+      public_class_method def self.close(opts = {})
+        dev = opts[:device]
+        return unless dev && !dev.null?
+
+        check!(hackrf_close(dev))
+        hackrf_exit
+        nil
+      end
+
+      # Supported Method Parameters::
+      # PWN::FFI::HackRF.configure(
+      #   device:     'required - pointer from .open',
+      #   freq_hz:    'required - center frequency Hz',
+      #   rate_hz:    'optional - sample rate (default 10e6)',
+      #   lna_gain:   'optional - 0..40 step 8 (default 16)',
+      #   vga_gain:   'optional - 0..62 step 2 (default 20)',
+      #   amp:        'optional - true/false RF amp (default false)',
+      #   bb_bw_hz:   'optional - baseband filter BW Hz'
+      # )
+
+      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] || 10_000_000).to_f
+        lna  = (opts[:lna_gain] || 16).to_i
+        vga  = (opts[:vga_gain] || 20).to_i
+        amp  = opts[:amp] ? 1 : 0
+
+        check!(hackrf_set_freq(dev, freq))
+        check!(hackrf_set_sample_rate(dev, rate))
+        check!(hackrf_set_lna_gain(dev, lna))
+        check!(hackrf_set_vga_gain(dev, vga))
+        check!(hackrf_set_amp_enable(dev, amp))
+        check!(hackrf_set_baseband_filter_bandwidth(dev, opts[:bb_bw_hz].to_i)) if opts[:bb_bw_hz]
+        true
+      end
+
+      # Supported Method Parameters::
+      # meta = PWN::FFI::HackRF.device_info(device: pointer)
+      # Returns { board_id:, board_name:, version: }
+
+      public_class_method def self.device_info(opts = {})
+        dev = opts[:device]
+        raise 'ERROR: :device required' if dev.nil? || dev.null?
+
+        bid_ptr = PubFFI::MemoryPointer.new(:uint8)
+        check!(hackrf_board_id_read(dev, bid_ptr))
+        bid = bid_ptr.read_uint8
+        ver_buf = PubFFI::MemoryPointer.new(:char, 255)
+        check!(hackrf_version_string_read(dev, ver_buf, 255))
+        {
+          board_id: bid,
+          board_name: hackrf_board_id_name(bid).to_s,
+          version: ver_buf.read_string
+        }
+      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
+          dev = #{self}.open(serial: nil)
+          #{self}.configure(device: dev, freq_hz:, rate_hz: 10e6, lna_gain: 16, vga_gain: 20, amp: false)
+          #{self}.device_info(device: dev)
+          #{self}.close(device: dev)
+
+          #{self}.authors
+        "
+      end
+
+      class << self
+        private
+
+        def check!(code)
+          return if code == HACKRF_SUCCESS
+
+          name = available? ? hackrf_error_name(code).to_s : code.to_s
+          raise "ERROR: libhackrf rc=#{code} (#{name})"
+        end
+      end
+    end
+  end
+end

data/lib/pwn/ffi/liquid.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+PubFFI = ::FFI unless defined?(PubFFI) # rubocop:disable Style/RedundantConstantBase
+
+module PWN
+  module FFI
+    # Thin liquid-dsp binding.
+    #
+    # Provides the high-level DSP building blocks that PWN::SDR::Decoder::*
+    # needs beyond pure-Ruby primitives: FM / frequency demodulation,
+    # multi-stage arbitrary resampling, and Kaiser FIR filters. Opaque
+    # liquid handles are held as FFI::Pointer and always freed in an
+    # ensure — no compile step, no shells. If libliquid is absent
+    # `.available?` is false and DSP falls back to pure Ruby.
+    #
+    # Complex samples use the GCC float _Complex ABI: interleaved
+    # float[2] (re, im) per sample, which is how liquid_float_complex is
+    # laid out under LIQUID_DEFINE_COMPLEX.
+    module Liquid
+      extend PubFFI::Library
+
+      @load_error = nil
+      begin
+        ffi_lib %w[liquid libliquid.so.1 libliquid.so]
+      rescue LoadError => e
+        @load_error = e
+      end
+
+      class << self
+        attr_reader :load_error
+      end
+
+      unless @load_error
+        # ── freqdem (analog FM / frequency demodulator) ────────────────
+        attach_function :freqdem_create, [:float], :pointer
+        attach_function :freqdem_destroy, [:pointer], :int
+        attach_function :freqdem_reset, [:pointer], :int
+        attach_function :freqdem_print, [:pointer], :int
+        attach_function :freqdem_demodulate_block,
+                        %i[pointer pointer uint pointer],
+                        :int
+
+        # ── msresamp_rrrf (multi-stage arbitrary real resampler) ───────
+        attach_function :msresamp_rrrf_create, %i[float float], :pointer
+        attach_function :msresamp_rrrf_destroy, [:pointer], :int
+        attach_function :msresamp_rrrf_reset, [:pointer], :int
+        attach_function :msresamp_rrrf_get_rate, [:pointer], :float
+        attach_function :msresamp_rrrf_get_delay, [:pointer], :float
+        attach_function :msresamp_rrrf_get_num_output, %i[pointer uint], :uint
+        attach_function :msresamp_rrrf_execute,
+                        %i[pointer pointer uint pointer pointer],
+                        :int
+
+        # ── firfilt_rrrf (real FIR filter) ─────────────────────────────
+        attach_function :firfilt_rrrf_create_kaiser,
+                        %i[uint float float float],
+                        :pointer
+        attach_function :firfilt_rrrf_create_dc_blocker,
+                        %i[uint float],
+                        :pointer
+        attach_function :firfilt_rrrf_destroy, [:pointer], :int
+        attach_function :firfilt_rrrf_reset, [:pointer], :int
+        attach_function :firfilt_rrrf_execute_block,
+                        %i[pointer pointer uint pointer],
+                        :int
+      end
+
+      # Supported Method Parameters::
+      # PWN::FFI::Liquid.available?
+
+      public_class_method def self.available?
+        !@load_error && respond_to?(:freqdem_create, true)
+      rescue StandardError
+        false
+      end
+
+      # Supported Method Parameters::
+      # audio = PWN::FFI::Liquid.freq_demod(
+      #   iq: 'required - interleaved I/Q Array<Float> (even length)',
+      #   kf: 'optional - modulation factor (default 0.5)'
+      # )
+      # Returns Array<Float> of demodulated real samples (length = iq.length/2).
+
+      public_class_method def self.freq_demod(opts = {})
+        raise 'ERROR: libliquid not available' unless available?
+
+        iq = opts[:iq]
+        kf = (opts[:kf] || 0.5).to_f
+        n  = iq.length / 2
+        return [] if n.zero?
+
+        fd = freqdem_create(kf)
+        raise 'ERROR: freqdem_create failed' if fd.null?
+
+        begin
+          in_ptr = float_ptr(iq.first(n * 2))
+          out_ptr = PubFFI::MemoryPointer.new(:float, n)
+          rc = freqdem_demodulate_block(fd, in_ptr, n, out_ptr)
+          raise "ERROR: freqdem_demodulate_block rc=#{rc}" unless rc.zero?
+
+          out_ptr.read_array_of_float(n)
+        ensure
+          freqdem_destroy(fd)
+        end
+      end
+
+      # Supported Method Parameters::
+      # out = PWN::FFI::Liquid.resample(
+      #   samples:  'required - Array<Float>',
+      #   rate:     'required - output/input ratio (>0)',
+      #   as_db:    'optional - stop-band attenuation dB (default 60.0)'
+      # )
+      # Returns Array<Float> of resampled samples.
+
+      public_class_method def self.resample(opts = {})
+        raise 'ERROR: libliquid not available' unless available?
+
+        samples = opts[:samples]
+        rate    = opts[:rate].to_f
+        as_db   = (opts[:as_db] || 60.0).to_f
+        raise 'ERROR: rate must be > 0' unless rate.positive?
+        return samples.dup if samples.empty?
+
+        q = msresamp_rrrf_create(rate, as_db)
+        raise 'ERROR: msresamp_rrrf_create failed' if q.null?
+
+        begin
+          nx = samples.length
+          # allocate generously: ceil(1 + 2*r*nx)
+          ny_max = [1, (1 + (2 * rate * nx)).ceil].max
+          in_ptr = float_ptr(samples)
+          out_ptr = PubFFI::MemoryPointer.new(:float, ny_max)
+          ny_ptr = PubFFI::MemoryPointer.new(:uint, 1)
+          rc = msresamp_rrrf_execute(q, in_ptr, nx, out_ptr, ny_ptr)
+          raise "ERROR: msresamp_rrrf_execute rc=#{rc}" unless rc.zero?
+
+          ny = ny_ptr.read_uint
+          out_ptr.read_array_of_float(ny)
+        ensure
+          msresamp_rrrf_destroy(q)
+        end
+      end
+
+      # Supported Method Parameters::
+      # out = PWN::FFI::Liquid.fir_kaiser(
+      #   samples: 'required - Array<Float>',
+      #   length:  'optional - filter length (default 51, odd preferred)',
+      #   fc:      'optional - normalised cutoff 0..0.5 (default 0.1)',
+      #   as_db:   'optional - stop-band attenuation dB (default 60.0)',
+      #   mu:      'optional - fractional sample offset (default 0.0)'
+      # )
+      # Returns Array<Float> same length as input.
+
+      public_class_method def self.fir_kaiser(opts = {})
+        raise 'ERROR: libliquid not available' unless available?
+
+        samples = opts[:samples]
+        length  = (opts[:length] || 51).to_i
+        fc      = (opts[:fc] || 0.1).to_f
+        as_db   = (opts[:as_db] || 60.0).to_f
+        mu      = (opts[:mu] || 0.0).to_f
+        return [] if samples.empty?
+
+        q = firfilt_rrrf_create_kaiser(length, fc, as_db, mu)
+        raise 'ERROR: firfilt_rrrf_create_kaiser failed' if q.null?
+
+        begin
+          n = samples.length
+          in_ptr = float_ptr(samples)
+          out_ptr = PubFFI::MemoryPointer.new(:float, n)
+          rc = firfilt_rrrf_execute_block(q, in_ptr, n, out_ptr)
+          raise "ERROR: firfilt_rrrf_execute_block rc=#{rc}" unless rc.zero?
+
+          out_ptr.read_array_of_float(n)
+        ensure
+          firfilt_rrrf_destroy(q)
+        end
+      end
+
+      # Supported Method Parameters::
+      # out = PWN::FFI::Liquid.dc_block(
+      #   samples: 'required - Array<Float>',
+      #   m:       'optional - prototype semi-length (default 7 → len 15)',
+      #   as_db:   'optional - stop-band attenuation dB (default 60.0)'
+      # )
+
+      public_class_method def self.dc_block(opts = {})
+        raise 'ERROR: libliquid not available' unless available?
+
+        samples = opts[:samples]
+        m       = (opts[:m] || 7).to_i
+        as_db   = (opts[:as_db] || 60.0).to_f
+        return [] if samples.empty?
+
+        q = firfilt_rrrf_create_dc_blocker(m, as_db)
+        raise 'ERROR: firfilt_rrrf_create_dc_blocker failed' if q.null?
+
+        begin
+          n = samples.length
+          in_ptr = float_ptr(samples)
+          out_ptr = PubFFI::MemoryPointer.new(:float, n)
+          rc = firfilt_rrrf_execute_block(q, in_ptr, n, out_ptr)
+          raise "ERROR: firfilt_rrrf_execute_block rc=#{rc}" unless rc.zero?
+
+          out_ptr.read_array_of_float(n)
+        ensure
+          firfilt_rrrf_destroy(q)
+        end
+      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}.freq_demod(iq:, kf: 0.5)                # FM I/Q → audio
+          #{self}.resample(samples:, rate:, as_db: 60.0)  # arbitrary rate
+          #{self}.fir_kaiser(samples:, length: 51, fc: 0.1, as_db: 60.0)
+          #{self}.dc_block(samples:, m: 7, as_db: 60.0)
+
+          #{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
+      end
+    end
+  end
+end