origen 0.0.1 → 0.0.2

data/lib/origen/utility/diff.rb

@@ -0,0 +1,158 @@
+module Origen
+  module Utility
+    # Diff provides an easy way to diff the contents of two files while optionally
+    # ignoring any differences in file comments.
+    #
+    #   differ = Origen::Utility::Diff.new(:ignore_blank_lines => true, :comment_char => "//")
+    #
+    #   differ.file_a = "#{Origen.root}/my/file1.v"
+    #   differ.file_b = "#{Origen.root}/my/file2.v"
+    #
+    #   if differ.diffs?
+    #     puts "You've changed something!"
+    #   end
+    class Diff
+      # Full path to File A, this attribute must be set before calling any diff actions
+      attr_accessor :file_a
+      # Full path to File B, this attribute must be set before calling any diff actions
+      attr_accessor :file_b
+      # When true the diff will ignore blank lines, or lines that contain only whitespace
+      attr_accessor :ignore_blank_lines
+      # Set this attribute to the comment char used by the given file and comments will
+      # be ignored by the diff.
+      # An array of strings can be passed in to mask multiple comment identifiers.
+      attr_accessor :comment_char
+
+      # Create a new diff, attributes can be initialized via the options, or can be
+      # set later.
+      def initialize(options = {})
+        @file_a = options[:file_a]
+        @file_b = options[:file_b]
+        @ignore_blank_lines = options[:ignore_blank_lines]
+        @comment_char = options[:comment_char]
+        @suspend_string = options[:suspend_string] # permits suspending diff check based on a string
+        @resume_string  = options[:resume_string]  # permits resuming diff check based on a string
+        @suspend_diff = false
+        @resume_diff = false
+      end
+
+      # Returns true if there are differences between the two files based on the
+      # current configuration
+      def diffs?
+        initialize_counters
+        result = false
+        content_a = File.readlines(@file_a)
+        content_b = File.readlines(@file_b)
+
+        changes = false
+        lines_remaining = true
+
+        while lines_remaining
+          a = get_next_line_a(content_a)   # Get the next vectors
+          b = get_next_line_b(content_b)
+          if !a && !b       # If both patterns finished
+            lines_remaining = false
+          elsif !a || !b    # If only 1 pattern finished
+            lines_remaining = false
+            changes = true unless @suspend_diff     # There are extra vectors in one of the patterns
+          elsif a != b      # If the vectors don't match
+            changes = true unless @suspend_diff
+          end
+          if @resume_diff # resume checking diffs for subsequent lines
+            @suspend_diff = false
+            @resume_diff = false
+          end
+        end
+
+        changes
+      end
+
+      private
+
+      def set_suspend_diff(line)
+        if line.valid_encoding?
+          if @suspend_string && !@suspend_diff
+            if line =~ /#{@suspend_string}/
+              @suspend_diff = true
+            end
+          elsif @resume_string && @suspend_diff
+            if line =~ /#{@resume_string}/
+              @resume_diff = true
+            end
+          end
+        end
+      end
+
+      def get_next_line_b(array)
+        @b_ix = next_index(array, @b_ix)
+        get_line(array, @b_ix)
+      end
+
+      def get_next_line_a(array)
+        @a_ix = next_index(array, @a_ix)
+        get_line(array, @a_ix)
+      end
+
+      # Fetches the line from the given array and does some pre-processing
+      def get_line(array, ix)
+        line = array[ix]
+        if line
+          set_suspend_diff(line)
+          if @comment_char
+            # Screen off any inline comments at the end of line
+            begin
+              [@comment_char].flatten.each do |_char|
+                if line =~ /(.*)#{@char}.*/
+                  return Regexp.last_match[1].strip
+                end
+              end
+            # This rescue is a crude way to guard against non-ASCII files that find
+            # their way in here
+          rescue
+            return line
+            end
+          else
+            line.strip
+          end
+        end
+      end
+
+      # Find the next line in the given array and return the new index pointer
+      def next_index(array, ix = nil)
+        ix = ix ? ix + 1 : 0
+        matched = false
+        while !matched && ix < array.size
+          begin
+            comment_matched = false
+            # Skip comment lines
+            if @comment_char
+              [@comment_char].flatten.each do |char|
+                if array[ix] =~ /^\s*#{char}.*/
+                  comment_matched = true
+                end
+              end
+            end
+            # Skip blank lines
+            if comment_matched
+              ix += 1
+            elsif @ignore_blank_lines && array[ix] =~ /^\s*$/
+              ix += 1
+            else
+              matched = true
+            end
+        # This rescue is a crude way to guard against non-ASCII files that find
+        # there way in here
+        rescue
+          matched = true
+          end
+        end
+        ix
+      end
+
+      def initialize_counters
+        @a_ix = nil
+        @b_ix = nil
+      end
+    end
+  end
+end

