Functions
def	include (fname)
	include python code in a test script More...

def	test_file ()
	get the test file name with path More...

def	test_dir ()
	get the test directory (relative to the current directory) More...

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)
	Send the QS Global Filter to the Target. More...

def	loc_filter (*args)
	Send the Local Filter to the Target. More...

def	ao_filter (obj_id)
	Updates the Local Filter for a given AO 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	expect_run ()
	defines expectation for calling QF_run()/QF::run() 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 in 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 = 693
	current version of the Python QUTest interface More...

Function Documentation

◆ include()

def qutest_dsl.include ( fname )

include python code in a test script

Description: This command includes python code in a specified file into the test script. The included file can contain any code that you would put into test scripts, such as

Parameters

[in] fname name of the file to include. May contain a path relative to the test script.

Usage: include("test_include.pyi") # file in the same directory as the script

~ ~ ~

include("../my_include/test_include.pyi") # relative directory

qutest_dsl.include
def include(fname)
include python code in a test script
Definition: qutest_dsl.py:79

Example
file to be included:

# file test_inc.pyi (include file)
 
# common on_reset() callback
def on_reset():
    expect_pause()
    glb_filter(GRP_ALL)
    continue_test()
 
def my_test_snippet():
    query_curr(OBJ_SM)
    expect("@timestamp Query-SM Obj=Blinky::inst,State=Blinky::off")

test script calling include():

# file test_blinky.py (actual test script)
 
include("test_inc.pyi") #<--- include common code
 
test("my test xyz")
my_test_snippet()
...

Definition at line 79 of file qutest_dsl.py.

◆ test_file()

def qutest_dsl.test_file ( )

get the test file name with path

Description: This command returns a string containing the file name of the currently executed test script ("test group").

Usage: file_name = test_file()

qutest_dsl.test_file
def test_file()
get the test file name with path
Definition: qutest_dsl.py:90

Definition at line 90 of file qutest_dsl.py.

◆ test_dir()

def qutest_dsl.test_dir ( )

get the test directory (relative to the current directory)

Description: This command returns a string containing the directory name of the currently executed test script ("test group").

Usage: dir_name = test_dir()

qutest_dsl.test_dir
def test_dir()
get the test directory (relative to the current directory)
Definition: qutest_dsl.py:101

Definition at line 101 of file qutest_dsl.py.

◆ 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]	title	title of the test
[in]	opt	options {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 120 of file qutest_dsl.py.

◆ skip()

def qutest_dsl.skip ( nTests = 9999 )

skip the tests following this command.

Description

Parameters

[in] nTests number 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")

~ ~ ~

qutest_dsl.skip
def skip(nTests=9999)
skip the tests following this command.
Definition: qutest_dsl.py:146

See also: test()

Definition at line 146 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] match the 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 174 of file qutest_dsl.py.

◆ glb_filter()

def qutest_dsl.glb_filter ( * args )

Send the QS Global Filter to the Target.

Description: This command sends the complete QS Global Filter to the Target. Any existing Global Filter setting inside the Target will be overwritten.

Parameters

[in] args list of Record-Type groups or individual Record-Types to set or clear. A given filter-group or an individual filter is set when it is positive, and cleared with it is preceded with the minus (-) sign.

The filter list can contain the following:

GRP_ALL # all Record-Types
GRP_SM # State Machine Record-Types
GRP_AO # Active Object Record-Types
GRP_MP # Memory Pool Record-Types
GRP_EQ # Event Queue Record-Types
GRP_TE # Time Events Record-Types
GRP_QF # Framework Record-Types (e.g., post/publish/..)
GRP_SC # Scheduler Record-Types (e.g., scheduler lock/unlock)
GRP_U0 # User group 0 (Record-Types 100-104)
GRP_U1 # User group 1 (Record-Types 105-109)
GRP_U2 # User group 2 (Record-Types 110-114)
GRP_U3 # User group 3 (Record-Types 115-119)
GRP_U4 # User group 0 (Record-Types 120-124)
GRP_UA # All user records (Record-Types 100-124)
<num>  # Specific QS trace Record-Type in the range 0..127

Usage: glb_filter() # clears all global filters

glb_filter(GRP_ALL) # sets all global filters

glb_filter(GRP_SM, GRP_AO) # sets SM-group and AO-group

glb_filter(GRP_ALL, -GRP_SC) # sets all global filters, but clears the SC-group

glb_filter(GRP_QF, "-QS_QF_TICK") # sets the QF-group, but clears the QS_QF_TICK filter

