UEFI Script Files (AN48)

Affected Products	All products featuring UEFI

Preface

This application note describes how to create a UEFI script file for automating the cBC firmware update and BIOS in a production line environment. It also shows how UEFI script files can be used with the congatec system utility CGUTIL. The scripts are suitable for all UEFI-enabled congatec x86 products.

Terminology

Term	Description
cBC	congatec Board Controller
BIOS	Basic Input Output System - Legacy boot firmware. Name still commonly used for UEFI firmware
UEFI	Unified Extensible Firmware Interface - New boot firmware
COM	Computer on Module
CGUTIL	congatec System Utility

Introduction

A UEFI script is a series of statements that tell an application to perform certain tasks. The script is written as plain text file and saved with .nsh extension. With these scripts, customers can simplify the process of updating the BIOS and cBC firmware on congatec COMs in their production line. Generally, these scripts can run in a built-in UEFI shell or in a bootable USB flash drive compiled with UEFI shell.

The congatec embedded BIOS however does not support the built-in UEFI shell because of security reasons. Having a built-in shell may allow users the possibility to bypass security mechanisms that are contained within the BIOS.

To execute UEFI scripts on congatec COMs, you need to create a bootable USB flash drive with compiled UEFI shell. The procedure to create such a boot USB flash drive is explained in the application note How to create a bootable USB stick with a UEFI shell (AN31). You can download this document from:

https://www.congatec.com/us/support/application-notes/article/an31-how-to-create-a-bootable-usb-stick-with-an-uefi-shell/

Caution:

Ensure that there is no loss of power during the BIOS and cBC firmware update. The loss of power during the flash update will result in a non-bootable product that requires RMA. The cBC firmware update should especially be performed only in a safe production environment.

Note:

There are two BIOS update procedures for the production line described in this document. The first procedure is for normal BIOS updates while the other procedure is for extended BIOS updates.

Unlike normal BIOS updates, the extended update requires a reboot cycle to unlock the flash.

Please refer to section 3 of BIOS Update (AN01) for more details on normal (UEFI firmware only) and extended BIOS update. You can download this document from the link below:

https://www.congatec.com/en/support/application-notes/article/an01-bios-update/

UEFI Script for Production Line

This section describes the UEFI scripts for automating production-line programming of the congatec BIOS or cBC firmware.

The table below describes the function of each UEFI script.

Script Name	Description
startup.nsh	The first script that is automatically executed when UEFI shell launches. This script is a container for other scripts (similar to autoexec.bat on old DOS system)
flash_bios.nsh	This script updates the congatec BIOS. Type the number “1” in startup script and press “Enter” to execute this script.
eflash_bios.nsh	This script updates the full BIOS flash (UEFI firmware + extended area). Type the number “2” in startup script and press “Enter” to execute this script.
flash_cbc.nsh	This script updates the congatec Board Controller (cBC). Type the number “3” in startup script and press “Enter” to execute this script.
flash_both.nsh	This script updates both the BIOS and the cBC. Type the number “4” in startup script and press “Enter” to execute this script.

Note:

Use plain text editor such as Notepad when creating UEFI scripts. If you use a word processor, the scripts may execute with errors due to hidden embedded characters associated with word processors.

Production-Line Script Files

The following are the UEFI script files required for production-line programming of the congatec BIOS or cBC firmware.

startup.nsh

Follow the steps below to create the startup.nsh script.

