origen_doc_helpers 0.1.0

data/templates/shared/_searchable.html.erb

@@ -0,0 +1,86 @@
+% options[:root] ||= "docs"
+% pdf_filename = ::OrigenDocHelpers::PDF.register(options)
+
+<div class="row">
+  <div class="col-md-3 sidebar-nav-container">
+    <div class="well sidebar-nav" style="margin-top: 20px;">
+        <div id="search">
+          <form style="margin-bottom: 15px;">
+            <div class="input-group">
+              <input class="form-control" type="search" placeholder="Search these docs..."/>
+              <span class="input-group-btn">
+                <button type="submit" class="btn btn-search">GO!</button>
+              </span>
+            </div>
+          </form>
+        </div>
+        <div class="panel-group" id="sidebar-accordion">
+
+% options[:index].each_with_index do |(subject, sections), i|          
+%   if subject
+          <div class="panel panel-default">
+            <div class="panel-heading clickable" data-toggle="collapse" data-parent="#sidebar-accordion" href="#sidebar-collapse-<%= i %>">
+              <a class="no-underline">
+                <%= subject %>
+              </a>
+            </div>
+            <div id="sidebar-collapse-<%= i %>" class="panel-collapse collapse <%= sections.has_key?(_resolve_tab(options)) ? 'in' : '' %>">
+              <div class="panel-body">
+                <ul class="nav nav-list">
+%     sections.each do |tab, section|
+% paths = tab.to_s.split("_")
+<li class="<%= tab == _resolve_tab(options) ? 'active' : '' %>"><a href="<%= path "/#{_root_path(options)}/#{paths[0]}/#{paths[1]}" %>"><%= section %></a></li>
+%     end          
+                </ul>
+              </div>
+            </div>
+          </div>
+%   else          
+          <ul class="nav nav-list">
+%     sections.each do |tab, section|
+% paths = tab.to_s.split("_")
+<li class="<%= tab == _resolve_tab(options) ? 'active' : '' %>"><a href="<%= path "/#{_root_path(options)}/#{paths[0]}/#{paths[1]}" %>"><%= section %></a></li>
+%     end          
+           </ul>
+%   end          
+% end          
+      
+% if pdf_filename
+          <div style="text-align: right; margin-top: 20px;">
+            <a href="<%= path "doc_helpers/pdfs/#{pdf_filename}" %>"><i class="fa fa-file-pdf-o"></i> Download PDF</a>
+          </div>
+% end
+
+        </div>
+
+    </div>
+  </div>
+
+%# The markdown attribute is important if you are going to include content written
+%# in markdown, without this is will be included verbatim
+  <div class="col-md-9 nav-page-container" markdown="1">
+  <article markdown="1">  
+
+% found = options[:index].find{ |k,v| v.has_key?(_resolve_tab(options)) }
+% topic_key = found ? found[0] : nil
+% topic = options[:topic] || topic_key
+% if topic
+  <h3 class="topic-title"><%= topic  %></h3>
+% end
+
+% heading = options[:heading] || (options[:index][topic_key] ? options[:index][topic_key][_resolve_tab(options)] : nil)
+% if heading
+  <h2 class="topic-subtitle"><%= heading %></h2>
+% end
+
+<hr>
+
+<%= yield %>    
+
+%# Also important to avoid indentation on return here, since otherwise it could be interpreted
+%# as markdown code
+</article>  
+</div>
+</div>
+
+<script src="<%= path "search.js" %>"></script>

data/templates/shared/_spec.html.erb

@@ -0,0 +1,20 @@
+# % specs = []
+# % if options[:spec].class == Origen::Specs::Spec # Found an individual spec
+#  % specs << options[:spec]
+# % elsif options[:spec].class == Hash && options[:spec].values.first.class == Origen::Specs::Spec # Found all specs for the owner
+#  % specs = options[:spec].values
+# % elsif options[:spec].respond_to?(:specs) && options[:spec].send(:specs) # Found an IP so just see if it has specs and get them if so
+#  % specs = options[:spec].send(:specs).values
+# % else
+#  % fail "'spec' option must point to  an indv. spec or a block that has specs."
+# % end
+
+# % include_data = false
+
+# % specs.each do |s|
+#  <div class="specification">
+#  <a class="anchor" name="<%= "#{s.owner.ip_name}, mode = #{s.mode}" %>"></a>
+#  <a href='#<%= "#{s.owner.ip_name}, mode = #{s.mode}" %>'>
+#  </a>
+# % end
+

