origen_doc_helpers 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ebbd238b54a19683203a725637f6c2734b65c188
-  data.tar.gz: b19db5c9ac282ad9cadccc0084969e58201b2bb5
+  metadata.gz: ddb0151af6cf74f9080784ce49f885fd55952d81
+  data.tar.gz: d18ecaa6b5e985b720082027f1377d442f3f26b0
 SHA512:
-  metadata.gz: a132f22c09f808879511749593ac122e8ca918cd69ee7c1132edcf7713ec3a90cbe6f7b5e5545a0eedaef5774cae518bd63c7bc4727246d477cc22779da721a9
-  data.tar.gz: ef35859c17efbc5c635a61606e11d8f73365e92fa71094691993ce6ed3b12458571928a6c75a43c251a3e66fccd332d2881c638929acddd67e0e883e5c9deac6
+  metadata.gz: 6339ee1a74d32e6073ad1e7a5f4483f9323ee08f6d73a348782902b104471a811ada5a40b0657e585bd671214729ba355410a9d66fa1ff83ce2b5426a6861bb9
+  data.tar.gz: 027348178efe90fac8e8f9ab8a623724c6beb119579f3ee438b71c8fcb9fed80c7f9158ab93e8bed5a62b0008cdc9d67fe816e5b3ed19070b43e1ad4f8283b21

data/config/application.rb

@@ -32,4 +32,13 @@ class OrigenDocHelpersApplication < Origen::Application
     end
   end
 
+  def after_web_site_compile(options)
+    Origen.app.runner.launch action: :program, files: "program"
+    # Then the documentation
+    OrigenDocHelpers.generate_flow_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :flows  do |d|
+      d.page flow: :probe1,
+             name: "Probe 1 Flow",
+             target: "default.rb"
+    end
+  end
 end

data/config/boot.rb

@@ -14,6 +14,5 @@ require "origen_doc_helpers"
 # and is required by some of our tests.
 # Normally such a class should not be exposed to 3rd party users of the plugin,
 # so we required it here rather than in lib/origen_doc_helpers.rb.
-module OrigenDocHelpers
-  autoload :DUT, "origen_doc_helpers/dut"
-end
+require "origen_doc_helpers_dev/dut"
+require "origen_doc_helpers_dev/interface"

data/config/version.rb

@@ -1,7 +1,7 @@
 module OrigenDocHelpers
   MAJOR = 0
-  MINOR = 5
-  BUGFIX = 2
+  MINOR = 6
+  BUGFIX = 0
   DEV = nil
 
   VERSION = [MAJOR, MINOR, BUGFIX].join(".") + (DEV ? ".pre#{DEV}" : '')

data/lib/origen_doc_helpers/model_page_generator.rb

@@ -50,8 +50,10 @@ module OrigenDocHelpers
     attr_reader :model
 
     def initialize(options)
+      options = { search_box: true }.merge(options)
       @options = options
       @model = options[:model]
+      @search_box = options[:search_box]
     end
 
     def run
@@ -72,12 +74,15 @@ module OrigenDocHelpers
                          model:          model,
                          breadcrumbs:    options[:breadcrumbs],
                          path:           options[:path],
-                         origen_path:    options[:origen_path]
+                         origen_path:    options[:origen_path],
+                         search_box:     @search_box
 
       write_out(output_file, t)
-      Origen.log.info "Building JSON page: #{json_file}"
-      File.open(json_file, 'w') do |f|
-        f.puts model.to_json
+      if @search_box
+        Origen.log.info "Building JSON page: #{json_file}"
+        File.open(json_file, 'w') do |f|
+          f.puts model.to_json
+        end
       end
 
       model.sub_blocks.each do |name, block|

data/lib/{origen_doc_helpers → origen_doc_helpers_dev}/dut.rb

@@ -1,4 +1,4 @@
-module OrigenDocHelpers
+module OrigenDocHelpersDev
   class DUT
     include Origen::TopLevel
 