data/lib/origen/utility/input_capture.rb

@@ -0,0 +1,121 @@
+require 'readline'
+module Origen
+  module Utility
+    module InputCapture
+      # Gets text input from the user
+      # Supply an optional default value in the event that the user enters nothing
+      def get_text(options = {})
+        options = { default:        false,
+                    single:         false,     # Set if only a single line entry is expected
+                    confirm:        false,
+                    accept:         false,         # Supply and array of entries you are willing to accept
+                    case_sensitive: false, # If accept values are supplied they will be treated as case
+                    # in-sensitive by default
+                    wrap:           true,   # Automatically split long lines
+        }.merge(options)
+        if options[:confirm]
+          puts "Type 'yes' or 'no' to confirm or 'quit' to abort."
+        elsif options[:accept]
+          puts "You can enter: #{options[:accept].map { |v| "'#{v}'" }.join(', ')} or 'quit' to abort."
+          # "
+        else
+          puts options[:single] ? "Enter 'quit' to abort." : "Enter a single '.' to finish, or 'quit' to abort."
+        end
+        puts '------------------------------------------------------------------------------------------'
+        text = ''
+        line = ''
+        if options[:confirm]
+          print "(#{options[:default]}): " if options[:default]
+        else
+          print "Hit return to accept the default (#{options[:default]}): " if options[:default]
+        end
+
+        while line != '.'
+          orig_line = Readline.readline('', false).chomp.rstrip
+          line = orig_line.strip
+          if (line.empty? || line == '.') && text.empty? && options[:default]
+            text = options[:default].to_s
+            line = '.'
+          elsif line.downcase == 'quit'
+            exit 0
+          elsif line == '.'
+          # Do nothing
+          else
+            if options[:wrap]
+              split_long_line(orig_line) do |short_line|
+                text << "#{short_line}\n"
+              end
+            else
+              text << orig_line
+            end
+          end
+          confirm = text.strip.downcase if options[:confirm]
+          text = text.strip if options[:single]
+          line = '.' if options[:single] || options[:confirm]
+        end
+        puts ''
+
+        if options[:confirm]
+          if confirm == 'no' || confirm == 'n'
+            if options[:confirm] == :return_boolean
+              return false
+            else
+              exit 0
+            end
+          end
+          if confirm == 'yes' || confirm == 'y'
+            if options[:confirm] == :return_boolean
+              return true
+            else
+              return
+            end
+          else
+            get_text(options)
+          end
+
+        elsif options[:accept]
+          accept = options[:accept].map do |v|
+            v = v.to_s
+            v = v.downcase unless options[:case_sensitive]
+            v
+          end
+          text = text.downcase unless options[:case_sensitive]
+          text = text.strip
+          if accept.include?(text)
+            text
+          else
+            get_text(options)
+          end
+
+        else
+          text
+        end
+      end
+
+      # Splits a long line into short ones, split by the nearest space
+      def split_long_line(line)
+        if line.length <= 90
+          yield line
+        else
+          until line.empty?
+            if line.length <= 90
+              yield line
+              line = ''
+            else
+              yield line.slice(0, find_space(line, 90))
+              line = line.slice(find_space(line, 90), line.length).strip
+            end
+          end
+        end
+      end
+
+      # Find the space closest to but less than max_position, returns max_position if none
+      # can be found
+      def find_space(line, max_position)
+        x = max_position
+        x -= 1 until line[x] == ' ' || x == 0
+        x == 0 ? max_position : x
+      end
+    end
+  end
+end

