origen_link 0.2.0 → 0.3.0

data/lib/origen_link/test/top_level_controller.rb

@@ -1,3 +1,5 @@
+require 'origen_jtag'
+
 module OrigenLink
   module Test
     class TopLevelController

data/lib/origen_link/vector_based.rb

@@ -6,41 +6,48 @@ require 'origen_link/configuration_commands'
 require 'origen_link/callback_handlers'
 module OrigenLink
   # OrigenLink::VectorBased
-  #   This class is meant to be used for live silicon debug.  Vector data that Origen
+  #   This class describes the OrigenLink app plug-in.  Vector data that Origen
   #   generates is intercepted and sent to a debug device (typically will be a Udoo
   #   Neo - www.udoo.org).  The debug device can be any device that is able to serve
   #   a TCP socket, recieve and interpret the command set used by this class and send
   #   the expected responses.
   #
-  # Integration instructions
-  #   Set the pin map (must be done first) and pin order
-  #     if tester.link?
-  #        tester.pinmap = 'tclk,26,tms,19,tdi,16,tdo,23'
-  #        tester.pinorder = 'tclk,tms,tdi,tdo'
-  #     end
-  #
-  #   Set Origen to only generate vectors for pins in the pinmap (order should match)
-  #        pin_pattern_order :tclk, :tms, :tdi, :tdo, only: true if tester.link?
-  #
-  #   At the beginning of the Startup method add this line
-  #      tester.initialize_pattern if tester.link?
-  #
-  #   At the end of the Shutdown method add this line
-  #     tester.finalize_pattern if tester.link?
-  #
-  #   Create a link environment with the IP address and socket number of a link server
-  #     $tester = OrigenLink::VectorBased.new('192.168.0.2', 12777)
   class VectorBased
     include OrigenTesters::VectorBasedTester
     include ServerCom
     include CaptureSupport
     include ConfigurationCommands
 
-    # these attributes are exposed for testing purposes, a user would not need to read them
-    attr_reader :fail_count, :vector_count, :total_comm_time, :total_connect_time, :total_xmit_time
-    attr_reader :total_recv_time, :total_packets, :vector_repeatcount, :tsets_programmed, :captured_data
-    attr_reader :vector_batch, :store_pins_batch, :comment_batch
-    attr_reader :user_name, :initial_comm_sent
+    # The number of cycles that fail
+    attr_reader :fail_count
+    # The number of vector cycles generated
+    attr_reader :vector_count
+    # The accumulated total time spent communicating with the server
+    attr_reader :total_comm_time
+    # The accumulated total time spent establishing the server connection
+    attr_reader :total_connect_time
+    # The accumulated total time spent transmitting to the server app
+    attr_reader :total_xmit_time
+    # The accumulated total time spent receiving from the server app
+    attr_reader :total_recv_time
+    # The accumulated total number of packets sent to the server
+    attr_reader :total_packets
+    # The accumulated number of times push_vector was called with the present tset and pin info
+    attr_reader :vector_repeatcount
+    # The look up of programmed tsets.  Names are converted to a unique number identifier
+    attr_reader :tsets_programmed
+    # Data captured using tester.capture
+    attr_reader :captured_data
+    # Array of vectors waiting to be sent to the sever
+    attr_reader :vector_batch
+    # Used with capture
+    attr_reader :store_pins_batch
+    # Array of comments received through push_comment
+    attr_reader :comment_batch
+    # The name of the user running OrigenLink
+    attr_reader :user_name
+    # Indicates that communication has been initiated with the server
+    attr_reader :initial_comm_sent
 
     def initialize(address, port, options = {})
       @address = address
@@ -58,6 +65,7 @@ module OrigenLink
       @max_packet_time = 0
       @max_receive_time = 0
       @tsets_programmed = {}
+      @tsets_warned = {}
       @tset_count = 1
       @store_pins = []
       @captured_data = []
@@ -72,6 +80,22 @@ module OrigenLink
       @pattern_comments = {}
       @user_name = Etc.getlogin
       @initial_comm_sent = false
+      @initial_vector_pushed = false
+      @pinorder = ''
+      @pinmap_hash = {}
+      @batched_setup_cmds = []
+
+      # check the server version against the plug-in version
+      response = send_cmd('version', '')
+      response = 'Error' if response.nil?	# prevent run time error in regression tests
+      response.chomp!
+      server_version = response.split(':')[1]
+      server_version = '?.?.? - 0.2.0 or earlier' if response =~ /Error/
+      app_version = Origen.app(:origen_link).version
+      Origen.log.info("Plug-in link version: #{app_version}, Server link version: #{server_version}")
+      unless app_version == server_version
+        Origen.log.warn('Server version and plug-in link versions do not match')
+      end
     end
 
     # push_comment
