libfst 0.1.0

data/lib/libfst/vcd.rb

@@ -0,0 +1,597 @@
+# Copyright (C) 2024 Théotime Bollengier <theotime.bollengier@ensta-bretagne.fr>
+#
+# This file is part of libfst.rb <https://gitlab.ensta-bretagne.fr/bollenth/libfst.rb>
+#
+# libfst.rb is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License,
+# or (at your option) any later version.
+#
+# libfst.rb is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with libfst.rb. If not, see <https://www.gnu.org/licenses/>. 
+
+
+# Handle [Value Change Dump](https://en.wikipedia.org/wiki/Value_change_dump) files.
+module VCD
+  # A Scope corresponds to a design element
+  class Scope
+    attr_reader :name      # @return [String]
+    attr_reader :type      # @return [Symbol] begin, fork, function, module or task
+    attr_reader :variables # @return [Array<Variable>]
+    attr_reader :children  # @return [Array<Scope>]
+    attr_reader :parent    # @return [Scope,nil]
+
+    # @!visibility private
+    def initialize(name, type, parent)
+      @name = name.to_s
+      @type = type.to_s.to_sym
+      @variables = []
+      @children = []
+      @parent = parent
+    end
+
+    # @return [String]
+    def to_s
+      "<#{self.class} @name=#{@name.inspect}, @type=#{@type.inspect}>"
+    end
+
+    # @return [String]
+    def path
+      return '/' if @parent.nil? # root
+      "#{@parent.path}#{@name}/"
+    end
+
+    # @return [String]
+    # @overload tree
+    def tree(prefix = '', last: true, first: true)
+      return @children.first.tree(prefix, last: last, first: first) if @parent.nil? && @variables.empty? && @children.length == 1
+      str = prefix + (first ? '' : (last ? '└─ ' : '├─ '))
+      str += "\e[34;1m#{@name}\e[0m (#{@type})\n"
+      prefix = prefix + (first ? '' : (last ? '   ' : '│  '))
+      mxvarnamelen = ([0] + @variables.collect{|v| v.name.length}).max
+      mxlenlen = ([0] + @variables.collect{|v| v.width == 0 ? 0 : v.width.to_s.length}).max
+      @variables.each_with_index do |v, i|
+        l = (@children.empty? and (i+1 == @variables.length))
+        str += prefix + (l ? '└─ ' : '├─ ') + v.name + ' '*(mxvarnamelen+1-v.name.length)
+        str += (v.width > 0 ? v.width.to_s : '').rjust(mxlenlen)
+        str += " #{v.type}\n"
+      end
+      @children.each_with_index do |c, i|
+        str += c.tree(prefix, last: (i+1 == @children.length), first: false)
+      end
+      str
+    end
+  end
+
+
+  # A Variable corresponds to a signal in the hierarchy of the design.
+  # It points to a {Trace}.
+  # Different variables can point to the same {Trace} : for example the clock signals from different modules
+  # are actualy the same physical signal.
+  class Variable
+    attr_reader :name   # @return [String]
+    attr_reader :type   # @return [Symbol] event, integer, parameter, real, realtime, reg, supply0, supply1, time, tri, triand, trior, trireg, tri0, tri1, wand, wire or wor
+    attr_reader :width  # @return [Integer]
+    attr_reader :id     # @return [String]
+    attr_reader :parent # @return [Scope]
+    attr_reader :trace  # @return [Trace]
+
+    # @!visibility private
+    def initialize(name, type, width, id, parent)
+      @name = name.to_s
+      @type = type.to_s.to_sym
+      @width = width.to_i
+      @id = id.to_s
+      @parent = parent
+    end
+
+    # @return [String]
+    def to_s
+      "<#{self.class} @name=#{@name.inspect}, @type=#{@type.inspect}, @width=#{@width.inspect}, @id=#{@id.inspect}>"
+    end
+
+    # @return [String]
+    def path
+      "#{@parent.path}#{@name}"
+    end
+
+    # @!visibility private
+    def set_trace(trace)
+      raise "Trace allready set for variable #{path}" if @trace
+      @trace = trace
+    end
+  end
+
+
+  class Trace
+    attr_reader :type      # @return [Symbol] event, integer, parameter, real, realtime, reg, supply0, supply1, time, tri, triand, trior, trireg, tri0, tri1, wand, wire or wor
+    attr_reader :width     # @return [Integer]
+    attr_reader :variables # @return [Array<Variable>]
+    attr_reader :id        # @return [String]
+
+    # @!visibility private
+    def initialize(type, width, variables, id)
+      @type = type.to_sym
+      @width = width.to_i
+      @variables = variables.freeze
+      @id = id.to_s
+    end
+  end
+
+
+  class Reader
+    attr_reader :date      # @return [String,nil]
+    attr_reader :version   # @return [String,nil]
+    attr_reader :comments  # @return [Array<String>]
+    attr_reader :timescale # @return [Float]
+    attr_reader :root      # @return [Scope]
+    attr_reader :traces    # @return [Hash{String => Trace}] Traces stored by ID
+
+
+    # @param io [String,IO] either a file name or an opened IO.
+    def initialize(io)
+      @io_is_file = false
+      if io.is_a?(String) then
+        @io_is_file = true
+        @io = File.open(io)
+      else
+        @io = io
+      end
+      @buf = []
+      @root = Scope.new('root', :module, nil)
+      @scope_stack = [@root]
+      @state = :process_definitions
+      @comments = []
+      @stop_parsing = false
+      @io.each_line do |line|
+        process_line(line.chomp)
+        break if @stop_parsing
+      end
+      if @io_is_file then
+        @io.close 
+        @io = io
+      end
+
+      remove_instance_variable :@stop_parsing
+      remove_instance_variable :@state
+      remove_instance_variable :@buf
+      remove_instance_variable :@scope_stack
+
+      @on_comment = nil
+      @on_time_change = nil
+    end
+
+
+    # Find a {Variable} by its name or path
+    # @param name [String] name or path to look for
+    # @return [Variable,nil]
+    def variable(name)
+      @traces.each_value do |t|
+        t.variables.each do |v|
+          return v if v.name == name or v.path == name
+        end
+      end
+      nil
+    end
+
+
+    # Returns the scope or variable corresponding to the specified path
+    # @param path [String]
+    # @return [Scope,Variable,nil]
+    def [](path)
+      return @root if path == '/'
+      raise ArgumentError, "expecting a String, not a #{path.class}" unless path.is_a?(String)
+      a = path.split('/').reject(&:empty?)
+      return nil if a.empty?
+      scope = @root
+      var = nil
+      a.each do |w|
+        var = scope.variables.select{ |v| v.name == w }.first
+        return var if var
+        s = scope.children.select{ |v| v.name == w }.first
+        return nil if s.nil?
+        scope = s
+      end
+      scope
+    end
+
+
+    # Set the block of code to be executed when a comment is found while reading the value change section of the file
+    # @return [self]
+    # @yieldparam comment [String]
+    # @yieldparam time [Integer] this integer is to be multiplied with {#timescale} the get the real time
+    # @yieldparam vcd [self]
+    def on_comment(&block)
+      @on_comment = block
+      self
+    end
+
+
+    # Set the block of code to be called when a time change is encountered.
+    # @return [self]
+    # @yieldparam time [Integer] this integer is to be multiplied with {#timescale} the get the real time
+    # @yieldparam vcd [self]
+    def on_time_change(&block)
+      @on_time_change = block
+      self
+    end
+
+
+    # Stop the parsing of the file.
+    # This method can be called from an {on_comment} or {read} block.
+    # @return [self]
+    def stop_parsing
+      @stop_parsing = true
+      self
+    end
+
+
+    # Read the value change section of the VCD file.
+    # @return [self]
+    # @param signals [Trace,Variable,Scope,String] if signals are specified, only those will trigger the block.
+    #  A path can be provided as a string, which correspond to a {Variable} or a {Scope}.
+    #  In the case of a {Scope}, all its variables will be added (NOT recursively).
+    # @param start_time [Integer,Float,String,nil] start time from which to trigger the block
+    # @param end_time [Integer,Float,String,nil] end time until which to trigger the block
+    # @yieldparam trace [Trace]
+    # @yieldparam value [String,Float]
+    # @yieldparam time [Integer] this integer is to be multiplied with {#timescale} the get the real time
+    # @yieldparam vcd [self]
+    def read(*signals, start_time: nil, end_time: nil, &block)
+      @time_win_start = nil
+      @time_win_end = nil
+      @trace_mask = nil
+
+      @time_win_start = time_to_itime(start_time, false) if start_time
+      @time_win_end   = time_to_itime(end_time,   true)  if end_time
+
+      unless signals.empty? then
+        @trace_mask = {}
+        signals.each do |sig|
+          if sig.is_a?(String) then
+            s = self[sig] 
+            raise "Cannot find #{sig.inspect} in the hierarchy" if s.nil?
+            sig = s
+          end
+          case sig
+          when Variable
+            @trace_mask[sig.trace.id] = true
+          when Trace
+            @trace_mask[sig.id] = true
+          when Scope
+            sig.variables.each do |var|
+              @trace_mask[var.trace.id] = true
+            end
+          else
+            raise TypeError, "Expecting a path, a #{Variable}, a #{Trace} or a #{Scope}, not a #{sig.class}"
+          end
+        end
+      end
+
+      @on_read = block
+
+      if @io_is_file then
+        io = @io
+        @io = File.open(io)
+        @io.seek(@value_change_pos, IO::SEEK_SET)
+      end
+
+      @stop_parsing = false
+      @state = nil
+      @buf = nil
+      @time = 0
+
+      @io.each_line do |line|
+        process_line(line.chomp)
+        break if @stop_parsing
+      end
+
+      remove_instance_variable :@time_win_start
+      remove_instance_variable :@time_win_end
+      remove_instance_variable :@trace_mask
+      remove_instance_variable :@on_read
+      remove_instance_variable :@stop_parsing
+      remove_instance_variable :@state
+      remove_instance_variable :@buf
+
+      if @io_is_file then
+        @io.close 
+        @io = io
+      end
+
+      @time = nil
+    end
+
+
+    # When called in one of the callbacks, returns the current time as an integer, `nil` otherwise.
+    # @return [Integer,nil] this value is to be multiplied with {#timescale} the get the real time
+    def time
+      @time
+    end
+
+
+    # When called in one of the callbacks, returns the current time in seconds, `nil` otherwise.
+    # @return [Float,nil]
+    def real_time
+      return nil unless @time
+      @time*@timescale
+    end
+
+
+    # When called in one of the callbacks, returns the current time as a string, `nil` otherwise.
+    # @param t [Integer,nil] 
+    # @return [String,nil] example: `"2.57 µs"`
+    def pretty_time(t = nil)
+      t ||= @time
+      return nil unless t
+      return '0 s' if t == 0
+      e = Math.log10(@timescale).round
+      while (-e % 3) != 0 do
+        t *= 10
+        e -= 1
+      end
+      while e < -15 do
+        t /= 10
+        e += 1
+      end
+
+      while e < 0 and (t % 1000) == 0 do
+        t /= 1000
+        e += 3
+      end
+
+      ent = t
+      qe = e
+      mf = 1
+      while qe < 0 and (ent / 1000) != 0 do
+        ent /= 1000
+        qe += 3
+        mf *= 1000
+      end
+
+      rem = t - mf*ent
+      while rem != 0 and (rem % 10) == 0 do
+        rem /= 10
+        e += 1
+      end
+
+      s = ent.to_s
+      if rem != 0 then
+        s += '.' + rem.to_s.rjust(qe - e, '0')
+      end
+      s += case qe
+           when   0; ' s'
+           when  -3; ' ms'
+           when  -6; ' µs'
+           when  -9; ' ns'
+           when -12; ' ps'
+           when -15; ' fs'
+           else
+             raise "unknown unit for exponent #{qe}"
+           end
+      s
+    end
+
+
+    # @return [String]
+    def to_s
+      [
+        "Date:      #{@date.inspect}",
+        "Version:   #{@version.inspect}",
+        "Timescale: #{@timescale}",
+        "Comments:",
+        @comments.collect{|s| "    " + s.inspect},
+        @root.tree
+      ].flatten.join("\n")
+    end
+
+
+    private
+
+
+    def process_line(line)
+      line.split(/\s+/).reject{|s| s.empty?}.each do |word|
+        process_word(word)
+      end
+    end
+
+
+    def process_word(word)
+      case @state
+      when :process_definitions
+        @buf << word
+        process_buffer if word == '$end'
+      when :get_bin_vector_vc
+        on_value_change_callback(word, @buf)
+        @state = nil
+      when :get_real_vc
+        on_value_change_callback(word, @buf)
+        @state = nil
+      when :get_string_vc
+        on_value_change_callback(word, @buf)
+        @state = nil
+      when :in_comment
+        if word == '$end' then
+          cmnt = @buf.join(' ')
+          @comments.push(cmnt)
+          @state = nil
+          on_comment_callback(cmnt)
+        else
+          @buf.push(word)
+        end
+      else
+        case word
+        when /^#(\d+)$/ # simulation time
+          @time = $1.to_i
+          on_time_change_callback
+        when /^([01xXzZuUwWlLhH-])([!-~]+)$/ # scalar value change
+          on_value_change_callback($2, $1)
+        when /^[bB]([01xXzZuUwWlLhH-]+)$/ # binary vector value change
+          @buf = $1
+          @state = :get_bin_vector_vc
+        when /^[sS](.+)$/
+          @buf = $1
+          @state = :get_string_vc
+        when /^[rR]([0-9.+eE-]+)$/ # real value change
+          @state = :get_real_vc
+          @buf = $1.to_f
+        when '$comment'
+          @buf = []
+          @state = :in_comment
+        when '$end'
+          @state = nil
+        when '$dumpall'
+          raise 'intricated simulation commands' if @state
+          @state = :in_dumpall
+        when '$dumpoff'
+          raise 'intricated simulation commands' if @state
+          @state = :in_dumpoff
+        when '$dumpon'
+          raise 'intricated simulation commands' if @state
+          @state = :in_dumpon
+        when '$dumpvars'
+          raise 'intricated simulation commands' if @state
+          @state = :in_dumpvars
+        else
+          raise "unexpected \"#{word}\""
+        end
+      end
+    end
+
+
+    def process_buffer
+      case @buf.first
+      when '$scope'
+        scope = Scope.new(@buf[2], @buf[1], @scope_stack.last)
+        @scope_stack.last.children.push(scope)
+        @scope_stack.push(scope)
+      when '$var'
+        var = Variable.new(@buf[4], @buf[1], @buf[2], @buf[3], @scope_stack.last)
+        @scope_stack.last.variables.push(var)
+      when '$upscope'
+        raise 'VCD hierarchy error: poping root scope with $upscope' if @scope_stack.pop == @root
+      when '$date'
+        if @date.nil? then
+          @date = ''
+        else 
+          @date += ' '
+        end
+        @date += @buf[1...-1].join(' ')
+      when '$version'
+        if @version.nil? then
+          @version = ''
+        else
+          @version += ' '
+        end
+        @version += @buf[1...-1].join(' ')
+      when '$comment'
+        @comments.push(@buf[1...-1].join(' '))
+      when '$attrbegin'
+        ## Ignore $attrbegin generated by nvc
+      when '$timescale'
+        s = @buf[1...-1].join
+        m = s.match(/^(\d+)([munpf]?)s$/)
+        raise "Cannot parse timescale: \"#{s}\"" unless m
+        @timescale = m[1].to_i * { '' => 1.0, 'm' => 1e-3, 'u' => 1e-6, 'n' => 1e-9, 'p' => 1e-12, 'f' => 1e-15 }[m[2]]
+      when '$enddefinitions'
+        @state = nil
+        gather_signals
+        @value_change_pos = @io.tell if @io_is_file
+        @stop_parsing = true
+      else
+        raise "VCD parsing ERROR: unexpected tocken: \"#{@buf.first}\""
+      end
+      @buf = []
+    end
+
+
+    def gather_variables(id_vararr, scope)
+      scope.variables.each do |var|
+        arr = id_vararr[var.id]
+        unless arr then
+          arr = []
+          id_vararr[var.id] = arr
+        end
+        arr.push(var)
+      end
+      scope.children.each do |subscope|
+        gather_variables(id_vararr, subscope)
+      end
+    end
+
+
+    def gather_signals
+      @traces = {}
+      variables = {}
+      gather_variables(variables, @root)
+      variables.each do |k, v|
+        type  = v.first.type
+        width = v.first.width
+        trace = Trace.new(type, width, v, k)
+        @traces[k] = trace
+        v.each do |var|
+          raise "trace with variables of different types (#{type}, #{var.type})" unless var.type == type
+          raise "trace with variables of different width (#{width}, #{var.width})" unless var.width == width
+          var.set_trace(trace)
+        end
+      end
+    end
+
+
+    def on_time_change_callback
+      return unless @on_time_change
+      return if @time_win_start && @time < @time_win_start
+      return if @time_win_end   && @time > @time_win_end
+      @on_time_change.call(@time, self)
+    end
+
+
+    def on_comment_callback(cmnt)
+      return unless @on_comment
+      return if @time_win_start && @time < @time_win_start
+      return if @time_win_end   && @time > @time_win_end
+      @on_comment.call(cmnt, @time, self)
+    end
+
+
+    def on_value_change_callback(id, value)
+      return unless @on_read
+      return if @time_win_start && @time < @time_win_start
+      return if @time_win_end   && @time > @time_win_end
+      return if @trace_mask && @trace_mask[id].nil?
+      @on_read.call(@traces[id], value, @time, self)
+    end
+
+
+    def time_to_itime(t, up = false)
+      u = case t
+          when Integer
+            t
+          when Float
+            if up then
+              (t / @timescale).ceil
+            else
+              (t / @timescale).floor
+            end
+          when String
+            m = t.match(/^([\d.eE+-]+)\s*([muµnpf]?)s?$/)
+            raise "cannot parse \"#{t}\" as a time" unless m
+            t = m[1].to_f
+            e = { '' => 1.0, 'm' => 1e-3, 'u' => 1e-6, 'µ' => 1e-6, 'n' => 1e-9, 'p' => 1e-12, 'f' => 1e-15 }[m[2]]
+            t *= e
+            t /= @timescale
+            up ? t.ceil : t.floor
+          else
+            raise "expecting an integer, a float or a string, not a #{t.class}"
+          end
+      [0, u].max
+    end
+
+  end
+end
+

