soc_maker 0.1.1

data/README.rdoc

@@ -0,0 +1,228 @@
+= System-on-Chip Maker (soc_maker) 
+===========
+
+The System-on-Chip (SoC) Maker is a tool to design and create SoCs
+in a simple way, written in Ruby.
+
+    PLEASE NOTE: THIS SOFTWARE IS IN DEVELOPMENT AND HIGHLY EXPERIMENTAL!!
+
+
+
+== Current Features
+
+* All configuration files are YAML based 
+  (see http://en.wikipedia.org/wiki/YAML)
+* Hierarchical systems can be designed
+* Usage of an IP core library
+* A CLI for an easy interaction 
+  (not completed, needs to be re-designed or removed, interaction is not that easy)
+* Ruby interface to interact with the soc_maker on a lower level
+* VHDL output
+* parameterization of cores
+  * instance parameterization (vhdl-generics/verilog-parameters)
+  * global/static parameterization (vhdl-packages/verilog-includes)
+
+
+== Install
+* from git:
+
+      git clone https://github.com/feddischson/soc_maker.git
+      cd soc_maker
+      git checkout tags/v0.1.0         # please adapt version if necessary
+                                       # see https://github.com/feddischson/soc_maker/releases
+      gem build soc_maker.gemspec
+      gem install soc_maker-0.1.0.gem  # requires ruby >= 2.0
+
+
+== TODOs
+* User-Guide
+  - YAML API documentation
+* API version check
+
+== Planed Features
+* Graphical User Interface (GUI) 
+* Import wizzard: should scan IP core sources and suggest configuration
+* Verilog output
+* Plugin-interface
+* Synthesis and Simulation support plugins
+* More cores
+
+== Status
+A first "Hellow World" SOC has been created, simulated, synthesized and tested 
+on a Spartan-3AN starter kit board. 
+The system consists of an OpenRISC CPU, some on-chip memory and a UART core
+(see ./examples/or1200_test).
+
+Furthermore, some dummy cores have been assembled to a hierarchical system, 
+where a SOC contains a few cores and a sub-SOC.
+
+The following cores are integrated into the SOC-Maker core library and can be used:
+* the Advanced Debug System (http://opencores.org/project,adv_debug_sys)
+* the OR1200 OpenRISC processor (http://opencores.org/or1k/Main_Page)
+* the ram_wb from the openrisc project (http://opencores.org/ocsvn/openrisc/openrisc/trunk/orpsocv2/rtl/verilog/ram_wb)
+* the UART16550 module (http://opencores.org/project,uart16550)
+* a wishbone bus connection from the min-soc project (http://www.minsoc.com/)
+
+
+
+== Motivation
+The motivation of this project is the need of an open-source application
+to create system-on-chips easily and fast on a higher level than vhdl or verilog.
+By creating a generic application, it can support a wide range of 
+processors, cores, controllers and bus-topologies. 
+By using the SoC-Maker, it should be easy for a system-designer to assemble 
+multiple IP-cores together with a low effort and without low-level knowledges.
+Furthermore, pre-defined SoCs can be published and extended. This makes it 
+interesting for IP-core developers. An existing SoC created with the
+Soc-Maker can be easily extended by a custom IP core which is then tested 
+and used.
+Not only memory-mapped systems are a target application, also signal-processing
+systems are interesting, where signal-processing blocks are concatenated.
+
+One useful example is an Open-RISC based SoC, where it would be nice, if
+core and system-developers can easily create a SoC with an
+Open-RISC CPU. The need of a detailed knowledge of the Open-RISC, the Wishbone 
+bus and so on is not needed anymore.
+
+A second example is a any kind of wireless receiver, where signals are filtered, mixed,
+decimated and further processed. All the signal processing can be put 
+together into a subsystem with 
+parameters (mixer-resolution, decimation-rate and son on). On a higher level, this
+sub-system can then be used in a typical memory-mapped SoC together with other 
+IP-cores and sub-systems.
+
+
+
+
+
+== The Goal
+
+<b>The goal in one sentence</b>: the SoC-Maker should make it possible to parameterize and assemble 
+one or multiple IP-cores into one IP-core on a high level.
+
+
+*IP-core*
+IP stands for Intellectual Property and the definition can be found on wikipedia: 
+http://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core
+
+
+*Parameterization*
+Parameterization of IP-cores says, that the user can configure and setup all
+required parameters of an IP-core.
+
+
+*Assembly*
+Assembly in this context means, that the IP-cores are connected in a pre-defined
+or user-defined way, that the final IP-core works as required by the 
+user.
+
+
+<b>One or Multiple IP cores</b>
+The minimum number of IP-cores, which are used in such a system is one. Of course,
+the common case is that more than one IP-core is used to create one final
+IP-core.
+
+
+<b>Into one IP core</b>
+The assembly into one IP-core can be seen in different ways: on the one hand, 
+this final IP-core can be seen as a System-on-Chip. On the other-hand, it can 
+be defined as a subsystem with additional parameters. This parameters are then
+passed to the single IP-cores. The subsystem, which is one big IP-core, can then
+be used in other systems or sub-systems.
+
+
+<b>The High Level</b>
+The high level says, that the user must not work on code or RTL level.
+Furthermore, the high-level can can be different: one way could be
+a graphical user interface. A second way might be an easy to read ASCII file 
+written for example in XML, YAML or JSON.
+
+
+
+
+
+== Requirements
+
+- The user is able to organize IP cores and interfaces in a library, which includes 
+  * adding existing IP cores / interfaces
+  * removing IP cores / interfaces
+  * displaying IP cores (which are in the library)
+  * adding IP cores to the target-SOC
+
+- There should be a library functionallity: the library should hold
+  * core definitions
+  * interface definitions
+
+
+- There should exist a core definition for each core. The definition should define the following data
+  * all source files, which are required for synthesis only
+  * all source files, which are required for simulation only
+  * all source files, for synthesis and simulation
+  * top-level source file
+  * top-level port and parameters
+  * parameter configuration and validation
+  * an option to download/check out files from a repository (svn, git ...)
+
+
+- There should exist an interface specification for each interface used in the library
+  * The interface specification defines, how the IP cores are connected
+  * Allow versioning
+  * Allow a wide range of topologies
+
+- There should be a SOC definition
+  The SOC definition defines, which IP cores are used
+  by the target-SOC, how they are connected and how the IP cores
+  are parameterized.
+
+- IP-core configuration
+  It must be possible to configure an IP core. The configurable parameters
+  are defined in the IP-core definition and set in the SOC definition.
+  The parameters are then used to instantiate the IP-core during the HDL generation
+
+- Toplevel-Generation
+  The SoC maker should auto-generate a toplevel in VHDL or Verilog.
+  Both HDL languages should be supported for generation.
+
+- Configuration Files
+  All configuration should be stored in YAML files, this includes
+  * SOC definition
+  * Core definition
+  * Interface specification
+  * SoC maker configuration
+
+- User-Interaction
+  It should be possible to use the SOC-Maker on three levels:
+  * Script-level: this is the lowest level and uses the ruby API directly
+  * CLI-level: a commandline-interface can be used to interact with the API
+  * GUI-Level: this is the highest level: a graphical user interface should
+  make it possible to have a simple interaction with the API 
+
+
+
+
+
+== Author
+
+<b>Christian Haettich</b>,
+<tt>feddischson [ at ] opencores.org</tt>
+
+
+== License
+
+
+Copyright (C) 2014  Christian Haettich  - feddischson [ at ] opencores.org
+
+This program 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.
+
+This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
+
+

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rspec/core/rake_task'
+require 'rake/task'
+require_relative 'lib/soc_maker'
+begin
+  require 'bones'
+rescue LoadError
+  abort '### Please install the "bones" gem ###'
+end
+
+
+task :default => :spec
+task 'gem:release' => 'test:all'
+
+task :build do
+  system "gem build soc_maker.gemspec"
+end
+
+task :release => :build do
+  system "gem push soc_maker-#{SOCMaker::VERSION}.gem"
+end
+
+
+Bones {
+  name     'soc_maker'
+  authors  'Christian Haettich'
+  email    'feddischson [ at ] opencores.org'
+  url      'https://github.com/feddischson/soc_maker'
+}
+
+RSpec::Core::RakeTask.new(:spec) do |c|
+   c.ruby_opts="-w"
+end
+
+
+desc 'generate API documentation to doc/rdocs/index.html'
+
+Rake::RDocTask.new do |rd|
+  rd.rdoc_dir = 'doc/rdocs'
+  rd.main = 'README.rdoc'
+  rd.rdoc_files.include 'README.rdoc', 'LICENSE', "bin", "lib"
+  rd.title = "System-on-Chip Maker (soc_maker) Version #{SOCMaker::VERSION} API Documentation"
+  rd.options << '--line-numbers'
+  rd.options << '--all'
+end
+
+

data/bin/soc_maker_cli

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+
+root = File.expand_path('../..', __FILE__)
+require File.join(root, %w[lib soc_maker])
+require 'ostruct'
+
+
+cmd_options = OpenStruct.new
+cmd_options.lib_inc = []
+cmd_options.log_out = "socmaker_log.txt"
+
+##
+# create option-parser and manage
+# options
+#
+OptionParser.new do |opts|
+
+  opts.banner = "Usage: soc_maker_cli [ options ]"
+
+  opts.on("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+
+  opts.on( "-l", "--library <p1,p2,p3...>", Array, 
+        "Sets library include paths (overrides config value)" ) do |path|
+    cmd_options.lib_inc << path
+  end
+
+  opts.on( "-o", "--log-out <file>", String, "Sets the log output file" ) do |file|
+    cmd_options.log_out = file 
+  end
+
+
+  opts.on( "-q", "--quiet", "Run quiet" ) do |q|
+    cmd_options.quiet = q
+  end
+
+
+  begin
+    opts.parse!( ARGV )
+  rescue OptionParser::ParseError => e
+    STDERR.puts e.message, "\n", opts
+    exit(-1)
+  end
+end
+
+
+# manage stdout value
+cmd_options.log_out = STDOUT if cmd_options.log_out.upcase == "STDOUT"
+
+
+# setup options for loading the SOCMaker core
+options = {}
+options[ :libpath     ] = cmd_options.lib_inc.flatten if cmd_options.lib_inc.size > 0
+options[ :logger_out  ] = cmd_options.log_out
+
+##
+# initialize SOCMaker core
+#   this sets up logging and parses all yaml files
+#   found in the configure path (see also soc_maker_conf.rb)
+SOCMaker::load( options )
+
+# Print license info
+
+if not cmd_options.quiet
+  puts SOCMaker::conf[ :LIC ] + "\n\n"
+end
+
+
+cli = SOCMaker::Cli::instance
+if ARGF.filename != '-'
+  ARGF.each do |line|
+    cli.process_cmd line 
+  end
+end
+cli.run
+
+# vim: noai:ts=2:sw=2
+

data/bin/soc_maker_parser

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+
+root = File.expand_path('../..', __FILE__)
+require File.join(root, %w[lib soc_maker])
+require 'ostruct'
+
+cmd_options = OpenStruct.new
+cmd_options.toplevel = ""
+cmd_options.log_out = "socmaker_log.txt"
+cmd_options.files = []
+cmd_options.out  = ""
+##
+# create option-parser and manage
+# options
+#
+OptionParser.new do |opts|
+
+  opts.banner = "Usage: soc_maker_parser [ options ]"
+
+  opts.on("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+
+  opts.on( "-t", "--toplevel <toplevel-file>", String, 
+        "The toplevel HDL file" ) do |path|
+    cmd_options.toplevel << path
+  end
+
+  opts.on( "-o", "--log-out <file>", String, "Sets the log output file" ) do |file|
+    cmd_options.log_out = file 
+  end
+
+
+  opts.on( "-f", "--files <files1, files2, >", Array, 
+          "Paths to identify the HDL files, for example \"./core_x/hdl/*.v\"" ) do |files|
+    cmd_options.files = files 
+  end
+
+
+  opts.on( "-q", "--quiet", "Run quiet" ) do |q|
+    cmd_options.quiet = q
+  end
+
+
+  opts.on( "-c", "--core-out <file>", String, "Sets the core output file" ) do |file|
+    cmd_options.out = file 
+  end
+
+
+
+  begin
+    opts.parse!( ARGV )
+    raise OptionParser::MissingArgument if cmd_options[ :toplevel ].size == 0
+    raise OptionParser::MissingArgument if cmd_options[ :files].size == 0
+  rescue OptionParser::ParseError => e
+    STDERR.puts e.message, "\n", opts
+    exit(-1)
+  end
+
+  options = {}
+  options[ :logger_out   ] = cmd_options.log_out
+  options[ :skip_refresh ] = true
+
+  ##
+  # initialize SOCMaker core
+  #   this sets up logging and parses all yaml files
+  #   found in the configure path (see also soc_maker_conf.rb)
+  SOCMaker::load( options )
+
+  # Print license info
+  if not cmd_options.quiet
+    puts SOCMaker::conf[ :LIC ] + "\n\n"
+  end
+
+
+
+  result = SOCMaker::HDLParser.instance.parse_core( cmd_options[ :toplevel ], cmd_options[ :files ] )
+  if cmd_options[ :out ] and cmd_options[ :out ].size > 0
+    File.open( cmd_options[ :out ], "w") { |file| file.write( result ) }
+  else
+    puts result
+  end
+end
+

data/core_lib/cores/adv_debug_sys/01_adv_debug_sys.yaml

@@ -0,0 +1,245 @@
+SOCM_CORE
+name: Advanced Debug System
+description: Advanced Debug System
+id: adv_debug_sys,ads_3
+license: LGPL
+licensefile: 
+author: 
+authormail: 
+vccmd: svn co http://opencores.org/ocsvn/adv_debug_sys/adv_debug_sys/tags/ADS_RELEASE_3_0_0/Hardware/adv_dbg_if/rtl rtl
+toplevel: adbg_top
+
+interfaces:
+
+
+
+  :jtag: SOCM_IFC
+    name: jtag_tap
+    dir: 1
+    id: jtag_tap,1
+    ports:
+      :tck_i: SOCM_PORT
+        len: 1
+        spc_ref: tck
+      :tdi_i: SOCM_PORT
+        len: 1
+        spc_ref: tdi
+      :tdo_o: SOCM_PORT
+        len: 1
+        spc_ref: tdo
+      :rst_i: SOCM_PORT
+        len: 1
+        spc_ref: rst
+
+      :shift_dr_i: SOCM_PORT
+        len: 1
+        spc_ref: shift
+      :pause_dr_i: SOCM_PORT
+        len: 1
+        spc_ref: pause
+      :update_dr_i: SOCM_PORT
+        len: 1
+        spc_ref: update
+      :capture_dr_i: SOCM_PORT
+        len: 1
+        spc_ref: capture
+      :debug_select_i: SOCM_PORT
+        len: 1
+        spc_ref: select
+
+
+
+
+  :wb_ifc: SOCM_IFC
+    name: wishbone_ma
+    dir: 1
+    id: wishbone_ma,b3
+    ports:
+      :wb_clk_i: SOCM_PORT
+        len: 1
+        spc_ref: clk
+      :wb_rst_i: SOCM_PORT
+        len: 1
+        spc_ref: rst
+      :wb_adr_o: SOCM_PORT
+        spc_ref: adr
+        len:  32
+      :wb_dat_o: SOCM_PORT
+        spc_ref: dat_i
+        len:  32
+      :wb_dat_i: SOCM_PORT
+        spc_ref: dat_o
+        len:  32
+      :wb_cyc_o: SOCM_PORT
+        spc_ref: cyc
+        len:  1
+      :wb_stb_o: SOCM_PORT
+        spc_ref: stb
+        len:  1
+      :wb_sel_o: SOCM_PORT
+        spc_ref: sel
+        len:  4
+      :wb_we_o: SOCM_PORT
+        spc_ref: we
+        len:  1
+      :wb_ack_i: SOCM_PORT
+        spc_ref: ack
+        len:  1
+      :wb_cab_o: SOCM_PORT
+        spc_ref: cab
+        len:  1
+      :wb_err_i: SOCM_PORT
+        spc_ref: err
+        len:  1
+      :wb_cti_o: SOCM_PORT
+        spc_ref: cti
+        len:  3
+      :wb_bte_o: SOCM_PORT
+        spc_ref: bte
+        len:  2
+
+  :cpu0_dbg_clk: SOCM_IFC
+    name: clk
+    dir: 1
+    id: clk,1
+    ports:
+      :cpu0_clk_i: SOCM_PORT
+        len: 1
+        spc_ref: clk
+
+  :cpu0_dbg_rst: SOCM_IFC
+    name: rst
+    dir: 0
+    id: rst,1
+    ports:
+      :cpu0_rst_o: SOCM_PORT
+        len: 1
+        spc_ref: rst
+
+  :cpu0_dbg: SOCM_IFC
+    name: debug
+    dir: 0
+    id: debug,1
+    ports:
+      :cpu0_addr_o: SOCM_PORT
+        len: 32
+        spc_ref: dbg_adr   
+      :cpu0_data_o: SOCM_PORT
+        len: 32
+        spc_ref: dbg_dat_o
+      :cpu0_data_i: SOCM_PORT
+        len: 32
+        spc_ref: dbg_dat_i
+      :cpu0_bp_i: SOCM_PORT
+        len: 1
+        spc_ref: dbg_bpo   
+      :cpu0_stall_o: SOCM_PORT
+        spc_ref: dbg_stall 
+        len: 1
+      :cpu0_stb_o: SOCM_PORT
+        len: 1
+        spc_ref: dbg_stb   
+      :cpu0_we_o: SOCM_PORT
+        len: 1
+        spc_ref: dbg_we    
+      :cpu0_ack_i: SOCM_PORT
+        len: 1
+        spc_ref: dbg_ack   
+
+#     :dbg_ewt_i: SOCM_PORT
+#       len: 1
+#       spc_ref: dbg_ewt   
+#     :dbg_lss_o: SOCM_PORT
+#       len: 4
+#       spc_ref: dbg_lss   
+#     :dbg_is_o: SOCM_PORT
+#       len: 2
+#       spc_ref: dbg_iso   
+#     :dbg_wp_o: SOCM_PORT
+#       len: 11
+#       spc_ref: dbg_wpo    
+
+
+hdlfiles:
+  :adbg_top: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_top.v            
+
+  :adbg_crc32: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_crc32.v
+  :adbg_defines: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_defines.v
+  :adbg_jsp_biu: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_jsp_biu.v
+  :adbg_jsp_module: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_jsp_module.v
+  :adbg_or1k_biu: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_or1k_biu.v
+  :adbg_or1k_defines: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_or1k_defines.v
+  :adbg_or1k_module: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_or1k_module.v
+  :adbg_or1k_status_reg: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_or1k_status_reg.v
+  :adbg_top: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_top.v
+  :adbg_wb_biu: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_wb_biu.v
+  :adbg_wb_defines: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_wb_defines.v
+  :adbg_wb_module: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/adbg_wb_module.v
+  :bytefifo: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/bytefifo.v
+  :syncflow: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/syncflop.v
+  :syncreg: SOCM_HDL_FILE
+    use_syn: true
+    use_sim: true
+    type: verilog
+    path: rtl/verilog/syncreg.v
+