Overview
 Top Next

One of the minor miracles of the Propeller chip is that all 8 cogs can "see" the state of all 32 I/O pins at the same time and can read and modify locations in Hub memory at any time. This makes it possible to "self-test" during development on a Propeller by using one or more cogs to "watch" what's going on in Hub memory with variables and read the state of I/O pins. This is the approach that ViewPort takes. In order to see/modify variables, one cog is loaded with a program (Conduit.spin) that streams at up to 2 Mbps the value of selected variables to the ViewPort GUI. Conduit.spin provides a bi-directional link that allows variable values to be changed while the program-under-test is running. It also provides a mechanism for the setting of breakpoints and single stepping through a SPIN program.

ViewPort has a second program (QuickSample.spin) that can be loaded into a cog (or optionally 4 cogs). This program continually samples all 32 I/O pins at a fixed rate and streams their values back to the ViewPort GUI where a logic state analyzer (LSA) displays the results. QuickSample can be configured from the ViewPort GUI to take samples at a rate as fast as one sample every 4 instruction times, which is every 200 ns when the Propeller is running at 80 Mhz. 360 samples are taken in a burst, then streamed to the GUI for display.

The Event Logger program is an add-on that communicates with ViewPort via the DDE (Dynamic Data Exchange) protocol and provides an event oriented LSA as opposed to the sampling LSA that ViewPort includes. The EventLogger.spin program is loaded into a cog (either instead of QuickSample or in addition to). After a specified trigger condition is satisfied, this cog records the time (via the CNT register) of changes of state on a specified set of I/O pins. Up to 99 events will be recorded and then sent via Conduit.spin running in the Propeller chip to ViewPort and on to the Event Logger Client.exe where a GUI displays the results in a plot that can be zoomed, scrolled, measured, printed, etc.

An event driven LSA is better able to deal with "bursty" data where some events of interest take a relatively long period of time, but are then followed by much faster events. On a sampling LSA, the sample rate would have to be set low enough to allow the long events to be seen, but then there would be insufficient resolution to see the fast events accurately. Sometimes ways can be found to work around this conflict, but an event driven LSA is easier to use in such a case.

The EventLogger.spin program uses a 4 instruction sequence to capture each event. That sets a lower limit of 200 ns on the shortest pulse that it can reliably detect. This is the same as QuickSample running at its highest speed. But EventLogger can capture a 250 ns "runt" pulse and continue to accurately detect much much longer pulses.

QuickSample runs continuously and always shows what's happening on all 32 I/O pins. EventLogger only shows what's happening on selected pins and only for 98 state changes past the trigger point. They are different tools with different strengths. Sometimes you need both, and you can run QuickSample and EventLogger at the same time!

Below is an example display of an SPI communication running at 1.3 Mhz. The device being tested is an MCP3208 8 channel 12 bit analog to digital converter. EventLogger is very useful during the development of drivers for such devices because of its stable display and accurate event timing (easily measured by the use of movable cursors). Note: there is an important context menu available for the plot. It was activated for the following screen shot by right clicking inside the trace plot area.

And here is a "zoom" into an area of interest in the above plot...


Getting Started
 Previous Top Next

The distribution includes:

The distribution comes as a zip file. Unzip it into any convenient folder. Make a shortcut to Event Logger Client.exe and move that to your desktop. The .chm and .dll files must remain in the same directory as Event Logger Client.exe. However, the .spin files can be moved to where they are needed.

EventLogger.spin is the Spin/assembly code object that has to be referenced in your program. It is loaded into a cog and does the actual recording of "events". This program must be placed either in the Propeller library (recommended), or in the same folder as the program you're testing.

Note: the Propeller library directory is the root directory for the version of the Propeller Tool that you are using. For example, at this writing, the PropTool is at Version 1.2.6, so on my computer, the "library" is at

C:\Program Files\Parallax Inc\Propeller Tool v1.2.6