data/lib/libfst/version.rb

@@ -0,0 +1,4 @@
+module LibFST
+  # LibFST gem version
+  VERSION = '0.1.0'
+end

data/lib/libfst/writer.rb

@@ -0,0 +1,50 @@
+# Copyright (C) 2024 Théotime Bollengier <theotime.bollengier@ensta-bretagne.fr>
+#
+# This file is part of libfst.rb <https://gitlab.ensta-bretagne.fr/bollenth/libfst.rb>
+#
+# libfst.rb is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License,
+# or (at your option) any later version.
+#
+# libfst.rb is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with libfst.rb. If not, see <https://www.gnu.org/licenses/>. 
+
+
+module LibFST
+  class Writer
+    # Helper to create a variable of type `:vcd_real`
+    # @see create_variable
+    # @return [Variable]
+    def create_float_variable(name, direction: :implicit)
+      create_variable(name, type: :vcd_real, direction: direction)
+    end
+
+    # Helper to create a 32-bit variable of type `:vcd_integer`
+    # @see create_variable
+    # @return [Variable]
+    def create_integer_variable(name, direction: :implicit)
+      create_variable(name, type: :vcd_integer, direction: direction, length: 32)
+    end
+
+    # Helper to create a 64-bit variable of type `:vcd_integer`
+    # @see create_variable
+    # @return [Variable]
+    def create_integer64_variable(name, direction: :implicit)
+      create_variable(name, type: :vcd_integer, direction: direction, length: 64)
+    end
+
+    # Helper to create a variable of type `:sv_logic`
+    # @see create_variable
+    # @return [Variable]
+    def create_logic_variable(name , direction: :implicit, length: 1)
+      create_variable(name, type: :sv_logic, direction: direction, length: length)
+    end
+  end
+end
+

