◀ Graphic User Interface
Contents
Project Management ▶

Command-Line Interface

  1. General Information of HKSAT CLI
  2. Detailed Overview of HKSAT CLI Features
  3. HKSAT-Jenkins Integration Tutorial

General Information of HKSAT CLI

HKSAT Command-Line Interface provides following features.

To provide the features, HKSAT ships with the following batch files.

Basic Usage

  1. Open the Windows Command Prompt.
  2. Excute the relevant HKSAT batch file (i.e., run.bat, genOdinInfo.bat, genProject.bat, genScript.bat) using the necessary parameters.

Options

Each batch file has a range of options.

Options for ODIN/Mobilgene Analysis Information Gathering Feature (genOdinInfo.bat)

Options for ODIN/Mobilgene Analysis Information Gathering Feature

Options for Creating HKSAT Project Feature (genProject.bat)

Options for Creating HKSAT Project Feature

Options for Executing Pre-existing Analyses in Batches Feature (run.bat)

Options for Executing Pre-existing Analyses in Batches Feature

Options for Creating Jenkins Pipeline Script Feature (genScript.bat)

Options for Creating Jenkins Pipeline Script Feature

Detailed Overview of HKSAT CLI Features

HKSAT CLI offers four distinct features; Batch execution, Analysis information gathering, HKSAT project creation, and Jenkins Pipeline script creation.

Batch Execution Feature

The usage of the batch execution feature is as follows:

> run.bat HKSAT_PRJ [-a <analyses>] [-c] [-r] [-v]

Sample Screenshot of Batch Execution Feature

Analysis Information Gathering Feature

The usage of the analysis information gathering from both of user and target Mobilgene/ODIN project code base is as follow:

> genOdinInfo.bat ODIN_PRJ_DIR [OUT_FILE] [-m <modules>] [-a <analyses>] [-old <old_branch>] [-post <edit_file>]

Sample Screenshot of Analysis Information Gathering Feature

Using the Post-processing Feature(-post)

You can specify the name of a file that contains post-processing contents to automate repetitive editing tasks that might be additionally required for the extracted analysis information.


The post-processing function operates by applying given post-processing content to the extracted analysis information. The post-processing content is described in JSON format as below, and it consists of 'delete' and 'add' sections. Here are the tips for writing each section. 

{
    delete : {
        "modules:[MODULE_NAME]:module:compilerOption" : [OPTION1, OPTION2, ...],
        "modules:[MODULE_NAME]:module:sourceCodeList" : [FILE1, FILE2, ...],
        "modules:[MODULE_NAME]:module:includeList" : [FOLDER1, FOLDER2, ...],
        "modules:[MODULE_NAME]:module:defineMap" : {KEY_VALUE1, KEY_VALUE2, ...}
    },
    add : {
        "modules:[MODULE_NAME]:wcrt:[TASK1_NAME]" : {
            [TASK1_INFO]
        },
        "modules:[MODULE_NAME]:wcrt:[TASK1_NAME]" : {
            [TASK2_INFO]
        },
    }
}
Section "delete"

Using the "delete" section, users can automate the removal of unnecessary source code or definitions from the analysis information (odin.tb2) that may hinder the analysis.

The example below illustrates how to delete specific compile options, include folder paths, and definitions associated with the "ASW" module from the analysis information.

For definitions, they are written in a key-value format; however, only the key is referenced for deletion, and the value is not used.

        
delete : {
    "modules:ASW:module:compilerOption" : ["-dual-debug"],
    "modules:ASW:module:includeList" : ["Bsw_Output\\inc", "Mcal_Output\\include"]
    "module:ASW:module:defineMap" : {"FOO": ""}
}
Section "add"

Using the "add" section, users can automate the process of supplementing the analysis information (odin.tb2) with the required inputs for schedulability analysis, such as priority, wcet, period, and deadline.

The example below illustrates how to supplement the schedulability analysis information for the task named "OsTask_ASW_FG2_LinScheduleRequest" related to the "ASW" module in the given analysis information.

        
add : {
    "modules:ASW:wcrt:OsTask_ASW_FG2_LinScheduleRequest" : {
        "priority": 221,
        "wcet": 178,
        "period": 10000000,
        "deadline": 10000
    }
}

Creating HKSAT Project Feature

The usage of creating HKSAT project feature is as follows:

> genProject.bat CUR_ROOT [OUT_FOLDER] [-old <old_branch>]

Sample Screenshot of Creating HKSAT Project Feature

Creating Jenkins Pipeline Script Feature

This feature creates a Jenkins project script for HKSAT's CI/CD integration. Running the feature will ask you to sequentially input the Git repository address, the branch to be analyzed, login details, and a notification email. A script will then be generated based on the provided information.

⟩ genScript.bat [OUT_FILE]