data/templates/shared/test/_flow.md.erb

@@ -0,0 +1,227 @@
+%# This is a template to create a test flow document like this one:
+%#   http://origen.freescale.net/tfs/latest/flows/low_cost/sort1/
+% program = options[:program]
+% flows = options[:flow] || options[:flows] 
+% flows = flows ? [flows].flatten : nil
+
+<div class="row">
+%# The markdown attribute is important if you are going to include content written
+%# in markdown, without this is will be included verbatim
+%# One downside is that html cannot be indented here, otherwise it will be parsed
+%# as a code block.
+<div class="col-md-12" markdown="1">
+<div class="panel-group" id="test_flow">  
+
+<a href="#_" class="expandcollapse btn btn-xs pull-right btn-default" state="0"><i class='fa fa-plus'></i></a>
+
+<h2><%= options[:heading] %> <span style="font-size: 14px">(generated for target '<%= program.target %>')</span></h2>
+
+% program.each_in_flow(flows, :context => options[:context]) do |t|
+%   type = t[:type]
+%   instances = t[:instance]
+%   i = instances
+%   flow = t[:flow]
+%   f = flow
+%   context = t[:context]
+%   c = context
+%   description = t[:description]
+
+%   if type == :label || type == :branch
+%     # Need to decide how to deal with label based jumps
+
+%   elsif type == :section_start
+
+<%= _stop_test_flow_table %>
+<%= _start_accordion(description.first) %>
+
+%     description.each_with_index do |line, ix|
+%       unless ix == 0
+<%= line %>
+%       end
+%     end
+
+%   elsif type == :section_stop
+
+<%= _stop_test_flow_table %>
+<%= _stop_accordion %>
+
+%   else
+
+%     unless flow[:name] == "power_cycle_ti"
+<%= _start_test_flow_table %>
+
+<tr>
+<td class="col1">
+<a class="anchor" name="<%= "#{_test_name(t)}_#{_test_number(t)}" %>"></a>
+<div><%= _test_to_local_link(t) %></div>  
+
+% if f[:id]
+% dependents = program.dependents_of(f[:id], flows, :context => options[:context])
+%   unless dependents.empty?
+<div class="alert alert-info">
+%     if dependents[:if_failed]  
+  <p><strong>Note</strong>
+  - This test does not bin out as later tests are dependent on it.
+  </p>
+  <p>These tests will run if this test FAILS:
+  <ul>
+%       dependents[:if_failed].each do |dependent|
+  <li><%= _test_to_local_link(dependent) %></li>
+%       end 
+  </ul></p>
+%     end 
+%     if dependents[:if_passed]  
+  <p><strong>Note</strong>
+  - This test does not bin out as later tests are dependent on it.
+  </p>
+  <p>These tests will run if this test PASSES:
+  <ul>
+%       dependents[:if_passed].each do |dependent|
+  <li><%= _test_to_local_link(dependent) %></li>
+%       end 
+  </ul></p>
+%     end 
+%     if dependents[:if_ran]  
+  <p><strong>Note</strong> - These tests will run if this test RUNS:
+  <ul>
+  <ul>
+%       dependents[:if_ran].each do |dependent|
+  <li><%= _test_to_local_link(dependent) %></li>
+%       end 
+  </ul></p>
+%     end 
+%     if dependents[:unless_ran]  
+  <p><strong>Note</strong> - These tests will run if this test DOES NOT RUN:
+  <ul>
+%       dependents[:unless_ran].each do |dependent|
+  <li><%= _test_to_local_link(dependent) %></li>
+%       end 
+  </ul></p>
+%     end 
+</div>
+%   end
+% end
+
+% if c[:if_enable]
+<div class="alert alert-success">
+  <strong>Note</strong>
+  - This test will only run when '<%= c[:if_enable] %>' is enabled.
+</div>
+% end
+
+% if c[:unless_enable]
+<div class="alert alert-success">
+  <strong>Note</strong>
+  - This test will NOT run when '<%= c[:unless_enable] %>' is enabled.
+</div>
+% end
+
+% if f[:continue]
+<div class="alert alert-danger">
+  <strong>Warning!</strong>
+  - This test does not bin out when failed.
+</div>
+% end
+
+% if c[:if_passed]
+<div class="alert alert-success">
+  <p><strong>Note</strong>
+  - This test will only run if this test PASSED:
+  <ul><li><%= _test_to_local_link(program.find_by_id(c[:if_passed], flows, :context => options[:context])) %></li></ul>
+  </p>
+</div>
+% end
+
+% if c[:if_failed]
+<div class="alert alert-success">
+  <p><strong>Note</strong>
+  - This test will only run if this test FAILED:
+  <ul><li><%= _test_to_local_link(program.find_by_id(c[:if_failed], flows, :context => options[:context])) %></li></ul>
+  </p>
+</div>
+% end
+
+% if c[:if_ran]
+<div class="alert alert-success">
+  <p><strong>Note</strong>
+  - This test will only run if this test RAN:
+  <ul><li><%= _test_to_local_link(program.find_by_id(c[:if_ran], flows, :context => options[:context])) %></li></ul>
+  </p>
+</div>
+% end
+
+% if c[:unless_ran]
+<div class="alert alert-success">
+  <p><strong>Note</strong>
+  - This test will only run if this test DID NOT RUN:
+  <ul><li><%= _test_to_local_link(program.find_by_id(c[:unless_ran], flows, :context => options[:context])) %></li></ul>
+  </p>
+</div>
+% end
+
+
+</td>
+<td class="col2">#<%= _test_number(t) %></td>
+<td class="col3">B<%= _bin_number(t) %></td>
+<td class="col4">B<%= _sbin_number(t) %></td>
+<td class="col5 attributes" markdown="1">
+
+% instances.each_with_index do |instance, i|
+%   if i > 0
+
+***
+
+%   end
+%   instance.each do |key, val|
+%     unless [:patterns, :pattern, :by_block, :name, :id].include?(key)
+%#       if val.is_a?(Numeric)
+%#         if val > 1000000
+%#           val = 
+%#         if val > 1000000
+%#       end
+* **<%= key.to_s.capitalize.gsub("_", " ") %>**: <%= val %>
+%     end
+%   end
+%   patterns = [instance[:pattern], instance[:patterns]].flatten.compact
+%   unless patterns.empty?
+%     if options[:link_to_pattern_docs]
+
+<div class="pattern-links">
+%       patterns.each_with_index do |pattern, i|
+%         if patterns.size > 1
+%         txt = "Pattern #{i}"
+%         else
+%         txt = "Pattern"
+%         end
+<a href="<%= path "/patterns/#{pattern}" %>" role="button" class="btn btn-primary btn-small"><%= txt %></a>
+%       end
+</div>
+%     else
+* **Patterns**:
+%       patterns.each_with_index do |pattern, i|
+  * <%= pattern %>
+%       end
+
+%     end
+%     
+%   end
+% end
+</td>
+
+<td class="col6" markdown="1">
+
+%     description.each do |line|
+<%= line %>
+%     end
+
+</td>
+</tr>
+%   end              
+% end
+% end
+
+<%= _stop_test_flow_table %>
+
+</div>
+</div>
+</div>

