TimeLine

Event-History Postprocessor

January 7, 2003
The TimeLine display utility formats simulation event-history files for visualizing timelines on generic XY plotters. Simulation models, as well as the software SCHEDULER often produce trace information in one of, (or both of), two forms: Raw XY data can be directly displayed by a generic XY data-plotter such as XGRAPH. In contrast, Event-History data must first be processed by TimeLine to produce a plot-file that can be displayed by the data-plotter. The difference is that the former is quick, but is not flexible, while the latter enables much customization in how the event-data can be viewed.

ATL's XGRAPH allows interactive zooming, panning, printing, as well as export of timelines into publishing tools such as FrameMaker, InterLeaf, PowerPoint and MS-Word for annotation and manipulation for incorporation into documents, reports and presentations. This unique capability allows selective editing, shading, and highlighting of data objects, as well as font modifications. See XGRAPH.

The TimeLine utility reads an event history file produced by ATL's performance model libraries for CSIM or VHDL. Event history files contain lines in the following format: 

	/Device_name @ time : event_type_name optional_event_info

For example:

	/sensor2 @ 2005 : Completed data write.
All file lines not beginning with a "/" as the first character are assumed to be comments and are ignored.

The event_type_name can be any string. For the purposes of the TimeLine utility, it consists of two parts:

  1. The event-name, which is the first word in the string,
  2. The event info, which is the rest of the event string.
The TimeLine utility keys off of the event-name, and ignores the rest of the string. Therefore, you should be thoughtful in making the messages you print correspond to event types that you want to plot. For example:

are two distinct event-name types, while 
			Data_Write_Complete addr=234 length=512
			Data_Write_Complete addr=3879 length=32
are the same event type.

There is a graphical front-end for TimeLine, called TLPP-GUI.

To make a time-line:

After you have run a simulation model that produced an event-history file, or ran the SCHEDULER with the -hist option, do the following:

  1. Invocation:

    2. From the GUI or the graphical simulation control-panel, you can invoke the TimeLine utility from the Tools menu, by selecting Tools / Post Analyze Event History.

    TimeLine will prompt you for options from the text window.

    Alternatively, you can invoke TimeLine from the command-line or from a script file by calling timeline with the name of your event history file, as in: 

    	timeline  EventHist.dat

Or, in the case of the SCHEDULER's history file:

	timeline  IdealEvHist.dat

  2. Selections:

    3. 2a. Event Selections:

    TimeLine will scan the event history file and will list to the screen the types of events that were traced. It then asks you to select which type of event that you want to see the time-lines for by asking for the numbers or names of the relevant "on" and "off" events as listed.

    (The "on" event-name would be the "pen-down" event, and the "off" event would be the "pen-up" event (in the sense of a plotter). For instance, a processing time-line could use: 

    	"on" = begin_process, "off" = completed_process.
    For instantaneous events, the "on" and "off" event-names would be the same event, and this would draw a single point on the graph, instead of a line-segment.)

    2b. Annotations:

    It will then ask what type of annotations you want to appear on the time-lines. Your answer will depend on how crowded your time-line is. 
    	For the time-line annotations, use:
		0. No Annotations.
		1. Event Number.
		2. Event Name.
		3. Event Info string.
		4. Full event string.
		5. Hyper-Notes.
    Usually you would choose (3), but if the text is too crowded, you may try shorter versions (1-3), none (0), or hyper-notes (5). With hyper-notes, the annotations will not appear on the graph. The annotation for each a specific trace appears only when clicked.

    2c. Ranges of Time and Device Ordering:

    TimeLine will ask several questions about the range of devices and time-range you want to have plotted. It will also ask about the sequence you want the devices listed on the vertical axis. You can specify a specific ordering.

    It will tell you the span of times that the events in the event file span. And it will ask over what range you would like output for. This allows you to focus on a sub-range.

    Similarly, it will tell you the range of devices and allow you to select a subset if you would like. It also allows you to rearrange their order from top-to-bottom on the graph.

    These features enable you to tailor the time-line graph to show just the resources you are interested in, in an order that is logical to you, and over specific time spans or interest.

    In this way, TimeLine is helpful for data-reduction when analyzing the results from simulations of complex systems over long durations. Reducing the resultant plot-file size speeds-up the interactive response of the ultimate plotter/displayer, while saving file-space.

    2d. Color Selections:

    The TimeLine utility will then ask you what color you want each event to be, if you should want to colorize your graph.

    You may assign colors to specific event types. For each event-type you want colored, enter enough of the event string to uniquely identify that event-type, followed by the color.

    Choose colors from: black, white, red, green, blue, cyan, violet, orange, yellow, pink, light-gray, dark-gray, and fuchsia. 

    
	(example: suppose your timeline data file contains entries such as:

		    /brd3/dev8 @ 345.2: start modem9_3a
		    /brd3/dev8 @ 345.2: done modem9_3a

		Then a valid color entry for any 'modem' event could be:

		    modem blue

		Special thought should be given to your event-type naming
		convention so as to distinguish appropriate events.
	)

    TimeLine will then produce a time-line plot file that shows the event history of devices versus time. The plot-file has a ".tln" suffix, such as: 

    		"DTN.tln".

  3. Display the Graph:

    4. Display the plot-file to the screen using XGRAPH: 
    	xgraph DTN.tln
    A graph window will then appear on your screen. XGRAPH contains several easy to use buttons on its panel for viewing or printing the graph. See XGRAPH for further information, such as producing hardcopy printout without running it interactively.
Figure 1 - Example TimeLine Graph


Hint: It is recommended that a command file be set-up with all
	the anticipated responses to the TimeLine program.
	To do this, you would run the TimeLine program only once
	interactively with the -capture option to capture your responses
	to a log-file, which becomes, in-effect, a command-file.
	Then run the TimeLine postprocessor from your command-file ever after.
	For example, run the TimeLine utility with input directed from that
	file, as in:

		timeline  events.dat  <  tline_log.com

Command-line Options

Other File Options