glb_filter(GRP_AO, 78)` # sets the AO-group and the QS record 78

See also: loc_filter()

Definition at line 212 of file qutest_dsl.py.

◆ loc_filter()

def qutest_dsl.loc_filter ( * args )

Send the Local Filter to the Target.

Description: This command sends the complete QS Local Filter to the Target. Any existing Local Filter setting inside the Target will be overwritten.

Parameters

[in]

args

list of QS-ID groups or individual QS-IDs to set or clear. A given filter-group or an individual filter is set when it is positive, and cleared with it is preceded with the minus (-) sign.
This parameter can take one of the following values:

IDS_ALL # all QS-IDs
IDS_AO # Active Object QS-IDs (1..64)
IDS_EP # Event Pool QS-IDs (65-80)
IDS_EQ # Event Queue QS-IDs (81-96)
IDS_AP # Application-Specific QS-IDs (97-127)

Usage: loc_filter(IDS_ALL) # enables all QS-IDs

loc_filter(-IDS_ALL) # disables all QS-IDs

loc_filter(IDS_AO) # enables all active objcts

loc_filter(IDS_AO, -6) # enables all active objcts,

# but disables AO with priority 6

loc_filter(IDS_AO, IDS_EP) # enables all active objects and event pools

loc_filter(IDS_AP) # enables all app-specific QS_IDs

qutest_dsl.loc_filter
def loc_filter(*args)
Send the Local Filter to the Target.
Definition: qutest_dsl.py:239

See also: glb_filter()

Definition at line 239 of file qutest_dsl.py.

◆ ao_filter()

def qutest_dsl.ao_filter ( obj_id )

Updates the Local Filter for a given AO in the Target.

Description: This command sets or clears the QS Local Filter corresponding to the given AO in the Target. Unlike loc_filter(), this facility changes only the QS-ID (AO's priority) of the given AO in the Target. All other Local Filters will be left unchanged.

Parameters

[in] obj_id active object to set/clear the local filter for in the Target
This parameter can be either a string (name of the AO) or the AO's priority. Also, it can be either positive (to set) or negative (to clear) the QS local filter.

Usage: ao_filter(6) # enables AO of priority 6 in the Target

ao_filter(-6) # disables AO of priority 6 in the Target

ao_filter("AO_Table") # enables "AO_Table" in the Target

ao_filter("-AO_Table") # disables "AO_Table" in the Target

qutest_dsl.ao_filter
def ao_filter(obj_id)
Updates the Local Filter for a given AO in the Target.
Definition: qutest_dsl.py:259

See also: loc_filter()

Definition at line 259 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_kind	Kind 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_id	Name or addres of the object

Usage: current_obj(OBJ_SM, "my_state_machine")

current_obj(OBJ_MP, "EvtPool1")

current_obj(OBJ_AP, "my_object")

current_obj(OBJ_SM_AO, "Philo[2]")

current_obj(OBJ_AP, 0x20001234)

qutest_dsl.current_obj
def current_obj(obj_kind, obj_id)
Set the Current-Object in the Target.
Definition: qutest_dsl.py:289

See also

Definition at line 289 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_kind

Kind of object to query
This parameter can take one of the following values:

OBJ_SM # State Machine object@n
OBJ_AO # Active Object object@n
OBJ_MP # Memory Pool object@n
OBJ_EQ # Event Queue object@n
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 326 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:

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.
The linked-list of all armed Time Events is updated.

Parameters

[in] tick_rate the tick rate (0..QF_MAX_TICK_RATE)

Usage: # tests...

test("tick")

glb_filter(GRP_ALL)

current_obj(OBJ_TE, "l_philo<2>.timeEvt")

tick() # <====

expect("...")

...

qutest_dsl.tick
def tick(tick_rate=0)
trigger system clock tick in the Target
Definition: qutest_dsl.py:345

See also: current_obj()

Definition at line 345 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: def on_reset():

expect_pause() # <====

glb_filter(GRP_UA)

current_obj(OBJ_SM_AO, "AO_MyAO")

continue_test()

expect_run()

qutest_dsl.expect_run
def expect_run()
defines expectation for calling QF_run()/QF::run()
Definition: qutest_dsl.py:381

See also: continue_test()

Definition at line 363 of file qutest_dsl.py.

◆ expect_run()

def qutest_dsl.expect_run ( )

defines expectation for calling QF_run()/QF::run()

Description: This is a special expectation for the target calling the QF_run()/QF::run() function.

Note: This expectation must be placed at the right place in the on_reset() callback.

Usage: def on_reset():

expect_pause()

glb_filter(GRP_UA)

current_obj(OBJ_SM_AO, "AO_MyAO")

continue_test()

expect_run() # <====

See also: on_reset()

Definition at line 381 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: def on_reset():

expect_pause()

glb_filter(GRP_UA)

current_obj(OBJ_SM_AO, "AO_MyAO")

continue_test() # <====

expect_run()

See also: expect_pause()

Definition at line 394 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]	cmdId	the 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]	param1	the "param1" argument to QS_onCommand() (optional)
[in]	param2	the "param2" argument to QS_onCommand() (optional)
[in]	param3	the "param3" argument to QS_onCommand() (optional)

Usage: test("...")

...

command(0, 78) # <===

expect("...")

...

qutest_dsl.command
def command(cmdId, param1=0, param2=0, param3=0)
executes a given command in the Target
Definition: qutest_dsl.py:411

Definition at line 411 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]	signal	the event signal of the "initialization event"
[in]	params	the parameters of the "initialization event"

Usage: init()

init("MY_SIG")

init("MY_SIG", pack("<B", 2))

qutest_dsl.pack
def pack(format, v1, v2)
packs data into binary string to be sent to QSPY.
Definition: qutest_dsl.py:584

qutest_dsl.init
def init(signal=0, params=None)
take the top-most initial transition in the current SM object in the Target
Definition: qutest_dsl.py:430

Definition at line 430 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]	signal	the event signal of the event to be dispatched
[in]	params	the parameters of the event to be dispatched

Usage: dispatch("MY_SIG")

dispatch("MY_SIG", pack("<B", 2))

qutest_dsl.dispatch
def dispatch(signal, params=None)
dispatch a given event in the current SM object in the Target
Definition: qutest_dsl.py:447

Definition at line 447 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]	signal	the event signal of the event to be posted
[in]	params	the parameters of the event to be posted

Usage: `post("MY_SIG")

