libfst 0.1.0

data/lib/libfst/reader.rb

@@ -0,0 +1,345 @@
+# 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 Reader
+    # A Trace keeps track of the value changes of a physical signal.
+    class Trace
+      attr_reader :handle     # @return [Integer]
+      attr_reader :variables  # @return [Array<Variable>]
+      attr_accessor :is_float # @return [Boolean]
+
+      # @!visibility private
+      def initialize(handle)
+        @handle = handle.to_i
+        @variables = []
+      end
+
+      # @return [String]
+      def to_s
+        "<#{self.class.name} #{@handle} #{name} [#{@variables.collect(&:path).join(', ')}]>"
+      end
+
+      # @return [String]
+      def name
+        return @name if @name
+        update_name_and_path!
+        @name
+      end
+
+      # @return [String]
+      def path
+        return @path if @path
+        update_name_and_path!
+        @path
+      end
+
+      private
+
+      def update_name_and_path!
+        v = @variables.reject(&:is_alias)
+        raise "There are #{v.length} variables for the same trace which are not aliases!" if v.length != 1
+        v = v.first
+        @path = v.path
+        @name = v.name
+        self
+      end
+    end
+
+
+    # An attribute can provide additional information to a scope or a variable.
+    #
+    # Attributes of {#type} `:misc` do not need a matching `:attrend`.
+    class Attribute
+      # @return [Symbol] Either `:misc`, `:array`, `:enum` or `:pack`
+      attr_reader :type
+
+      # When `@type` is
+      # - __:misc__:  `:comment`, `:envvar`, `:supvar`, `:pathname`, `:sourcestem`, `:sourceistem`, `:valuelist`, `:enumtable`, `:unknown`
+      # - __:array__: `:none`, `:unpacked`, `:packed` or `:sparse`
+      # - __:enum__:  `:integer`, `:bit`, `:logic`, `:int`, `:shortint`, `:longint`, `:byte`, `:unsigned_integer`, `:unsigned_bit`, `:unsigned_logic`, `:unsigned_int`, `:unsigned_shortint`, `:unsigned_longint`, `:unsigned_byte`, `:reg` or `:time`
+      # - __:pack__:  `:none`, `:unpacked`, `:packed` or `:tagged_packed`
+      # @return [Symbol] 
+      attr_reader :subtype       
+
+      attr_reader :name          # @return [String]
+      attr_reader :arg           # @return [Integer]
+      attr_reader :arg_from_name # @return [Integer]
+
+      # @!visibility private
+      def initialize(type, subtype, name, arg, arg_from_name)
+        @type = type
+        @subtype = subtype
+        @name = name
+        @arg = arg
+        @arg_from_name = arg_from_name
+      end
+
+      # @return [String]
+      def to_s
+        "<#{self.class.name} #{@name}, type: #{@type}, subtype: #{@subtype}, arg: #{@arg}, arg_from_name: #{@arg_from_name}>"
+      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 signal from different modules is actualy the same 
+    # physical signal.
+    class Variable
+      attr_reader   :type       # @return [Symbol] Either `:vcd_event`, `:vcd_integer`, `:vcd_parameter`, `:vcd_real`, `:vcd_real_parameter`, `:vcd_reg`, `:vcd_supply0`, `:vcd_supply1`, `:vcd_time`, `:vcd_tri`, `:vcd_triand`, `:vcd_trior`, `:vcd_trireg`, `:vcd_tri0`, `:vcd_tri1`, `:vcd_wand`, `:vcd_wire`, `:vcd_wor`, `:vcd_port`, `:vcd_sparray`, `:vcd_realtime`, `:gen_string`, `:sv_bit`, `:sv_logic`, `:sv_int`, `:sv_shortint`, `:sv_longint`, `:sv_byte`, `:sv_enum` or `:sv_shortreal` 
+      attr_reader   :direction  # @return [Symbol] Either `:implicit`, `:input`, `:output`, `:inout`, `:buffer` or `:linkage`
+      attr_reader   :name       # @return [String]
+      attr_reader   :length     # @return [Integer]
+      attr_reader   :handle     # @return [Integer]
+      attr_reader   :is_alias   # @return [Boolean]
+      attr_accessor :trace      # @return [Trace] 
+      attr_accessor :scope      # @return [Scope]
+      attr_accessor :attributes # @return [Array<Attribute>]
+
+      # @!visibility private
+      def initialize(type, direction, name, length, handle, is_alias)
+        @type       = type
+        @direction  = direction
+        @name       = name
+        @length     = length
+        @handle     = handle
+        @is_alias   = is_alias
+        @attributes = []
+      end
+
+      # @return [String]
+      def path
+        return @path if @path
+        p = "/#{name}"
+        p = @scope.path + p if @scope
+        @path = p
+      end
+
+      # @return [String]
+      def to_s
+        "<#{self.class.name} #{path}  type: #{@type}, dir: #{@direction}, len: #{@length}, handle: #{@handle}, is_alias: #{!!@is_alias}>"
+      end
+    end
+
+
+    # A Scope corresponds to a design element
+    class Scope
+      attr_reader   :type       # @return [Symbol] Either `:vcd_module`, `:vcd_task`, `:vcd_function`, `:vcd_begin`, `:vcd_fork`, `:vcd_generate`, `:vcd_struct`, `:vcd_union`, `:vcd_class`, `:vcd_interface`, `:vcd_package`, `:vcd_program`, `:vhdl_architecture`, `:vhdl_procedure`, `:vhdl_function`, `:vhdl_record`, `:vhdl_process`, `:vhdl_block`, `:vhdl_for_generate`, `:vhdl_if_generate`, `:vhdl_generate` or `:vhdl_package`
+      attr_reader   :name       # @return [String]
+      attr_reader   :component  # @return [String,nil]
+      attr_reader   :variables  # @return [Array<Variable>]
+      attr_accessor :attributes # @return [Array<Attribute>]
+      attr_accessor :parent     # @return [Scope, nil]
+      attr_reader   :children   # @return [Array<Scope>]
+
+      # @!visibility private
+      def initialize(type, name, component)
+        @type = type
+        @name = name
+        @component = component
+        @variables = []
+        @attributes = []
+        @parent = nil
+        @children = []
+      end
+
+      # @return [String]
+      def path
+        return @path if @path
+        s = self
+        p = ''
+        until s.nil?
+          p = "/#{s.name}#{p}"
+          s = s.parent
+        end
+        @path = p
+      end
+
+      # @return [String]
+      def to_s
+        "<#{self.class.name} #{path}, type: #{@type}, component: \"#{@component}\">"
+      end
+
+      # @return [String]
+      # @overload tree
+      def tree(prefix = '', last: true, first: true)
+        str = prefix + (first ? '' : (last ? '└─ ' : '├─ '))
+        str += "\e[34;1m#{@name}\e[0m (#{@type})\n"
+        prefix += (first ? '' : (last ? '   ' : '│  '))
+        mxvarnamelen = ([0] + @variables.collect{|v| v.name.length}).max
+        mxlenlen = ([0] + @variables.collect { |v| v.length == 0 ? 0 : v.length.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 += case v.direction
+                 when :input  then ' I '
+                 when :output then ' O '
+                 when :inout  then 'IO '
+                 else              '   '
+                 end
+          str += (v.length > 0 ? v.length.to_s : '').rjust(mxlenlen)
+          str += " #{v.type}\n"
+        end
+        @children.each_with_index do |c, i|
+          str += c.tree(prefix, (i+1 == @children.length), false)
+        end
+        str
+      end
+    end
+  end
+
+
+  class Reader
+    attr_reader :filename  # @return [String]
+    attr_reader :traces    # @return [Array<Trace>]
+    attr_reader :variables # @return [Array<Variable>]
+    attr_reader :root      # @return [Scope]
+
+    def initialize(filename)
+      @filename = File.expand_path(filename)
+      open(@filename)
+      @traces = max_handle.times.collect { |i| Trace.new(i+1) }
+      @variables = []
+      travel_hierarchy
+    end
+
+
+    # Find a {Trace} by its name or path
+    # @param name [String] name or path to look for
+    # @return [Trace,nil]
+    def trace(name)
+      @traces.each do |t|
+        return t if t.name == name or t.path == name
+      end
+      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)
+      @variables.each do |v|
+        return v if v.name == name or v.path == name
+      end
+      nil
+    end
+
+    # Returns the scope or variable corresponding to the specified path
+    # @param path [String]
+    # @return [Scope,Variable,nil]
+    def [](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?
+      return nil if a[0] != @root.name
+      scope = @root
+      var = nil
+      a[1..].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
+
+    # Pretty print the integer time given as parametter according to the time scale
+    # @param timei [Integer]
+    # @return [String]
+    def pretty_time(timei)
+      return '0 s' if timei == 0
+      i = time_scale_exponent
+      e = (i/3)*3
+      f = 10**(i - e)
+      timei *= f
+      loop do
+        break if e >= 0
+        m = timei % 1000
+        break if m != 0
+        timei /= 1000
+        e += 3
+      end
+      s = timei.to_s
+      l = s.length
+      i = ((l-1)/3)*3
+      return "#{timei} #{['', 'm', 'µ', 'n', 'p', 'f'][-e/3]}s" if i <= 0 or e+i > 0
+      e += i
+      ent = s[0...l-i]
+      frac = s[l-i..].sub(/0+$/, '')
+      "#{ent}.#{frac} #{['', 'm', 'µ', 'n', 'p', 'f'][-e/3]}s"
+    end
+
+
+    private
+
+    # Build up the design hierarchy
+    def travel_hierarchy
+      scopes = []
+      attributes = []
+      iterate_hier_rewind
+      loop do
+        h = iterate_hier
+        break if h.nil?
+        case h
+        when Scope
+          unless attributes.empty? then
+            h.attributes = attributes
+            attributes = []
+          end
+          if scopes.empty? then
+            raise 'what?' unless @root.nil?
+            @root = h
+          else
+            p = scopes.last
+            h.parent = p
+            p.children.push h
+          end
+          scopes.push h
+        when Variable
+          trace = @traces[h.handle-1]
+          h.trace = trace
+          trace.variables.push h
+          unless attributes.empty? then
+            h.attributes = attributes
+            attributes = []
+          end
+          @variables.push h
+          if scopes.empty? then
+            raise 'what?' unless @root.nil?
+            p = Scope.new(:vcd_module, 'root', nil)
+            scopes.push p
+            @root = p
+          end
+          scopes.last.variables.push h
+          h.scope = scopes.last
+          trace.is_float = true if h.type == :vcd_real or h.type == :vcd_real_parameter or h.type == :vcd_realtime or h.type == :sv_shortreal
+        when Attribute
+          attributes << h
+        when :upscope
+          scopes.pop
+        when :attrend
+          raise 'What attrend is used for?'
+        end
+      end
+      iterate_hier_rewind
+      self
+    end
+  end
+end
+

data/lib/libfst/tfp.rb

@@ -0,0 +1,112 @@
+# 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/>. 
+
+require_relative './vcd'
+
+# This module handles GTKWave specific stuf.
+module GTKWave
+  # This is a base class which ease the creation of GTKWave Transaction Filter Process.
+  #
+  # Such a process is called by GTKWave which feeds it some VCD on the standard input,
+  # the process decodes what it can from the input then writes some kind of VCD on the 
+  # standard output, which is interpreted and displayed by GTKWave.
+  class TransactionFilter
+    attr_reader :ivcd              # @return [VCD::Reader]
+    attr_reader :name              # @return [String]
+    attr_reader :data_start_tocken # @return [Integer]
+    attr_reader :min_time          # @return [Integer]
+    attr_reader :max_time          # @return [Integer]
+    attr_reader :max_seqn          # @return [Integer]
+    attr_reader :args              # @return [String]
+    attr_reader :signames          # @return [Array<String>] Signal names ordered according to "seqn"
+
+    def initialize
+      @ivcd = VCD::Reader.new($stdin)
+      exit 0 if $stdin.eof?
+
+      @signames = []
+
+      @ivcd.comments.each do |cmnt|
+        case cmnt
+        when /^name (.+)$/
+          @name = $1
+        when /^data_start 0x(\h+)$/
+          @data_start_tocken = $1.to_i(16)
+        when /^min_time (\d+)$/
+          @min_time = $1.to_i
+        when /^max_time (\d+)$/
+          @max_time = $1.to_i
+        when /^max_seqn (\d+)$/
+          @max_seqn = $1.to_i
+        when /^seqn (\d+) (.+)$/
+          @signames[$1.to_i - 1] = $2
+        when /^args "(.*?)"$/
+          @args = $1.split(/\s*;\s*/).reject{|v| v.empty?}
+        end
+      end
+
+      raise "Cannot find name comment"       if @name.nil?
+      raise "Cannot find data_start comment" if @data_start_tocken.nil?
+      raise "Cannot find min_time comment"   if @min_time.nil?
+      raise "Cannot find max_time comment"   if @max_time.nil?
+      raise "Cannot find max_seqn comment"   if @max_seqn.nil?
+      raise "Cannot find args comment"       if @args.nil?
+
+      @ivcd.on_comment do |cmnt|
+        m = cmnt.match(/^data_end 0x(\h+)$/)
+        next if m.nil?
+        @ivcd.stop_parsing if m[1].to_i(16) == @data_start_tocken
+      end
+
+    end
+
+
+    def read
+      @ivcd.read
+    end
+
+
+    def self.run
+      loop do
+        read_all_input = false
+        begin
+          decoder = self.new
+          decoder.read
+          read_all_input = true
+          decoder.write
+        rescue => e
+          $stderr.puts e.full_message(highlight: true, order: :top)
+#          $stderr.puts e.message
+          unless read_all_input then
+            #$stderr.puts "Flushing STDIN..."
+            $stdin.each_line do |line|
+              #$stderr.puts line
+              break if line =~ /^\$comment\s+data_end\s+0x\h+\s+\$end\n$/
+            end
+            #$stderr.puts "DONE"
+          end
+          $stdout.puts '$name DECODE_ERROR'
+          $stdout.puts "#0 ?red?#{e.message}"
+          $stdout.puts '$finish'
+          $stdout.flush
+        end
+      end
+    end
+
+  end
+end
+