data/lib/origen_doc_helpers_dev/interface.rb

@@ -0,0 +1,69 @@
+module LinkDemo
+  module TestProgram
+    class Interface
+      include OrigenTesters::ProgramGenerators
+
+      def instance_name(name, options = {})
+        name = pattern_name(name)
+        if options[:vdd] || options[:vdd] != :nom
+          name += "_#{options[:vdd]}"
+        end
+        name
+      end
+
+      def pattern_name(name, options = {})
+        options[:pattern] || name.to_s
+      end
+
+      def vdd_loop(options)
+        [options[:vdd]].flatten.each do |vdd|
+          yield options.merge(vdd: vdd)
+        end
+      end
+
+      def func(name, options = {})
+        options = {
+          vdd:  [:min, :max],
+          type: :functional
+        }.merge(options)
+        vdd_loop(options) do |options|
+          test = test_instances.functional(instance_name(name, options), options)
+          test.pattern = pattern_name(name, options)
+          apply_levels(test, options)
+          add_flow_entry(test, options)
+        end
+      end
+
+      def para(name, options = {})
+        options = {
+          vdd:  [:min, :max],
+          type: :parametric
+        }.merge(options)
+        unless options[:cz]
+          vdd_loop(options) do |options|
+            test = test_instances.ppmu(instance_name(name, options), options)
+            test.pattern = pattern_name(name, options)
+            test.lo_limit = options[:lo]
+            test.hi_limit = options[:hi]
+            test.force_cond = options[:force] || 0
+            apply_levels(test, options)
+            add_flow_entry(test, options)
+          end
+        end
+      end
+
+      def apply_levels(test, options)
+        test.dc_category = 'spec'
+        test.dc_selector = options[:vdd] || :nom
+      end
+
+      def add_flow_entry(test, options)
+        options = {
+          number:   options[:bin] * 1000,
+          soft_bin: options[:bin]
+        }.merge(options)
+        flow.test test, options
+      end
+    end
+  end
+end

data/program/_func.rb

@@ -0,0 +1,12 @@
+# Functional test of the Vreg
+Flow.create do
+  # This test verifies that the following things work:
+  #
+  # * The vreg can be disabled
+  # * The trim register can be written to and read from
+  func :vreg_functional, vdd: :min, bin: 101
+
+  func :vreg_functional, vdd: :max, bin: 101, continue: true
+
+  import "hvst"
+end

data/program/_hvst.rb

@@ -0,0 +1,12 @@
+# HVST
+Flow.create do
+  # Check if this device has already had the Vreg HVST
+  func :rd_vreg_hvst_passcode, bin: 50, vdd: :nom, id: :vreg_hvst_done
+
+  # Apply HVST to the vreg module
+  func :vreg_hvst, bin: 101, hv: 10.V, vdd: :max, unless_passed: :vreg_hvst_done
+
+  # Program a passcode to the device to record that the HVST
+  # has been applied
+  func :pgm_vreg_hvst_passcode, bin: 51, vdd: :nom, unless_passed: :vreg_hvst_done
+end

data/program/_para.rb

@@ -0,0 +1,26 @@
+# Parametric flow
+#
+# Blah blah, this is marked down:
+#
+# * blah
+# * blah
+Flow.create do
+  # Measure the output of the vreg under no load, this is a simple
+  # test to catch any gross defects that prevent the vreg from working
+  #
+  # Blah blah, this is marked down:
+  #
+  # * blah
+  # * blah
+  pp "No load tests" do
+    para :vreg_meas, bin: 105, lo: 1.12, hi: 1.34
+
+    para :vreg_meas, bin: 105, cz: true, if_enable: "vreg_cz"
+  end
+
+  # Measure the output of the vreg under the given load, this is approximately
+  # equivalent to 1.5x the maximum load anticipated in a customer application.
+  para :vreg_meas_loaded, vdd: :min, bin: 105, force: 5.mA, lo: 1.10, hi: 1.34, pattern: "vreg_meas"
+
+  para :vreg_meas_loaded, vdd: :max, bin: 105, force: 5.mA, lo: 1.12, hi: 1.34, pattern: "vreg_meas"
+end

