Skip to content

Latest commit

 

History

History
227 lines (163 loc) · 11.3 KB

user_guide.md

File metadata and controls

227 lines (163 loc) · 11.3 KB
Raw

SCMI Compliance Suite User Guide

Table of Contents:

Introduction

This document outlines how to fetch, adapt, and build the SCMI test suite. The steps to build and run the test suite for a mocker platform on host machine, OSPM agent on System Guidance for Mobile (SGM) System Guidance and as baremetal library.

Prerequisites

The following are the prerequisites to build the SCMI test suite.

Host machine requirements and tools

The software is built on Ubuntu 16.04 LTS (64-bit). Packages used for building the software are installed from this distribution unless specified. Though it is tested only on Ubuntu 16.04, it is expected to also work on later versions of Ubuntu.

Install the following tools with the command:

sudo apt-get install build-essential gcc make git

Download and install the AArch64 little-endian GCC cross compiler as specified in Linaro Release.

Downloading the SCMI test suite source code

To download the SCMI test suite source code from GitHub, execute:

git clone https://github.com/ARM-software/scmi-tests

Compliance suite design and library of tests

For details on the SCMI compliance suite design, see Validation Methodology Document. The design document provides an overview of the design considerations, the interfaces that must be implemented to adapt this test suite for your own platform, and the overall code organization. Some control flows are also detailed to describe the execution flow.

For details on the tests that are included in the test suite, see Test checklist.

Build steps

The compliance suite can be built as a library which can be linked to your execution environment or as an Operating System Power Management (OSPM) agent running on Linux. The tests are designed for SCMI version 2.0, but backward compatibility is maintained with version 1.0. Test suit will internally check the version and do the tests accordingly.

1. Building the test suite as a library

To start the build, perform the following steps from the <test suite clone location>.

CROSS_COMPILE=<path/to/your/AArch64/compiler/bin>/aarch64-linux-gnu- make clean

CROSS_COMPILE=<path/to/your/AArch64/compiler/bin>/aarch64-linux-gnu- make PROTOCOLS=<comma separated protocol list> VERBOSE=<level>

Example:

CROSS_COMPILE=<path/to/your/AArch64 compiler/bin>/aarch64-linux-gnu- make clean

CROSS_COMPILE=<path/to/your/AArch64 compiler/bin>/aarch64-linux-gnu- make PROTOCOLS=base,clock,power_domain,system_power,performance,sensor,reset VERBOSE=1

If you do not specify the PROTOCOLS variable when invoking the make command, Base Protocol test library alone is generated by default.

The output of this make command is the libscmi_test.a library that includes the tests for all the specified protocols and version . The library will be generated in the <test suite clone location>. The arguments passed to the PROTOCOLS parameter are the subfolder names that are found in <test suite clone location>/test_pool folder. If there are memory constraints on the platform, fewer tests can be included by modifying the PROTOCOLS variable. The library can be linked to your execution environment.

2. Building the test suite as a test agent

A test agent is an execution wrapper for libscmi_test.a. Currently, support is provided for the following two platforms.

2.1 Mocker platform

A self-test framework is implemented on a mocker platform that provides a simulated response to the SCMI commands issued by the test suite. To start the build, perform the following steps from the <test suite clone location>.

make clean

make PLAT=mocker PROTOCOLS=base,clock,performance,power_domain,system_power,sensor,reset VERBOSE=1

The output will be libscmi_test.a and scmi_test_agent in the <test suite clone location>. When the test library is extended to support new protocols or commands, it is not necessary to support the same in the mocker platform, unless it is warranted for testing the framework changes.

2.2 OSPM agent

In addition to building the library, the build also enables the SCMI test suite to run as an OSPM agent running from Linux using publicly available mailbox test driver interface.A reference implementation for SGM is provided in the suite. To start the build, perform the following steps from the <test suite clone location>.

CROSS_COMPILE=<path/to/your/AArch64 compiler/bin>/aarch64-linux-gnu- make clean

CROSS_COMPILE=<path/to/your/AArch64 compiler/bin>/aarch64-linux-gnu- make PLAT=linux PROTOCOLS=base,clock,power_domain,performance,system_power,sensor,reset VERBOSE=1

The output will be libscmi_test.a and scmi_test_agent for the Linux platform in the <test suite clone location>.

NOTE:

  • The same executable can be used on SGM-775 or SGM-776
  • You must rebuild the Linux kernel and device trees for SGM by following the Guide to test SCMI on SGM.

2.3 Baremetal

The SCMI test suite can be complied as libscmi_test.a and integrated with your baremetal test framework. Please refer to Validation Methodology Document for PAL API's which needs to be ported for baremetal.