data/templates/web/examples.md.erb

@@ -0,0 +1,19 @@
+% render "layouts/basic.html", :tab => :examples do
+
+# Examples
+
+The available helpers are split by engineering function below, click the
+helper of interest to see a live example of it and the application code
+that should be used to generate it.
+
+### General
+
+* [Searchable Documents](<%= path "/examples/searchable/intro" %>)
+* [Register Descriptions](<%= path "/examples/register" %>)
+* [Yammer Widgets](<%= path "/examples/yammer" %>)
+
+### Test Engineering
+
+* [Test Flow](<%= path "/examples/test/flow" %>)
+
+% end

data/templates/web/examples/register.md.erb

@@ -0,0 +1,101 @@
+% render "../layouts/examples.html" do
+
+# Register Helpers
+
+Use the [Origen register API](http://origen-sdk.org/origen/guides/models/registers)
+to define registers in the normal way,
+all of the examples are here are based on this register definition:
+
+~~~ruby
+# **The Long Name of the Reg**
+#
+# The MCLKDIV register is used to divide down the frequency of the HBOSCCLK input. If the MCLKDIV
+# register is set to value "N", then the output (beat) frequency of the clock divider is OSCCLK / (N+1). The
+# resulting beats are, in turn, counted by the PTIMER module to control the duration of Flash high-voltage
+# operations.
+#
+# This is just a test that paragraphs work.
+add_reg :mclkdiv, 0x0003, :size => 16 do
+  # **Oscillator (Hi)** - Firmware FMU clock source selection. (Note that in addition to this firmware-controlled bit, the
+  # FMU clock source is also dependent on test and power control discretes).
+  #
+  # 0 | FMU clock is the externally supplied bus clock ipg_clk
+  # 1 | FMU clock is the internal oscillator from the TFS hardblock
+  bit 15, :osch, :reset => 1
+  # **Mode Ready** - A Synchronized version of the *ftf_mode_ready[1:0]* output from the flash analog hard block.
+  # See the TFL3 Hard Block Creation Guide for more details.
+  #
+  # 0 | Analog voltages have not reached target levels for the specified mode of operation
+  # 1 | Analog voltages have reached target levels for the specified mode of operation
+  bit 13..12, :mode_rdy, :writable => false
+  # **IFR and FW ECC Enable for LDM** - On / off control for UIFR, RIFR, and FW when reading with the MGATE's
+  # Load Memory (LDM) instruction. The setting of this bit only makes a difference when reading with LDM, all other
+  # MGATE reads from UIFR/RIFR will always have ECC disabled and reads from FW will have ECC enabled.
+  #
+  # 0 | ECC is disabled for UIFR, RIFR, and FW reads when using the LDM instruction
+  # 1 | ECC is enabled for all UIFR, RIFR, and FW reads when using the LDM instruction
+  bit 10, :eccen, :reset => 1
+  # **MGATE Command Location Code** - A 2-bit code that tells the MGATE where to go for its instruction fetches
+  # (location of command definitions). These bits are used to form different MGATE command request IDs from a
+  # falling CCIF, one request ID for each of the possible locations of the MGATE executable. If this field is changed,
+  # all subsequent command launches (falling CCIF) will execute from the new area. Note that the MGATE also has
+  # a reset request ID. The reset request ID always targets the Boot Code and is unaffected by the CMDLOC setting.
+  #
+  # 00 | Execute from the Beginning of the MGRAM + 256B (the normal location)
+  # 01 | Execute from the Beginning of the MGRAM
+  # 10 | Execute from the Stack start at the end of MGRAM
+  # 11 | Reserved
+  bit 9..7, :cmdloc, :reset => :undefined
+  # **Clock Divider Bits** - DIV[7:0] must be set to effectively divide HBOSCCLK down to a known beat frequency
+  # having acceptable resolution and dynamic range for timing high-voltage operations on the Flash hardblocks
+  # during algorithms with timed events. Table 1-50 shows the range of timed events (i.e. pulse widths) that can be
+  # achieved with 8-bit and 16-bit PTIMER loads for various input clock frequencies and clock divider settings.
+  bit 6..2, :div, :reset => :memory
+end
+~~~
+
+### Basic Register Diagram
+
+<%= render "templates/shared/register", :reg => $dut.reg(:mclkdiv) %>
+
+Here is an example of how to insert a basic register diagram in
+a document:
+
+~~~eruby
+## Register Map
+
+<%= "%" %> $dut.regs.each do |name, reg|
+
+<%= "<" + "%= render \"doc_helpers/register.html\", reg: reg, preserve_target: true %" + ">" %>
+
+<%= "%" %> end
+~~~
+
+### Register Diagram with Descriptions
+
+<%= render "templates/shared/register", :reg => $dut.reg(:mclkdiv), :descriptions => true %>
+
+Set the <code>:descriptions</code> switch to true to include the register and
+bit descriptions:
+
+~~~eruby
+## Register Map
+
+<%= "%" %> $dut.regs.each do |name, reg|
+
+<%= "<" + "%= render \"doc_helpers/register.html\", reg: reg, preserve_target: true, descriptions: true %" + ">" %>
+
+<%= "%" %> end
+~~~
+
+### Additional Test Cases
+
+<%= render "templates/shared/register", :reg => $dut.reg(:proth) %>
+
+<%= render "templates/shared/register", :reg => $dut.reg(:protl) %>
+
+% $dut.sub_module.regs.each do |name, reg|
+<%= render "templates/shared/register", :reg => reg, :descriptions => true %>
+% end
+
+% end