data/program/probe1.rb

@@ -0,0 +1,9 @@
+Flow.create interface: "LinkDemo::TestProgram::Interface" do
+  log "Vreg test module"
+
+  import "func"
+
+  import "para"
+
+  pass 1, sofbin: 55
+end

data/templates/model_page.md.erb

@@ -23,6 +23,7 @@
     <img src="http://origen-sdk.org/img/origen-device.png" style="float: left; height:50px; width: 50px; margin-top: 14px;">
     <h1 style="float: left; margin-left: 10px;"><%= opts[:heading] %></h1>
   </div>
+% if opts[:search_box]
   <div id="search" class="col-md-3" style="margin-top: 20px;">
     <form style="margin-bottom: 15px;">
       <div class="input-group">
@@ -33,6 +34,7 @@
       </div>
     </form>
   </div>
+% end
 </div>
 
 <div class="row">
@@ -101,7 +103,9 @@
 <hr>
 <div class="row">
   <div class="col-md-12">
+%   if opts[:search_box]
     <article>
+%   end
     <h3>Registers of <%= model.model.class%> <%= model.name ? "(#{model.name})" : model.try(:includes_origen_top_level?) ? "(dut)" : "" %></h3>
 
 %     model.regs.sort_by { |name, reg| reg.offset }.each do |name, reg|
@@ -114,7 +118,9 @@
 
 %     end
 
+%   if opts[:search_box]
     </article>
+%   end
   </div>
 </div>
 

data/templates/model_page.md.erb~