data/lib/origen/utility/mailer.rb

@@ -0,0 +1,143 @@
+require 'net/smtp'
+module Origen
+  module Utility
+    class Mailer
+      include Users
+
+      # Generic method to send an email, alternatively use one of the
+      # pre-defined mail types using the other methods.
+      def send_email(options = {})
+        options = { server:     Origen.site_config.email_server,
+                    port:       Origen.site_config.email_port,
+                    from:       current_user.email,
+                    from_alias: current_user.name,
+                    subject:    'Hello',
+                    body:       'Hello from Origen!',
+                    to:         'Stephen McGinty <stephen.mcginty@freescale.com>'
+                  }.merge(options)
+
+        # Force to an array
+        to = options[:to].respond_to?('each') ? options[:to] : [options[:to]]
+
+        # Convert any user objects to an email
+        to = to.map { |obj| obj.respond_to?('email') ? obj.email : obj }
+
+        to.uniq.each do |addr|
+          msg = <<END_OF_MESSAGE
+From: #{options[:from_alias]} <#{options[:from]}>
+To: #{addr}
+Subject: #{options[:subject]}
+
+#{options[:body]}
+END_OF_MESSAGE
+
+          begin
+            # Exceptions raised here will be caught by rescue clause
+            Net::SMTP.start(options[:server], options[:port]) do |smtp|
+              smtp.send_message msg, options[:from], addr
+            end
+          rescue
+            warn "Email not able to be sent to address '#{addr}'"
+          end
+        end
+      end
+
+      # Call to send a notice
+      def send_release_notice(version, release_note, type, selectors, options = {})
+        if external?(type)
+          header = "A new version of #{config.name} is available:"
+        else
+          header = "A new development version of #{config.name} is available:"
+        end
+
+        msg = <<-END1
+Hi,
+
+#{header}
+
+    #{version}    #{selectors}
+
+Release note:
+
+--------------------------------------------------------------------------------------
+
+#{release_note}
+
+--------------------------------------------------------------------------------------
+          END1
+
+        if config.release_instructions
+          msg += <<-END2
+
+#{config.release_instructions}
+
+--------------------------------------------------------------------------------------
+            END2
+        end
+
+        msg += <<-END3
+
+You are receiving this because you are a member of the #{config.name} Mailing List,
+or a member of the development team.
+END3
+
+        if external?(type)
+          to = app_users + Origen.app.subscribers_prod + Origen.app.subscribers_dev
+          if config.release_email_subject
+            subject = "[#{Origen.app.namespace}] New Official Release: #{config.release_email_subject}"
+          else
+            subject = "[#{Origen.app.namespace}] New Official Release"
+          end
+        else
+          to = admins + Origen.app.subscribers_dev
+          if config.release_email_subject
+            subject = "[#{Origen.app.namespace}] New Development Tag: #{config.release_email_subject}"
+          else
+            subject = "[#{Origen.app.namespace}] New Development Tag"
+          end
+        end
+
+        begin
+          send_email({ to: to, subject: subject, body: msg }.merge(options))
+        rescue
+          warn "Email could not be sent to #{to}"
+        end
+      end
+
+      # Send a regression complete notice,
+      def send_regression_complete_notice(stats = Origen.app.runner.stats, options = {})
+        stats, options = Origen.app.runner.stats, stats if stats.is_a?(Hash)
+        options = {
+          to: current_user
+        }.merge(options)
+
+        msg = <<-END1
+Hi,
+
+The regression results are:
+
+#{stats.summary_text}
+
+        END1
+
+        subject = "[#{Origen.app.namespace}] Regression - "
+        if stats.clean_run?
+          subject += 'PASSED'
+        else
+          subject += 'FAILED'
+        end
+        send_email({ to: options[:to], subject: subject, body: msg }.merge(options))
+      end
+
+      private
+
+      def config
+        Origen.config
+      end
+
+      def external?(type)
+        [:production, :major, :minor, :bugfix].include?(type)
+      end
+    end
+  end
+end

