QTools  6.6.0
qutest_dsl Namespace Reference

Functions

def test (title, opt=0)
 start a new test More...
 
def skip (nTests=9999)
 skip the tests following this command. More...
 
def expect (match)
 defines an expectation for the current test More...
 
def glb_filter (*args)
 Set the Global-Filter in the Target. More...
 
def loc_filter (obj_kind, obj_id)
 Set the Local Filter in the Target. More...
 
def current_obj (obj_kind, obj_id)
 Set the Current-Object in the Target. More...
 
def query_curr (obj_kind)
 query the current object in the Target More...
 
def tick (tick_rate=0)
 trigger system clock tick in the Target More...
 
def expect_pause ()
 defines expectation for a Test Pause More...
 
def continue_test ()
 sends the CONTINUE packet to the Target to continue a test More...
 
def command (cmdId, param1=0, param2=0, param3=0)
 executes a given command in the Target More...
 
def init (signal=0, params=None)
 take the top-most initial transition in the current SM object in the Target More...
 
def dispatch (signal, params=None)
 dispatch a given event in the current SM object in the Target More...
 
def post (signal, params=None)
 post a given event to the current AO object in the Target More...
 
def publish (signal, params=None)
 publish a given event to subscribers in the Target More...
 
def probe (func, data)
 sends a Test-Probe to the Target More...
 
def peek (offset, size, num)
 peeks data into the Target More...
 
def poke (offset, size, data)
 pokes data into the Target. More...
 
def fill (offset, size, num, item=0)
 fills data into the Target. More...
 
def pack (format, v1, v2)
 packs data into binary string to be sent to QSPY. More...
 
def on_reset ()
 callback function invoked after each Target reset More...
 
def on_setup ()
 callback function invoked at the beginning of each test More...
 
def on_teardown ()
 callback function invoked at the end of each test More...
 

Variables

int VERSION = 637
 current version of the Python QUTest interface More...
 

Function Documentation

◆ test()

def qutest_dsl.test (   title,
  opt = 0 
)

start a new test

Description
This command starts a new test and gives it a name.
Parameters
[in]titletitle of the test
[in]optoptions {0=default, NORESET}
Usage
test("my first test") # test with title and with full target reset
~ ~ ~
test("my second test", NORESET) # test without target reset
~ ~ ~
See also
skip()

Definition at line 33 of file qutest_dsl.py.

◆ skip()

def qutest_dsl.skip (   nTests = 9999)

skip the tests following this command.

Description
Parameters
[in]nTestsnumber of tests to skip (default-all remaining tests) e.g., skip(1) will skip one test following this command.
Note
The skipped tests are not executed, but they are checked for syntax errors, such as commands and parameters coded in the skipped tests.
Usage
test("my first test")
~ ~ ~
skip(1) # skip one subsequent test
test("my second test")
~ ~ ~
skip() # skip all subsequent tests
test("my second test")
~ ~ ~
~ ~ ~
See also
test()

Definition at line 58 of file qutest_dsl.py.

◆ expect()

def qutest_dsl.expect (   match)

defines an expectation for the current test

Description
This command defines a new expecation for the textual output produced by QSPY.
Parameters
[in]matchthe expected match for the QSPY output The match string can contain special characters, such as: *, ? and [chars], which are matched according to the Python command fnmatch.fnmatchcase()
Note
The match string can be the printf-style %-subsitution string (compatible with Python 2 and Python 3), or the new "f-string" (compatible only with Python 3).
The special string "@timestamp" (or "%timestamp") at the beginning of the match parameter will be automatically replaced with the current numerical value of the test sequence-counter.
Usage
expect("0000000001 USER+000 FindFunction_WhichIsBroken 0 78")
expect("@timestamp Trg-Done QS_RX_COMMAND")
expect(" Tick<0> Ctr=*")
expect("@timestamp IO_CALL IO_Write %d %d" %(CommandReg, ProgramCmd))

Definition at line 89 of file qutest_dsl.py.

◆ glb_filter()

def qutest_dsl.glb_filter ( args)

Set the Global-Filter in the Target.