Sample Screenshot of Generating Jenkins Pipeline Script Feature

The generated Jenkins Pipeline script performs four functions sequentially:

  1. It fetches the source code and the analysis information file from Git.
  2. It creates an HKSAT project using the source code and the analysis information file.
  3. It executes the HKSAT analysis and generates a SW Test Report.
  4. It sends the logs and the SW Test Report to the developer.

Retrieving Source Code and Analysis Information File

Initially, the script utilizes the repository information provided by the user during the Jenkins Pipeline script generation phase to fetch the target source code and the accompanying analysis information file (either odin.tb2 or hksat.tb2).

Subsequently, the script analyzes the information file. If the user has provided details for software change impact analysis (like the name of the repository branch where the previous version of the target is stored), the script will also fetch that source code as well.

    // Fetching source code from GIT repository
    stage('checkout'){
        steps{
            // Clean-up
            cleanWs()
 
            // Fetching the latest source code of the target
            bat "mkdir ${curr}"
            dir("${curr}") {
                checkout scmGit(
                    branches: [[name: "*/${curr}"]], 
                    extensions: [], 
                    userRemoteConfigs: [[credentialsId: "${cid}", url: "${repo}"]])
            }
 
            // Fetching the previous version of the module if needed
            script {
                old = getOldBranch("${curr}")
                if (old != null){
                    bat "mkdir ${old}"
                    dir("${old}"){
                        checkout scmGit(
                            branches: [[name: "*/${old}"]], 
                            extensions: [], 
                            userRemoteConfigs: [[credentialsId: "${cid}", url: "${repo}"]])
                    }
                }                   
            }
        }
    }

Creating HKSAT Project

Using the fetched source code and the anlaysis information file, the script executes the HKSAT CLI's function to create an HKSAT project (refer to Section 2.3).

If previous version information was provided in the prior step for software change impact analysis, this analysis will be added into the HKSAT project.

    // Creating HKSAT Project
    stage('project'){
        steps {
            bat "mkdir ${target}"

            // Add SCIA if needed
            script{

                if (old != null){
                    bat """"${hksat}" -cc ${curr} ${target} -old ${old}"""
                } else {
                    bat """"${hksat}" -cc ${curr} ${target}"""
                }
            }
        }
    }

Executing HKSAT Analysis and Generating SW Test Report

The script executes the analysis defined in the generated HKSAT project and outputs the SW Test Report.

    // Executing analysis and generating SW Test Report
    stage('analysis') {
        steps {
            script {
                batExit = bat returnStatus: true,
                script: """"${hksat}" ${target} -a -r"""
                echo "batExit = " + batExit
                if (batExit != 0){
                    catchError(buildResult: 'SUCCESS', stageResult: 'FAILURE') {
                        error "An error occurred during the analysis."
                    }
                }
            }
        }
    }

Sending Logs and SW Test Report Function

The script sends an email to the designated email address, attaching the SW Test Report generated in the previous step as well as the Jenkins log.

The email subject and content indicate whether the analysis was successful or not. Below is an example of an email in the event of a successful analysis.