`post("MY_SIG", pack("<B", 2))

qutest_dsl.post
def post(signal, params=None)
post a given event to the current AO object in the Target
Definition: qutest_dsl.py:464

Definition at line 464 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]	signal	the event signal of the event to be posted
[in]	params	the parameters of the event to be posted

Usage: publish("MY_SIG")

publish("MY_SIG", pack("<B", 2))

qutest_dsl.publish
def publish(signal, params=None)
publish a given event to subscribers in the Target
Definition: qutest_dsl.py:480

Definition at line 480 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]	func	the name or raw address of a function
[in]	data	the 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)

qutest_dsl.probe
def probe(func, data)
sends a Test-Probe to the Target
Definition: qutest_dsl.py:505

Definition at line 505 of file qutest_dsl.py.

◆ peek()

def qutest_dsl.peek	(	offset,
		size,
		num
	)

peeks data in the Target

Description: This command peeks data at the given offset from the start address of the current_obj() inside the Target.

Parameters

[in]	offset	offset [in bytes] from the start of the current_obj()
[in]	size	size of the data items (1, 2, or 4)
[in]	num	number of data items to peek

Usage: peek(0, 1, 10)

peek(8, 2, 4)

peek(4, 4, 2)

qutest_dsl.peek
def peek(offset, size, num)
peeks data in the Target
Definition: qutest_dsl.py:524

Definition at line 524 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]	offset	offset [in bytes] from the start of the current_obj()
[in]	size	size of the data items (1, 2, or 4)
[in]	data	binary data to send

Usage: poke(4,4,pack("<II",0xB4C4D4E4,0xB5C5D5E5))

poke(0, 1, bytearray("dec=%d\0", "ascii"))

poke(0, 1, bytes("Hello World!\0","ascii"))

qutest_dsl.poke
def poke(offset, size, data)
pokes data into the Target.
Definition: qutest_dsl.py:542

Definition at line 542 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]	offset	offset [in bytes] from the start of the current_obj()
[in]	size	size of the data item (1, 2, or 4)
[in]	num	number of data items to fill
[in]	item	data item to fill with

Usage: fill(0, 1, 100, 0x1A)

fill(0, 2, 50, 0x2A2B)

fill(0, 4, 25, 0x4A4B4C4D)

qutest_dsl.fill
def fill(offset, size, num, item=0)
fills data into the Target.
Definition: qutest_dsl.py:561

Definition at line 561 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]	format	string
[in]	v1	one or more data elements requried by format
[in]	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 584 of file qutest_dsl.py.

◆ on_reset()

def qutest_dsl.on_reset ( )

callback function invoked after each Target reset

Definition at line 588 of file qutest_dsl.py.

◆ on_setup()

def qutest_dsl.on_setup ( )

callback function invoked at the beginning of each test

Definition at line 592 of file qutest_dsl.py.

◆ on_teardown()

def qutest_dsl.on_teardown ( )

callback function invoked at the end of each test

Definition at line 596 of file qutest_dsl.py.

Variable Documentation

◆ VERSION

int VERSION = 693

current version of the Python QUTest interface

Definition at line 54 of file qutest_dsl.py.

Functions

Variables

Function Documentation

◆ include()

◆ test_file()

◆ test_dir()

◆ test()

◆ skip()

◆ expect()

◆ glb_filter()

◆ loc_filter()

◆ ao_filter()

◆ current_obj()

◆ query_curr()

◆ tick()

◆ expect_pause()

◆ expect_run()

◆ continue_test()

◆ command()

◆ init()

◆ dispatch()

◆ post()

◆ publish()

◆ probe()

◆ peek()

◆ poke()

◆ fill()

◆ pack()

◆ on_reset()

◆ on_setup()

◆ on_teardown()

Variable Documentation

◆ VERSION