Open Notepad.
Type the following texts below. The comment lines (#) will be ignored during execution.

echo -off
# echo -off inhibits the display of the command line.  
# This prevents the user from seeing the script commands.
cls   
# cls will present a blank screen.
FS0:  
# FS0: Is the file system on the bootable UEFI USB stick where 
# the files are stored. Make sure to use the correct FSx 
# nomination, if your files are on a different file system.
cgutlcmd cginfo /ot:board /dump /bios /bcfw
# The above command line will display the current BIOS and cBC
# firmware installed on the module.
alias -v 1 "flash_bios"
alias -v 2 "flash_cbc"
alias -v 3 "flash_both"
alias -v 4 "startup"
# The alias -v command will temporarily create an alternative
# name for the script file that it corresponds to. Because UEFI 
# script files do not have an input command to read the
# keyboard, the aliases 1, 2, 3 correspond to the names of
# script files and can be entered at the keyboard and executed 
# as commands, to get around this UEFI limitation.
# as commands, to get around this UEFI limitation.
echo " "
echo "Enter choice number below followed by the enter key"
echo "1 for a normal BIOS update"
echo "2 for an extended BIOS update"
echo "3 to update the cBC firmware"
echo "4 to update the BIOS and the cBC firmware"
# The above echo commands are sent to the display
# The above echo commands are sent to the display to offer the  
# user a menu.
echo -on
# Turning echo -on will force the script to wait for input and 
# prevents a blinking display.  
# The standard inputs are 1, 2 or 3.
# However, any UEFI command or .efi executable can be called as  
# well.

Save the script as startup.nsh file.

flash_bios.nsh

Follow the steps below to create the script for updating the congatec BIOS (UEFI firmware only).

Open Notepad.
Type the following texts:

echo -off
cls
cgutlcmd bflash SA50R061.BIN
# This command line is used to update the BIOS with the file 
# SA50R061.BIN. To flash a different BIOS file, simply replace 
# SA50R061.BIN with its name. 
echo " "
echo "If the BIOS was updated successfully, reset or repower the system."
echo "Then verify on the main setup menu that the BIOS name shown is correct."
echo " "
echo "Press 5 followed by the enter key to return to the main menu"
# displays instructions to the user after the BIOS has been  
# updated.
echo -on

Save the script as flash_bios.nsh file.

eflash_bios.nsh

Follow the steps below to create the script for extended BIOS update.

Open Notepad.
Type the following texts:

echo -off 
cls
cgutlcmd bflash /eil 
# The above command checks the status of the extended BIOS flash lock # and returns 0x00 if the flash is still locked.
# and returns 0x00 if the flash is still locked.
if %lasterror% eq 0x0 then 
echo "Extended flash is locked" 
cgutlcmd bflash /eu
# The command to unlock the extended flash. The system will reboot 
# automatically after completion.
endif
echo "Extended flash is unlocked"
cgutlcmd bflash SA50R061.BIN /e
# With the /e parameter, cgutlcmd will perform an extended BIOS 
# update and automatically reboot the system after completion.
echo -on

Save the script as eflash_bios.nsh file.

flash_cbc.nsh

Follow the steps below to create the script for updating the congatec cBC firmware.

Open Notepad.
Type the following texts:

echo -off
cls
cgutlcmd bcprog CGBCP440.DAT
#command to update cBC firmware.
# To flash a different cBC firmware file, simply replace 
# CGBCP440.DAT with its name.
echo " "
echo "If the cBC firmware was updated successfully, turn the power off and then back on (G3 cycle)."
echo "Then verify on the main setup menu that the cBC firmware shown is correct."
echo " "
echo "Press 5 followed by the enter key to return to the main menu."
# displays instructions to the user after the cBC firmware has 
# been updated.
echo -on

Save the script as flash_cbc.nsh file.

flash_both-nsh

Follow the steps below to create the script for updating both congatec BIOS and the cBC firmware.

Open Notepad.
Type the following texts:

echo -off
cls
cgutlcmd bcprog CGBCP440.DAT
# command to update cBC firmware
cgutlcmd bflash SA50R061.BIN
# command to update BIOS
echo "
" echo "If the BIOS and cBC firmware were updated successfully, turn the power off and then back on (G3 cycle)."
echo "Then verify on the main setup menu that the BIOS name and cBC firmware shown are correct."
echo "
" echo "Press 5 followed by the enter key to return to the main menu"
# displays instructions to the user after the BIOS and cBC FW
# have been updated.
echo -on

Save the script as flash_both.nsh file.

Dynamic Detection of Correct File System

If storage devices with file systems on it are connected to or disconnected from the system, the file system with the EFI shell might change. The script code below can be used instead of the fix FS0: command to dynamically detect the EFI Shell file system number:

for %i run (0 9)
  set TEMP_PATH fs"%i":\startup.nsh
  if exist %TEMP_PATH% then
    fs"%i":
  endif
endfor

Prepare USB Stick for Production Line

Follow this procedure to add the required files to the bootable USB stick:

Create a bootable USB stick with compiled UEFI shell as described in congatec Application Note How to create a bootable USB stick with a UEFI shell (AN31)
Download cgutil_V159.zip from congatec at https://www.congatec.com

To download this file, click the "Products" menu on congatec website and select any of the x86 modules.
Click on the software tab and navigate to Windows 10 section
Locate the cgutil_V159.zip file and download it.

Unzip the cgutil_V159.zip file.
Copy the cgutlcmd.efi file from cgutil/uefi/X64 directory to the root directory of the UEFI Shell USB stick.
Copy also the previously created script files startup.nsh, flash_bios.nsh, flash_cbc.nsh and flash_both.nsh to the root directory of the UEFI Shell USB stick.
Copy the BIOS file you want to update to the root directory of the UEFI Shell USB stick. You can have several BIOS files on the USB stick. However, the UEFI script will update only the BIOS file that is indicated with the cgutlcmd bflash biosfile.bin command in the flash_bios.nsh and flash_both.nsh script files.
Copy the cBC Firmware file you want to update to the root directory of the UEFI Shell USB stick. You can have several cBC firmware files on the USB stick. However, the UEFI script will update only the cBC firmware that is indicated with the cgutlcmd bcprog cgbcpxxx.dat command in the flash_cbc.nsh and flash_both.nsh script files.

How to Use the Script Files

Follow the steps below to apply the UEFI script files in production-line programming of the congatec BIOS or cBC firmware.

Caution:

Do not use a dedicated programming station on the production line to update the BIOS or cBC firmware or both. Using dedicated programming station will wear out connectors that mate with the dedicated programming station such as the COM Express connectors due to multiple insertion.
Once these connectors wear out, the BIOS or cBC firmware or both will get corrupted, thereby requiring the module to be repaired.
Instead, update the BIOS or cBC firmware or both with the production carrier board that these modules are to be assembled into. Doing this will ensure that a module is inserted only once into each carrier board in the production line. This action eliminates the wear out of connectors.

Shut down the system containing the carrier board and congatec module.
Insert bootable UEFI shell USB stick into a USB slot on the carrier board.
Power on the system containing the carrier board and congatec module.

The system boots. The display shows that it has booted into UEFI shell.
A 5-second countdown begins at the bottom of the screen.
The startup.nsh script executes automatically when countdown reaches 0 second.
The startup.nsh script clears the screen and displays the following:

congatec System Configuration Utility --- Version 1.5.9
© Copyright 2005-2021 congatec GmbH
Board/BIOS Information Module

System BIOS Version: BIOSNAME
OEM BIOS Version: OEMNAME
BC Firmware Version: CGBCPxxx

Enter choice number below followed by the enter key
1    to update production BIOS
2    to update production BC Firmware
3    to update both the production BIOS and production BC Firmware
FS0:\>

Type one of the choice numbers and press Enter.
The script executes and at completion, displays an instruction to check if the update is successful and to restart the system.
Shutdown the system.
You can now remove the carrier board and module, and then attach the next carrier board with module. Follow the steps above to update each system.

UEFI Script Files for CGUTIL Lab Usage

In the laboratory, the UEFI script helps simplify the process of testing and verification. On one UEFI shell USB stick, the engineer can save various BIOS and cBC firmware versions for different congatec products. This allows the UEFI shell USB stick to be used on different congatec platforms.

With the UEFI script, the user can do the following:

Type in any CGUTIL command at the file system prompt FS0:\>
List all BIOS files on the USB stick when using the BIOS update menu. The list also shows the format of the BIOS update command.
List all cBC firmware files on the USB stick when using the cBC firmware update menu. The list also shows the format of the cBC firmware update command.
Display all the board information data when the board information menu is selected.

Prepare the USB Stick for Lab

Follow the steps below to create the bootable USB stick with UEFI script for lab environment.

Note:

Do not use one UEFI shell USB stick for both the production line scripts and the laboratory scripts. Use a separate UEFI shell USB stick for each environment.

Create a bootable UEFI shell USB stick as described in congatec Application Note How to create a bootable USB stick with a UEFI shell (AN31)
Follow steps 1 to 4 of section Prepare USB Stick for Production Line to add the cgutlcmd.efi file.
Create the UEFI scripts as described in section Lab Script Files below.
Copy the UEFI scripts to the root directory of the bootable USB stick.
Copy the BIOS or the cBC firmware or both to the root directory of the bootable USB stick. You can also copy several BIOS and cBC firmware files of different congatec products to the root directory of the bootable USB stick. This allows you to use the bootable USB stick on different congatec platforms. You must type the full CGUTIL command. This allows you to enter any CGUTIL command any time the file system displays the FS0:\> prompt. You can also enter any UEFI Shell command at either the Shell:> prompt or at the FS0:\> prompt

Note:

Unlike the production-line script files, the lab script files do not update the firmware automatically. Instead, it lists only the files on the USB stick that can be used with the command:

cgutlcmd bflash or cgutlcmd bcprog

It also shows the most used formats of these commands.

Lab Script Files

The startup.nsh script file starts automatically on power up. It enters the correct file system on the USB stick and displays a menu followed by the file system prompt FS0:\>.

startup.nsh

Follow the steps below to create the startup.nsh script.

Open Notepad:
Type the following texts and save the script as startup.nsh file:

echo -off
cls
FS0:
# FS0: directs the UEFI shell to the file system on the bootable 
# UEFI Shell USB stick
alias -v 1 "bios"
alias -v 2 "cbc"
alias -v 3 "bbi"
# alias -v commands assign a temporary name (1, 2 or 3) to the 
# other script files so that 1, 2 or 3 can be used as a menu 
# selection
echo " "
echo "Press number from menu below, followed by the enter key"
echo "or enter any cgutil command"
echo " "
echo "1 to update BIOS"
echo "2 to update cBC Firmware"
echo "3 to list board and BIOS information"
# the above echo commands are used to display the menu
echo -on

bios.nsh

Follow the steps below to create the script for BIOS update.

Open Notepad.
Type the following texts and save the script as bios.nsh file.

echo -off
cls
ls *.bin
# lists all files in the directory that have the extension .bin 
# (BIOS files)
echo " "
echo "BIOS update command format is:"
echo "cgutlcmd bflash filename.bin normal BIOS Update"
echo "cgutlcmd bflash filename.bin /e extended BIOS Update"
# Displays the cgutil format for updating the BIOS
# Reference to AN1
echo " "
echo "Enter the BIOS Update Command in the format shown above,” 
echo "or press a number from menu below, followed by the enter key"
echo " "
echo "1 to update BIOS"
echo "2 to update cBC firmware"
echo "3 to list board and BIOS information"
# displays the menu and allows the user to enter any cgutil 
# command, including the BIOS update command shown above 
echo -on

cbc.nsh

Follow the steps below to create the script for cBC firmware update.

Open Notepad.
Type the following texts and save the script as bc.nsh file.

echo -off
cls
ls *.dat
# lists all files in the directory that have the extension .dat 
# (cBC firmware files)
echo " "
echo "cBC update command format is:"
echo "cgutlcmd bcprog filename.dat"
# displays the cgutil format for updating the cBC firmware
echo " "
echo "Enter the cBC update command in the format shown above,” 
echo "or press a number from menu below, followed by the enter key"
echo " "
echo "1 to update BIOS"
echo "2 to update cBC firmware"
echo "3 to list board and BIOS information"
# displays the menu and allows the user to enter any cgutil
# command,including the cBC firmware update command shown above
echo -on

bbi.nsh

Follow the steps below to create the script that displays the board and firmware information.

Open Notepad.
Type the following texts and save the script as bbi.nsh file.

echo -off
cls
cgutlcmd cginfo /ot:board /dump /bios /bcfw /cgos /manu /bcnt /rtim
# displays the board information including the System and OEM 
# BIOS versions, cBC firmware version, CGOS driver version,
# manufacturing data, boot counter and running time meter
echo " "
echo "Press number from menu below, followed by the enter key"
echo "or enter any cgutil command"
echo " "
echo "1 to update BIOS"
echo "2 to update BC Firmware"
echo "3 to list board and BIOS information"
# displays the menu and allows the user to enter any cgutil command
echo -on

Sample UEFI Shell Commands

The following section describes some UEFI shell commands. The UEFI shell commands can be used at the UEFI Shell prompt Shell> or at the file system prompt FS0:\>. Refer to the UEFI Shell Specification for detailed description of all available description of all available commands. The specification can be downloaded at https://uefi.org/specifications

Help Command

The help -b command lists all the UEFI Shell commands.
The -b parameter displays the output one screen at a time.
The -verbose parameter displays the details of each UEFI shell command. It also shows an example of how to use the command. For example, the command help -b -verbose pci will parse and pause on each screen, giving verbose description of the pci command.

Mode Command

The mode command can change the number of characters per line and the number of lines that can be displayed. You can check the assigned mode for your display by typing the command:

mode

Typical modes supported by an HD display are:


Col 80	Row 25
Col 80	Row 50
Col 100	Row 31
Col 240	Row 56

For example, to change the display mode to 100 characters per line and 31 lines, use:

mode 100 31

Cls Command

The cls command can be used to clear the screen and to change the background color of the display. For more details about the cls command, use:

help -b cls

Set Command

With the set command, you can display, create, change or delete a UEFI Shell environment variable. Such variables are often necessary in more complex scripts. Refer to section Dynamic Detection of Correct File System above, for an example of how to use the set command:

set TEMP_PATH fs"%i":\startup.nsh

In this example, TEMP_PATH is the variable name and fs"%i":\startup.nsh is the variable value.

The general syntax of the set command is:

set vname vvalue

where vname is the variable name and vvalue is the new value.

The command set -d vname can be used to delete a previously created variable.

Use the set command without any parameter to display all environment variables.

Pause Command

The pause command displays the message “Enter 'q' to quit, any other key to continue:”and then suspends the script file execution and waits for keyboard input. When you press any key except q or Q, the execution resumes and continues with the next line after the pause command. If q or Q is pressed, script processing terminates.

With -q parameter, the pause command waits for user input without displaying a message

Stall Command

The stall command can be used to delay the script operation for a specified number of microseconds.

To delay the script operation for one second (1000000 microseconds), use the example below: stall 1000000

Conclusion

The UEFI scripts help simplify the process of updating the BIOS and cBC firmware both in production line and in the lab.