Description
This command sets the QS globar filters in the Target.
Parameters
[in]argslist of global filter groups to set in the Target
The filter list can contain the following filters:
GRP_ON – all filters on
GRP_SM – State Machine filters
GRP_AO – Active Object filters
GRP_MP – Memory Pool filters
GRP_EQ – Event Queue filters
GRP_TE – Time Events filters
GRP_QF – Framework filters (e.g., post/publish/..)
GRP_SC – Scheduler filters (e.g., schduler lock/unlock)
GRP_U0 – User group 0 (70-79)
GRP_U1 – User group 1 (80-89)
GRP_U2 – User group 2 (90-99)
GRP_U3 – User group 3 (100-109)
GRP_U4 – User group 0 (110-124)
GRP_UA – All user records (70-124)
<num> – Specific QS trace record number in the range 0..127
Usage
glb_filter() – disables all global filters
glb_filter(GRP_ON) - enables all global filters
glb_filter(GRP_SM_AO)- enables only State Machines and Active Objects
glb_filter(GRP_AO, GRP_TE) - enables Active Objects and Time Events
glb_filter(GRP_AO, 78) - enables Active Objects and the QS record 78
See also
loc_filter()

Definition at line 125 of file qutest_dsl.py.

◆ loc_filter()

def qutest_dsl.loc_filter (   obj_kind,
  obj_id 
)

Set the Local Filter in the Target.

Description
This command sets the QS local filters in the Target.
Parameters
[in]obj_kindKind of object to filter
This parameter can take one of the following values:
OBJ_SM – State Machine object
OBJ_AO – Active Object object
OBJ_MP – Memory Pool object
OBJ_EQ – Event Queue object
OBJ_TE – Time Event object
OBJ_AP – Application-Specific object
OBJ_SM_AO – Both, State Machine and Active Object
[in]obj_idName or addres of the object
Usage
loc_filter(OBJ_SM, "my_state_machine")
loc_filter(OBJ_MP, "EvtPool0")
loc_filter(OBJ_AP, "my_object")
loc_filter(OBJ_SM_AO, "Philo<2>")
loc_filter(OBJ_AP, 0x20001234)
See also
glb_filter()

Definition at line 155 of file qutest_dsl.py.

◆ current_obj()

def qutest_dsl.current_obj (   obj_kind,
  obj_id 
)

Set the Current-Object in the Target.

Description
This command sets the "current object" in the Target.
Parameters
[in]obj_kindKind of object to set
This parameter can take one of the following values:
OBJ_SM – State Machine object
OBJ_AO – Active Object object
OBJ_MP – Memory Pool object
OBJ_EQ – Event Queue object
OBJ_TE – Time Event object
OBJ_AP – Application-Specific object
OBJ_SM_AO – Both, State Machine and Active Object
[in]obj_idName or addres of the object
Usage
current_obj(OBJ_SM, "my_state_machine")
current_obj(OBJ_MP, "EvtPool0")
current_obj(OBJ_AP, "my_object")
current_obj(OBJ_SM_AO, "Philo<2>")
current_obj(OBJ_AP, 0x20001234)
See also
query_curr()
init()
dispatch()

Definition at line 187 of file qutest_dsl.py.

◆ query_curr()

def qutest_dsl.query_curr (   obj_kind)

query the current object in the Target

Description
This command queries the current object in the Target.
Parameters
[in]obj_kindKind of object to query
This parameter can take one of the following values:
OBJ_SM – State Machine object
OBJ_AO – Active Object object
OBJ_MP – Memory Pool object
OBJ_EQ – Event Queue object
OBJ_TE – Time Event object
Usage
The queries for various objects generate the following QS trace records from the Target:
query_curr(OBJ_SM):
"@timestamp Query-SM Obj=<obj-name>,State=<state-name>"
query_curr(OBJ_AO):
"@timestamp Query-AO Obj=<obj-name>,Queue<Free=<n>,Min=<m>>"
query_curr(OBJ_EQ):
"@timestamp Query-EQ Obj=<obj-name>,Queue<Free=<n>,Min=<m>>"
query_curr(OBJ_MP):
"@timestamp Query-MP Obj=<obj-name>,Free=<n>,Min=<m>"
query_curr(OBJ_TE):
"@timestamp Query-TE Obj=<obj-name>,Rate=<r>,Sig=<s>,Tim=<n>,Int=<m>,Flags=<f>"
See also
current_obj()