@@ -92,14 +116,89 @@ module OrigenLink
       end
     end
 
+    # ordered_pins(options = {})
+    #   expand pin groups to their component pins after the pin ordering is completed
+    #   OrigenLink always operates on individual pins.  This saves other methods
+    #   from each needing to handle pins and/or groups of pins.
+    def ordered_pins(options = {})
+      result = super
+      groups = []
+      result.each { |p| groups << p if p.size > 1 }
+      groups.each do |group|
+        # locate this group in the result array
+        i = result.index(group)
+        result.delete_at(i)
+        dut.pins(group.id).map.each do |sub_pin|
+          result.insert(i, sub_pin)
+          i += 1
+        end
+      end
+
+      if @pinmap.nil?
+        # create the pinmap if pin metadata was provided
+        pinarr = []
+        result.each do |pin|
+          if pin.meta.key?(:link_io)
+            pinarr << pin.name.to_s
+            pinarr << pin.meta[:link_io].to_s
+          end
+        end
+        self.pinmap = pinarr.join(',') unless pinarr.size == 0
+      end
+
+      result
+    end
+
+    # fix_ordered_pins(options)
+    #   This method is called the first time push_vector is called.
+    #
+    #   This method will create the pinmap from pin meta data if needed.
+    #
+    #   This method will remove any pin data that doesn't correspond
+    #   to a pin in the link pinmap and remove those pins from the
+    #   @ordered_pins_cache to prevent them from being rendered
+    #   on the next cycle.
+    #   This will prevent unwanted behavior.  The link server
+    #   expects only pin data for pins in the pinmap.
+    def fix_ordered_pins(options)
+      # remove non-mapped pins from the ordered pins cache - prevents them appearing in future push_vector calls
+      orig_size = @ordered_pins_cache.size
+      @ordered_pins_cache.delete_if { |p| !@pinmap_hash[p.name.to_s] }
+      Origen.log.debug('OrigenLink removed non-mapped pins from the cached pin order array') unless orig_size == @ordered_pins_cache.size
+      # update pin values for the current  push_vector call
+      vals = []
+      @ordered_pins_cache.each { |p| vals << p.to_vector }
+      options[:pin_vals] = vals.join('')
+      options
+    end
+
     # push_vector
     #   This method intercepts vector data from Origen, removes white spaces and compresses repeats
     def push_vector(options)
+      unless @initial_vector_pushed
+        if @pinmap.nil?
+          Origen.log.error('OrigenLink: pinmap has not been setup, use tester.pinmap= to initialize a pinmap')
+        else
+          Origen.log.debug('OrigenLink: executing pattern with pinmap:' + @pinmap.to_s)
+        end
+
+        # remove pins not in the link pinmap
+        options = fix_ordered_pins(options)
+
+        # now send any configuration commands that were saved prior to pinmap setup (clears all server configs)
+        @batched_setup_cmds.each do |cmd|
+          response = send_cmd(cmd[0], cmd[1])
+          setup_cmd_response_logger(cmd[0], response)
+        end
+
+        @initial_vector_pushed = true
+      end
+      set_pinorder if @pinorder == ''
       programmed_data = options[:pin_vals].gsub(/\s+/, '')
       unless options[:timeset]
         puts 'No timeset defined!'
         puts 'Add one to your top level startup method or target like this:'
-        puts '$tester.set_timeset("nvmbist", 40)   # Where 40 is the period in ns'
+        puts 'tester.set_timeset("nvmbist", 40)   # Where 40 is the period in ns'
         exit 1
       end
       tset = options[:timeset].name
@@ -126,9 +225,6 @@ module OrigenLink
     # flush_vector
     #   Just as the name suggests, this method "flushes" a vector.  This is necessary because
     #   of repeat compression (a vector isn't sent until different vector data is encountered)
-    #
-    #   Don't forget to flush when you're in debug mode.  Otherwise, the last vector of a
-    #   write command won't be sent to the server.
     def flush_vector(programmed_data = '', tset = '')
       # prevent server crash when vector_flush is used during debug
       unless @previous_vectordata == ''
