Create Function Call Sequence Assessments

R2026b

A function call sequence assessment verifies the order in which your code under test calls other functions. Use call sequence assessments when the order of function calls is important. In this example, you verify that a communication driver calls comm_open, comm_configure, comm_transmit, and comm_close, in this order.

Each test step, whether tabular or scripted, can have one call sequence assessment consisting of:

• An ordered list of functions that you expect to be called.

• Optional input parameter assessments for each function in the sequence. Input parameter assessments allow you to check the arguments passed to each function call against an expected value or range of values.

A function call sequence assessment fails when:

• The functions are not called in the expected order.

• One or more of the input parameter assessments fail.

Note

Function call sequences are strict. Once you include a function in the call sequence, the assessment checks for all calls to that function. If the function is called before, after, or in between the expected calls you specify, the call sequence assessment fails.

Example Files

This tutorial uses the files in the folder polyspaceroot\polyspace\examples\doc_pstest\call_sequence\src. Here, polyspaceroot is the Polyspace^® installation folder, for instance, C:\Program Files\Polyspace\R2026b.

These files define and implement a communication driver with a protocol that requires functions to be called in a specific order.

comm_driver.h

#ifndef COMM_DRIVER_H
#define COMM_DRIVER_H

#include <stdint.h>

typedef enum CommStatus {
    COMM_OK = 0,
    COMM_ERR_NOT_OPEN,
    COMM_ERR_NOT_CONFIGURED,
    COMM_ERR_INVALID_PORT
} CommStatus;

typedef struct CommChannel {
    uint8_t port;
    uint32_t baud_rate;
    uint8_t is_open;
    uint8_t is_configured;
} CommChannel;

CommStatus comm_open(CommChannel *ch, uint8_t port);
CommStatus comm_configure(CommChannel *ch, uint32_t baud_rate);
CommStatus comm_transmit(CommChannel *ch, const uint8_t *data, uint16_t length);
CommStatus comm_close(CommChannel *ch);

CommStatus send_message(uint8_t port, uint32_t baud_rate,
                        const uint8_t *data, uint16_t length);

#endif

comm_driver.c

#include "comm_driver.h"

CommStatus comm_open(CommChannel *ch, uint8_t port) {
    ch->port = port;
    ch->is_open = 1;
    ch->is_configured = 0;
    return COMM_OK;
}

CommStatus comm_configure(CommChannel *ch, uint32_t baud_rate) {
    ch->baud_rate = baud_rate;
    ch->is_configured = 1;
    return COMM_OK;
}

CommStatus comm_transmit(CommChannel *ch, const uint8_t *data, uint16_t length) {
    /* Hardware transmit logic */
    (void)ch;
    (void)data;
    (void)length;
    return COMM_OK;
}

CommStatus comm_close(CommChannel *ch) {
    ch->is_open = 0;
    ch->is_configured = 0;
    return COMM_OK;
}

CommStatus send_message(uint8_t port, uint32_t baud_rate,
                        const uint8_t *data, uint16_t length) {
    CommChannel ch;
    comm_open(&ch, port);
    comm_configure(&ch, baud_rate);
    comm_transmit(&ch, data, length);
    comm_close(&ch);
    return COMM_OK;
}

To continue with this tutorial:

1. Create a new Polyspace Platform project and add the src folder to the project.

2. Click Parse Code on the toolstrip to analyze the files in the folder.

Create a Call Sequence Assessment

In this example, you write a test for the function send_message() and add a call sequence assessment to verify that it calls its internal functions in the correct order.

1. On the Projects pane, right-click send_message and select Add Test Case.

2. In the Inputs section, set the values for these input variables:

   • Set port to 2.

   • Set baud_rate to 115200.

   • Set length to 3.

3. For the input parameter data, create a pointer target. To do so, right-click the data row in the Inputs table and select Add Pointer Target. In the Add Pointer Target dialog box, accept the default name, set the size to 3, and click OK. Click the link in the Value column to navigate to the Test Data section of the test. Specify the values 0xAA, 0xBB, and 0xCC:

   

4. In the Call Sequence Assessment section, click the Add button to select functions from the list of available callees. Hold Shift and select all four functions. Click OK to add the functions to the call sequence.

5. Drag and drop the function cards into this order:

   • comm_open

   • comm_configure

   • comm_transmit

   • comm_close

   

6. Expand the comm_open card to view the input parameter assessments. Assessments are automatically added, but are disabled by default for each input to the function. Enable the assessment for the port parameter and set the expected value to 2.

   

7. For the comm_configure function, enable the assessment for baud_rate and set the expected value to 115200. For comm_transmit, enable the assessment for length and set the expected value to 3. Do not enable any input assessments for comm_close.

8. Build and run the test. Then, open the Review perspective and select the test case in the Results List. The Result Details pane shows the test results.

   

   Green checks indicate passing assessments. For more information on:

   • Building and running tests, see Build and Run Tests in Polyspace Platform User Interface.

   • Reviewing function call sequence test results, see Review Function Call Sequence Assessment Results.