@@ -0,0 +1,129 @@
+% opts = options
+% model = options[:model]
+% render options[:layout], options[:layout_options] do
+
+<script type="text/javascript">
+  // Modified from: http://jsfiddle.net/jhfrench/mc4Qd/
+  window.onload = function() {
+    // Links to the top of the page
+    $('.top-link').click(function() {
+      jQuery('html,body').animate({scrollTop: 0}, 500);
+      return false;
+    });
+  };
+</script>
+
+<style>
+  tr.clickable td { padding: 0px !important; }
+  tr.clickable a { display: block; height: 100%; width: 100%; padding: 8px; text-decoration: none; }
+</style>
+
+<div class="row" style="margin-top: 10px; margin-bottom: 15px;">
+  <div class="col-md-9">
+    <img src="http://origen-sdk.org/img/origen-device.png" style="float: left; height:50px; width: 50px; margin-top: 14px;">
+    <h1 style="float: left; margin-left: 10px;"><%= opts[:heading] %></h1>
+  </div>
+% if opts[:search_box]
+  <div id="search" class="col-md-3" style="margin-top: 20px;">
+    <form style="margin-bottom: 15px;">
+      <div class="input-group">
+        <input class="form-control" type="search" placeholder="Search within this model..."/>
+        <span class="input-group-btn">
+          <button type="submit" class="btn btn-search">GO!</button>
+        </span>
+      </div>
+    </form>
+  </div>
+% end
+</div>
+
+<div class="row">
+  <div class="col-md-12">
+    <ol class="breadcrumb">
+%   size = opts[:breadcrumbs].size      
+%   opts[:breadcrumbs].each_with_index do |crumb, i|
+%     if i == size - 1
+      <li class="active"><%= crumb[0] %></li>
+%     else
+      <li><a href="<%= path crumb[1] %>"><%= crumb[0] %></a></li>
+%     end
+%   end      
+    </ol>
+  </div>
+</div>
+
+<div class="row">
+  <div class="col-md-12 search-results">
+  </div>
+</div>
+
+<div class="row">
+  <div class="col-md-6">
+    <h3>Blocks</h3>
+
+    <table class="table table-hover">
+      <thead><tr>
+        <th>Address</th>
+        <th>Name</th>
+      </tr></thead>
+      <tbody>
+%   model.sub_blocks.sort_by { |name, block| block.base_address }.each do |name, block|
+        <tr class="clickable"> 
+          <td><a href="<%= path "#{opts[:path]}/#{name}" %>"><%= block.base_address.to_hex %></a></td>
+          <td><a href="<%= path "#{opts[:path]}/#{name}" %>"><%= name %></a></td>
+        </tr> 
+%   end
+      </tbody>
+    </table>
+  </div>
+
+  <div class="col-md-6">
+    <h3>Registers</h3>
+
+    <table class="table table-hover">
+      <thead><tr>
+        <th>Address</th>
+        <th>Name</th>
+      </tr></thead>
+      <tbody>
+%   model.regs.sort_by { |name, reg| reg.offset }.each do |name, reg|
+        <tr class="clickable"> 
+          <td><a href="#<%= reg.name %>"><%= reg.address.to_hex %></a></td>
+          <td><a href="#<%= reg.name %>"><%= name %></a></td>
+        </tr> 
+%   end
+      </tbody>
+    </table>
+  </div>
+</div>
+
+
+%   if model.owns_registers?
+
+<hr>
+<div class="row">
+  <div class="col-md-12">
+%   if opts[:search_box]
+    <article>
+%   end
+    <h3>Registers of <%= model.model.class%> <%= model.name ? "(#{model.name})" : model.try(:includes_origen_top_level?) ? "(dut)" : "" %></h3>
+
+%     model.regs.sort_by { |name, reg| reg.offset }.each do |name, reg|
+
+    <div>
+      <span class="pull-right"><a class="top-link" href="#">back to top</a></span>
+    </div>
+
+<%= render "doc_helpers/register.html", reg: reg, preserve_target: true, descriptions: true, origen_path: opts[:origen_path] %>
+
+%     end
+
+    </article>
+  </div>
+</div>
+
+%   end
+
+% end
+<script>window.origen_search_id = "<%= opts[:search_id] %>";</script>
+<script src="<%= path "search.js" %>"></script>

data/templates/web/helpers/flow.md.erb

@@ -4,9 +4,9 @@
 
 This helper will build a web page to document a test program flow the has been created with Origen.
 