Definition at line 220 of file qutest_dsl.py.

◆ tick()

def qutest_dsl.tick (   tick_rate = 0)

trigger system clock tick in the Target

Description
This command triggers the following actions in the Target:
  1. If the current TE object is defined and the TE is armed, the TE is disarmed (if one-shot) and then posted to the recipient AO.
  2. The linked-list of all armed Time Events is updated.
Parameters
[in]tick_ratethe tick rate (0..QF_MAX_TICK_RATE)
Usage
tick()
tick(1)
See also
current_obj()

Definition at line 240 of file qutest_dsl.py.

◆ expect_pause()

def qutest_dsl.expect_pause ( )

defines expectation for a Test Pause

Description
This is a special expectation that must match the macro QS_TEST_PAUSE() inside the test fixture.
Note
If QS_TEST_PAUSE() is called before QF_run(), the expect_pause() expectation must be placed in the on_reset() callback.
Usage
expect_pause()
glb_filter(GRP_AO)
continue_test()
See also
continue_test()

Definition at line 260 of file qutest_dsl.py.

◆ continue_test()

def qutest_dsl.continue_test ( )

sends the CONTINUE packet to the Target to continue a test

Description
This command continues the test after QS_TEST_PAUSE().
Usage
expect_pause()
glb_filter(GRP_AO)
continue_test()
See also
expect_pause()

Definition at line 275 of file qutest_dsl.py.

◆ command()

def qutest_dsl.command (   cmdId,
  param1 = 0,
  param2 = 0,
  param3 = 0 
)

executes a given command in the Target

Description
This command causes execution of the callback QS_onCommand() inside the the Target system.
Parameters
[in]cmdIdthe command-id first argument to QS_onCommand()
NOTE: this could be either the raw number or a name that is delivered by QS_USR_DICTIONARY() from the Target
[in]param1the 'param1' argument to QS_onCommand() (optional)
[in]param2the 'param2' argument to QS_onCommand() (optional)
[in]param3the 'param3' argument to QS_onCommand() (optional)
Usage
command(0)
command(3, 0x123, 23)
command("MY_COMMAND", 0x123, 23, 34)

Definition at line 294 of file qutest_dsl.py.

◆ init()

def qutest_dsl.init (   signal = 0,
  params = None 
)

take the top-most initial transition in the current SM object in the Target

Description
This command takes the top-most initial transition in the current SM object in the Target.
Parameters
[in]signalthe event signal of the "initialization event"
[in]paramsthe parameters of the "initialization event"
Usage
init()
init("MY_SIG")
init("MY_SIG", pack("<B", 2))

Definition at line 311 of file qutest_dsl.py.

◆ dispatch()

def qutest_dsl.dispatch (   signal,
  params = None 
)

dispatch a given event in the current SM object in the Target

Description
This command dispatches a given event in the current SM object in the Target.
Parameters
[in]signalthe event signal of the event to be dispatched
[in]paramsthe parameters of the event to be dispatched
Usage
dispatch("MY_SIG")
dispatch("MY_SIG", pack("<B", 2))

Definition at line 326 of file qutest_dsl.py.

◆ post()

def qutest_dsl.post (   signal,
  params = None 
)

post a given event to the current AO object in the Target

Description
This command posts a given event to the current AO object in the Target.
Parameters
[in]signalthe event signal of the event to be posted
[in]paramsthe parameters of the event to be posted
Usage
post("MY_SIG")
post("MY_SIG", pack("<B", 2))

Definition at line 341 of file qutest_dsl.py.

◆ publish()

def qutest_dsl.publish (   signal,
  params = None 
)

publish a given event to subscribers in the Target