SUCCESS: Job 'hksat_cicd_git_server [66]':
Check console output at "hksat_cicd_git_server [66]" 

    // Sending email
    stage('report') {
        steps {
            script {
                // Configuring the email subject based on analysis result.
                if (batExit == 0){
                    result = "SUCCESS"
                }

                emailext (
                    // Subject
                    subject: "${result}: Job '${env.JOB_NAME} [${env.BUILD_NUMBER}]'",
                        
                    // Body
                    body: """<p>${result}: Job '${env.JOB_NAME} [${env.BUILD_NUMBER}]':</p>
                    [<p>Check console output at ...],
                        
                    // Recipients
                    to: "${mailto}",
                    recipientProviders: [developers(), requestor()],
                    
                    // Attachments
                    attachLog: true,                            // Jenkins 콘솔로그 첨부
                    attachmentsPattern: 'target/report.html',   // HKSAT 분석 보고서 첨부
                )
            }
        }
    }

HKSAT-Jenkins Integration Tutorial

In this tutorial, we will cover how to create an HKSAT-Jenkins integration project that uses the HKSAT CLI feature to automatically perform HKSAT analysis and notify the developer of the results via email.

Overview of HKAST-Jenkins Workflow (KR)

The HKSAT-Jenkins integration project introduced in this tutorial requires the following prerequisites

Tutorial Prerequisites
Category Requirements
Software Jenkins
HKSAT (with license and compatible compilers)
Git
Test editor
Hardware Windows PC with all the necessary software pre-installed
Compiler USB dongle (if needed)
Etc. Git repository location of target module
Jenkins user's credential ID
Task information for schedulability analysis (priority, WCET, deadline, period)
Additional information required for compiling the target source code (if necessary)/td>

This tutorial assumes the following for simplicity:

Step 1: Gathering Analysis Information

In this step, you'll create an analysis information file (either odin.tb2 or hksat.tb2) based on the target source code and user requirements. There are two methods to achieve this: either by utilizing the HKSAT Command-Line Interface (CLI) or by using the HKSAT Graphical User Interface (GUI).

Using HKSAT CLI

If your analysis target is ODIN/Mobilgene, the HKSAT CLI can be utilized to extract information for all analyses supported by HKSAT.

To extract analysis information, run the HKSAT CLI in the Windows Command Line (cmd.exe). The following command is an example for generating analysis information for the ASW module of the target Mobilgene project, specifically for longest execution time analysis, stack usage analysis, static software analysis, and duplicate code analysis. The resulting information will be saved in odin.tb2.

⟩ genOdinInfo.bat C:\Project

Using HKSAT GUI

Regardless of whether the target is an ODIN/Mobilgene project, users can utilize the HKSAT GUI to configure the analysis settings. After setting up, you can select the desired analysis kind and save it as an analysis information file. For detailed guidance, please refer to "Project Management", in the Help section.

  1. Creating a Project: Use the HKSAT GUI to create a new HKSAT project.
  2. Project Configuration: Set up the project by adding the desired analysis target modules and analysis types.
  3. Generating Analysis Information: Navigate to the top menu bar in HKSAT, and select "Project" → "Export Project Analyses (CI/CD)" (refer to the illustration below). From here, choose the analysis you want to perform with the CI/CD tools. Select where you want to save the analysis information file (i.e., hksat.tb2), then click "Export". If you wish to add a software change impact analysis, navigate to "Add SCIA" tab and enter the branch name where the previous version of the source code is stored.
    4. Location of Export Project Analyses Menu Item
    Export Project Analyses Window

Step 2: Uploading Analysis Information File

This step involves uploading the extracted analysis information (either odin.tb2 or hksat.tb2) to the source code repository (e.g., Git). The uploaded analysis information file will later be utilized by the HKSAT CLI's project creation feature.

  1. Copy the analysis information file to the target source code directory, for instance, C:\Project.
  2. Use Git commands to upload the analysis information file to the source code repository. Below is an example Git command for uploading the odin.tb2 file:

    3. C:\Project⟩ git add odin.tb2
    C:\Project⟩ git commit -m "Sample commit message"
    C:\Project⟩ git push
    Enumerating objects: 13, done.
    Counting objects: 100% (12/12), done.
    ...
    13d5b9f..48da849 master -> master

    C:\Project⟩

Step 3: Creation of HKSAT-Jenkins Integration Project

This section guides you through the steps to create a Jenkins project for executing HKSAT.

  1. Login to Jenkins.
    2. Jenkins Login Page
  2. From the Jenkins Dashboard, select "New Item".
    3. Adding New Jenkins Project
  3. Choose the "Pipeline" project type, input your desired project name, then click on "OK".
    4. Setting Project Type and Name
  4. Configure the project by adding a description, setting up build triggers, and making any other necessary adjustments. Once done, click on "Save".
    5. Configuring Project

Step 4: Generating Jenkins Pipeline Script for HKSAT-Jenkins Integration Project

  1. The heart of the HKSAT-Jenkins integration project lies in the creation of the Pipeline script. Refer to Section 2.4 for detailed guidance. Below, we illustrate how to generate a Pipeline script named "pipeline.gvy" in the specified execution location.

    2. ⟩ genScript.bat

    Running the batch file will ask you to sequentially input the Git repository address, the branch to be analyzed, login details, and a notification email. A script will then be generated based on the provided information.

    Sample Screenshot of Jenkins Script Generation
  2. After crafting your script, open it with a text editor of your choice. Select the entire script content and copy it. Then, navigate to the settings interface of the previously set up HKSAT-Jenkins integration project. Locate the "Pipeline" section and paste the copied script content there.
    3. Screenshot of Pipeline Script Configuration Section

Step 5: Running HKSAT-Jenkins Integration Project

Using the completed project, execute automated HKSAT analyses and reports

  1. Open the HKSAT-Jenkins integration project page.
    2. Selecting the created project from the Jenkins dashboard screen
  2. Select "Build Now" from the left-hand menu.
    3. Selecting "Build Now" button from the project page
  3. In the central Stage View, observe the creation of a new build item (denoted as "#number"), and verify that each step is executed correctly by the Pipeline script.
    4. HKSAT executing step by step following the Pipeline script
  4. Check your email to ensure you've received the analysis results log and attached HKSAT SW Test Report.
    5. Email with attached analysis result log and HKSAT SW Test Report

FAQ

We have compiled answers to potential questions that may arise when setting up the HKSAT Jenkins project.