-[Here is an example](http://origen-sdk.org/link_demo/flows/probe_1_flow/).
+[Here is an example](<%= path "flows/probe_1_flow" %>).
 
-Multiple flows can be supplied and an [index page like this](http://origen-sdk.org/link_demo/flows)
+Multiple flows can be supplied and an [index page like this](<%= path "flows" %>)
 is generated to help locate the documentation for a given flow.
 
 ## How To Use

data/templates/web/helpers/model.md.erb

@@ -27,6 +27,19 @@ def after_web_site_compile(options)
 end
 ~~~
 
+For very large models the model search feature may cause the model pages to load slowly. In this
+case it may be desirable to disable the model search feature. You can do this by adding an optional
+argument to the your application's callback handler like this:
+
+~~~ruby
+def after_web_site_compile(options)
+  # Build the model documentation
+  OrigenDocHelpers.generate_model_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :model do |d|
+    d.page model: $dut, search_box: false
+  end
+end
+~~~
+
 To generate documentation for more than one model, call the page method multiple times like this:
 
 ~~~ruby

data/templates/web/helpers/model.md.erb~

@@ -0,0 +1,81 @@
+% render "../layouts/helpers.html" do
+
+# Model Documentation
+
+This helper will build a collection of web pages that document a model's attributes,
+currently this includes its sub-blocks and registers.
+
+[Here is an example](http://origen-sdk.org/link_demo/models/linkdemo_toplevel/).
+
+Multiple models can be supplied and an [index page like this](http://origen-sdk.org/link_demo/models)
+is generated to help locate the documentation for a given model.
+
+The collection of pages associated with a particular model is also fully searchable via
+the provided search box.
+
+## How To Use
+
+Call the helper from an <code>after_web_site_compile</code> callback handler in your
+application's <code>config/application.rb</code> like this:
+
+~~~ruby
+def after_web_site_compile(options)
+  # Build the model documentation
+  OrigenDocHelpers.generate_model_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :model do |d|
+    d.page model: $dut
+  end
+end
+~~~
+
+To generate documentation for more than one model, call the page method multiple times like this:
+
+~~~ruby
+def after_web_site_compile(options)
+  # Build the model documentation
+  OrigenDocHelpers.generate_model_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :model do |d|
+    d.page model: MyApp::ModelA.new
+    d.page model: MyApp::ModelB.new
+    d.page model: MyApp::ModelC.new
+  end
+end
+~~~
+
+If the different models are all top-level instances (i.e. they include <code>Origen::TopLevel</code> and are
+what is commonly referred to as <code>$dut</code>), then a target loop should be used like this:
+
+~~~ruby
+def after_web_site_compile(options)
+  # Build the model documentation
+  OrigenDocHelpers.generate_model_docs layout: "#{Origen.root}/templates/web/layouts/_basic.html.erb", tab: :model do |d|
+    Origen.target.loop targets: ["target_a", "target_b", "target_c"] do
+      d.page model: $dut
+    end
+  end
+end
+~~~
+
+## Options
+
+<code>OrigenDocHelpers.generate_model_docs</code>
+
+* <code>:layout</code> - **Required**, supply a full path to your application's layout file
+* Any other options will be passed to your layout file unmodified, e.g. to set the tab in the generated
+  pages in the above example
+
+<code>page</code>  
+
+* <code>:model</code> - **Required**, supply an instance of the model
+* <code>:group</code> - Optional, a heading to group similar models under on the index page, e.g. "Production", "In Development"
+
+## Website Integration
+
+The model index page will be generated at path <code>/models</code> within your application, and it is common
+to create a "Model(s)" tab in your website's navigation bar to link to this.
+
+If your application only has one model, then the navbar link should be setup to point directly to
+that model's page.
+
+The location of the pages for the individual models are based on the model name and will be unique to each application,
+you can find them initially via the index page.
+
+% end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: origen_doc_helpers
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Stephen McGinty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-15 00:00:00.000000000 Z
+date: 2018-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: origen
@@ -51,17 +51,23 @@ files:
 - config/users.rb
 - config/version.rb
 - lib/origen_doc_helpers.rb
-- lib/origen_doc_helpers/dut.rb
 - lib/origen_doc_helpers/flow_page_generator.rb
 - lib/origen_doc_helpers/helpers.rb
 - lib/origen_doc_helpers/html_flow_formatter.rb
 - lib/origen_doc_helpers/list_flow_formatter.rb
 - lib/origen_doc_helpers/model_page_generator.rb
 - lib/origen_doc_helpers/pdf.rb
+- lib/origen_doc_helpers_dev/dut.rb
+- lib/origen_doc_helpers_dev/interface.rb
+- program/_func.rb
+- program/_hvst.rb
+- program/_para.rb
+- program/probe1.rb
 - templates/flow_index.md.erb
 - templates/flow_page.md.erb
 - templates/model_index.md.erb
 - templates/model_page.md.erb
+- templates/model_page.md.erb~
 - templates/pdf/topic_wrapper.html
 - templates/shared/_register.html.erb
 - templates/shared/_searchable.html.erb
@@ -71,6 +77,7 @@ files:
 - templates/web/helpers/disqus.md.erb
 - templates/web/helpers/flow.md.erb
 - templates/web/helpers/model.md.erb
+- templates/web/helpers/model.md.erb~
 - templates/web/helpers/register.md.erb
 - templates/web/helpers/searchable/intro.md.erb
 - templates/web/helpers/searchable/page2.md.erb