------------ Description of The WaveFormer(TM) API ----------- The WaveFormer (TWF) application programming interface (API) is a set of functions inside TWF's core code that can be called from within Waveperl scripts to manipulate TWF. The API of TWF is broken up into different function categories (each category is in a separate package). The first package, twf, contains all the global routines. To call these routines, use the package name followed by :: and then the routine name. Below are example calls to routines in the twf package: my $gScrSignals = twf::GetScrSignals(); $signalI = twf::NewSigObjIterator( $gScrSignals ); The other API packages each represent the interface (list of messages that can be sent) to a particular TWF object type. To call these routines, use an object pointer followed by -> and then the routine name. For example, if $sig contains a TSignalPtr, you can set the name of that signal to SIG0 by making the following call: $sig->SetName('SIG0'); Below is a description of each package and the routines in it, starting with twf. Several pac MODULE = twf PACKAGE = twf ############################################################### # This package lists global routines contained in TWF # that can be called from Waveperl scripts. # # Most of the routines in this package create new # objects (the NewXXX functions) or return pointers # to existing objects (the GetXXX functions) in TWF. # Once you obtain a pointer to an object using a # function from one of the above two categories, you # can send messages to the object using the pointer # (in C++ terms, each object type has a set of # member functions that can be called on it). The # functions for each object type are contained in # a perl package (see description of packages that # follow this one). # # Iterators # # Several of the NewXXX functions in this package create # iterator objects. These functions require a list to # iterate over (i.e. traverse). When an iterator is # first created it "points" to the first object on its # list. To get a pointer to the object that the iterator # "points" to, use the iterator's Current() function. # The iterator can be moved up and down its list # using the iterator's PostDec() and PostInc() functions, # respectively (PostDec is not available for all iterators). # To test if an iterator has moved beyond the end of its # list (and therefore points to an invalid object), use the # iterator's NotAtTail() function. After moving the iterator # down the list, always check the iterator to make sure that # it is valid before attempting to use a pointer obtained # from the iterator's new position. Similarly, when moving # an iterator up a list use the NotAtHead() function to know # when you have moved beyond the beginning of a list. # ############################################################### TOptions * GetOptions() #-------------------------------------------------------------- # Returns a pointer to the global options object that # contains user-settable program options. Primary use # in scripts is to set the Base Time Unit (BTU). #-------------------------------------------------------------- TSigObjList * GetScrSignals() #-------------------------------------------------------------- # Returns a pointer to the global sigobj list. This # list contains the sigobjs (signals, clocks, buses) that # are displayed in TWF's diagram window. Primary use # in scripts is to add sigobjs to the list (import script) # or to iterate over existing sigobjs in TWF. #-------------------------------------------------------------- TParmList * GetParms() #-------------------------------------------------------------- # ADV: Returns a pointer to the global parameter list. This # list contains the parameters (delays,setups, etc) that # are displayed in TWF's diagram window. Primary use # in scripts is to add parameters to the list (import script) # or to iterate over existing parameters in TWF. Only # advanced scripts that manipulate timing parameters # will need access to this list. #-------------------------------------------------------------- TParmDataList * GetParmDatas() #-------------------------------------------------------------- # ADV: Returns a pointer to the global parameter data list. This # list contains the parmData objects that are displayed in # TWF's parameter spreadsheet window. Primary use # in scripts is to add parmeters to the list (import script) # or to iterate over existing parmdatas in TWF. Only # advanced scripts that manipulate timing parameters # will need access to this list. #-------------------------------------------------------------- TSelection * GetSelection() #-------------------------------------------------------------- # ADV: Returns a pointer to the current selection in the # diagram window. Only for use in advanced scripts that # need to know/change the currently selected object in TWF #-------------------------------------------------------------- TTime GetLastOutputTime() #-------------------------------------------------------------- # Returns the time of the last event in any signal currently # loaded in TWF (signals on ScrSignals list). Useful in # scripts that don't output clocks as a repetitive waveform # in order to set a cutoff time for the clock waveform. Also # useful when setting the last event time of signals loaded # from a future state format (see FSignal.pm for details). #-------------------------------------------------------------- TPropList * GetPropList() #-------------------------------------------------------------- # Returns a pointer to the project-level object property list #-------------------------------------------------------------- TSigObjIterator * NewSigObjIterator(signals) TSigObjList * signals #-------------------------------------------------------------- # Return an iterator to the list "signals". The most # commonly passed parameter to this function is a pointer # to ScrSignals (the global signal list). #-------------------------------------------------------------- TSigIterator * NewSigIterator() #-------------------------------------------------------------- # ADV: Returns an unattached TSignal iterator #-------------------------------------------------------------- TEventIterator * NewEventIterator() #-------------------------------------------------------------- # ADV: Returns an unattached TEvent iterator #-------------------------------------------------------------- TSigList * NewSigList() #-------------------------------------------------------------- # ADV: Creates a blank list that can hold TSignal objects #-------------------------------------------------------------- TSignal * NewSignal() #-------------------------------------------------------------- # Creates a new signal object. The signal is NOT automatically # placed on ScrSignals list. It is up to your script to # do this if you want to keep the signal around. #-------------------------------------------------------------- TClock * NewClock() #-------------------------------------------------------------- # Creates a new clock object. The clock is NOT automatically # placed on ScrSignals list. It is up to your script to # do this if you want to keep the clock around. #-------------------------------------------------------------- TParmData * NewParmData() #-------------------------------------------------------------- # ADV: Used by scripts that need to create timing parameters #-------------------------------------------------------------- TDelay * NewDelay() #-------------------------------------------------------------- # ADV: Used by scripts that need to create timing parameters #-------------------------------------------------------------- TSetup * NewSetup() #-------------------------------------------------------------- # ADV: Used by scripts that need to create timing parameters #-------------------------------------------------------------- THold * NewHold() #-------------------------------------------------------------- # ADV: Used by scripts that need to create timing parameters #-------------------------------------------------------------- TProp * NewProp() #-------------------------------------------------------------- # Creates a new property object. #-------------------------------------------------------------- #-------------------------------------------------------------- # ADV: The next three routines are used together. Their primary # usage is in export scripts in which all events in a group # of signals are to be output in time order. They are # currently only used in the wait statement VHDL export # script (wvhdl.pl). StartGetNextEdgeAfter() must be # called at the beginning to initialize #-------------------------------------------------------------- int * StartGetNextEdgeAfter(sigList,time) TSigList * sigList TTime time TTime GetNextEdge(sigList,time,ts,nextSigI,nextEventI,isMin) TSigList * sigList TTime time int * ts TSigIterator * nextSigI TEventIterator * nextEventI int &isMin = NO_INIT OUTPUT: ts nextSigI nextEventI isMin void EndGetNextEdge(sigList,ts) TSigList * sigList int * ts void UnkinkAndRepaint() #-------------------------------------------------------------- # ADV: Not useful for import/export scripts #-------------------------------------------------------------- MODULE = twf PACKAGE = TPropPtr ############################################################### # Properties (TProp objects) are used to attach additional # information to objects in TWF. Properties have a name # and a value. Names and values can be any arbitrary string # and can contain spaces (tab characters are not allowed). # Properties are particularly useful for attaching information # to TWF objects for use by your scripts. This allows your # scripts to store new types of information in TWF project # files (*.TIM), even though TWF doesn't necessarily # know how to interpret the information. One example of the # use of properties is to attach VHDL type information to # signals. Inside TWF, properties can be edited using the # Edit Object Properties dialog box. ############################################################### char * TProp::GetName() void TProp::SetName(name) char * name bool TProp::SetNameOrClosest(name) char * name #-------------------------------------------------------------- # If a property of the given name exists, a new, unique name # is automatically generated by concatenating a digit to # the name (i.e. MyPropName becomes MyPropName1). #-------------------------------------------------------------- char * TProp::GetValue() void TProp::SetValue(value) char * value MODULE = twf PACKAGE = TPropListPtr ############################################################### # Contains a list of properties. Many TWF objects have # a TPropList associated with them (e.g. signals, clocks, etc). ############################################################### TProp * TPropList::Find(name) char * name #-------------------------------------------------------------- # Returns a property with the given name. If no property # of that name exists, the return value is set to undefined (in # the Perl sense). #-------------------------------------------------------------- void TPropList::Add(prop) TProp * prop #-------------------------------------------------------------- # Adds a property to the list. If a property with the same # name as prop is already on the list, the value of the # property on the list will be changed to the value of prop # and prop will not be added to the list. #-------------------------------------------------------------- MODULE = twf PACKAGE = TOptionsPtr ############################################################### # There is only one TOptions object in TWF. This is a global # object that contains the programs options available to # users (settable through TWF's Options menu). ############################################################### int TOptions::GetBaseTimeUnit() #-------------------------------------------------------------- # Get base time unit of a project. # See the discussion on base time units in TWF manual. # 0=fs, 1=ps, 2=ns, 3=us, 4=ms #-------------------------------------------------------------- void TOptions::SetBaseTimeUnit(btu) int btu #-------------------------------------------------------------- # Set base time unit of a project. # See the discussion on base time units in TWF manual. # 0=fs, 1=ps, 2=ns, 3=us, 4=ms #-------------------------------------------------------------- MODULE = twf PACKAGE = TSigObjIteratorPtr ############################################################### # Iterates over TSignalObj objects. The Ex functions only # iterate over TSignalObj's marked as exportable (other # TSignalObj's are automatically skipped over). # See discussion of iterators in package twf for more info. ############################################################### TSignalObj * TSigObjIterator::GoNextValidEx() TSignalObj * TSigObjIterator::PostIncEx() TSignalObj * TSigObjIterator::GoNextValid() TSignalObj * TSigObjIterator::PostInc() TSignalObj * TSigObjIterator::Current() int TSigObjIterator::NotAtTail() MODULE = twf PACKAGE = TSigIteratorPtr ############################################################### # Iterates over TSignal objects on a TSignal list. # See discussion of iterators in package twf for more info. ############################################################### TSignal * TSigIterator::PostInc() TSignal * TSigIterator::Current() int TSigIterator::NotAtTail() MODULE = twf PACKAGE = TEventIteratorPtr ############################################################### # Iterates over events on an event list. Each signal has # a time-ordered event list. # See discussion of iterators in package twf for more info. ############################################################### TEvent * TEventIterator::PreInc() TEvent * TEventIterator::PreDec() TEvent * TEventIterator::PostInc() TEvent * TEventIterator::PostDec() TEvent * TEventIterator::Current() int TEventIterator::NotAtTail() int TEventIterator::NotAtHead() MODULE = twf PACKAGE = TEventPtr ############################################################### # An event is a transition in a signal's state at a # particular time. Events have a min time, a max time, # a state, and an extended state (ExState). ############################################################### void TEvent::SetMinTimeIO(minTime) TTime minTime void TEvent::SetMaxTimeIO(maxTime) TTime maxTime void TEvent::SetState(state) TState state TTime TEvent::GetMinTime() TTime TEvent::GetMaxTime() TState TEvent::GetState() char * TEvent::GetExState() void TEvent::SetExState(exState) char * exState #-------------------------------------------------------------- # SetMinTime and SetMaxTime are advanced functions that # should not be used in import scripts. Use # the IO version of these functions instead. These functions # are only intended for use in dynamic scripts (not yet # implemented). #-------------------------------------------------------------- void TEvent::SetMinTime(minTime) TTime minTime void TEvent::SetMaxTime(maxTime) TTime maxTime MODULE = twf PACKAGE = TSignalObjPtr ############################################################### # SignalObj is the ancestor for signals, clocks, & # buses. SignalObjs are abstract, they cannot actually # be created as objects. Instead they represent an interface # that can be called by TSignal, TClock, and TBus # objects. TSignals, TClocks, and TBus objects can be # passed be as parameters to any function that requires a # TSignalObj. ############################################################### bool TSignalObj::IsClock() bool TSignalObj::IsBus() TSignal * TSignalObj::ToSignal() #-------------------------------------------------------------- # Converts a TSignalObj pointer to a TSignal pointer. This # should only be done if you know the object is a TSignal # pointer and not a bus or a clock (you can use IsClock() # and IsBus() to determine this). #-------------------------------------------------------------- TClock * TSignalObj::ToClock() #-------------------------------------------------------------- # Converts a TSignalObj pointer to a TClock pointer. This # should only be done if you know the object is a TClock. #-------------------------------------------------------------- TBus * TSignalObj::ToBus() #-------------------------------------------------------------- # Converts a TSignalObj pointer to a TBus pointer. This # should only be done if you know the object is a TBus. #-------------------------------------------------------------- char * TSignalObj::GetName() #-------------------------------------------------------------- # Gets the name of a signal #-------------------------------------------------------------- void TSignalObj::SetName(name) char * name #-------------------------------------------------------------- # Sets the name of a signal #-------------------------------------------------------------- TEvent * TSignalObj::LastEvent() #-------------------------------------------------------------- # Returns the last event in a signal #-------------------------------------------------------------- TPropList * TSignalObj::GetPropList() MODULE = twf PACKAGE = TSignalPtr ############################################################### # Signals are SignalObjs used to represent a single waveform ############################################################### void TSignal::SetName(name) char * name void TSignal::AddFutureEvent(state,time) TState state TTime time void TSignal::AddEvent(state,time) TState state TTime time void TSignal::AddEvent2(state,minT,maxT,exState=0) TState state TTime minT TTime maxT char * exState TEventIterator * TSignal::NewFirstEventI() #-------------------------------------------------------------- # Returns an iterator to the first event in the signal's # event list. Useful in export scripts. #-------------------------------------------------------------- TPropList * TSignal::GetPropList() MODULE = twf PACKAGE = TClockPtr ############################################################### # Clock objects are a special form of periodic signal. ############################################################### char * TClock::GetName() void TClock::SetName(name) char * name bool TClock::SetNameOrClosest(name) char * name TTime TClock::GetPeriodResult() int TClock::GetDuty() bool TClock::GetInvert() TTime TClock::GetOffset() TPropList * TClock::GetPropList() void TClock::SetPeriodExprStr(formula) char * formula void TClock::SetOffsetExprStr(formula) char * formula void TClock::SetDuty(duty) int duty MODULE = twf PACKAGE = TBusPtr ############################################################### # For advanced scripts only, not currently documented ############################################################### char * TBus::GetName() void TBus::SetName(name) char * name bool TBus::SetNameOrClosest(name) char * name void TBus::AddBusSignals(signals,hide) TSigObjList * signals bool hide void TBus::AddFutureBusEvent(states,time) char * states TTime time TPropList * TBus::GetPropList() MODULE = twf PACKAGE = TSigObjListPtr ############################################################### # List of TSignalObj's. Although scripts can create their # own TSigObjList objects, this interface is mainly used # for manipulating the global ScrSignals object (see # twf::GetScrSignals() for more info on ScrSignals). ############################################################### void TSigObjList::SetVisibleSignals(time) TTime time #-------------------------------------------------------------- # ADV: #-------------------------------------------------------------- void TSigObjList::Add(signal) TSignalObj * signal #-------------------------------------------------------------- # Add a TSignalObj to the list. #-------------------------------------------------------------- TSignalObj * TSigObjList::GetSignal(name) char * name #-------------------------------------------------------------- # Returns a TSignalObj with the given name on the list. # If no signal of the given name can be found, the # return value is set to undefined. NOTE: This function # will not work properly if the signal's name is set or # changed after it was added to the list. #-------------------------------------------------------------- MODULE = twf PACKAGE = TSigListPtr ############################################################### # For advanced scripts only, not currently documented ############################################################### void TSigList::addAtTail(signal) TSignal * signal MODULE = twf PACKAGE = TSelectionPtr ############################################################### # For advanced scripts only, not currently documented ############################################################### int TSelection::GetValidSelType() TEventIterator * TSelection::GetEventI() TSigObjIterator * TSelection::GetSignalI() TSigObjList * TSelection::GetSignalList() MODULE = twf PACKAGE = TParmDataPtr ############################################################### # For advanced scripts only, not currently documented ############################################################### char * TParmData::GetName() void TParmData::SetName(name) char * name TPropList * TParmData::GetPropList() void TParmData::SetMinExprStr(formula) char * formula void TParmData::SetMaxExprStr(formula) char * formula MODULE = twf PACKAGE = TParmPtr void TParm::SetMinExprStr(formula) char * formula void TParm::SetMaxExprStr(formula) char * formula TTime TParm::GetMinResult() TTime TParm::GetMaxResult() char TParm::GetMinError() char TParm::GetMaxError() TSmartEvent * TParm::GetStartingEvent() TSmartEvent * TParm::GetEndingEvent() TPropList * TParm::GetPropList() void TParm::SetSource(signame,eventNum) char * signame long eventNum void TParm::SetTarget(signame,eventNum) char * signame long eventNum void TParm::SetParmData(parmData) TParmData * parmData MODULE = twf PACKAGE = TParmDataListPtr ############################################################### # For advanced scripts only, not currently documented ############################################################### void TParmDataList::Add(parmData) TParmData * parmData MODULE = twf PACKAGE = TParmListPtr ############################################################### # For advanced scripts only, not currently documented ############################################################### void TParmList::Add(parm) TParm * parm MODULE = twf PACKAGE = TParmIteratorPtr ############################################################### # For advanced scripts only, not currently documented ############################################################### TParm * TParmIterator::Current() TParm * TParmIterator::PreInc() TParm * TParmIterator::PostInc() int TParmIterator::NotAtTail() MODULE = twf PACKAGE = TSmartEventPtr ############################################################### # For advanced scripts only, not currently documented ############################################################### TSigObjIterator * TSmartEvent::GetSignalI() TEventIterator * TSmartEvent::GetEventI()