@@ -140,7 +236,15 @@ module OrigenLink
         if @tsets_programmed[@previous_tset]
           tset_prefix = "tset#{@tsets_programmed[@previous_tset]},"
         else
-          tset_prefix = ''
+          # The hash of programmed tsets does not contain this tset
+          # Check the timing api to see if there is timing info there
+          # and send the timing info to the link server
+          if dut.respond_to?(:timeset)
+            tset_prefix = process_timeset(tset)
+          else
+            tset_warning(tset)
+            tset_prefix = ''
+          end
         end
 
         if @batch_vectors
@@ -233,9 +337,11 @@ module OrigenLink
 
       vector_cycles.each do |cycle|
         thiscyclefail = false
+        bad_pin_data = false
         if pfstatus == 'F'
           # check to see if this cycle failed
           0.upto(cycle.length - 1) do |index|
+            bad_pin_data = true if (cycle[index] == 'W')
             thiscyclefail = true if (cycle[index] == 'H') && (expected_msg[expected_msg.length - cycle.length + index] == 'L')
             thiscyclefail = true if (cycle[index] == 'L') && (expected_msg[expected_msg.length - cycle.length + index] == 'H')
           end
@@ -247,6 +353,10 @@ module OrigenLink
           expected_msg_prnt = ''
           prepend = 'P:'
         end
+        if bad_pin_data
+          expected_msg_prnt = ' ' + 'W indicates no operation, check timeset definition'
+          prepend = 'F:'
+        end
 
         if output_obj.nil?
           microcode prepend + cycle + expected_msg_prnt + msg
@@ -263,8 +373,8 @@ module OrigenLink
     end
 
     # initialize_pattern
-    #   This method sets initializes variables at the start of a pattern.
-    #   it is called automatically when pattern generation starts.
+    #   This method initializes variables at the start of a pattern.
+    #   It is called automatically when pattern generation starts.
     def initialize_pattern
       @fail_count = 0
       @vector_count = 0
@@ -280,11 +390,12 @@ module OrigenLink
       @total_xmit_time = 0
       @total_recv_time = 0
 
-      if @pinmap.nil?
-        Origen.log.error('pinmap has not been setup, use tester.pinmap= to initialize a pinmap')
-      else
-        Origen.log.debug('executing pattern with pinmap:' + @pinmap.to_s)
-      end
+      # moved to push_vector to allow auto-pinmap
+      # if @pinmap.nil?
+      #   Origen.log.error('OrigenLink: pinmap has not been setup, use tester.pinmap= to initialize a pinmap')
+      # else
+      #   Origen.log.debug('OrigenLink: executing pattern with pinmap:' + @pinmap.to_s)
+      # end
     end
 
     # finalize_pattern
@@ -327,11 +438,9 @@ module OrigenLink
     end
 
     # to_s
-    #   returns 'Origen::VectorBased'
+    #   returns 'OrigenLink::VectorBased'
     #
-    #   This method at the moment is used for implementing code that runs only if the
-    #   environment is set to link vector based.  tester.link? will be used once the testers
-    #   plug in supports the method link?.
+    #   No longer a use for this.  Use tester.link?
     def to_s
       'OrigenLink::VectorBased'
     end
@@ -341,11 +450,10 @@ module OrigenLink
     #   true = pass
     #   false = fail
     #
-    # TODO: capture transaction vector data and response for use in debug
-    #
-    # if !tester.transaction {dut.reg blah blah}
-    #   puts 'transaction failed'
-    # end
+    # @example
+    #   if !tester.transaction {dut.reg blah blah}
+    #     puts 'transaction failed'
+    #   end
     def transaction
       if block_given?
         synchronize

data/pattern/jtag_comm_timing_api.rb

@@ -0,0 +1,26 @@
+Pattern.create(options={:name => "Timing_API_Test"})do
+  tester.set_timeset('api_tst', 40)
+  $dut.timeset :api_tst do |t|
+    t.wave :tclk do |w|
+      w.drive :data, at: 10
+      w.drive 0, at: 30
+    end
+    t.wave :tdi, :tms, :tdo do |w|
+      w.drive :data, at: 5
+    end
+    t.wave do |w|
+      w.compare :data, at: 25
+    end
+  end
+  $dut.current_timeset_period = 40
+
+  $dut.jtag.reset
+  $dut.jtag.idle
+  ss "reading Halo debugger ID"
+  $dut.reg(:testreg).read(0x5ba00477)
+  $dut.jtag.read_dr dut.reg(:testreg), size: 32
+  $dut.jtag.write_ir 0, size: 4
+  ss "reading Halo JTAG ID"
+  $dut.reg(:testreg).read(0x1984101d)
+  $dut.jtag.read_dr dut.reg(:testreg), size: 32
+end