data/lib/origen/utility/s_record.rb

@@ -0,0 +1,205 @@
+module Origen
+  module Utility
+    # A class to handle the parsing of S-records
+    #
+    # An S-record file consists of a sequence of specially formatted ASCII character strings. An S-record will
+    # be less than or equal to 78 bytes in length.
+    # The order of S-records within a file is of no significance and no particular order may be assumed.
+    #
+    # The general format of an S-record follows:
+    #
+    #   +-------------------//------------------//-----------------------+
+    #   | type | count | address  |            data           | checksum |
+    #   +-------------------//------------------//-----------------------+
+    #
+    # type -- A char[2] field. These characters describe the type of record (S0, S1, S2, S3, S5, S7, S8, or S9).
+    # count -- A char[2] field. These characters when paired and interpreted as a hexadecimal value, display
+    # the count of remaining character pairs in the record.
+    #
+    # address -- A char[4,6, or 8] field. These characters grouped and interpreted as a hexadecimal value,
+    # display the address at which the data field is to be loaded into memory. The length of the field depends
+    # on the number of bytes necessary to hold the address. A 2-byte address uses 4 characters, a 3-byte
+    # address uses 6 characters, and a 4-byte address uses 8 characters.
+    #
+    # data -- A char [0-64] field. These characters when paired and interpreted as hexadecimal values represent
+    # the memory loadable data or descriptive information.
+    #
+    # data -- A char [0-64] field. These characters when paired and interpreted as hexadecimal values represent
+    # checksum -- A char[2] field. These characters when paired and interpreted as a hexadecimal value display
+    # the least significant byte of the ones complement of the sum of the byte values represented by the pairs
+    # of characters making up the count, the address, and the data fields.
+    #
+    # data -- A char [0-64] field. These characters when paired and interpreted as hexadecimal values represent
+    # Each record is terminated with a line feed. If any additional or different record terminator(s) or delay
+    # characters are needed during transmission to the target system it is the responsibility of the
+    # transmitting program to provide them.
+    #
+    # data -- A char [0-64] field. These characters when paired and interpreted as hexadecimal values represent
+    # S0 Record. The type of record is 'S0' (0x5330). The address field is unused and will be filled with zeros
+    # (0x0000). The header information within the data field is divided into the following subfields.
+    #
+    # * mname is char[20] and is the module name.
+    # * ver is char[2] and is the version number.
+    # * rev is char[2] and is the revision number.
+    # * description is char[0-36] and is a text comment.
+    #
+    # Each of the subfields is composed of ASCII bytes whose associated characters, when paired, represent one
+    # byte hexadecimal values in the case of the version and revision numbers, or represent the hexadecimal
+    # values of the ASCII characters comprising the module name and description.
+    #
+    # S1 Record. The type of record field is 'S1' (0x5331). The address field is intrepreted as a 2-byte
+    # address. The data field is composed of memory loadable data.
+    #
+    # S2 Record. The type of record field is 'S2' (0x5332). The address field is intrepreted as a 3-byte
+    # address. The data field is composed of memory loadable data.
+    #
+    # S3 Record. The type of record field is 'S3' (0x5333). The address field is intrepreted as a 4-byte
+    # address. The data field is composed of memory loadable data.
+    #
+    # S5 Record. The type of record field is 'S5' (0x5335). The address field is intrepreted as a 2-byte value
+    # and contains the count of S1, S2, and S3 records previously transmitted. There is no data field.
+    #
+    # S7 Record. The type of record field is 'S7' (0x5337). The address field contains the starting execution
+    # address and is intrepreted as 4-byte address. There is no data field.
+    #
+    # S8 Record. The type of record field is 'S8' (0x5338). The address field contains the starting execution
+    # address and is intrepreted as 3-byte address. There is no data field.
+    #
+    # S9 Record. The type of record field is 'S9' (0x5339). The address field contains the starting execution
+    # address and is intrepreted as 2-byte address. There is no data field.
+    #
+    # EXAMPLE
+    #
+    # Shown below is a typical S-record format file.
+    #
+    #   S00600004844521B
+    #   S1130000285F245F2212226A000424290008237C2A
+    #   S11300100002000800082629001853812341001813
+    #   S113002041E900084E42234300182342000824A952
+    #   S107003000144ED492
+    #   S5030004F8
+    #   S9030000FC
+    #
+    # The file consists of one S0 record, four S1 records, one S5 record and an S9 record.
+    #
+    # The S0 record is comprised as follows:
+    #
+    # * S0 S-record type S0, indicating it is a header record.
+    # * 06 Hexadecimal 06 (decimal 6), indicating that six character pairs (or ASCII bytes) follow.
+    # * 00 00 Four character 2-byte address field, zeroes in this example.
+    # * 48 44 52 ASCII H, D, and R - "HDR".
+    # * 1B The checksum.
+    #
+    # The first S1 record is comprised as follows:
+    #
+    # * S1 S-record type S1, indicating it is a data record to be loaded at a 2-byte address.
+    # * 13 Hexadecimal 13 (decimal 19), indicating that nineteen character pairs, representing a 2 byte address,
+    # * 16 bytes of binary data, and a 1 byte checksum, follow.
+    # * 00 00 Four character 2-byte address field; hexidecimal address 0x0000, where the data which follows is to
+    #   be loaded.
+    # * 28 5F 24 5F 22 12 22 6A 00 04 24 29 00 08 23 7C Sixteen character pairs representing the actual binary
+    #   data.
+    # * 2A The checksum.
+    # * The second and third S1 records each contain 0x13 (19) character pairs and are ended with checksums of 13
+    #   and 52, respectively. The fourth S1 record contains 07 character pairs and has a checksum of 92.
+    #
+    # The S5 record is comprised as follows:
+    #
+    # * S5 S-record type S5, indicating it is a count record indicating the number of S1 records
+    # * 03 Hexadecimal 03 (decimal 3), indicating that three character pairs follow.
+    # * 00 04 Hexadecimal 0004 (decimal 4), indicating that there are four data records previous to this record.
+    # * F8 The checksum.
+    #
+    # The S9 record is comprised as follows:
+    #
+    # * S9 S-record type S9, indicating it is a termination record.
+    # * 03 Hexadecimal 03 (decimal 3), indicating that three character pairs follow.
+    # * 00 00 The address field, hexadecimal 0 (decimal 0) indicating the starting execution address.
+    # * FC The checksum.
+    #
+    # --------------------------------------------------------------------------------
+    #
+    # Instructor Notes
+    #
+    # There isn't any evidence that Motorola ever has made use of the header information within the data field
+    # of the S0 record, as described above. This must have been used by some third party vendors.
+    # This is the only place that a 78-byte limit on total record length or 64-byte limit on data length is
+    # documented. These values shouldn't be trusted for the general case.
+    # The count field can have values in the range of 0x3 (2 bytes of address + 1 byte checksum = 3, a not
+    # very useful record) to 0xff; this is the count of remaining character pairs, including checksum.
+    # If you write code to convert S-Records, you should always assume that a record can be as long as 514
+    # (decimal) characters in length (255 * 2 = 510, plus 4 characters for the type and count fields), plus
+    # any terminating character(s). That is, in establishing an input buffer in C, you would declare it to be
+    # an array of 515 chars, thus leaving room for the terminating null character.
+    class SRecord
+      # Supply a path to the S-record file, this should be a relative path from the top
+      # level of your project workspace (Origen.root)
+      def initialize(file)
+        @file = file
+      end
+
+      # Parses the S-record and returns either an array of address and data values like this:
+      # * \[addr, data, addr, data, addr, data\]
+      # Or if a block is supplied it will pass back a single address and a single data value
+      # in turn.
+      # ==== Options
+      # * :data_width_in_bytes - By default the returned data items will be 1 byte wide, set
+      # this option to have it parsed and passed back in N byte wide packets
+      # ==== Example
+      #   srec = SRecord.new("srecs/test_atd.abs.S19")
+      #   $top.write_addr_data(srec.parse)   # Let write_addr_data handle the processing
+      #   # As above but pass the data to the top block in 16-bit packets
+      #   $top.write_addr_data(srec.parse(:data_width_in_bytes => 2))
+      #
+      #   # Handle the processing from here...
+      #   srec.parse do |addr,data|
+      #       $top.write(addr, data)
+      #   end
+      def parse(options = {})
+        addr_data = extract_addr_data(options)
+        if block_given?
+          addr_data.each_slice(2) do |pair|
+            yield pair[0], pair[1]
+          end
+        else
+          addr_data
+        end
+      end
+
+      private
+
+      # Returns an array containing all address/data from the given s-record
+      # No address manipulation is performed, that is left to the caller to apply
+      # any scrambling as required by the target system
+      def extract_addr_data(options = {}) # :nodoc:
+        options = { data_width_in_bytes: 1
+                  }.merge(options)
+
+        result = []
+        File.readlines(Origen.file_handler.clean_path_to(@file)).each do |line|
+          # Only if the line is an s-record with data...
+          if line =~ /^S([1-3])/
+            type = Regexp.last_match[1].to_i(16)    # S-record type, 1-3
+            # Set the matcher to capture x number of bytes dependent on the s-rec type
+            addr_matcher = '\w\w' * (1 + type)
+            line.strip =~ /^S\d\w\w(#{addr_matcher})(\w*)\w\w$/   # $1 = address, $2 = data
+            addr = Regexp.last_match[1].to_i(16)
+            data = Regexp.last_match[2]
+            data_matcher = '\w\w' * options[:data_width_in_bytes]
+            data.scan(/#{data_matcher}/).each do |data_packet|
+              result << addr
+              result << data_packet.to_i(16)
+              addr += options[:data_width_in_bytes]
+            end
+            # If a partial word is left over
+            if (remainder = data.length % (2 * options[:data_width_in_bytes])) > 0
+              result << addr
+              result << data[data.length - remainder..data.length].to_i(16)
+            end
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/origen/utility/time_and_date.rb

@@ -0,0 +1,30 @@
+module Origen
+  module Utility
+    # Collection of methods related to time and dates
+    module TimeAndDate
+      # Returns the current time in this format:
+      # 05-Jun-2010 10:05AM
+      def time_now(options = {})
+        options = { underscore:   false,
+                    format:       :human,
+                    include_time: true
+        }.merge(options)
+
+        # Nice description of time format options
+        # http://wesgarrison.us/2006/03/12/ruby-strftime-options-for-date-formatting/
+
+        if options[:format] == :human
+          Time.now.strftime('%d-%b-%Y %H:%M%p')
+        elsif options[:format] == :universal
+          time = options[:underscore] ? Time.now.strftime('_%H_%M') : Time.now.strftime('%H%M')
+          date = options[:underscore] ? Time.now.strftime('%Y_%m_%d') : Time.now.strftime('%Y%m%d')
+          options[:include_time] ? date + time : date
+        elsif options[:format] == :timestamp
+          Time.now.strftime('%Y%m%d%H%M%S')
+        else
+          fail 'Unknown date format requested!'
+        end
+      end
+    end
+  end
+end

data/lib/origen/utility.rb

@@ -0,0 +1,12 @@
+module Origen
+  module Utility
+    autoload :DesignSync,  'origen/utility/design_sync'
+    autoload :Diff,        'origen/utility/diff'
+    autoload :Mailer,      'origen/utility/mailer'
+    autoload :SRecord,     'origen/utility/s_record'
+    autoload :CSV,     'origen/utility/csv_data'
+    autoload :TimeAndDate, 'origen/utility/time_and_date'
+    autoload :InputCapture, 'origen/utility/input_capture'
+    autoload :BlockArgs, 'origen/utility/block_args'
+  end
+end