Description
This command publishes a given event in the Target.
Parameters
[in]signalthe event signal of the event to be posted
[in]paramsthe parameters of the event to be posted
Usage
publish("MY_SIG")
publish("MY_SIG", pack("<B", 2))

Definition at line 355 of file qutest_dsl.py.

◆ probe()

def qutest_dsl.probe (   func,
  data 
)

sends a Test-Probe to the Target

Description
This command sends the Test Probe data to the Target. The Target collects these Test Probes preserving the order in which they were sent. Subsequently, whenever a given API is called inside the Target, it can obtain the Test-Probe by means of the QS_TEST_PROBE_DEF() macro. The QS_TEST_PROBE_DEF() macro returns the Test-Probes in the same order as they were received to the Target. If there are no more Test- Probes for a given API, the Test-Probe is initialized to zero.
Parameters
[in]functhe name or raw address of a function
[in]datathe data (uint32_t) for the Test-Probe
Note
All Test-Probes are cleared when the Target resets and also upon the start of a new test, even if this test does not reset the Target (NORESET tests).
Usage
probe("myFunction", 123)

Definition at line 378 of file qutest_dsl.py.

◆ peek()

def qutest_dsl.peek (   offset,
  size,
  num 
)

peeks data into the Target

Description
This command peeks data at the given offset from the start address of the current_obj() inside the Target.
Parameters
[in]offsetoffset [in bytes] from the start of the current_obj()
[in]sizesize of the data items (1, 2, or 4)
[in]numnumber of data items to peek
Usage
peek(0, 1, 10)
peek(8, 2, 4)
peek(4, 4, 2)

Definition at line 395 of file qutest_dsl.py.

◆ poke()

def qutest_dsl.poke (   offset,
  size,
  data 
)

pokes data into the Target.

Description
This command pokes provided data at the given offset from the start address of the current AP object inside the Target.
Parameters
[in]offsetoffset [in bytes] from the start of the current_obj()
[in]databinary data to send
[in]sizesize of the data items (1, 2, or 4)
Usage
‘poke(4,4,pack(’<II',0xB4C4D4E4,0xB5C5D5E5))@n poke(0, 1, bytearray("dec=%d\0", "ascii"))`

Definition at line 410 of file qutest_dsl.py.

◆ fill()

def qutest_dsl.fill (   offset,
  size,
  num,
  item = 0 
)

fills data into the Target.

Description
This command fills provided data at the given offset from the start address of the current_obj() inside the Target.
Parameters
[in]offsetoffset [in bytes] from the start of the current_obj()
[in]sizesize of the data item (1, 2, or 4)
[in]numnumber of data items to fill
[in]itemdata item to fill with
Usage
fill(0, 1, 100, 0x1A)
fill(0, 2, 50, 0x2A2B)
fill(0, 4, 25, 0x4A4B4C4D)

Definition at line 427 of file qutest_dsl.py.

◆ pack()

def qutest_dsl.pack (   format,
  v1,
  v2 
)

packs data into binary string to be sent to QSPY.

Description
This command corresponds to Python struct.pack(). It returns a bytes object containing the values v1, v2,... packed according to the format string format. The arguments must match the values required by the format exactly. The pack() command is typically used inside other QUTest commands to pack the binary event parameters or binary data for poke() and fill().
Parameters
[in]formatstring
[in]v1,v2...one or more data elements requried by format
Usage

dispatch("MY_SIG", pack("<B", 2))
poke(2, 2, pack("<HH", 0xB2C2, 0xD2E2))

Definition at line 448 of file qutest_dsl.py.

◆ on_reset()

def qutest_dsl.on_reset ( )

callback function invoked after each Target reset

Definition at line 452 of file qutest_dsl.py.

◆ on_setup()

def qutest_dsl.on_setup ( )

callback function invoked at the beginning of each test

Definition at line 456 of file qutest_dsl.py.

◆ on_teardown()

def qutest_dsl.on_teardown ( )

callback function invoked at the end of each test

Definition at line 460 of file qutest_dsl.py.

Variable Documentation

◆ VERSION

int VERSION = 637

current version of the Python QUTest interface

Definition at line 16 of file qutest_dsl.py.