data/templates/web/index.md.erb

@@ -4,22 +4,409 @@
 %# formatting like this, but in most cases that is not required.
 <h1><%= Origen.app.namespace %> <span style="font-size: 14px">(<%= Origen.app.version %>)</span></h1>
 
-### Purpose
+# Purpose
 
-This is a plug-in for Origen that enables live silicon debug directly from origen source.
+This is a plug-in for Origen that enables live silicon debug directly from origen source.  There are 2 parts to OrigenLink, the plug-in and the server.  Setup for each is documented separately.  The OrigenLink server is capable of being shared by multiple people working on the same project.  It will lock out other users during your debug or pattern execution session.
 
-### How To Use
+# Plug-in
 
-Add the following line to your application's GEMFILE:
+Instructions for integrating and using the plug-in with your app.
 
-* gem 'origen_link'
+## How To Import
 
-Add the following line to your application:
+* Add the following line to your application's GEMFILE:
 
-* require 'origen_link'
+~~~ruby
+ gem 'origen_link'
+~~~
 
-### How To Setup the Application Environment
 
-Describe how a user would setup a new workspace for this application...
+* Add a link environment (./environment/link.rb).  See server setup section for more information:
+
+~~~ruby
+# Note that the field for providing the computer name or IP address is a string
+OrigenLink::VectorBased.new('<ServerComputerName -- or IP_Address>', 12777)
+~~~
+
+
+* Select link as your environment to run a pattern over the link connection when the origen generate command is run:
+
+~~~
+origen e environment/link.rb
+origen g pattern/my_pattern.rb
+~~~ 
+
+
+## How To Configure
+
+Before OrigenLink can be used the physical pin map and timing must be setup.  There are 2 supported ways of doing this.  The high-level setup method allows OrigenLink to determine how to configure the server side pin sequencer.  The high-level setup method is highly recommended.  For cases where the high-level setup is not functioning correctly, legacy apps, or if you just enjoy doing things the hard way, a legacy low-level api is available.  Both will be described here.
+
+### How To Configure - High-Level Method (Preferred)
+
+This is the recomended way to setup OrigenLink in your application.
+
+#### Physical Pin Map
+
+OrigenLink needs to tell the server application which physical IO pin on the UDOO device (see UDOO-Neo GPIO documentation) corresponds to which DUT pin in your app.  The number after 'gpio_' is what OrigenLink needs.  This IO number is passed to OrigenLink through pin meta data.
+
+~~~ruby
+add_pin :tclk, meta: {link_io: 8}
+add_pin :tdi, meta: {link_io: 146}
+~~~
+
+#### Timing
+
+OrigenLink emulates a tester sequencer through software.  The timing it implemtents will not be precise.  Setting the drive edge of tdi to 5ns and tclk to 20ns will not result in tclk being driven 15ns after tdi.  What will happen, though, is the sequencer will drive tdi first, followed by tclk.  It is recommended that you use the built in Origen API for setting timing.
+
+~~~ruby
+  # Configure timing for jtag communication with RL tclk
+  tester.set_timeset('api_tst', 40)
+  dut.timeset :api_tst do |t|
+    t.drive_wave :tclk do |w|
+      w.drive :data, at: 10
+      w.drive 0, at: 30
+    end
+    t.drive_wave :tdi, :tms, :tdo do |w|
+      w.drive :data, at: 5
+    end
+    t.compare_wave do |w|
+      w.compare :data, at: 25
+    end
+  end
+~~~
+
+#### Finished
+
+Start your OrigenLink server (see server setup section), connect your DUT to the server device and off you go.
+
+### How To Configure - Low-Level Legacy API (Skip Reading This Section)
+
+The prefered configuration method is above.  These methods for configuring the server application are supported for legacy applications.  This method is more prone to producing hard to debug errors during setup of a new app.
+
+#### Low-Level Physical Pin Map Setup
+
+Create a comma separated list of pin_name and IO# and pass it to the tester.  The .pinmap method will clear all server settings.  So, this should be done first.  The pin name string provided to the pinmap must exactly match the pin name string provided to the pin timing and pin order methods.  Any typo may result strange behavior (pin operation not occuring, timing error messages, and/or server crash).  No cause for alarm, just be sure to check for consistent names if you get those problems.
+
+~~~ruby
+  tester.pinmap = 'tclk,119,tms,6,tdi,116,tdo,124'
+~~~
+
+#### Low-Level Pattern Pin Order Setup
+
+Pins that don't have an assiciated physical IO will not have their pin data transmitted to the link server.  Create a comma separated list of the pins that are linked (only include pins that are in the pinmap) in the order that they appear in the pattern.  Using this command is not needed unless you used the low-level pin map setup command AND your dut.pins(:pin_name) doesn't match the pin name that you setup using 'tester.pinmap ='.
+
+~~~ruby
+  pin_pattern_order :tclk, :tms, :tdi, :tdo	# This sets the order of the pins in the pattern
+
+  # order given below must match order in pin_pattern_order
+  # names used below must match names used in tester.pinmap=
+  # the below example will cause issues because of a typo: 'tck' versus 'tclk' (tester.pinmap = 'tclk,119,)
+  tester.pinorder = 'tck,tms,tdi,tdo'		# This tells the server what order the pins are in the pattern
+~~~
+
+#### Low-Level Timing Setup
+
+~~~ruby
+    # pinformat=
+    #   This method is used to setup the pin clock format on the debugger device.
+    #   The supported formats are rl and rh
+    #
+    #   example:
+    #     tester.pinformat = 'func_25mhz,tclk,rl'
+
+    # pintiming=
+    #   This method is used to setup the pin timing on the debugger device.
+    #   Timing is relative to the rise and fall of a clock
+    #
+    #   timing value:         0   1   2
+    #   clock waveform:      ___/***\___
+    #
+    #   example:
+    #     tester.pintiming = 'func_25mhz,tms,0,tdi,0,tdo,1'
+
+~~~
+
+### Debugging Your App
+
+What follows are some pointers for using OrigenLink to debug your app (or pattern).  Run the origen pattern generation command with debug enabled and set a break point in your code to interactively debug.
+
+~~~
+origen g pattern/my_pattern.rb -d
+~~~
+
+~~~ruby
+  # inside pattern/my_pattern.rb
+
+  dut.reg(:MyReg).write!(my_value)
+
+  # stop after updating this register to observe device state
+  debugger	# generation of the pattern will pause here
+~~~
+
+#### Debugging Pin Map
+
+There are pin methods available to aid debug of an OrigenLink setup.
+
+~~~
+  # Cause a pin to continuously toggle every 2 seconds
+  (debugger prompt): dut.pin(:tdi).hello
+  
+  # Stop the pin from toggling
+  (debugger prompt): dut.pin(:tdi).goodbye
+~~~
+
+#### Staying Synchronized
+
+For efficiency vectors that are generated by your app are compressed and stored until the pattern generation is completed.  This means that when execution reaches a 'debugger' statement the previously generated vectors may not have been sent to the server yet.  There are a handful of ways to make this happen.
+
+* Use the tester.synchronize command from the debugger interface:
+
+~~~
+  # one time synchronize
+  (debugger prompt): tester.synchronize
+
+  # tell debugger to evaluate the synchronize command every time it gets control
+  # will cause continuous synchronization
+  (debugger prompt): disp tester.synchronize
+~~~
+
+* Use tester.transaction (makes the most sense to have this in your app's reg read/write methods).  Before the transaction method executes the code block provided it will perform a synchronization.  Then, the code in the block is executed (which generates new vectors) and a second synchronization is performed.  The transaction method returns a boolean indicating whether the vectors generated by the code block passed or failed.
+
+~~~ruby
+  result = tester.transaction { dut.jtag.shift_xx (yy) }
+  if tester.link?
+    # result = true if the code in the provided block passed
+  end
+~~~
+
+#### Capturing DUT Information
+
+There are a few methods for observing the actual state of the DUT.
+
+* Capture using tester.capture
+
+~~~ruby
+  # example of capturing and programatically using information read from the DUT
+  ss "reading default ID"
+  dut.reg(:testreg).bits(31..0).store
+  default_id = tester.capture {dut.jtag.read_dr dut.reg(:testreg), size: 32 }
+  default_id_str = default_id[0].to_s(2)
+  default_id_str.reverse!
+  default_id = default_id_str.to_i(2)
+  puts '**************************************************'
+  puts 'Captured default ID through JTAG: 0x' + default_id.to_s(16)
+  puts '**************************************************'
+~~~
+
+* Capture using mem api
+
+This command will read the contents of memory from the DUT and display it.
+
+~~~
+  # example of mem api use
+  (debugger prompt): dut.mem(0x2000_0000).sync(3)
+  20000000: DEADBEEF
+  20000004: 200000D4
+  20000008: 1C000898
+  
+  (debugger prompt): dut.mem(0x2000_0000).write!(0x1234567)
+  (debugger prompt): dut.mem(0x2000_0000).sync(3)
+  20000000: 01234567
+  20000004: 200000D4
+  20000008: 1C000898
+~~~
+
+* reg.sync!
+
+This command will read the contents of the register from the DUT and display it by bit field.
+
+~~~
+  (debugger prompt): dut.reg(:MyReg).sync! 
+~~~
+
+#### When A Shared Server Session Isn't Properly Ended
+
+The server is able to handle multiple users.  Once a user connects to the server, it will only allow access from that same IP address and user name until the session has ended.  The session end command is transmitted when pattern generation is completed.  If a user fails to properly end their session (happens when you exit debug mode by typing 'q' instead of 'c'), the server application will continue to lock out access until the time out has expired (20 minutes).  Before terminating a running session, check with the user who started the session to make sure they aren't in the middle of debug (the user id and IP address will be displayed when you try to connect).  If the previous session needs to be manually terminated, this is how you do it (this should be a rare exception to the rule - it's bad manners to forcefully kill another user's session):
+
+~~~ruby
+# run this code to forcefully terminate a session
+require 'socket'
+
+TCPSocket.open('udooneo-computer-name', 12777) do |link|
+  link.puts("session_end\n\n")
+  while received = link.gets
+    puts received
+  end
+  link.puts("session_kill\n\n")
+  while received = link.gets
+    puts received
+  end
+end
+puts "unlocked the server"
+~~~
+
+------------------------------------------------------------------------------------------------------
+
+# Server
+
+This section describes how to setup a new IOT device to serve the OrigenLink pin sequencer.
+
+## Setting Up a New UDOO device
+
+Here are the steps to take to setup a new UDOO-Neo to run the OrigenLink server application.  These instructions are not intended to be exhaustive, but should be good enough to get you up and running.
+
+* Change the name of the computer to something unique (like udooneo-myname).  This name is the string that you will enter in your environment ruby file for your app.  Your computer running origen g pattern/my_pattern.rb and the UDOO should be attached to the same network (either through USB or ethernet)
+
+~~~
+prompt$> sudo nano /etc/hostname
+~~~
+
+~~~ruby
+# Note that the field for providing the computer name or IP address is a string
+OrigenLink::VectorBased.new('<ServerComputerName -- or IP_Address>', 12777)
+~~~
+
+* Disable the M4 core (allows access to all IO's from unix)
+
+~~~
+menu -> preferences -> Udoo web configuration -> Advanced settings
+~~~
+
+* Install ruby.  This is a decision point.  If you want to install the OrigenLink gem, the steps are a bit more complicated.
+
+** Option 1 (I want the gem): You need to install ruby 2.2.
+
+~~~
+prompt$> sudo apt-get ruby22
+~~~
+
+** Option 2 (I'm fine using git to pull down the server code)
+
+~~~
+# of course you're still welcomed to install a newer ruby version
+# the server will run just fine
+prompt$> sudo apt-get ruby
+~~~
+
+* Install the OrigenLink server.
+
+** Option 1 (if you installed ruby22 you can do this).  Install origen and origen_link gems.
+
+~~~
+# follow the instructions for installing origen at origen-sdk.org
+prompt$> sudo gem install origen
+prompt$> sudo gem install origen_link
+~~~
+
+** Option 2 (This is what I do)
+
+~~~
+prompt$> git clone https://github.com/Origen-SDK/OrigenLink.git
+
+# if you get SSL certificate errors do this and retry the clone command
+prompt$> git config --global http.sslverify false
+~~~
+
+## Starting the Server
+
+If you installed Ruby 2.x and Origen, run this command to start the server:
+
+~~~
+<command_prompt>$ start_link_server
+~~~
+
+If you chose to clone the OrigenLink project from github, navigate to the OrigenLink directory and type this command:
+
+~~~
+<command_prompt>$ bin/start_link_server
+~~~
+
+The server is now running
+
+## Physical Interconnect
+
+Keep the following things in mind when connecting the IO's of your UDOO Neo to a DUT
+
+* Ground is important.  As a rule of thumb, connect at least 2 ground wires between the UDOO and your DUT
+
+* Pay attention to pin levels.  The UDOO IO's are 3.3v.  If your device is not also 3.3v, the most reliable and convenient way to connect the IO's is by using a bi-directional (auto-direction sensing) level shifter.  This one works well and is easy to find (available on Amazon Prime at the writing of this document): TXB0108
+
+* An alternative method for shifting a voltage down is to use a diode and pullup resistor.  The anode gets connected to the higher voltage device.  The cathode is connected to the lower voltage device.  A 10K pullup resistor is connected from the cathode to the supply voltage for the lower voltage device.  --- A word of advice: This method is quick and easy.  But, you get a slow rise time which makes it a terrible way of shifting the level of a clock signal (like TCLK for JTAG or SPICLK for SPI).
+
+---
+
+# How It Works
+
+This section will explain the in's and out's of how the plug-in and server applications work and how they communicate.  This section is intended to aid developers who want to add or modify features.  More in depth information can be found in the api documentation.
+
+## Server Side App
+
+What follows is the structure of the server side app.
+
+### Pin IO
+
+Pin IO is accomplished by using the file objects exported by linux at \sys\class\gpio
+
+~~~
+<command_prompt>$ cd /sys/class/gpio
+
+# export the file objects for a pin
+<command_prompt>$ echo 20 > export
+
+# read the state of gpio20
+<command_prompt>$ cd gpio20
+<command_prompt>$ cat value
+
+# drive gpio20 to logic 1
+<command_prompt>$ echo out > direction
+<command_prompt>$ echo 1 > value
+
+# change gpio20 from output to input
+<command_prompt>$ echo in > direction
+~~~
+
+### Pin Class
+
+The server pin class implements IO interactions for a pin.  When the pin assign command creates a pin object, it exports the associated IO number and opens IO objects for the direction and value of that pin.  The IO objects are kept open until the pin is destroyed.  For more information see the api documentation.
+
+### Pin Sequencer
+
+The pin sequencer is the class that does all of the heavy lifting for the server side app.  It implements all of the command messages that begin with "pin_".  See the api documentation (Server::Sequencer) for more information.  Timing is perhaps the most complicated construct to understand:
+
+~~~ruby
+  # tset is a number that corresponds to a timeset name from origen ex: 1 corresponds to 'tp0'
+  # @cycletiming[tset] is a hash
+  # each timeset contains these keys: 
+  #    'events'               -  [array of timestamps for timing events]
+  #    'drive_event_data'     -  hash, the keys of the hash correspond to elements of 'events'
+  #                           -  each value in the hash is an array
+  #                           -  each element in the array is one of 3 values: 'data', '0', or '1'
+  #    'drive_event_pins'     -  hash, the keys of the hash correspond to elements of 'events'
+  #                           -  each value in the hash is an array
+  #                           -  each element in the array is an array of pin objects
+  #                           -  the drive event data will be performed for each pin object
+  #    'compare_event_data'   -  similar to drive_event_data, the only valid event data is 'data'
+  #    'compare_event_pins'     -  similar to drive_event_pins
+  
+  @cycletiming[tset] = {
+  ['events'] = [0, 5, 10, 35]
+  ['drive_event_data'] = {
+        0: ['data']
+       10: ['data','0']
+       35: ['0']
+      }
+  ['drive_event_pins'] = {
+        0: [[pin_obj1, pin_obj2]]
+       10: [[pin1,pin2], [pin3]]
+       35: [[pin4]]
+      }
+  }
+~~~
+
+The main message supported by the sequencer is 'pin_cycle'.  As the name implies, this message implements 1 or more cycles of vector data.  It will return the response of the dut to the plug-in side app along with pass/fail information.
+
+### Server
+
+The server serves a TCP socket at 12777.  No fancy gems are used for several reasons, the main one being simplicity.  Ruby has a built in socket library that is extremely simple to use.  Multiple messages from the plug-in side app can be received with a single connection.  "\n" indicates the end of a message.  "\n\n" indicates that the packet of messages has ended.  Why TCP and not UDP?  I know the web says that UDP socket communication is faster.  But, my testing indicated otherwise.  Plus, TCP is more reliable.
 
 % end