data/lib/libfst.rb

@@ -0,0 +1,6 @@
+require_relative './libfst/libfst'
+require_relative './libfst/version.rb'
+require_relative './libfst/reader.rb'
+require_relative './libfst/writer.rb'
+require_relative './libfst/vcd.rb'
+require_relative './libfst/tfp.rb'

data/libfst.gemspec

@@ -0,0 +1,50 @@
+require File.expand_path('../lib/libfst/version.rb', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name = 'libfst'
+  s.version = LibFST::VERSION
+  s.date = Time.now.strftime '%Y-%m-%d'
+  s.summary = 'Fast Signal Trace bindings for Ruby'
+  s.description = 'fstlib allows to read and write FST files (Fast Signal Trace) from Ruby'
+  s.license = 'GPL-3.0-or-later'
+  s.authors = ['Théotime Bollengier']
+  s.email = 'theotime.bollengier@ensta-bretagne.fr'
+  s.homepage = 'https://gitlab.ensta-bretagne.fr/bollenth/fstlib.rb'
+  s.extensions = ['ext/extconf.rb']
+  s.files = [
+    'LICENSE',
+    'README.md',
+    'libfst.gemspec',
+    'lib/libfst.rb',
+    'lib/libfst/version.rb',
+    'lib/libfst/reader.rb',
+    'lib/libfst/writer.rb',
+    'lib/libfst/vcd.rb',
+    'lib/libfst/tfp.rb',
+    'ext/extconf.rb',
+    'ext/libfst_rb.c',
+    'ext/fstapi.c',
+    'ext/fastlz.c',
+    'ext/lz4.c',
+    'ext/fst_config.h',
+    'ext/lz4.h',
+    'ext/fstapi.h',
+    'ext/fastlz.h',
+    'ext/fst_win_unistd.h',
+    'samples/create_file.rb',
+    'samples/read_file.rb',
+    'samples/read2.rb',
+    'samples/skinny_rand.fst',
+    'samples/gtkwave.png',
+    'samples/out.gtkw',
+    'samples/vcd/skinny_rand.vcd.xz',
+    'samples/vcd/vcd_read.rb',
+    'samples/transaction_filter_process/full_boot.fst',
+    'samples/transaction_filter_process/full_boot.gtkw',
+    'samples/transaction_filter_process/uart.rb',
+    'samples/transaction_filter_process/sdcard.rb',
+    '.yardopts'
+  ]
+  s.required_ruby_version = '>= 2.7'
+end
+