CROSS_COMPILE=<path/to/your/AArch64 compiler/bin>/aarch64-linux-gnu- make clean

CROSS_COMPILE=<path/to/your/AArch64 compiler/bin>/aarch64-linux-gnu- make PLAT=baremetal PROTOCOLS=base,clock,power_domain,performance,system_power,sensor,reset VERBOSE=1

The output will be libscmi_test.a for baremetal platform and available in the <test suite clone location>.

Test suite execution

Running the test agent on the host machine

To run the test suite on the host machine, execute the command:

./scmi_test_agent

For the self_test/mocker platform, the test logs are dumped on the console itself.

Running as OSPM test agent

To run the test suite on the SGM Linux platform, execute the following command in the filesystem that is mounted on SGM:

cd <path/to/executable in filesystem>

./scmi_test_agent

The test logs are captured in a report file arm_scmi_test_log.txt in the same directory as the executable.

Running in Baremetal environment

To run the test suite on the baremetal environment, invoke to arm_scmi_agent_execute() from test framework. For more details, refer to Validation Methodology Document.

Test execution report

The test report lists results per test case. The tests are organized as a collection within individual protocol. For every test case, the following verification steps occur:

Message Header: The message header that is received from the platform is checked against what is in the send command.

Status: The platform returns a status for a command that is issued by the agent and this is checked as per specification or as per the expected values provided by you.

Return Values - if relevant: The remaining return values for a command response are valid based on the status return value. Checks are performed only if the status return value returned SUCCESS and expected values were given by the user.

Each individual check delivers a PASS, FAIL, or SKIPPED.

  • Sample report with minimum verbosity (VERBOSE=1)

      101: Base protocol version check
         VERSION        : 0x00020000                           : CONFORMANT
  102: Base protocol attributes check                          : CONFORMANT
  103: Base msg attributes mandatory cmd check                 : CONFORMANT
  104: Base msg attributes invalid msg id check                : CONFORMANT
  105: Base query vendor name check                            : CONFORMANT
  106: Base query subvendor name check                         : CONFORMANT
  107: Base query implementation version check                 : CONFORMANT

  • Sample report with maximum verbosity (VERBOSE=5)

      101: Base protocol version check
       [Check 1] Query protocol version
         MSG HDR        : 0x00004000
         NUM PARAM      : 0
         CHECK STATUS   : PASSED [SCMI_STATUS_SUCCES]
         CHECK HEADER   : PASSED [0x00004000]
         RETURN COUNT   : 1
         RETURN[00]     : 0x00020000
         VERSION        : 0x00020000                           : CONFORMANT
  102: Base protocol attributes check
       [Check 1] Query protocol attributes
         MSG HDR        : 0x00004001
         NUM PARAM      : 0
         CHECK STATUS   : PASSED [SCMI_STATUS_SUCCES]
         CHECK HEADER   : PASSED [0x00004001]
         RETURN COUNT   : 1
         RETURN[00]     : 0x00000206
         CHECK RSVD BITS: PASSED
         CHECK NUM AGENTS: PASSED [0x00000002]
         CHECK NUM PROTOCOLS: PASSED [0x00000006]               : CONFORMANT
  103: Base msg attributes mandatory cmd check
       [Check 1] BASE DISCOVER VENDOR support
         MSG HDR        : 0x00004002
         NUM PARAM      : 1
         PARAMETER[00]  : 0x00000003
         CHECK STATUS   : PASSED [SCMI_STATUS_SUCCES]
         CHECK HEADER   : PASSED [0x00004002]
         RETURN COUNT   : 1
         RETURN[00]     : 0x00000000
         CHECK RSVD BITS: PASSED
       [Check 2] BASE DISCOVER IMPL VERSION support
         MSG HDR        : 0x00004002
         NUM PARAM      : 1
         PARAMETER[00]  : 0x00000005
         CHECK STATUS   : PASSED [SCMI_STATUS_SUCCES]
         CHECK HEADER   : PASSED [0x00004002]
         RETURN COUNT   : 1
         RETURN[00]     : 0x00000000
         CHECK RSVD BITS: PASSED
       [Check 3] BASE DISCOVER LIST PROTOCOLS support
         MSG HDR        : 0x00004002
         NUM PARAM      : 1
         PARAMETER[00]  : 0x00000006
         CHECK STATUS   : PASSED [SCMI_STATUS_SUCCES]
         CHECK HEADER   : PASSED [0x00004002]
         RETURN COUNT   : 1
         RETURN[00]     : 0x00000000
         CHECK RSVD BITS: PASSED                               : CONFORMANT

Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.