EventLog Test.spin is a preconfigured test program that monitors port pins 30 and 31 (which are always active because ViewPort's Conduit.spin is using them for the high-speed data link.) This should run "out of the box". To do this:

1. Assuming that ViewPort has been installed, put EventLog Test.spin in a convenient folder. As this program needs the objects Conduit.spin and QuickSample.spin, these files must be either in the Propeller "library" (recommended) or in the same folder as EventLog Test.spin.

2. Open ViewPort.

3. Open Event Logger Client. It should connect to ViewPort but give a status message at the bottom that looks like this:

the elog array is where the EventLogger object records its data. Until the elog array has been named and made available to ViewPort, you will get this message.

4. Click on File|Load SPIN file to Propeller

and navigate to where you stored EventLog Test.spin. Select it.

5. You will see ViewPort accepting the selected file, compiling it, and loading it into the Propeller chip.

6. Briefly, Client disconnects from ViewPort (while it is loading the Propeller), then reconnects. You will see the message:

7. When that message changes to:

click the Start Capture button. Then you should see:

You may find it convenient to reverse the sequence just described:

1. Open ViewPort and start your program.

2. Open Event Logger Client. You should immediately see

in the lower left corner.

3. Click on the Start Capture button.


Adding EventLogger to your program
 Previous Top Next

In broad terms, this is what you do to add the EventLogger to your program...

1. Create references to the EventLogger.spin and Conduit.spin objects in an OBJ section.

2. Create a ViewPort array "channel".

3. Name the array "channel" elog (lower case is required).

4. Initialize and configure the EventLogger at the beginning of the executable code.

An example is often the best instruction and EventLog Test.spin (which is in the distribution) has been thoroughly commented. It is reproduced here for your reading convenience...

Note: the order of ViewPort configuration statements is important. Do follow the ordering shown in the example below.

Executable code starts here...


FAQ
 Previous Top Next

Question:
A trace that I was expecting does not show up on the plot. What happened?

Answer 1:
Perhaps you forgot to enable the recording of events on that port pin. This is controlled by the Event Pin Mask. Click on View|Configuration wizard and examine the setting that is in effect for the pin in question.

Answer 2:
Possibly the trace has been plotted, but it is "off-screen". Check the vertical scroll bar on the plot. Any time that is present, it means that there are more traces available. Scroll to see the otheres.

Suggestion: click on View|Plot Legend Control and change the plot position for traces of interest to make them display in the first dozen trace positions. Note that this table does not make traces appear (that's controlled by Event Pin Mask) but simply deals with the "cosmetics" of a trace that is to be plotted.

Question:
I started a capture but nothing is happening. The trace plot went empty and the status bar says Capture initiated: What do I do?

Answer:
The EventLogger is either waiting for a trigger sequence to complete or the requested number of events to occur. It is not possible to know which condition it is waiting for. The first thing to try is to click the Request capture finish button (but only if you made accommodation in your program to look for this command and finish the capture sequence by injecting events). If that fails, then the cog is waiting for a trigger condition to be met. The only cure for this is to restart the cog. Click the Request cog restart button (you should always try to make accommodation for this command).

Question:
I accidentally clicked on some context menu item in the plot and now the traces aren't lined up right. How do I fix this?

Answer:
You clicked on the Set Scale to Default menu item. In this application, that menu item provides no useful function. Avoid it. To fix things, right click in the trace area to bring up the context menu and then click the Undo All Zoom/Pan menu item to restore trace and legend alignments.

Question:
How do I Zoom and pan? And if I do, can I undo those effect?

Answer:
Click on Help|How to manipulate trace plot for help in this area.

Question:
I get tired of clicking on the up/down controls to move the cursors. Is there a quicker way?

Answer:
Yes. You can enter an event directly in either box. The cursor will immediately jump to that event. Use the up/down control to refine its position. Now you can use that event number with appropriate offsets in the other cursor box to enclose and time events of interest.

Question:
Can I plot a trace on top of another to ease comparisons?

Answer:
Yes. Just set the trace plot positions to be the same. Click on View|Plot Legend Control to access the settings for trace plots.

Question:
Can I plot the same trace in multiple positions?

Answer:
Unfortunately, you can't do that, nice as it would be in some circumstances.

Question:
Can you run more than one copy of Event Logger Client at a time.

Answer:
Yes. I have personally had three copies open at the same. I don't know what the limit might be. It is sometimes nice to have two copies. One captures some reference traces. Then the second is used to experiment and compare.


Contact information
 Previous Top

This program was written by Bob Anderson with the assistance of Hanno Sanders, the creator of ViewPort.

It uses the DDE (Dynamic Data Exchange) protocol implemented in ViewPort to communicate with the Propeller chip under test.

Bob Anderson can be reached via email at:

bob.anderson@centurytel.net

For information about ViewPort, go to www.hannoware.com .