Studio:AutoScript Functions

 

Overview

This section describes basic functionality for ascript function processing. For ease of understanding, this section describes overall concepts and then describes the precise functionality that STRIDE provides.

Function Interception

A powerful feature of STRIDE is the ability to intercept function calls. While this capability is known to most seasoned STRIDE users, it is not necessarily as known to STRIDE newbies. Comprehension of general STRIDE terms requires a small amount of knowledge as to what function interception means.

STRIDE is generally used to debug remote hardware (e.g. a cellphone) from a Windows computer running STRIDE. The remote hardware is refered to as the target. The Windows computer is refered to as the host. Scripts are used to communicate with STRIDE to pass data between the host and target.

While there are several models for how to connect to host and target and to transfer data inbetween them, this wiki page is only to describe how perform this connectability via ascript. The following issues have to be resolved to communicate between host and target using two scripts:

• Which script owns a particular function (e.g. a script on the target)?
• Which script desires access to the function (e.g. a script on the host)?
• What is types of data (i.e. parameters, pointers, and return value payloads) will be passed between them?
• How will the owner and the user communicate to pass payloads?

The how of questions will be answered in the following sections. The why will depend on a particular testing solution to each distinct type of hardware being developed.

Ownership vs. Usage

STRIDE has the concept of a Function Owner and a Function User. In general STRIDE usage the Owner and User imply the owner of a function on the target and the user of a function on the host.

Function User

A Function User may be any script that is not registered as the function owner or function override owner. The Function User may be access via the message as ascript.Functions.Item.User.

Function Owner

The Function Owner is the script that has successfully registered itself as the owner of the function (by calling the Register method). A function will only have one registered owner. Calls to register a second owner will result in an exception will be thrown. Ownership can be surrendered by calling the Unregister method (or by exiting the script that registered ownership). The Function Owner may be accessed via ascript.Functions.Item.Owner.

Override Owner

The Function Override Owner of a function is the script that successfully registered as the override owner (using the RegisterOverride method). An override owner is used to bypass the registered owner. If a function has an override owner registered, function calls are made to the registered override owner and not the registered owner. This allows the ability to code scripting with the registered owner, but to bypass the registered owner for certain processing for a variety of reasons (i.e. some code not implemented for the registered owner, some exception cases, etc.). It is legal for a script to declare both forms of function ownership. Thus, the same script may be both registered owner and the registered override owner.

Function Payloads

Payloads are Dynamic Objects containing data related to a function's parameters, a function's return value, or pointer values passed for a function. These payloads are defined as properties for both a Function User and a Function Owner. By being part of both user and owner allows their values can be checked for validity in the event that a call did not pass correct data from user to owner (or visa-versa).

OutPointers

This payload exists only if a function's payload has at least one pointer that is qualified as OUT or INOUT. In other words, the function returns an object via a pointer through its parameter list.

If this property exists, its members are comprised of all the top-level parameters that are either OUT or INOUT pointers. This can also exist for structured types (structs or unions) that contain members that are OUT or INOUT. It can also exist if a structured type contains a nested structured type that contains members that are OUT or INOUT. In the case of structured type objects appearing in the OutPointers hierarchy, only members that are qualified as OUT or INOUT (or that themselves contain these qualified types) are available.

Upon a function's return, the OutPointers property of the Function User object (ascript.Functions.Item().User.OutPointers) will reflect (contain) the values set by the Function Owner object (ascript.Functions.Item().Owner.OutPointers).

ParameterList

A ParameterList payload only exists if the given Function Owner contains one or more parameters. This payload will contain the values of all ParameterList fields at the time the function User called the Owner (on the user side before a call). The ParameterList payload is a Dynamic Object. This payload will contain all the ParameterList field results after a call (on the owner side after a call).

ReturnValue

The ReturnValue Payload only exists if the given Function Owner returns a value. Functions returning void will not have this property. The ReturnValue payload is a Dynamic Object. After a call, the ReturnValue payload will contain the return results (on the owner side after a call).

Synchronous / Asynchronous Interception

Function calls that are made between a function Owner and a function User will be either asynchronous or synchronous.

Asynchronous Calls (non-blocking)

An asynchronous function call is also known as a "non-blocking" call. This is the type of call that occurs for both CallNonBlocking and CallBypassOverrideNonBlocking.

CallBypassOverrideNonBlocking

Asynchronously calls the override registered owner of the function (Non-blocking call).

• Invokes call to registered function owner bypassing the registered override owner (if one exists).
• If there is no registered owner but there is an override registered owner, the call is routed to the override registered owner.
• Current values of all fields of the ParameterList property are marshaled to the called function.
• This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using ascript.WaitForEvent().
• If the RspTimeoutPeriod is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see Timeout Considerations.
• The object returned from WaitForEvent() in response to CallByPassOverrideNonBlocking() can be:

The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation. An Error Object containing information about the error that occurred (Type="Error"; Name="error source").

CallNonBlocking

Asynchronously calls the registered owner of the function (Non-blocking call).

• This call invokes a call to the currently registered owner of the function. If there is an override registered owner, it is called. If there is no override registered owner, but there is a registered owner, the registered owner is called.
• The current values of all fields in the ParameterList property are marshaled to the called function.
• This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using ascript.WaitForEvent().
• If the RspTimeoutPeriod is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see Timeout Considerations.
• The object returned from WaitForEvent() in response to CallByPassOverrideNonBlocking() can be:

The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation. An Error Object containing information about the error that occurred (Type="Error"; Name="error source").

Synchronous Calls (blocking)

A synchronous call is also known as a "blocking" call. Blocking calls a made using the Call or CallBypassOverride methods. These calls are made from the User.

Call

Synchronously calls the registered owner of the function (Blocking call).

• All current field values of the ParameterList property are marshaled to the function Owner.
• If there is no registered owner or registered override owner, an exception is thrown.
• If there is no registered owner but there is an override registered owner, the call is routed to the override registered owner.
• If the RspTimeoutPeriod is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see Timeout Considerations.

CallBypassOverride

Synchronously calls the override registered owner of the function (Blocking call).

• The call is made to the override registered owner of the function bypassing any existing registered owner.
• The current values of all fields in the ParameterList property are marshaled to the override registered function Owner.
• If there is no override registered owner, an exception is thrown.
• If the RspTimeoutPeriod is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see Timeout Considerations.

Returns

When the callee (owner) script wants to generate a function return, it makes a call to the Return method. This method is used for both synchronous and unsynchronous calls.