-

Developer’s Guide
E
R
Document No. SW-DPG-2023-SP-X-DPG

O T T E
N IBU
SP-X
O R
D T 241 2
Generic MegaRAC® SP-X Firmware
Developer’s Guide

I S
D 30 8 1 n
a
Revision: 13.6

h
1 4 u s
Published by Software R&D

e
70 b h a l
1 n t i i v s
AMI-CONFIDENTIAL | NDA Required

a
Copyright © 2023 American Megatrends International LLC.

h AMI

s h
All rights reserved.

s da 3095 Satellite Boulevard, Building 800, Suite 425,

Duluth, Georgia 30096, U.S.A
Property of AMI

s a
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Revision History
Document
S. No. Date Comments
Version
1

2
13.0

13.1

E -
May 22, 2020

July 10, 2020

Initial Draft for SPX 13.0
Updated the document as per the release update
Updated the Features Configuration under Chapter 2
3

4
13.1

13.1

T R
July 21, 2020

E
Sep 21, 2020
Updated the JViewer Binary Package Maintenance content under
Chapter 12
Included Media Configuration under Chapter 2 and updated images
in KVM Configuration
5 13.1

O
N IBU T
Sep 22, 2020 Included the content in Extended Log Configuration under Chapter
2
Updated screenshots and included content for SOC Configuration,
General Configuration, Features Configuration, Component
Management Configuration, Features Configuration, Back up/
Restore Configuration, Flasher Configuration, Extended Log
6

O13.1

R
D T 241
Sep 29, 2020

2
Configuration, IPMI Configuration, SEL Configuration, Device
Configuration, Test Tools Configuration, Smashlite Configuration,
Runtime Libraries Configuration, Software Configuration, Dual
Image Configuration, SOL and Serial Port Configuration under
Chapter 2

S
Included content in Test Tools Configuration under Chapter 2

I
7 13.1 Oct 13, 2020

D 30
13.1

8 1 n
Dec 10, 2020

a
Included new chapter as LibusbGadget Porting Guide
Added new Chapter 23 Device Drivers
Updated Document version as 13.2

4 hs
Removed VMedia Support for Linux 32-Bit Clients and
VMedia Support for Windows 32-Bit Clients from section KVM

u
9 13.2 Mar 16, 2021

1 e
Configuration in chapter 2

70 b h a l Removed Vmedia_Win32-src and Vmedia_Linux_32-src from

Table - VMedia Library Packages in chapter 12

1
10

n t i
13.2

i v s
Mar 23, 2021
Updated Media Configuration screenshot and added NBD Support
for VMedia, Media Redirection over HTTPS support and SD Server
Support in Media Configuration in Chapter 2

11

h a 13.2

s h Apr 01, 2021

Added NCSI Configuration under Device Configuration in SPX
Package Configurator in Chapter 2

s da
Added Boot From eMMC under General Configuration in Chapter
2

s a
2 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

12 13.2 Apr 03, 2021 Updated content in SP-X Development-Hands on in chapter 4,

Application Package Creation in chapter 6, dev_install for library
binary package as dev-install.py for library binary package, dev_
install for library development packageāś dev_install.py for library
development package, Build Details in chapter 9 Library Package

13 13.2

E -
June 28, 2021
Creation
Added new Chapter 19 Secure Boot

R
14 13.3 Aug 11, 2021 Updated document version as 13.3
Updated KVM Configuration in Chapter 2
15 13.3

O T T E
Oct 15, 2021 Included USB Port B Feature in Chapter 14 and included
Kernel Fit Image and Multiplatform Support in Chapter 19
Included content in IPMI Configuration section and IPMI

N IBU
Interface Thread Priority Section under Chapter 2
Included new section IPMI Over USB Support as Chapter 20
16 13.3 Oct 30, 2021 Updated the entire section of Chapter 20

17

18
O13.3

R
D T 241
13.3 2
March
2022
March
07,

14,
Included KVM Server Port usage information
in Port Usage Table under Appendix
Included Customization of upload file handler API in SP-X Rest

S
2022 Service topic under Chapter 10
19

20
I13.3

D 30
13.4

8 1
April 05, 2022

n
May 17, 2022

a
Included VGA Memory Size Configuration (AST2600) as a Chapter
18
Updated the document version as 13.4 and included new Chapters
22 to 32
21

4
13.4

h
May 18, 2022

s
Included new Chapter 33 as BMC Version Format
Included Boot From SW-eMMC section in General Configuration

22

0 1 13.4

h u l e
May 19, 2022
under Chapter 2
Included Engine ID format related information for SNMP

a
Configuration under Chapter 2
23

1
24 7 13.4

t
13.4
i b May 26, 2022

v s
May 26, 2022
Included Dual Image Build Guidelines as new Chapter 34

Updated the MDS version under Chapter 20

25

a n
13.4

h iMay 30, 2022 Included the content in Dual Image Confirmation under Chapter 2
and removed the chapter Dual Image Build Guidelines
26

27
h
s da
13.4

13.4
s June 06, 2022

June 22, 2022

Included Launching Jviewer From Eclipse and Debugging JViewer
in Eclipse under Chapter 12
Included AST2620 SOC Build Guide as a new Chapter 34

28

s a 13.4 June 22, 2022 Included AMI NDIS Driver Reference in Windows Server 2019
under Chapter 21

3 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

29 13.4 July 19, 2022 Removed Secured Boot Chapter

Included Required Packages information and updated Note content
in SECURED BOOT SUPPORT Section of Secure Boot under
Chapter 20
30

31
13.4

13.4

E -
July 22, 2022 Updated Signed Hash Support Flow diagram and Note content in

August
Secure Boot under Chapter 20
01, Included JViewer Folder Redirection Support in KVM Configuration

R
2022 under Chapter 2
32 13.4 Oct 14, 2022 Included Conf corruption information in Recommended Factory
Configuration under Chapter 2
33 13.5

O T E
Oct 18, 2022 Updated the document version as 13.5

T Removed changeMouseAbs2Rel and Relative Mouse Mode from

Supported APIs under Chapter 14
34

35
N IBU
13.5

13.5
Jan 06, 2023

Jan 12, 2023

Updated Port number of uPnP Discovery Owner module in Port
Usage of APPENDIX
Included sol.conf file information in HTML5 based SOL Chapter 30

36

37
O13.5

R
D T 241
13.6 2
Jan 30, 2023

Oct 30, 2023

Included Chapter 34 Enable/Disable TCP Socket

Updated the document version as 13.6

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
4 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

TABLE OF CONTENTS
CHAPTER 1........................................................................................................................ 11
Introduction to MEGARAC® SP-X............................................................................................................. 11

E -
CHAPTER 2........................................................................................................................ 12
Project Configuration using MegaRAC Development Studio (MDS) ��������������������������������������������������� 12

R
SPX Package Configurator ...................................................................................................................... 12
Basic Configuration ................................................................................................................................................................................ 12

O T T E
SOC Configuration.................................................................................................................................................................................. 13
General Configuration........................................................................................................................................................................... 15
Component Management Configuration....................................................................................................................................... 22

N IBU
Features Configuration ......................................................................................................................................................................... 22
Dual Image Configuration.................................................................................................................................................................... 32

O
IPMI Configuration.................................................................................................................................................................................. 47

R
D T 241 2
Platform Configuration.......................................................................................................................................................................... 62
KVM Configuration.................................................................................................................................................................................. 62

S
Media Configuration ............................................................................................................................................................................. 70

I
D 30 8 1
Device Configuration............................................................................................................................................................................. 78

n
SMASH Configuration............................................................................................................................................................................ 81

a
Test Tools Configuration ....................................................................................................................................................................... 82

s h
Runtime Libraries Configuration ....................................................................................................................................................... 85

4 u
Development Kits Configuration....................................................................................................................................................... 88

0 1 h l e
Software Configuration ........................................................................................................................................................................ 89

a
b
User Management Configuration...................................................................................................................................................... 90

1 7 t i s
Recommended Factory Configuration ........................................................................................................................................... 91

v
n i
References ................................................................................................................................................................................................. 93

h a s h
CHAPTER 3........................................................................................................................ 94
MEGARAC® SP-X Package Architecture................................................................................................... 94

s da
Types of Packages................................................................................................................................................................................... 94
Package Naming Format....................................................................................................................................................................... 95

s a
Components of a Package................................................................................................................................................................... 96

CHAPTER 4......................................................................................................................112
SP-X Development – Hands On.............................................................................................................112

5 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

SP-X Package based stack – various components ��������������������������������������������������������������������������������������������������������������������112

SP-X Development – Hands-On.......................................................................................................................................................113

CHAPTER 5......................................................................................................................119

E -
SP-X Based Project Creation..................................................................................................................119

CHAPTER 6......................................................................................................................120
Application Package Creation...............................................................................................................120

T R
Prerequisites............................................................................................................................................................................................120

E
Makefile.....................................................................................................................................................................................................120

T
Using MDS SP-X package creator....................................................................................................................................................121

O
CHAPTER 7......................................................................................................................125

N IBU
Common Driver Package Creation........................................................................................................125
SP-X Package creation for a common driver module ��������������������������������������������������������������������������������������������������������������125

O
CHAPTER 8......................................................................................................................131

R
D T 241 2
Hardware Driver Package Creation.......................................................................................................131
SP-X Package creation for a driver module..................................................................................................................................131

I S
CHAPTER 9......................................................................................................................136

D 30 8 1 n
Library Package Creation.......................................................................................................................136

h a
SP-X Package creation for a library module.................................................................................................................................136
Using MDS SP-X package creator....................................................................................................................................................137

1 4 u s
CHAPTER 10....................................................................................................................143

e
SP-X Web Customization HTML5...........................................................................................................143

70 b h a l
webui_html5-src ...................................................................................................................................................................................143

n i i v s
webui_html5_libs-src...........................................................................................................................................................................154

1 t
Webui_Scaffolder..................................................................................................................................................................................155
Server-Side Processing of REST API.................................................................................................................................................177

h a s h
spx_restservice_ext.src........................................................................................................................................................................182

SP-X Web UI Customization for implementing Content Security Policy �������������������������������������������183

s da
Overview...................................................................................................................................................................................................183

a
CSP header and directives .................................................................................................................................................................183

s
SP-X Web Customization HTML5 Using i18next Plugin ��������������������������������������������������������������������187
i18n plugin migration to i18next.....................................................................................................................................................187

6 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Enabling favicon Customization in SPX Web UI HTML5 ���������������������������������������������������������������������191

Customization of Upload File Handler API in SP-X REST Service �������������������������������������������������������196

CHAPTER 11....................................................................................................................197

E -
Signing JAR Files.....................................................................................................................................197
Creating JAR Signing Key Store........................................................................................................................................................197
Creating Certificate Signing Request.............................................................................................................................................198

T R
Creating Certificate File.......................................................................................................................................................................198

E
Verifying Keystore (JAR Sign Key)....................................................................................................................................................199

T
Verifying Signed JAR Files...................................................................................................................................................................199

O
Re-signing JAR Files..............................................................................................................................................................................199

N IBU
References................................................................................................................................................................................................200

CHAPTER12.....................................................................................................................201

O
JDK Upgrade Guide................................................................................................................................201

R
D T 241 2
Things to be considered while upgrading JDK version ���������������������������������������������������������������������������������������������������������201
Procedure To Upgrade JDK................................................................................................................................................................202

I S
JViewer Binary Package Maintenance..................................................................................................210

1
Steps to build JViewer Binary Packages........................................................................................................................................210

D 30 8 n
a
Launching JViewer From Eclipse...........................................................................................................211

h
Debugging JViewer In Eclipse..............................................................................................................223

1 u s
CHAPTER 13....................................................................................................................226

4 e
IPMI Configuration.................................................................................................................................226

70 b h a l
LAN Configuration................................................................................................................................................................................226

CHAPTER 14....................................................................................................................227

1 n t i i v s
LibusbGadget Porting Guide.................................................................................................................227
References................................................................................................................................................................................................227

h a s h
Supported APIs.......................................................................................................................................227
SendKeybdData.....................................................................................................................................................................................228

s da
USB Port B Feature Support...................................................................................................................236
USB Port B Supported APIs................................................................................................................................................................239

s a
CHAPTER 15....................................................................................................................243
Reset Hardware Porting Guide..............................................................................................................243

7 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Helper Data Structures and Functions...........................................................................................................................................243

Common Data Structures and Interface Functions ������������������������������������������������������������������������������������������������������������������243
Initialization and Cleanup..................................................................................................................................................................244
References................................................................................................................................................................................................244

E -
CHAPTER 16....................................................................................................................245
Hardware Watchdog Usage...................................................................................................................245

T R
CHAPTER 17....................................................................................................................246
eSPI..........................................................................................................................................................246

E
Initialization and Cleanup..................................................................................................................................................................246

O
N IBU T
Helper Data Structures and Functions...........................................................................................................................................247
Common Data Structures and Interface Functions ������������������������������������������������������������������������������������������������������������������247

CHAPTER 18....................................................................................................................253

O
VGA Memory Size Configuration (AST2600)........................................................................................253

R
D T 241 2
CHAPTER 19....................................................................................................................254
Device Drivers.........................................................................................................................................254

I S
CHAPTER 20....................................................................................................................255

D 30 8 1 n
Secure Boot.............................................................................................................................................255

h a
PRJ Configuration..................................................................................................................................................................................255
ImageSigning Tool Configuration...................................................................................................................................................256

1 u s
Configuration Setting Description..................................................................................................................................................256

4
Multiplatform and FIT Image Support..................................................................................................261

e
70 b h a l
Kernel FIT Image Creation..................................................................................................................................................................265
Kernel Fit Image Flowchart................................................................................................................................................................266

1 t i s
Multiplatform Porting Guide.................................................................................................................267

n i v
CHAPTER 21....................................................................................................................272

h a s h
IPMI over USB Support...........................................................................................................................272
Pre-requisite............................................................................................................................................................................................272

s da
Configuration..........................................................................................................................................................................................272

CHAPTER 22....................................................................................................................295

s a
Built-in Core Level "Thermal Management Support" �������������������������������������������������������������������������295
Required Packages................................................................................................................................................................................295

8 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

PRJ Configuration..................................................................................................................................................................................295
Know Limitations/Issues.....................................................................................................................................................................296

CHAPTER 23....................................................................................................................297

E -
LAN and DRAM Test Support in U-boot................................................................................................297
Required Packages................................................................................................................................................................................297
PRJ Configuration..................................................................................................................................................................................297

T R
Known Limitations/Issues..................................................................................................................................................................298

E
CHAPTER 24....................................................................................................................299

T
LLDP Support..........................................................................................................................................299

O
Required Packages................................................................................................................................................................................299

N IBU
PRJ Configuration .................................................................................................................................................................................299
Known Limitations/Issues..................................................................................................................................................................300

O
CHAPTER 25....................................................................................................................301

R
D T 241 2
Automation Engine Support in HTML5 using Web UI ������������������������������������������������������������������������301
Required Packages................................................................................................................................................................................301

S
PRJ Configuration .................................................................................................................................................................................301

I
D 30 8 1
Known Limitations/Issues..................................................................................................................................................................302

a n
CHAPTER 26....................................................................................................................303

h
Hardware Encryption Support..............................................................................................................303

1 u s
AMI OPENSSL Engine Info..................................................................................................................................................................303

4
DTS and Kernel Configuration..........................................................................................................................................................303

e
70 b h a l
PRJ Configuration..................................................................................................................................................................................304
Packages Used in AMI Crypto Engine Support ��������������������������������������������������������������������������������������������������������������������������305

1 t i s
CHAPTER 27....................................................................................................................306

n i v
Multi-SOL Support..................................................................................................................................306

h a s h
PRJ Configuration..................................................................................................................................................................................306

CHAPTER 28....................................................................................................................308

s da
Precision Time Protocol IEEE 1588 Support.........................................................................................308
Required Packages................................................................................................................................................................................308

s a
PRJ Configuration..................................................................................................................................................................................308

CHAPTER 29....................................................................................................................310

9 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Boot Logo Support.................................................................................................................................310

Required Packages................................................................................................................................................................................310
PRJ Configuration..................................................................................................................................................................................310

-
CHAPTER 30....................................................................................................................313

E
HTML5 based SOL...................................................................................................................................313
Required Packages................................................................................................................................................................................313

T R
PRJ Configuration..................................................................................................................................................................................313

E
CHAPTER 31....................................................................................................................315

T
Customization Logo Support for HTML5..............................................................................................315

O
Required Packages................................................................................................................................................................................315

N IBU
PRJ Configuration..................................................................................................................................................................................315

CHAPTER 32....................................................................................................................317

O
BMC Version Format...............................................................................................................................317

R
D T 241 2
CHAPTER 33....................................................................................................................319
AST2620 SOC Build Guide......................................................................................................................319

I S
PRJ Configuration..................................................................................................................................................................................319

D 30 8 1 n
CHAPTER 34....................................................................................................................321

h a
Enable/Disable TCP Socket....................................................................................................................321
Enable TCP Socket ................................................................................................................................................................................321

1 4 u s
Disable TCP Socket ...............................................................................................................................................................................321

e
APPENDIX........................................................................................................................323

0 h l
Ports Usage.............................................................................................................................................323

7 b a
1 n i i v s
Index................................................................................................................................325

t
h a s h
s da
s a
10 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 1

E -
Introduction to MEGARAC® SP-X
R
This document details specification information about the features of the new core (SP-X) for Software

T E
Developers of AMI’s generic MegaRAC® SP firmware. This document, until and unless specified, confirms the
functionality on all the SoC (System On Chip) platforms listed in this document.

platforms.
O
N IBU T
Generic MegaRAC® SP-X core refers to the new core of AMI’s MegaRAC® SP firmware running on various SoC

SP and Service Processor terms are used interchangeably throughout this document to refer to AMI’s generic
MegaRAC® SP solution.

O R
D T 241 2
MegaRAC® SP-X, MegaRAC® SP, SP-X, SP-X Core and Generic MegaRAC® SP terms are used interchangeably
throughout this document to refer to AMI’s service processor firmware solution.
For details on supported SOC and features of AMI’s MegaRAC® SP firmware, refer SPX_User_Guide.

I S
SMASH-Lite functionality mentioned in this document may or may not be available in all versions of Generic
MegaRAC® SP. Please refer to the release notes of your firmware version for more details.

D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
11 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 2

E -
Project Configuration using MegaRAC

T R
Development Studio (MDS)

E
The project can be configured using MegaRAC Development Studio. The various configurations and a brief

O
N IBU T
description of these features are mentioned in this chapter. This chapter provides brief description of the
features specific to AST2600.
Select the required configuration from the left hand side menu. Features in the left hand side menu can be
expanded by clicking the icon. Enable the required features in the Configuration section. Enable/Disable
options are done by double clicking the specific feature. Similarly radio button selection is also done by double

O
clicking the particular feature.

R
D T 241
SPX Package Configurator 2
I S
Basic Configuration

D 30 8 1 n
The Basic Configuration can be done here. You can check or un-check to enable or disable supports. To change

a
the value of the configuration field, click the value column of the corresponding configuration and enter the
value. H represents hexadecimal value, I represents Integer, N represents Numeric value and S represents
string.

h
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
12 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
•
O R
D T 241 2
AMI OEM - Select OEM as AMI.
Basic Configuration

•
•
I S
ARM Compiler - Cross compiler for ARM buster (gcc 8.3.0 + glic 2.28).

D 30 8 1 n
AST2600EVB - It is used to select Platform
•
a
Core Version - Select the desired Base Package Set. SPX-13 AST2600 Supports following set.

h
s
• Kernel Version 5.X.X + U-Boot 20XX.XX

•
•

1 4 h u
Debian-Buster - Debian 10.0 Buster

l e
Disable Udev Support - Dummy package to disable Udev
•

70 b a
IPv6 Support - Enables the IPv6 support in SP-X firmware.

i s
•
•
1 n t
NTP Support - This package provides support for libntpconf library.

i v
Rebuild First Loader - This value is to select the rebuild of First Loader.
•
a h
Target Version - SysV Soft Float Target File System for ARM (armel) based on Debian 10.0.0 (Buster).

h s
s da
SOC Configuration

s a
The features of SOC Configuration are mentioned below. A sample screenshot of SOC Configuration is as
shown below.

13 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 SOC Configuration

S
• Flash Erase Block Size (hex) - Size of the memory block specified in the SOC datasheet.
•
•
•
I 8 1
Max Flash Banks - Maximum number of memory banks specified in the SOC datasheet.

D 30 n
Number of Network Interfaces - Number of network interfaces to be used in the platform.

a
Size of Boot Loader (hex) - Size of the Boot Loader excluding Environment area. Normally a multiple of

•
flash block size.

4 h
s
Size of Boot Loader Environment (hex) - Size of Boot Loader Environment. Normally one flash block

0 1 h u l e
size. Adding to the start address will yield the end address of boot Loader environment.
Start Address of Memory (hex) - Start address of SDRAM specified in the SOC datasheet.
•

7 i b s a
Start of Boot Loader Environment (hex) - Start Address of Boot Loader environment. Normally follows

1 t
the U-boot End address.
•
• n i v
Total Memory Size (hex) - Total size of SDRAM excluding size dedicated for VGA.

a h
Total Size of Flash (hex) - Entire size of Flash range, including all banks (if multiple banks are supported)
•

•
h
s da s
Total Size of the Used Flash (hex) - Usable size of the Flash area by the firmware image. Configured with
the Firmware image size.
Frame buffer driver support - Support of Frame buffer driver.
•
•
s a
LAN and DRAM test tool in uboot - Enable/disable to add hardware test tool in uboot.
Memory ECC Support - Supports ECC protection function, the overhead of memory size equals to 1/8
ECC protected memory size. Please make sure that the ECC configuration change (Enable to Disable or

14 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

vice versa) requires a hard reset of the BMC to ensure that the memory initialization is done accordingly.

• Number of SD Slots - Specify the number of SD slots

General Configuration

E -
The General Configuration of the SOC can be edited here. Most of the features can be enabled or disabled. The

T R
General Configuration features are as follows.

E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
•
1 n t i i v s General Configuration
Disable Ping Support - Used to disable ping support
•
•

h a s h
Baudrate for TTY to be used as console - Specify the baud rate to be used for the console.
Boot Configuration - Used for selection of ‘Faster Boot Support’ or ‘INITRD support’.
•

s da
Faster Boot Support - Bootloader which loads the kernel and root file system is directly accessed from
SPI and this leads to faster booting of the image. Please configure the ‘MAP’ section as shown below.

s a
15 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
S
General Configuration - Faster Boot Support
•

I
D 30 8 1
INITRD Support - Bootloader directly loads the kernel and initial root file system into memory and

n
then start the kernel passing in the memory address of the image. INITRD is the system image which

a
is made available in a special block device (/dev/ram). Please configure the ‘MAP’ section as shown

h
below.

1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
16 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
•
O R
D T 241 2
General Configuration - INITRD Support

Enable/Disable Advanced IP Routing - Enable/Disable Advanced IP Routing support

•
•
S
Default domain name - Specify the default domain name for DNS configuration.

I
D 30 8 1 n
Login Shell for Remote Terminal - Specify the shell to be launched on login in remote terminals like
SSH (Secure Shell), telnet, etc.
•
a
Prefix to be used for default host name (3 chars) - During the first power up of firmware, the default

h
hostname will be the string specified here followed by MAC address.
•

1 4 u s
Set default network config to DHCP - Enable if you want default network configuration as dhcp.Other-

e
wise it will be set to manual and cannot connect to device till it is enabled.
•

0 h l
TTY to be used console - Specify the serial port device name to be used as console.

7 b a
1 n t i i v s
h a s h
s da
s a
17 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Boot From eMMC

E -
T R EGeneral Configuration - Boot From eMMC Support
•
•
O T
HW Enabled Boot From eMMC - Enable SOC’s boot-from-eMMC feature

N IBU
Dual Images for HW Enabled eMMC BOOT - Make boot-from-eMMC image dual image

O R
D T 241 2
I S
D 30 8 1 n
•

h a Boot From eMMC Configuration

Conf Partition Size in eMMC - Conf partition size
•
•

1 4 u s
Dual Image Name for HW Enabled eMMC BOOT - The file name of dual MMC image

e
Include Kernel in MMC Image - Include kernel image uImage in /boot of root file system
•

0 h l
MMC Image Name - The file name of single MMC image

7 b a
•
•
1 i v s
MMC Root Partition Size - Root file system size

t
SD/eMMC Slot Selection - Slot number for eMMC

n i
a
• SD/eMMC Slot-2 - Define the partition number of root file system in eMMC

h s h
s da
s a
18 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Boot From SW-eMMC

1. Enable the SW MMC support in the PRJ.

E -
T R E
O
N IBU T
O R
D T 241
2. Select Boot Device.
2 PRJ Configuration - MMC Support

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h Boot Device Selection

s da
3. Including the Kernel Image in MMC image and Default Image Name is mmc.ima

s a
19 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
4. Configuring the mmc root partition size
MMC Image Name

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a lConfiguration - MMC Root Partition Size

1 t i s
5. Image component Sections

n i v
h a s h
s da
s a
20 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
Image Generated:
O
N IBU T Image Components Section

O
rom.ima – 4MB, (U-boot + Conf Section)

R
D T 241 2
mmc.ima – 162MB (kernel FIT Image+ FS + Web section)
Partition Size: 200 MB ( >170 MB)

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
21 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Component Management Configuration

The features of Component Management Configuration are mentioned below. A sample screenshot of
Component Management Configuration is as shown below.

E -
T R E
O
N IBU T
•
O R
D T 241 2 Component Management Configuration
Component Manager BMC Support - Enable/Disable component manager BMC support.
•

I S
Component Manager Support - Enable/Disable component manager support. Component Manager is a

D 30 8 1
centralized mechanism to monitor components like RAID, BIOS, CPLD and so on.

n
a
• Component Manager CPLD Update Support - This library package acts as an interface between compo-
nent manager and other services for CPLD.
•
•

4 h
Component Manager NVMe MI Support - Dummy package to help selected NVMe related packages.

s
Component Manager RAID/HBA Component Support - Dummy package to help selected RAID/HBA

1
related packages

0 h u l e
a
• NCSI Network Card Support - This library package acts as an interface between component manager

1 7 t b
and other services for NCSI network card whcih support MCTP.

i v s
a n
Features Configuration
h i
h s
The features configuration of the SOC can be edited here. Most of the features can be enabled or disabled. The

s da
features are as follows.

s a
22 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O
Features Configuration 1
•

• R
D T 241
configuration files.
2
Backup -Restore BMC Configuration Support - This package provides API’s for backup-restore BMC

Bonding Configuration – This feature allows the user to enable bonding configuration based on the

I S
number of Network interface, if the bonding is enabled by default.

1 n
DHCP Renewal Support upon Network Link-Up – This feature enables the IP Release/Renew support

D 30 8
upon link status.
•
a
Dynamic DNS Support - This feature allows user to register the hostname with DNS Server.

h
s
• Dynamically change OEM logo and copyright files - This option enables the support for dynamic Logo

1 4
and Copyright strings replacement for an already built image. Once enabled, the related utilities are built

u e
that could be used to replace the Logo and copyright strings, as required by the customers.

h l
•

70
Extended Log Area Support in SD/eMMC - This field is used to enable/disable the Extended log support

b a
(Firmware Upgrade Support to Fimware Flash support).

i s
•
•
1 n t
Fail-safe conf Support - This feature enables the fail-safe conf support in the SPX stack.

i v
File Override Support during Preserve Configuration - This feature allows user to override the specific

h a s h
section while upgrading the firmware using preserve configuration option.
Firmware Flash Support - This package includes the binary for Flasher application.
•

s da
Firmware Upload Protocol Selection - This feature enables the Firmware upload protocol selection sup-
port like TFTP (Trivial File Transfer Protocol), FTP (File Transfer Protocol).
•
•
•
a
I2C Standard Test Tool – This packages includes the binary for I2C test application.

s
Lib USB Gadget – Provides USB Gadget library support.
Lighttpd v1.4.45 – Provides WEB server for BMC Firmware.

23 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• Automation Engine - This module enables administrators to automate many BMC tasks.
• BMC Firmware Auto Recovery Support - BMC Firmware Auto Recovery support provides a mechanism
to retrieve the BMC image from network share or SD/eMMC and flash the image to BMC boot SPI when
image in BMC SPI is corrupted.
•
•

E -
Bootlogo Support - This package contains source to show bootlogo as a deamon.
Dual Image Support – The dual image feature supports more than one firmware images on SP for the
following reasons.
•
•

T R
Fail-safe booting

E
Multiple image choice selection
•

O T
Fail-safe booting requires having the same or different image existing on another SPI (Serial Peripheral
Interface) flash part as a backup image that is used in case the first firmware image is corrupted and is un-

N IBU
usable. Basically, the firmware booting automatically switches to the backup image if the primary image is
found to be unbootable.

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
•

h a s h Features Configuration 2
MAC EEPROM - Enable/Disable MAC adress store to eeprom Support.
•
s da
Power Saving of using USB selective Suspend Support - The feature allows an USB device driver which
supports selective suspend to turn off the USB device it controls when the device is idle.
•
•
•
a
Runtime Feature Licensing Supoort - This package contains the application to manage feature licenses.

s
LLDP – System package that includes all the LLDP related system-level libraries.
Multicast DNS Support - This field is used to enable/disable multicast DNS support.

24 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• NET-SNMP Support - This option enables the SNMP interface in the SP-X stack.
• Network Bonding Support – This feature enables the bonding support in SP-X firmware.
• Network Time Protocol Server Support - This field is used to enable /disable the NTP (Network Time
Protocol) server support, if it is enabled the Network time protocol server support can be utilized in the

•
BMC.

E -
PHY Configuration Support - This feature allows user to configure the PHY settings like speed, duplex
etc.,
•

•
T R
Precision Time Protocol Server Support - Precise synchronization of clocks in measurement and
control systems implemented with technologies such as network communication and distributed objects.

E
Run Time Debug Messages Control Support - This option is used to enable/disable the run time control

•
O T
debug messages support.

N IBU
Services Configuration Support – This option enables the support for run-time configuration support
for various services offered by the stack. Once enabled, various configuration factors like interface, ports,
state (enabled/disabled) can be configured at run-time for the services like web, KVM (Kernel based Vir-

O
tual Machine) or VMedia.
•

• R
D T 241 2
Session Management support - This option is used to enable/disable the Session management for the
services in the BMC such as web, KVM, VMedia, SSH and telnet.
Single Port Application Support - This feature exposes only web ports outside of BMC which reduces

S
security risks. Webserver ports will be used to communicate video and media servers running inside
BMC.

I
D 30 8 1 a n
4 h
s
0 1 h u l e
1 7 t i b s a
a n h i v
h
s da s
•
s a Features Configuration 3
SNMP AEP Support - SNMP AEP Support Extension.

25 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• SNMP Get the Host Device Change Log - SNMP Get the Host Device Infomation.
• SNMP Get the Host Device Information - SNMP Get the Host Device Infomation.
• SNMP Hostname Extension - This option enables the SNMP (Simple Network Management Protocol)
hostname configuration settings available on SNMP interface
•
•

E -
SNMP Trap V2C V3 Support - This package is for snmptrap.
System debug log support - Enable system debug log feature support.
•

T R
TELCO rsyslog Library Support - This package includes function gets the system status and show to
rsyslog.

E
SNMP System Status Extension : This option enables the SNMP MIB library to return the system health

T
status like power and sensor status.
•
O
SNMP Template Extension - This option enables the SNMP template existence in the stack. Template

N IBU
itself doesn’t provide any functionality but can be used to add more SNMP extensions to expose other
information on SNMP interface.

O
• SPX REST Web Service/FASTCGI/Lighttpd – REST Web service implemented as FASTCGI. Supports

2
lighttpd.
•
• R
D T 241
SysLog Library Support - This feature enables the system log support.
syslogmonitor - This option enables the syslog monitoring at run-time in the SP-X stack.
•
•
I S
System Firewall Support - This feature enables the iptables firewall support.

1 n
Thermal Management Support – It contains the thermal management application.

D 30 8
•

a
Timeout Daemon Support - This feature enables the timeout daemon to monitor the timeout values for

h
the services like web, ssh, telnet etc.
•

4
support.

1 u s
Timezone Configuration Support - This option is used to enable/disable the Timezone configuration

e
•
•

70 b h a l
U-Boot Memory Test - U-boot Memory test to verify the RAM Memory area.
Uart Mirroring & Logging - This package provides functionality for Mirroring 2 UARTs and also log the
UART data.

1 n t i i v
DHCP Monitor Configurations
h a s h
The features of DHCP Monitor Configuration are mentioned below. A sample screenshot of DHCP Monitor
Configuration is as shown below.

s da
s a
26 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
•
O R
D T 241 2
DHCP Monitor Configuration
Ignore link down event in DHCP monitor - DHCP (Dynamic Host Configuration Protocol) Monitor
will not release the IP when link down event occurs in an interface, if this option is enabled.

Backup/Restore BMC Configurations

I S
D 30 8 1
The features of Backup/Restore BMC Configurations are mentioned below. A sample screenshot of Backup/

n
Restore BMC Configurations is as shown below.

h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a Backup/Restore BMC Configurations

27 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• BACKUP_CONFIG_SPACE
• Support to store backup file in SPI - This option is used to enable/disable backup file store into SPI
Memory.
• Support to store backup file in SD/eMMC card - Enables backup file storage in SD/eMMC card

DNS Configuration

E -
The features of DNS Configuration are mentioned below. A sample screenshot of DNS Configuration is as
shown below.

T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a DNS Configuration
•

4 s
Periodic DNS Update Support - This feature updates DNS once in a day using cronjob.

1 u e
l
• TSIG Authentication Support - This option is used to enable/disable TSIG (Transaction Signature) Au-

70 i b h
thentication for dynamic DNS (Domain Name System) support.

s a
1 t
Flasher Configuration

n i v
a
as shown below.

h s h
The features of Flasher Configuration are mentioned below. A sample screenshot of Flasher Configuration is

s da
s a
28 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T Flasher Configuration
•

•
O R
D T 241 2
Full Firmware Upgrade with Version Comparison Flash - This feature is used to avoid flashing of mod-
ules when module versions are same.
Prepare Image Flash Init Timeout - Maximum timeout value that BMC can take for preparing the de-

S
vice to flash mode (Web Preview Support to Remote Console Preview Support).
•

I 1
Section Based Flashing Support - This feature enables Section Based Flashing support. This allows user

n
to flash selective modules like WWW instead of flashing whole image. This support cannot be enabled

D 30 8 a
when “Secured Boot Support” is enabled.
•

4 h
Secure Boot Support - This support validates non-JFFS2 sections of image before Booting. By de-

s
fault U-Boot section is not verified, but to include U-Boot in validation see Secure Boot Configuration.
When Secure Boot Support is enabled with Dual Image Support, ensure that Fail Safe Booting Support

1 h u l e
(FEATURE_HW_FAILSAFE_BOOT) and Use Dedicated Flash Bank (FEATURE_DEDICATED_SPI_
FLASH_BANK) are also enabled.

0
•

1 t b s a
Note: Secure boot support will increase boot time of about 50sec.

7 i
Signed Hashed Image Support - The purpose of the signed image support is to verify the Build Image

n i v
security and Integrity in the field.The Build image integrity is validated when the image is flashed via We-
bUI. When the image fails verification when flashing, then the image may be corrupted at any point from

a h
building the rom.ima to flashing it in the Server.
•

h s
Secure Boot encryption support - Enabling this support booting from sections of image which encrypt

s da
via AES 256.
Note: Secure boot support will cause an increase of about 7 min to boot time when image type is inint RD.

s a
Secure Boot Configuration
The features of Secure Boot Configuration are mentioned below. A sample screenshot of Secure Boot
Configuration is as shown below.

29 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T Secure Boot Configuration

O
• Enable UBoot Validation-
Validation- Selecting this option will include U-Boot section in the Secure Boot Support

2
signature validation.

R
D T 241
Default Bonding Configurations
The features of Default Bonding Configurations are mentioned below. A sample screenshot of Default Bonding

I S
Configurations is as shown below.

D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da Default Bonding Configurations
•
•
•
a
Default bonding mode

s
both - Selects both eth0 and eth1 as active slave for the bonding
Eth0 - Selects eth0 as active slave for the bonding

30 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• Eth1 - Selects eth1 as active slave for the bonding

Extended Log Configuration

The features of Extended Log Configuration are mentioned below. A sample screenshot of Extended Log

-
Configuration is as shown below.

R E
O T T E
N IBU
O R
D T 241 2
I S
D 30 8 1 n
•
h a
Extended Log Medium Selection
Extended Log Configuration

•
SPI.

1 4 u s
EXTENDEDLOG storage medium is SPI - If the storage medium of extended log is selected as as

e
•

0 h l
EXTENDEDLOG storage medium is SD/eMMc - This feature stores extended log in SD/eMMC.

7 b a
•
•
•
n i i v s
Fail-safe extended log area support - This option is used to enable/disable the backup extlog support.

1 t
Log IPMI command data - This option to enable log for IPMI command data
Log IPMI Command Selection
•

h a s h
All Command control - Log all the IPMI commands to the extended log
•

s da
Individual Command control - Log selected individual commands to the extended log.The com-
mands can be selected/customized in the libipmipdkcmds-src/data/cmdselect.c.The third argument
in the structure would define where the commands will be logged.
•
•
s aBit0 - Log into Extended Log
Bit1 - Log into Volatile memory inside /var/log

31 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• Bit2 - Log the Response into Extended Log

The bitmap macros have been defined in ipmipdk_dev-src/data/cmdselect.h
Below commands are available in cmdselect.c
•
•

E -
Get Chassis Status (CMD_GET_CHASSIS_STATUS) will be logged into /var/log
Add Sel Entry (CMD_ADD_SEL_ENTRY) will be logged into extended log
Steps to add commands for Individual Command Control - Individual command can be enabled/disabled
using the below tables.

T R E
6. The first entry denotes command number.
7. The second entry can be ENABLED or DISABLED.

can be
NONE
O
N IBU T
8. The third entry should be changed only if logging of “IPMI command support” is enabled. The third entry

- Command will not be logged

O
EXT_REQ_LOG

R
D T 241
EXT_RES_LOG
VOL_REQ_RES_LOG 2
- IPMI command reqest will be logged into extended log (SD Card)
- IPMI command response will be logged into extended log (SD Card)
- Both request and response will be logged into /var/log

I S
D 30 8 1
To Enable/Disable the command “CMD_GET_CHASSIS_STATUS” should be added in table g_Chassis

n
which corresponds to its Net Function (0x00).
e.g,

h a
In table g_Chassis, {CMD_GET_CHASSIS_STATUS, ENABLED, VOL_REQ_RES_LOG}

4 u s
In table g_Storage, {CMD_ADD_SEL_ENTRY, ENABLED, EXT_REQ_LOG | EXT_RES_LOG}

1 e
•

0 h a l
Request Data - This is only applicable when all the IPMI commands logging is enabled. All the Request
data will be logged into the Extended Log

7 b
•

•
n i v s
Response Data - This is only applicable when all the IPMI commands logging is enabled. All the Re-

1 t
sponse data will be logged into the Extended Log.

i
Support to store IPMI SEL in Extended Log - This feature stores ipmi SEL in extended log area.

a h
Dual Image Configuration
h s
s da
Enabling Support
This feature can be enabled by selecting “Dual Image Support” under Features configuration. A sample

a
screenshot is displayed below.

s
32 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E Dual Image Support

O
N IBU T
The features of Dual Image Configuration are mentioned below. A sample screenshot of Dual Image
Configuration is as shown below.

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i
Conf Section Selection
i v s Dual Image Configuration

h a s h
This Configuration is used to select the Conf Section type. Two section types are available. One is Common
and other is Individual.

s da
Common Conf Section

s a
33 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T Common Conf Section
When Common conf is selected, both the images will share same area for the conf section. The conf section will
be present at the end of second image.
In this case, conf section will be allocated in runtime. The “Size of Conf ” field is used to determine the size

O
allocated for the conf section.
Note:

R
D T 241 2
Conf entries will not be present in image component section of PRJ. The default conf entries will be generated
dynamically by firmware during first boot.

I S
In this case, the size of the BMC image will be 31MB/62MB only. After flashing 2 images continuosly in the

D 30 8 1 n
SPI, rest of the 2MB/4MB SPI size will be used for conf sections.

a
Firmware layout of Common conf

h
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
34 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1
Individual Conf Section
n
Firmware Layout Of Common Conf

h a
When Individual conf is selected, conf section will be present within the image area. Primary and Secondary
images have their own separate conf section.

1 4 u s
Synchronize both conf is a feature which allows us to keep the conf sections of both images in sync.

e
70 b h a l
1 n t i i v s
h a s h Individual Conf Section

s da
This feature will be unlocked only when user selects both individual conf and fail safe conf feature. When Sync
conf feature is enabled, no extra section is added for backup conf. The conf section of inactive image will be

s a
mounted as backup conf for the running image.

Firmware layout of Individual conf

35 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
S
Firmware Layout Of Individual Conf

I
D 30 8 1 a n
Fail Safe Booting Configuration

4 h
When Primary image fails to boot, switching of secondary image can be done in 2 ways. They are

s
1. Hardware based Fail Safe reset

1 u e
2. Software based Fail Safe reset

0 h l
1 7 t i b s a
a n h i v
h
s da s
a
Fail Safe Booting Configuration

s
Hardware based Fail Safe reset
This feature requires Hardware support which can automatically switch the boot source from primary image to

36 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

secondary image if primary image fails to boot properly.

Note:

-
Hardware based fail safe reset can work when image on 1st flash is corrupted or 1st flash is broken cases.

E
For Hardware based fail safe reset, the location of the secondary firmware should be present in a Dedicated
SPI mode. Please verify with SOC documents for the SPI selection details. (USE DEDICATED SPI feature for

R
secondary image location and configure the proper SPI number (which can vary based on SOC)). Secondary
image location is not needed for Single SPI ABR mode.

T E
Limitation:

T
For Dedicated SPI mode, both primary and secondary SPI should be of same type and same size. It is recom-

O
mended to use SPI from same manufacturer.

N IBU
Software based Fail Safe reset

Note:
O
When this feature is selected, Both Primary and secondary image will share same Boot Loader. When primary

R 2
image fails to boot, Boot loader will try to boot from the secondary image.

D T 241
S
As Boot loader is taking the role of switching the Image, this feature will not work when Boot loader is cor-
rupted.

I
D 30 8 1 n
This Feature is to provide a way to support Dual Image for the SOC’s which doesn’t have hardware support to
switch the Boot source.

a
4 h
s
Secondary Firmware Image Location selection

1 u l e
Primary image will be always flashed to first BOOT SPI. But the location of the secondary image will be based

0 h
on the Feature requirements or Hardware requirements.

1 7 t i b s a
SP-X firmware provides the following options to configure the Secondary image location.

Use Contiguous Memory

a n h i v
If this feature is enabled, secondary image will be flashed immediately after the end of the primary image. A
sample screenshot is displayed below.

h
s da s
s a
37 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
Note:

T R E
Use Contiguous Memory

O T
Customers with single large flash bank or multiple smaller flash banks (bank size may be smaller than im-
age size as it will be considered as single large virtual flash bank) can use this feature to achieve dual image

N IBU
functionalities.
This feature is available only along with software based fail safe booting which is described in following sec-

O
tions.

R
D T 241
Use Dedicated FlashBank 2
I S
If this feature is selected, then secondary image will be flashed in SPI which is configured in “SPI for Secondary
Image”. The value for “SPI for secondary image” can be 1 to maximum flash banks – 1 (This is because, it is 0

1 n
index value and SPI 0 will be always allocated for primary image.) A sample screenshot is displayed below.

D 30 8 h a
1 4 u s e
70 b h a l
1 n t i i v s Use Dedicated FlashBlank
Note:

h a s h
This Features requires at least 2 flash banks of same type.

s da
Size of the flash banks must be greater than or equal to the size of the image.
Customers who want to keep 2 images in different SPI can use this feature.

s a
Use Single SPI ABR (Only for AST2600)
If this feature is selected, then Single SPI flash will split into two parts of same size. The secondary image will

38 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

flash into upper part of SPI Flash. A sample screenshot is displayed below.

E -
T R E Use Single SPI ABR
Note:

O
N IBU T
Customers with single large flash bank can use this feature to achieve dual image functionalities.
Size of the flash bank should be greater than or equal to the size of both images.

tions.
O
This feature is available only along with hardware-based fail-safe booting which is described in following sec-

R
D T 241 2
Feature Compatibility Matrix

I S
This section explains the various possible combinations of the above-mentioned features. Customer can select
any one of the combinations based on their requirements.

D 30 8 1 n
S.NO FAIL SAFE
1 HW FAIL
h a SPI
DEDICATED
CONF
INDIVIDUAL
FEASIBILITY COMMENTS
YES

2
SAFE
HW FAIL

1 4 u s DEDICATED

e
INDIVIDUAL - YES

3
SAFE

70
HW FAIL
SAFE

b h a l
SINGLE SPI
ABR
SYNC
INDIVIDUAL YES Single SPI
ABR ap-

1 n t i i v s plicable for
AST2600
alone
4

5
h a
HW FAIL
SAFE
SW FAIL
s h SINGLE SPI
ABR
DEDICATED
INDIVIDUAL -
SYNC
INDIVIDUAL
YES

YES

6
s da
SAFE
SW FAIL DEDICATED INDIVIDUAL - YES

a
SAFE SYNC
7 SW FAIL CONTIGUOUS COMMON YES

sSAFE

39 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

S.NO FAIL SAFE SPI CONF FEASIBILITY COMMENTS

8 SW FAIL CONTIGUOUS INDIVIDUAL YES
SAFE
9 SW FAIL CONTIGUOUS INDIVIDUAL - YES

-
SAFE SYNC

Online Flash

R E
Online flashing is the mechanism of updating the firmware without stopping any of the current running

O T T E
process. In normal flash, while preparing the BMC for firmware update, all the running process will be killed
except the one used for flashing.
With the help of online flash, we can flash the image without terminating any process.

Note:
N IBU
O
Online flashing is applicable only when the firmware has following configurations

R
D T 241 2
Dual image with common conf should be enabled
Initrd support should be enabled

S
Please refer flasher design document for detailed explanation of Online flashing procedure.

I
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s Online Flash

h a s h
s da
Web Configuration
The Features of Web Configuration are as shown below.

s a
40 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
•
•
O
N IBU T Web Configuration
Save SEL log via web – Enables/Disables the Save SEL log feature in Web-UI.
Set Sensor Thresholds Via WEB – Enables/Disables the set sensor threshold in Web-UI.
•
•
•
O
Use HTML5 SOL Agent - Use the sol agent for HTML5 SOL.

R
D T 241 2
Use mod_websocket - It is used for the mod_websocket plugin for Lighttpd.
Web Session Timeout (Seconds) – Timeout value of web session. This is an Integer value.

I S
Web Language Configuration

D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
•
s a
Default Language Settings
•
Web Language Configuration

HTML5 Simplified Chinese Web user interface.

41 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• HTML5 Traditional Chinese web user interface.

License Configuration
The features of License Configuration are mentioned below. A sample screenshot of License Configuration is
as shown below.

E -
T R E
O
N IBU T
O R
D T 241 2
•

I S 1
License Configuration
KVM license support - Enables/Disables license control for KVM feature.

D 30 8 n
•
•

h a
LMEDIA license support - Enable/Disable local media license support.
If not selected then MEDIA license will be applicable for lmedia also.
•

1 4 u s
If selected then separate LMEDIA license need to be applied. Also the LMEDIA license will be appli-
cable for media also (like cdserver, vmapp, etc.,). There is no need for MEDIA license (optional).

e
•
•

7 b h a l
Media license support - Enable/Disable license support.

0
RMEDIA license support - Enable/Disable remote media license suport.

1
•
•
t i s
If not selected then MEDIA license will be applicable for lmedia also.

n i v
If selected then seperate RMEDIA license need to be applied. Also the RMEDIA license will be appli-

h a s h
cable for media also (like cdserver, vmapp, etc.,). There is no need for MEDIA license (optional).

License Encryption Key

s da
The features of License Encryption Key configured in PRJ are used for Encryption/Decryption of license. A
sample screenshot of License Encryption Key configuration is as displayed below.

s a
42 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T License Encryption Key

O
This feature is enabled only when “Run Time Licensing Support” is enabled. After configuring key value

2
‘licensegentool’ must be compiled before generating the License to use the configured key.

R
D T 241
Processmanager Configurations

I S
D 30 8 1
The features of Processmanager Configuration are mentioned below. A sample screenshot of Processmanager

n
Configuration is as shown below.

h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
•
s a Processmanager Configuration
Enable/Disable Memory Monitoring Feature - Enable/Disable memory monitoring of registered pro-
cesses by proc manager.

43 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• Enable/Disable Refreshing hardware watchdog Periodically - This enables/disables Refresh watchdog

periodically feature.
• Process Manager Polling Interval(Seconds) - Time interval for polling process presence in seconds
•

-
Stop OOM-Killer to kill processes when out-of-memory situation occurs - If enabled, OOM-Killer will
not kill any process if out of memory situation occurs.

E
System Firewall Configuration

R
The features of System Firewall Configuration are mentioned below. A sample screenshot of System Firewall
Configuration is as shown below.

T E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
System Firewall Configuration
•

0 h l
Firewall Timeout Support - Enable System Firewall Timeout Support.

7 b a
•

1
0524)

n i
Enable Blocking ICMP Timestamp request - Enable Blocking ICMP Timestamp Request (CVE1999-

t i v s
UART Mirroring Configurations

a h
The features of UART Mirroring Configurations are as shown below.

h s
s da
s a
44 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
•
O
N IBU T UART Mirroring Configuration
Do you want to Log the Host Serial Data ? - Enabling this feature will start logging the serial data from
UART Source Device to a file in BMC. By default UART data will be logged to a user configured Remote

•
•
O
Share,if “Extended Log” support is not enabled.

R
D T 241 2
Enable Memory Buffering - Enable this feature to support memory buffering.
Enable Mirroring from one UART to another UART - Enable this feature to start mirroring from

S
Source-Device to Destination-Device.
•
•
•
I 8 1
Number of Log File in storage - Number of Log File in Local or Remote Storage.

D 30 n
Size of Serial Data Log File in bytes - Maximum size of the Serial data Log File in bytes.

a
UART Source Device - The UART device given here will be used as source of serial-data for Logging/

•
Mirroring.

4
UART_LOGGING_STORAGEh
s
•

0 1 h u l e
Stores the Host Serial data in Remote Location - Enable serial data storage in Remote Location
•

1 7 b a
Stores the Host Serial data in BMC - Enable serial data storage in SPI.

t i s
n
SNMP Configuration

a h i v
The features of SNMP Configuration are as shown below.

h
s da s
s a
45 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T SNMP Configuration

O
• SNMP USER DEFINED COMMUNITY STRING - This option is used to Enable or Disable user de-

2
fined Community String.
•

R
D T 241
SNMP V1/V2C Support - This configuration enables SNMP v1/v2c support. SNMP v1/v2c is not se-
cured and should be enabled only on need basis.
•

S
SNMP V3 USER DEFINED ENGINE ID FORMAT - This option is used to Enable or Disable the format

I
D 30 8 1
of Engine ID which is stored in snmp_user.conf file.

n
Timeout Configuration
h a
1 4 u s
The features of Timeout Configuration are as shown below.

e
70 b h a l
1 n t i i v s
h a s h
s da
s a Timeout Configuration

46 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• Telnet/SSH Session Timeout (Minutes) - Number of Minutes of Inactivity to close the Telnet/SSH ses-
sion

IPMI Configuration

-
The features supported in IPMI such as interface support can be enabled or disabled by double-clicking the
required checkbox. To change the value of the configuration field, click the value column of the corresponding

E
configuration and enter the value. The list of libraries are mentioned below.

T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
•

h a IPMI Configuration 1
IPMI AMI OEM Net function command Support - It is used to enable the AMI OEM Net Function

•
Related commands.

4 u s
IPMI SSIF Support – SSIF interface acts as an in-band communication on SMBUS . It defines how IPMI

1 e
0 h l
messages can be transmitted to and from BMC on SMBUS. Enabling this interface will enable single SSIF
interface which can be configured using IPMI.conf.

7 b a
•

• i s
Multi SSIF support - Enabling this will allow user to configure three SSIF interfaces using IPMI.conf and

1 t
upto a total of 7 interfaces using OEM PDK Hooks.

n i v
IPMI Block Transfer Support (BT) – The block transfer interface provides a higher performance system

a h
interface option. Unlike the KCS (Keyboard Controller Style) interface, a per-block handshake is used
for transferring data across the interface. The BT interface also provides an alternative to use a controller

h s
with a built-in KCS interface. Enabling this interface will enable the Block Transfer Support in SPX IPMI.
•
s da
IPMI DCMI Support – DCMI (Data Center Manageability Interface) is used for Internet Portal servers.
The DCMI specifications define standardized, abstracted interfaces to the server management subsystem

• a
specific to Data Center Servers. These specifications are built upon the IPMI) 2.0 specifications. Enabling

s
this interface will enable the DCMI Support in SPX IPMI.
IPMI Serial Interface Support - The Serial Interface specifications define how IPMI messages can be sent
to and form the BMC via a direct serial. The IPMI messages are encapsulated with minimal additional

47 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

framing and escaping for transport over a serial connection. Enabling this interface will enable the Basic
Mode Serial Interface in SPX IPMI.
• IPMI Serial Terminal Interface Support - The Serial Interface specifications define how IPMI messages
can be sent to and form the BMC via a direct serial. Terminal Mode defines how IPMI messages can be

-
transferred using printable characters. It also includes a limited number of English ASCII text commands
for doing such things as getting a high level system status and causing a system reset or power state

E
change. Enabling this interface will enable the Terminal Mode Serial Interface in SPX IPMI.
• IPMI SOL Support - Serial Over LAN interface is used for the redirection of baseboard serial controller

IPMI.

T R
traffic over an IPMI session. This can be used to enable asynchronous serial-based OS and pre-OS com-
munication over a connection to the BMC. Enabling this interface will enable the SOL Support in SPX

E
T
• IPMI Support – This feature enables the library layer of IPMI which contains intermediate API’s to com-

•
O
municate with IPMI.

N IBU
IPMI USB Support - Universal Serial Bus interface is used for flashing BMC Firmware. Tools such as
yafuflash communicates via USB to USB Interface in IPMI. Enabling this interface will enable the USB
Support in SPX IPMI.
•
• O R
D T 241 2
OEM Proprietary Level Support - Enable OEM Proprietary level support for user and lan Channel.
Remote BIOS Control using IPMI command Support - This Package Contains the BIOS Remote Con-
trol feature related IPMI Commands.
•

• S
SSH Server Configuration Support - This Package Contains the SSH Configuration related IPMI Com-
mands.

I
D 30 8 1 n
User Password Encryption Feature – The user passwords stored in IPMI are encrypted using openssl

h a
AES CBC 256 algorithm if this support is enabled.
IPMI Command to read BIOS Post Code Support - Support to read the BIOS Post codes using IPMI-

•
Command.

1 4 u s e
IPMI Sensor Threshold Across Resets Support - This package contains the library for IPMI command

7 b h a l
to set sensor threshold across resets.

0
REST Interface IPMI Command - This package contains the library for IPMI command to set sensor

•
i v s
threshold across resets.

1 t
Sensor Monitor Interval in Seconds - IPMI Sensor Monitor Interval in seconds.

n i
a h
• Timeout for Network restart after set lan command - No. of seconds to wait for network restart after set
lan parameter command is received.

h
s da s
Configuration Flushing Support

a
The features of Configuration Flushing Support are as shown below.

s
48 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
• O
N IBU T Configuration Flushing Support
Watchdog Timer Configuration Flushing - Enable/Disable flushing of WDT configurations to NVRAM.

IPMB Configuration

O R 2
The features of IPMB Configuration are as shown below.

D T 241
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
•

h a s h IPMB Configuration
Disable I2C Bus recovery for IPMB Buses - Disable I2C Bus recovery for IPMB Buses.

s da
SOL Configuration
The features of SOL Configuration are as shown below.

s a
49 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T SOL Configuration
•

O R 2
Number Of SOL Serial Ports - This field is used to configure number of SOL Serial ports.

D T 241
S
Interface Specific Message Handling Support

I
D 30 8 1
The features of Interface Specific Message Handling Support are as shown below.

a n
4 hs
0 1 h u l e
1 7 t i b s a
a n h i v
h
s da s Interface Specific Message Handling Support
•

s a
Interface Specific Message Handling Support - This feature enables interface specific message handling
support. All the interfaces have their own message handlers instead of a common one.

50 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Internal Sensor Support

The features of Internal Sensor Support are as shown below.

E -
T R E
O
N IBU T
O R
D T 241 2 Internal Sensor Support

S
• Internal Sensor Support - Internal Sensors are nothing but the sensors use to know status of SEL reposi-

I
tory size(100%/75%,Full), Watchdog Timeout/Pre-Timeout actions based on the event logged etc. This

D 30 8 1 n
option also require SDR for appropriate Sensors. It is recommended not to disable this feature. Disable
this feature will block logging SEL events for internal sensors(SEL, Watchdog, etc.,). This feature enables

a
Internal Sensor Support such as SEL Capacity Sensor etc in IPMI.

4 h
s
1 h u
IPMI Configuration Directory Path

l e
The features of IPMI Configuration Directory Path are as shown below.

0
1 7 t i b s a
a n h i v
h
s da s
s a
51 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T IPMI Configuration Directory Path
•

O
Path Prefix for IPMI configuration file - IPMI configuration file can be stored in the configured direc-
tory path.

R
D T 241 2
I S
IPMI Interface Thread Priority

D 30 8 1 n
Listed below configurations are used to set the thread priority for each interface. Based on the thread priority,
the threads are initiated in the BMC.

h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
•
s a
BT Interface Thread Priority
IPMI Interface Thread Priority

52 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• Set BT Interface priority as High - This feature enables BT Interface priority as High.
• Set BT Interface priority as Normal - This feature enables BT Interface priority as Normal.
• SSIF Interface Thread Priority
•
•

E -
Set SSIF Interface Thread priority as High - This feature enables SSIF Interface priority as High.
Set SSIF Interface Thread priority as Normal - This feature enables SSIF Interface priority as Nor-
mal.
•
•

T R
IPMB Interface Thread Priority

E
Set IPMB Interface priority as High - This feature enables IPMB Interface priority as High.

T
• Set IPMB Interface priority as Normal - This feature enables IPMB Interface priority as Normal.
•
•
•
O
KCS Interface Thread Priority

N IBU
Set KCS Interface priority as High - This feature enables KCS Interface priority as High.
Set KCS Interface priority as Normal - This feature enables KCS Interface priority as Normal.
•
•
•
O
D T 241 2
LAN Interface Thread Priority

R
Set LAN Interface priority as High - This feature enables LAN Interface priority as High.
Set LAN Interface priority as Normal - This feature enables LAN Interface priority as Normal.
•
•
I S
Serial Interface Thread Priority

D 30 8 1 n
Set Serial Interface priority as High - This feature enables Serial Interface priority as High.

•
•

h a
Set Serial Interface priority as Normal - This feature enables Serial Interface priority as Normal.
Thread Priority for IPMI interfaces - Enables the feature to assign the thread priority to IPMI interfaces

1 4 s
like LAN, IPMB, and etc.,

u e
UDS Interface Thread Priority
•

70 h a l
Set UDS Interface priority as High - This feature enables UDS Interface priority as High.

b
•
•

1 i v s
Set UDS Interface priority as Normal - This feature enables UDS Interface priority as Normal.

t
USB Interface Thread Priority

n i
a h
• Set USB Interface priority as High - This feature enables USB Interface priority as High.
•

h s
Set USB Interface priority as Normal - This feature enables USB Interface priority as Normal.

s da
SEL Configuration

s a
The features of SEL Configuration are as shown below.

53 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
•
O R
D T 241 2 SEL Configuration
Extended SEL record support - Enables Extended SEL record support. This support helps in logging SEL

•
Commands.

I S
entries that are larger than standard IPMI SEL Size.The SEL entries are added using separate AMI OEM

D 30 8 1
Extended SEL Space:
n
•
a
Extended SEL storage in SPI - Enables Extended SEL storage to SPI.

h
s
• Extended SEL storage in SD/eMMC card - Enables Extended SEL storage to EMMC/SD card
•

1 4 h u
Move Extended SEL to Extlog Partition - Move Extended SEL to extlog Partition

l e
0
• SEL flushing in the background support - This support enables writing of SEL entries to SPI in back-

•
7 t i b s a
ground. This helps in faster command response time.
Circular SEL Policy Support – This option enables the Circular SEL support i.e new SEL record will be

1
•
n i v
added at the beginning of SEL repository like round-robin if the SEL repository is full.
Disable PEF action for AddSEL command – This feature disables PEF (Platform Event Filter) action

a h
when SEL Entry is added via Add SEL Command in IPMI.
•
h s
Logging of SEL Timestamp Clock Sync Events - This option generates the pair of events correlating the

s da
timestamps for events occurring before and after the new clock value while executing Set SEL time IPMI
command.

s a
54 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

IPMI Response Auto Timeout

The features of IPMI Response Auto Timeout are as shown below.

E -
T R E
O
N IBU T
•
O R
D T 241 2 IPMI Response Auto Timeout
IPMI Command Response Timeout Support - This feature enables Response Auto Timeout feature for

S
IPMI Commands. Enabling this feature will limit the message processing time to a specific time (PRJ

I
configurable for each interface) and the message will not be processed beyond the timeout value. Either

D 30
IPv6 Configuration 8 1
of the completion codes 0xC0 or 0xC3, based on PRJ configuration, will be returned if a message pro-

n
cessing is stopped due to timeout. Otherwise the timeout is infinite.

a
hs
The features of IPv6 Configuration are mentioned below. A sample screenshot of IPv6 Configuration is as
shown below.

4
0 1 h u l e
1 7 t i b s a
a n h i v
h
s da s
s a
55 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
•
•
O R
D T 241 2 IPv6 Configuration
IPMI IPv6 SUPPORT – This feature enables IPV6 Support in IPMI.
IPMI LAN Parameter Configuration
•

I S
Support for both IPMI-IPV6 Compliance and AMI OEM LAN Parameters - It is used to enable

1 n
both Latest IPMI Spec defined and AMI OEM LAN Parameter.

D 30 8
•

a
Support for IPMI-IPV6 Compliance LAN Parameters - It is used to enable the Latest IPMI Spec

h
defined LAN Parameter alone.
•
sion 1.1.

1 u s
IPV6-IPMI 2.0 version 1.1 Compliance Support - Enables ipv6 compliance support for IPMI 2.0 ver-

4 e
0 b h a l
IPMI Configuration Version Check

7
1 t i s
The features of IPMI Configuration Version Check are mentioned below. A sample screenshot of IPMI

n i v
Configuration Version Check is as shown below.

h a s h
s da
s a
56 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T IPMI Configuration Version Check
•

O
Enable IPMI Configuration Version check – IPMI Configuration version is maintained in order to find

R 2
out the configuration mismatch with configurations in PMC. Enabling this feature validates the IPMI

D T 241
Configuration version with the CDF version of libipmipar package.

IPMI Send Message Response Header

I S
The features of IPMI Send Message Response Header are mentioned below. A sample screenshot of IPMI Send

1
Message Response Header is as shown below.

D 30 8 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da IPMI Send Message Response Header
•

s a
Prefix Send Message Command Header –This feature enables the send message response encapsulation
of origin header with destination header.
All successful send message requests have 2 responses. First response indicates the successful posting of message

57 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

to the destination and bears the originator IPMI header.

The second response is the actual response from the destination and it is asynchronous to the request. It bears
the destination IPMI header which is generated by BMC and the origin has no relationship to it.

-
This makes matching the destination response with request for the originator if same NetFn/Cmd is bridged
multiple times in short interval. Enabling this feature will prefix the originator header to the destination

R E
response, with which the originator can match it against the request.
Note: Most ipmi clients will not understand the send message responses prefixed with originator header.

Support for more than 256 sensors

T E
The features of Support for more than 256 sensors are as shown below.

O T
N IBU
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
Support for more than 256 sensors

l
• More than 256 sensors support - This extents support to more than 256 sensors.

70 i b h s a
1 n t
IPMI Thread Monitor
i v
a h
The features of IPMI Thread Monitor are as shown below.

h s
s da
s a
58 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T IPMI Thread Monitor
•

•
O
IPMI Thread Monitoring Support – Monitoring all the threads in IPMI Stack and restart the IPMI Stack

R 2
if any of the thread becomes unresponsive. This feature allows the user to enable the Thread Monitoring

D T 241
Support in SPX IPMI.
Timeout for IPMI Thread monitor (seconds) – No. of seconds to wait before restarting the IPMI Stack

DCMI Version
I S
in case of IPMI thread timeout.

D 30 8 1 n
a
The features of DCMI Version are as shown below.

h
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
•
s a DCMI Version
Additional Vendor Information - The Field Code as per DCMI 1.5 Specification is 0xF2.Optional ad-
ditional information for the vendor identified by field type 0x02.

59 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• DCMI 1.5 Support – Enable DCMI 1.5 Version Support - DCMI 1.1 is already present in SPX IPMI
(IPMI DCMI Configuration). DCMI 1.5 includes clarifications and corrections over DCMI 1.1. DCMI
1.5 also adds a Thermal Limit capability, refines options available with RMCP and DHCP discovery, and
improves access efficiency through support for reservation-less SEL and SDR access and the Get Temper-
ature Readings command. Enabling this feature will enable DCMI 1.5 Support in SPX IPMI.
•

-
Firmware Version Information - The Field Code as per DCMI 1.5 Specification is 0x03.Information
shall be encoded as 8-bit characters encoded per ISO/IEC 8859-1. Otherwise, the format and content is

E
specified by the vendor identified by field type 0x02.
•

•
information.

T R
Private IANA Number of Firmware Vendor - The Field Code as per DCMI 1.5 Specification is 0x02.
Firmware Vendor IANA. IANA Private Enterprise ID for the vendor providing the firmware version

E
Synchronize asset tag with IPMI FRU - Enabling this will Synchronize the asset tag information with
IPMI FRU

O
N IBU
User Password Encryption
T
O
The features of User Password Encryption are as shown below.

R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s User Password Encryption
•
•

h a s
Encoding Methodh
Default Password - This contains the Default password.

•
• s da
Encoding in Base64 Format - Enables Encoding Method in Base64 Format.
Encoding in HEX Format - Enables Encoding Method in HEX Format.
•

s a
Key for User Password Encryption - This Key can be used as encrypt/decrypt key for user password
encryption.

60 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• User Password Encryption Backward Compatibility - Enable/Disable to support Backward compatibil-

ity user password encryption.

Disable Password Change at First Login Support

E -
T R E
O
N IBU T
O R
D T 241 2 Disable Password Change at First Login Support

I S
This feature is made as hidden PRJ configurable, if OEM wants to disable Password change at first login then

1
they can add the PRJ Configration entry “FEATURE_DISABLE_CHANGE_PSWD_FIRST_LOGIN” in
P.CONFIG file.

D 30 8 n
h a
If this feature option is added and enabled then Password Change at first login will not be mandatory and

s
user login will be success with default password.

1 4 u e
“FEATURE_DISABLE_CHANGE_PSWD_FIRST_LOGIN” configuration will not be available in default

h l
70
core stack code.

i b s a
1 n t
Sample P.CONFIG entry added in ipmimain-src package

i v
h a s h
s da
s a
61 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Platform Configuration
This section helps to select the OEM (Original Equipment Manufacturer) IPMI customization packages such
as OEM Commands (libipmipdk cmds), Sensor porting/Default IPMI Configurations (libipmipar) and OEM
defined hooks(libipmipdk). The list of libraries are mentioned below.

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
Platform Configuration
•

0 h l
IPMI Platform Library for AST2600EVB Platform (Default Version) – This kit contains the dummy

b a
sensors and IPMI default Configurations ported for the platform AST2600EVB.

7
•
•
1 t i s
IPMI_PDK – This kit contains platform specific functionalities that needs to be customized.

n i v
IPMI_PDKCommands – This kit contains implementation of OEM IPMI commands.
•

a h
Platform Support Model – Enabling this feature supports multiple platforms in a single image/stack. The

h s
platform specific configurations are chosen at runtime based on the platform type.

s da
KVM Configuration

s a
The KVM related features like Video Server, Java Client and Auto Video recording can be configured here.

62 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T KVM Configuration 1
•

• O
Allow Multiple KVM sessions from same client - This feature allows more than one KVM session in the

R 2
same client other wise we can launch only one KVM session as default.

D T 241
Allow Non-Secure communication For KVM/Media - This option allows Non-Secure communication
for KVM. It should be disabled by default. This option should be enabled only when KVM performance

I S
matters more than security.

1
Auto Video Recording Support - This feature records host video when events are triggered in the BMC.

D 30 8 n
It stores the video in the BMC local path or configured remote path. Enable this option for Auto Video

a
Recording configuration. When the option is enabled, the Auto Video Recording Configuration is en-

h
abled under the KVM configuration in the left panel menu. Click Auto Video Recording Configuration
Double-click Remote Storage Space Support to enable/disable this support.
Configuration..

1 4 u s
Automatically lock the host screen upon JViewer Launch - This feature allows user to configure Auto-

e
matically OFF Local Monitor, when JViewer launch from web page. Depending on the selection from

70 b h a l
web page, host screen display will be locked automatically when JViewer is launched.
Capture BSOD as JPEG – This feature captures Blue Screen Of Death (BSOD) during the run-time criti-

• 1 n t i v s
cal stop error thrown by the Operating System. When this error occurs, the operating system generates a
System Event (OS stop event runtime critical stop) to BMC. The BSOD image is available as JPEG.

i
Capture BSOD as JPEG for RVAS - BSOD capture using RVAS (Pilot video engine) video driver.
•

h a s h
Extended Privilege Support - This option enables the extended privilege support for KVM/vMedia ser-
vices on specific users’ accounts. When enabled, individual user account can be configured at run-time to

• s da
have/not-to-have KVM or Media services.
HID initialization upon adviser restart - Enable this feature to initialize the HID device when ever the

•
a
KVM server restarts.

s
HTML5 KVM/Media feature - This package is used to select/deselect HTML5 KVM (H5Viewer). This
package contains files that provide the HTML5 framework for H5Viewer.

63 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• Ignore KVM Server Restart when Network change : Enable this feature to skip KVM Server Restart or
intimate KVM server when there is a change in network.
• Internal Video Library for AST – The package contains built video library.
• Internal Video Library for RVAS – This enables RVAS (Pilot Video Engine). This feature allows user to

-
redirect video using Pilot video engine.

E
T R E
O
N IBU T
O R
D T 241 2
S
Internal Video Library for RVAS

•
I 1 n
Java KVM Client Support - This feature allows user to control host machine through Java Client. User

D 30 8 a
can control video redirection in host from the client machine.
•
•
h
JavaClient - This feature is used to view the selected JViewer SoC package version.

s
JViewer for AST - This package contains the video encode/decoding functionality specific to AST

4 u
SOC with AST Video engine. This package should be selected for JViewer to perform video redirec-

0 1
tion.

h a l e
JViewer for RVAS - This package contains the video encode/decoding functionality specific to AST

1 7 tion.

t i b
SOC with RVAS video engine. This package should be selected for JViewer to perform video redirec-

v s
•

a n h i
Jviewer Single Stand Alone Application - This feature is used to select JViewer Single Stand Alone Ap-
plication support. If this feature is selected, the separate JAR files like JViewer_common, JViewer_OEM
and JViewer_SOC will be combined and generated as a single JAR file.

h
s da s
s a
64 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
•
O
N IBU T KVM Configuration 2
Physical KeyBoard Language Selection Support - Enable or Disable Physical KeyBoard Language selec-
tion feature.
•
O R 2
JViewer Folder Redirection Support - This feature redirects the client-side folder to the host-side as a

D T 241
virtual USB drive so the user can create new files, modify or delete the existed files in the USB drive. First,
converts the folder to a disk image and saves the image on the client-side.

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s KVM Configuration 2
•

a h
Rebuild Java Apps - If this feature is selected, JViewer source packages will be taken for building Firm-
ware. If this feature is not selected, JViewer binary packages will be taken for building Firmware.

h s
s da
Example:

Source Package Format: src.spx

JViewer_common-x.x.x.x.x.src
JViewer_common-x.x.x.x.x. .spx

s
Note: a
Binary Package Format: JViewer_common-x.x.x.x.x.ANY.spx
JViewer_common-x.x.x.x.x.ANY .spx

If warning message is displayed like “WARNING: Duplicate Binary Packages are observed” during

65 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

firmware BUILD, do the following.

If Rebuild Java Apps is selected, Keep only JViewer*, VMedia* related source packages in packages folder.
If Rebuild Java Apps is not selected, Keep only JViewer*, VMedia* related binary packages in packages
folder.
•

E -
Runtime Enable/Disable of Host lock command - This feature allows user to configure Local Monitor
OFF from web page. Depending on the selection from web page, host display can be locked/unlocked at
runtime from JViewer.

T R
Note: Automatically OFF Local Monitor, When JViewer launch option will be accessible only if Local
Monitor OFF option is enabled in web page.

E
Video Helper Library Support - - This option enables Video Helper Library Support.
•

• O
N IBU
these libraries.
T
VideoLibrary – The package contains built video library. Enable Java KVM client support to include

Video Library Support - This option enables Video Library Support.

O
KVM Session Management

R
D T 241 2
The features of KVM Session Management are mentioned below.

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h KVM Session Management

s da
• KVM Session Connection Retry Support - This Feature will allow KVM session to reconnect in case of
network connection failure.

a
• The time taken to detect network disconnect, and trigger websocket close event varies on different
web browsers and client platforms. So in H5Viewer, it cannot be always guaranteed that the reconnect

• swill be triggered exactly after a particular time interval, on all web browsers and all client platforms.
The rate at which the timer events are triggered and the timer count down is updated depends on the

66 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

processing load at that time in H5Viewer. This will lead to inconsistent timer countdown update.
Due to these limitations, we cannot implement the timer count down, and retry count down functionality in
H5Viewer.
• KVM Session maximum retry allowed - This feature allows to configure the maximum no of retries for

•
KVM session.

E -
KVM Session Retries Interval (seconds) - This feature allows to configure the time interval between the
retries.
•

T R
KVM Session Time Out Support - Enable/Disable the KVM Session Timeout Support. If the KVM is
Idle for the configured value, it automatically closes the active session.

E
KVM Session Timeout (Seconds) - Configured value is used for the timeout of the KVM session such

O
that idle time out.

N IBU T
Auto Video Recording Configuration
The features of Auto Video Recording Configuration are mentioned below.

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
•

70 b h a l Auto Video Recording Configuration

Post-Event Video Recording - Enable/Disable Post Event Video Recording feature.
•
•
1 t i s
Pre-Event Video Recording - Enable/Disable Pre Event Video Recording Feature.

n i v
Remote Storage Space Support - Enable/Disable Remote Storage space support for auto video recording

h a
feature.

s h
Pre-Event Video Recording Configuration

s da
The features of Pre-Event Video Recording Configuration are mentioned below.

s a
67 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T Pre-Event Video Recording Configuration
•
•
•
O
Enter Video Compression Mode - This field is used to configure the video compression mode.

R
D T 241 2
Enter Video duration - This field is used to configure the duration of the Video to record.
Enter Video frame Count/sec for Recording - This field is used to configure the frame count per sec-

S
onds.
•
ed.
I
D 30 8 1
Enter Video quality for Recording - This field is used to configure the Quality of the Video to be record-

KVM Default Configuration

a n
h
s
The features of KVM Default Configuration are mentioned below.

4
0 1 h u l e
1 7 t i b s a
a n h i v
h
s da s
s a
68 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T KVM Default Configuration
•
• O
D T 241 2
Auto Resize KVM Client Window - This feature resizes KVM Window to fit with Host Video resolution.

R
CD/DVD Image Redirection using Java - Enable or Disable CD/DVD image redirection using Java
implementation.
•
•
S
Keyboard LED Synchronization

I
D 30 8 1
board LED status.
n
Sync with client keyboard LED Status - Synchronize Host keyboard LED status with Client key-

h a
Sync with Host keyboard LED Status - Synchronize Client keyboard LED status with Host keyboard
LED status.
•

1 4 u s
Redirect device Always in Read and Write mode - This feature allows user to redirect HDD Device /

e
Image as read and write always. Read only HDD Device/Image redirection will be blocked.

70 h l
Note: CD/DVD Device/Image redirection will be always READ Only.

b a
•

1 i s
Skip Repositioning JViewer Window to top left corner:

t
corner: By default this option will be unselected. This
option will be present under KVM Configuration -> KVM Default Configuration, as shown in the picture
below.

n i v
•

h a h
If this option is Disabled, JViewer windows will move to the top left corner of the current monitor
inorder to make jviewer window accessibility better. On host resolution change, fit to host resolution

s
(or) fit to client resolution, mouse mode change and virtual media dialog open/close.
•
s da
If this option is Enabled, JViewer window will be remained in the same position at which it is located.
It will not move to top left corner of the current monitor.

a
Note: JViewer window accessibility may not be better.

s
69 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Physical Keyboard layouts

This feature allows user to set JViewer default physical keyboard layout.

E -
T R E
O
N IBU T
•
O R
D T 241 2 Physical Keyboard Layout
KeyBoard Language Selection Support - This feature allows user to set JViewer physical keyboard lay-
out language based on the selection made in PRJ.

I S
• Auto Detect Keyboard Language - This feature sets the JViewer physical keyboard layout lan-

1
guage automatically.

D 30 8 n
h a
• English-US (US) - This feature allows the user to set the JViewer physical keyboard layout lan-
guage in English (US).

s
• French-France (FR) - This feature allows the user to set the JViewer physical keyboard layout

4
language in French (FR).

1 u e
l
• German-Germany (DE) - This feature allows the user to set the JViewer physical keyboard layout

70 i b h
language in German (DE).

a
• Spanish-International Sort (ES) - This feature allows the user to set the JViewer physical key-

s
1 n t
board layout language in Spanish (ES).

Media Configuration
i v
a h
The media servers such as CD, HD, SD and RD Servers can be enabled or disabled here.

h s
s da
s a
70 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
• O R
D T 241 2 Media Configuration
CD/DVD ROM Device Support - This feature includes support for CD/DVD ROM media redirection
support. CD server handles request from KVM client and sends response back to client and manages CD

I S
redirection sessions.

1
Configure KVM Client media instance count - Enable this feature to configure maximum media in-

D 30 8
stance for KVM clients.

n
•
a
Dedicated media instances for lmedia, rmedia - Enable the feature to use the dedicated devices for lme-

h
dia, Rmedia and JViewer. Disable this option to emulate the configured devices and use across JViewer,

•
LMedia and RMedia.

1 4 u s e
Dynamically updating the VMedia device - Enable this feature to get the updated active session in the

b h a l
vmedia to the active JViewer and render the vmedia dialog based on the free slots available.

0
Enable boot once Support for VMedia - Enable this option is used to boot only once from the CD/DVD

7
•

n i i v s
from the AMI Virtual device.

1 t
Harddisk Server Support - This feature includes support for harddisk redirection support. HD server
handles request from KVM client and sends response back to client and manages HD redirection ses-

•
sions.

h a s h
Ignore Media Server Restart When Network change - Enable this feature to skip Media Server Restart

•
s da
when there is a change in network.
Local Media Support - This package includes Local Media Client
•
•
s a
Remote Images Support - This package includes Remote Image redirection Client.
VMedia support across concurrent users sessions - Enable this option is used to access the Vmedia
from Multiple Users. Default only one user can use the vmedia devices.

71 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• NBD Support for VMedia - Clientless implementation of Network Block Device (NBD) layer used for
VMedia redirection.
• Media Redirection over HTTPS Support - This feature allows redirecting CD image file from remote
HTTPS server using RMedia client.
•

-
SD Server Support - This feature includes SD server application which will receive SCSI commands from
host using USB driver and read/write appropriately from/to the SD card using SD driver

E
T R
CD/DVD Media Configuration

E
The features of CD/DVD Media Configuration are mentioned below.

O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
•

70 b h a l CD/DVD Media Configuration

CD/DVD ROM Device Product Name (Max 13 chars) - Configure value is used for the Virtual CD/

n t i
DVD Product Name .

1 i v s
CD/DVD ROM Device Product Revision (Max 4 chars) - Configure value is used for the Virtual CD/
DVD Product Revision.
•
a s h
CD/DVD ROM Device Vendor Name (Max 8 chars) - Configured value is used for the Virtual CD/

h
DVD Device vendor name.
•
s da
Number of CD/DVD Devices - Maximum number of CD/DVD devices to be emulated in the BMC.

a
• Number of CD/DVD Devices for KVM - Maximum number of CD/DVD devices to be emulated in the
BMC for KVM

s
72 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

HDD Media Configuration

The features of HDD Media Configuration are mentioned below.

E -
T R E
O
N IBU T
O R
D T 241 2 HDD Media Configuration
•

I S 1
Harddisk Server Product Name (Max 13 chars) - Configured value is used for the Virtual Harddisk
Product Name.

D 30 8 n
•

a
Harddisk Server Product Revision (Max 4 chars) - Configured value is used for the Virtual Harddisk
Product Revision.

h
•
vice vendor name.

1 u s
Harddisk Server Vendor Name (Max 8 chars) - Configured value is used for the Virtual Harddisk De-

4 e
•
•

7 b h a l
Number of HDD Devices - Maximum number of Harddisk devices to be emulated in the BMC.

0
Number of HDD Devices for KVM - Maximum number of Harddisk devices to be emulated in the BMC
for KVM.

1 n t i i v s
h a s h
s da
s a
73 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Lmedia Configuration
The features of Lmedia Configuration are mentioned below.

E -
T R E
O
N IBU T
O R
D T 241 2 Lmedia Configuration
•

I
the user.
S
Display Local Media Redirection web page - Enable the option to show the Local Media webpages to

D 30 8 1 n
•

a
LMEDIA-Multiple Image Redirection - Enable the option to support multiple instance redirection for

h
different device type.
•

1 u s
Specify mount options for SD card partition - This feature is used to specify mount option for SD card

4
Partition. Example: -t ext2 -o noatime, async.

e
•

0 h a l
The max number of image detection supported - This feature enables us to enter the Max number of
images that is to be detected (Max is 15).

7 b
1 n t i i v s
h a s h
s da
s a
74 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Lmedia Medium Configuration

The features of lmedia medium configuration are mentioned below.

E -
T R E
O
N IBU T
O R
D T 241 2 lmedia medium configuration
•
•
I S
lmedia medium selection - Select the required LMEDIA storage medium.

D 30 8 1 n
LMEDIA storage medium is SD card - If this option is selected, Local Media images will be stored

h a
in configured SD card.
LMEDIA storage medium is SPI - If this option is selected, Local Media images will be stored in
BMC memory.

1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
75 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

LMedia Multiple Image Redirection

The features of lmedia medium configuration are mentioned below.

E -
T R E
O
N IBU T
O R
D T 241 2 LMedia Multiple Image Redirection
•
tion.

I S
Multiple Lmedia CD maximum number of redirection - Defines the maximum number of CD redirec-

D 30 8 1 n
a
• Multiple Lmedia CD redirection - Configure the no of instance for the lmedia CD / DVD image redi-
rection.
•
tion.

4 h
Multiple Lmedia harddisk maximum number of redirection - Defines the max no of hard disk redirec-

s
•

1 u e
Multiple Lmedia Harddisk redirection - Configure the no of instance for the lmedia Harddisk Image

0
redirection.

h l
1 7 t i b s a
a n h i v
h
s da s
s a
76 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Rmedia Configuration
The features of Rmedia Configuration are mentioned below.

E -
T R E
O
N IBU T
O R
D T 241 2
S
Rmedia Configuration
•

• I
to the User.

D 30 8 1
Display Remote Media Redirection web page - Enable the option to show the Remote Media webpages

a n
RMEDIA-Multiple Image Redirection - Enable the option to support multiple instance redirection for

4 h
different device type.

s
RMedia Multiple Image Redirection

1 u e
The features of RMedia Multiple Image Redirection are mentioned below.

0 h l
1 7 t i b s a
a n h i v
h
s da s
s a
77 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
•
•
O R
D T 241 2
RMedia Multiple Image Redirection
Multiple Rmedia CD maximum number of redirection - Defines number of CD redirections.
Multiple Rmedia CD redirection - Enables the option to support multiple instance redirection for CD. If

I S
disabled, Rmedia CD redirection will not be possible.

1 n
Multiple Rmedia harddisk maximum number of redirection - Defines the max no. of hard disk redi-

D 30
rection.

8
•
a
Multiple Rmedia Harddisk redirection - Enable the option to support multiple instance redirection for

h
HD. If disabled, Rmedia HD redirection will not be possible.

1 4 u s e
Device Configuration

70 b h a l
The SOC supported devices like ADC, I2C, GPIO etc., can be enabled or disabled here.

1 n t i i v s
h a s h
s da
s a
78 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
•
O R
D T 241 2 Device Configuration 1
GPIO Device Support - This option is to include the GPIO driver in the stack. Selecting higher level

S
functionality like GPIO test app/library or IPMI support will automatically include the driver support.
•
•
I
D 30 8 1
Internal Video Driver – This package contains the built video driver for AST SOC.

n
NETMON Device Support - Network Interface Monitor. It monitors addition/removal of network inter-

a
face and changes in the Interface status. Applications query the Interface count, name and information.

4 h
Also applications use ioctl calls to wait for Interface changes.

s
Reset Manager Support - Reset common driver binary package.
•

1 u e
UART Route Support - This package contains lpcuart driver for AST2400 to control routing between io

0 h
com ports and uarts

l
•

7 t i b s a
Video Device Support - This option is to include the video driver in the stack. It will automatically in-
clude this device depend on the selected SoC.

1
•

• n i v
CD/DVD Device Support - This is a dummy package to properly select USB driver modules to support
cd/dvd device on the selected SoC.

a h
CPLD Device Support - This package contains cpld device related sources.
•
h
s da s
Hard Disk Device Support - This package contains cpld device related sources.

s a
79 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

NCSI Configuration
The NCSI Configuration is used to enable/disable the NCSi flow ontrol feature. The NCSI Configuration
features are as shown below.

E -
T R E
O
N IBU T
•
O R
D T 241 2 NCSI Configuration
Allow user to detect packages and channels - Allow user to detect the packages and channels manually,
if this feature is selected the driver will not detect the packages and channels when loading of it, so user

•
I S
must detect manually before initializing the interface.

1 n
Default channel id - NCSI default channel id [Only for NCSI Manual Switch Mode].

D 30 8
•

a
Default Flow control - This option is used to Set NCSI default Flow Control value.

h
0 - Disable FLow control

1 4 u s
1 - Enables Network Controller to Management Controller flow control frames.

e
2 - Enables Management Controller to Network Controller flow control frames.

70 b h a l
3 - Enables Bi-directional flow control frames.
•
•
1 i v s
Default Force LAN Speed 10G - NCSI force LAN speed 10G.

t
Default interface name - NCSI default interface name.

n i
a h
• Default VetoBit - This field is used to set the Default vetobit value for the NCSI to be used.
•
•
•
h
s da s
Disable Hardware Arbitration - Enable/Disable Hardware arbitration between packages.
NCSI Interface Names - This field is used to set the NCSI Interface name value for the NCSI to be used.
NCSI Support Model
•

• s a
NCSI Auto Failover Mode – This mode is used to switch the NCSI Channel automatically in case of
Shared LAN Fail-over.
NCSI Manual Switch Mode – This mode is used when the user wants to manually switch the NCSI

80 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Channel.
• Support for Asynchrounous Reset detection on NCSI Controllers - This feature detects asynchronous
reset on the network controller and reconfigures the link, a Kernel Timer will be invoked to periodically
issue Get Link Status command to the Network Controller.
•
•

E -
Support For flow control - It is used to Enable/Disable NCSI Flow Control feature.
Support for keep PHY Link-UP on NCSI Controller - This field is used to Enable/Disable Keep PHY
Link Up on NCSI Controller.
•

•
R
Support for Non-AEN Supported Controllers - If the Network Controller does not support AEN, a Ker-

T E
nel Timer will be invoked to periodically issue Get Link Status command to the Network Controller.
Timer Delay For Issuing Get Link Status Command - Periodic time interval(in seconds) for issuing the

O T
Get Link Status command to the network controller.

N IBU
SMASH Configuration

O
The features of SMASH Configuration are mentioned below. A sample screenshot of SMASH Configuration is
as shown below.

R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h SMASH Configuration
•
s da
SMASHLITE - This field used to select the package for smash client.

s a
81 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Smash Lite Configuration

The features of Smash Lite Configuration are mentioned below. A sample screenshot of Smash Lite Configuration
is as shown below.

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
•

1 4 u s e
Smash Lite Configuration
SMASH LITE MODE - Defines the SMASH LITE mode.
•

70 h l
SMASH Lite core Mode - Able to perform basic smashlite

b a
•

1 i
Test Tools Configuration

n i v s
SMASH Lite Scorpio Mode - Able to perform Scorpio smashlite.

t
a h
The test tools used to test the supported features or communication protocol in the BMC can be enabled or
disabled by double-clicking the respective feature. The list of test tools are given below.

h s
s da
s a
82 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
•
O R
D T 241 2
Test Tools Configuration 1
ADC Test Tool - This test tool is for test the functionality of ADC hardware.
Example:

I S
Get all adc value:

D 30 8 1 n
# ./adcapp --read-adc-channel
•

a
Gadget Unit Test Tool - This test tool is for testing the functionality of USB Gadget device.

h
Example: Emulate a Ether module

1 4 u s
#./gadgetut -d eth

e
l
Example: Emulate a HID module

70 b h
#./gadgetut -d hid

i s a
1 t
Example: Send Keyboard data

n i v
#./gadgetut -d hid -k $keycode

a h
$keycode: reference follow URL Table 12 Keyboard/Keypad Page

h
s da s
https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf
Example: Send mouse data
#./gadgetut -d hid -b $b -x $x -y $y -w $w -s

s a
-b: button data
-x: x point data

83 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

-y: y point data

-w: wheel data
-s: means send mouse data to the Host via USB cable

#./gadgetut -m $m
-m: abs/rel
E -
Example: Mouse mode setting

T R
Example: Get Host LED Status
#./gadgetut -r $r

E
O
-r: wait/no_wait

N IBU T
Example: Get mouse mode
#./gadgetut -g

O
Example: Power Consumption mode Status/Enable/Disable

R
#./gadgetut -e $e

D T 241 2
-e: status/enable/disable

S
Example: Emulate Virtual CDROM/Harddisk devices

I
D 30 8 1
#./gadgetut -i $i -d $d -p $P

n
-i: instance number, the valid value is 1 ~ 4

a
h
-d: cd/hd

1 u s
-p: ISO/IMG/IMA absolute path

4
Example: close virtual devices

e
70 h
#./gadget -d $d -c

b a l
i
-d: eth/hid/cd/hd

• 1 t v
-c: close devices

n i s
GPIO Test Tool - This test tool is for test the functionality of GPIO hardware.

a h
Example: Set GPIO pin 141 to input

h s
s da
#./gpiotool 141 --set-dir-input
Inside Set as Input

s a
GPIO pin is set as input pin
Get level from GPIO pin 141:
# ./gpiotool 141 --get-data

84 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Inside Read gpio.

Pin is High
• ipmitool IPMI Test Utility - This tool is used to manage Intelligent Platform Management Interface
(IPMI) functions of either the local system, via a kernel device driver, or a remote system, using IPMI

•
E -
V1.5 and IPMI v2.0. These functions include printing FRU information, LAN configuration, sensor
readings, and remote chassis power control.
JTAG Unit Test Tool – This package contains the unit test tool for testing JTAG driver.
•
• R
Openssl App - Tool to generate and view the SSL certificates

T E
PWMTACH Test Tool - Selecting this option includes the command line test application that interfaces
with the PWMTACH library to control various fans using on chip PWM and TACH lines. Various

•
• O T
command line options allow to set the PWM TACH line mappings and read/control the fans.

N IBU
Uart route test tool - This package includes the binary for UART troute est application.
Componenet Manager Test Tool - This package contains the test tool to test the component manager
related commands.This package contains the test tool to test the component manager related commands.
•
•
•
O
D T 241 2
fail-safe conf test utils - This package contains script files for testing fail-safe configuration function.

R
FB Test Tool - This package includes the binary for framebuffer test application.
MCTP App - MCTP Application to communicate with the MCTP Layer
•
driver

I S
NetMon Test Tool - Network Monitor Driver Test Application. Used to test the functionality of Netmon

D 30 8 1 n
•
•

h a
PECI Test Tool and Library Function - PECI Test Tool and Library Functions.
PMBUS Test Tool - This package includes the binary for PMBus test application.
•

4
watchdog driver.

1 u s
Watchdog Unit Test Application Support - This package contains watchdog unit test application for

e
70 b h a l
Runtime Libraries Configuration

1 n t i i v s
The runtime libraries that are required to run the application to be stable can be enabled or disabled by double-
clicking the required checkbox. The list of libraries are mentioned below.

h a s h
s da
s a
85 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 Runtime Libraries Configuration
•

S
ADC Library Support - This option includes the ADC library support in the stack that interfaces with

I 1
the ADC driver to manipulate the ADC hardware available on SoC. Selecting higher level functionality,

n
like ADC test app that requires this library, will automatically select this option. Selecting this option will

D 30 8
•

h a
automatically include the driver required for this functionality.
Email Alert AMI Format - This option includes FTS AMI format for Email Alert
•

1 4 u s
Email Alert fixed subject format - This option includes the support for fixed subject format that could
be selected as the default email format sent out as the event alerts.

e
•
•

7 b h a l
Event Log error Description - Enables lib package for event log error description.

0
GPIO Library Support - This option includes the GPIO library support in the stack that interfaces with

•
n t i v s
the GPIO driver to manipulate the GPIOs on SoC. Selecting higher level functionality, like GPIO test app

1
or IPMI that requires the GPIO support, will automatically select this option.

i
I2C Library Support - This option includes the I2C library support in the stack that interfaces with the

h a s h
I2C driver to use I2C on SoC. Selecting higher level functionality, like I2C test app or IPMI that requires
the I2C support, will automatically select this option. Selecting this option will automatically include the
driver required for this functionality.
•
s da
Library which contains the API Calls for OEM System log - Library which contains the API Calls for
OEM System log.
•

• s a
Memory Map Library Support - This option includes the memory map library support on the SOC
based hardware. Selecting this option will automatically include the driver required for this functionality.
NCML Library Support - This option is to include single-point services configuration support for all

86 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

out-of-band services. It is the central common access point for all the network connection related activi-
ties in the system. The network configuration details for all the services will be kept together and NCML
will access them to know which service is to be configured on which interface/port number etc.
• Node Manager Library Support - This Package contains helper function required for node manager.
•

•
E -
PHY Library Support - This option allows to include the library needed for forced PHY configuration
functionality in the stack.
CPLD Library Support - This package includes function calls to access CPLD devices.
•
• R
HiRedis Library - Storing data directly from ipmi command to redis-db using libhiredis library.

T E
IPMI Redfish Hooks Library for AST2600EVB Platform - This package contains IPMI PDK Hooks
Library for AST2400EVB (AMI OEM Version)

O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s Runtime Libraries Configuration

h a s h
PMBUS LIBRARY SUPPORT - This option includes the PMBUS library support in the stack that

s da
interfaces with the PMBUS driver to communicate with PMBUS devices. Selecting higher level
functionality, like PMBUS test app or IPMI that requires the PMBUS support, will automatically select
this option. Selecting this option will automatically include the driver required for this functionality.
•

s a
PWMTACH Library Support - This option includes the PWMTACH library support in the stack that in-
terfaces with the PWMTACH driver for fan control. Selecting higher level functionality, like PWMTACH
test app or IPMI that requires the fan control support, will automatically select this option. Selecting this
option will automatically include the driver required for this functionality.

87 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• Reset Manager Library Support - This is the binary package for LIBRESET.
• SSL Certificate Library - This option includes the SSL certificate library in the stack. This library
provides APIs to manipulate/generate the SSL certificate on the stack. Selecting higher level feature will
automatically select this library option.
•

•
E -
UART Route Library Support - This option provides UART Route Library Support for achieving the
uart routing application and functionality.
Virtual Media Library Support - This package includes build vmedia library module. This library con-

•
•

T R
tains functionalities to configure virtual media, local media and remote media information.
Watchdog Library Support - Watchdog Library Binary.

E
SMB Library Support - SMB Library Binary.
•

O T
SNOOP Library support - This package includes the API calls to access the snoop driver.

N IBU
Development Kits Configuration
The header files required during the Development of SPX firmware can be updated here. A sample screenshot

O
of Development Kits Configuration is as shown below.

R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
•
s da Development Kits Configuration
NCML development header files - Network connection manager library development package.
•

a
Internal Video Driver - This package contains video capture driver development header files.

s
88 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

SOL and Serial Port Sharing Configuration

The SOL and Serial Port Sharing Configuration of the SOC can be edited here. Most of the features can be
enabled or disabled. The SOL and Serial Port Sharing Configuration features are as follows.

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
SOL and Serial Port Sharing Configuration

•
•
h a
SOL with Internal SuperIO - It is used to Configure UART routing with Internal SuperIO.
SOL With External SuperIO - Configure UART routing with EXternal SuperIO.

1 4 u s e
70 b h
Software Configuration

a l
i
The Software Configuration tools such as YAFU Flash, YAFU KCS, VMCLI can be enabled or disabled here.

1 n t i v s
h a s h
s da
s a
89 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
•
O R
D T 241 2 Software Configuration
libipmi (software) - This Package contains the files to refer original libipmi library.
•

• S
Ipmi application (Network and USB) - This package contains source code for IPMI based application

I
(Network and USB) software module.

D 30 8 1 n
CDROM library files - This Package Contains the cdrom related library files
•
a
Hard disk library files - This Package contains the harddisk related library files.

h
s
• INI Parser for Software Utility - Iniparser library for software utility.
•
•
1 4 h u
Java Wrapper (harddisk) - This Package contains the java library files for harddisk.

l e
Java Wrapper (cdrom) - This Package contains the java library files for cdrom.
•

70 b a
Java Wrapper (ClientConf) - This package contains the java library files for fetching and updating client

i s
t
system configuration.
•
1 n i v
License Key Generation Tool - This package contains the source code for license generation tool. It sup-
ports both Windows/Linux 32/64 bit Operating systems.
•
a h
Vmcli package - This package contains the source code for VMCLI software Module. VMCLI is used to

h s
redirect CD / DVD and HD / USB media to host.

s da
User Management Configuration

s a
This section helps in selecting authentication mechanisms such as Active Directory (AD), Light Weight
Directory Access Protocol (LDAP) and Radius.

90 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 User Management Configuration
•

• S
Active Directory Authentication Support - All Acive Directory related Authentication Packages are

I 1
selected, only this package is included.

D 30 8 n
LDAP Authentication Support - All LDAP related Authentication Packages are selected, only this pack-

•
age is included.

h a
PAM Reorder Support - PAM reorder support helps in selecting the order of PAM authentication during

1 4 u s
runtime using AMI OEM IPMI commands.

e
Radius Authentication Support - All RADIUS related Authentication Packages are selected only if this

70 b h
package is included.

a l
1 t i s
Recommended Factory Configuration

n i v
For the secured access to the system, do the following:

h a s h
1. The default user account sysadmin should not be enabled in the final firmware image. This user account
is used during the development stage.

s da
2. Telnet support shouldn’t be enabled in the default Services Configuration, if an unsecured access of any
kind is undesirable.

a
3. Enable Encrypted Image support for added security during firmware update process. This will require a
pair of keys.

s
4. Login Shell for Remote Terminal option under General Configuration option shouldn’t be configured to
provide direct shell access to avoid full system access grant to a user.

91 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

5. SNMP V1/V2 based access shouldn’t be enabled, if available.

6. User Password Encryption Feature under IPMI configuration can be enabled for added security of
stored passwords on the system. Appropriate key for user password encryption should be set under User
Password Encryption Key option.

-
7. Default SSL_certificates must be replaced with customer owned SSL_Certificates.
8. If force password change at first login (california law) feature is not enabled then it is recommended not

E
to use same default password for all BMC’s during production.
IPMI LAN Configuration - Allowing only RMCP Plus (Disable RMCP)

R
1. Open the pmc file from libipmipar package.

T E
2. Disable the MD5 Auth type in LAN config params section as shown in below screen shot. Disable MD5
Auth type in all LAN config params if enabled (LAN1,LAN2,LAN3 and LAN4).

O T
N IBU
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l IPMI LAN Config Params

1 t i s
3. Save & Generate the configuration output and build the source Project again.

n i v
h a s h
Conf corruption due to unexpected AC Loss mechanism
1. During abrupt AC loss, conf partition may get corrupted due to last milliseconds erase/write operation in

s da
/conf partition.
2. An Implementation was done to discard such erase/write operation by checking for a file flag(AC_LOST)

s a
in /var before any write to SPI expecially /conf area. An API like OnAcLost() was implemented to create the
flag to avoid any write operation, This API can be used whenever AC LOST is detected.
3. Customers can use the API in PDK or custom code which has frequent conf write operation to prevent

92 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

primary flash corruption during AC loss.

Limitations
1. Even if erase/write operation is discarded , there are some cases where there will be no time for the existing
write operations to be completed during AC LOSS due to which conf corruption cannot be prevented.

E -
NOTE : To avoid the limitation kindly follow the recommendations provided by ASPEED - Platform design
should consider to have a certain amount of capacitor capacity to supply BMC to work for while after AC
Loss (Ref : section 3.9 in Aspeed specification). With this, sufficient time can be available for BMC to com-

T R
plete the ongoing operation before the power goes down.

E
References

O
N IBU
• IPMI Specification 2.0
T
• Node Manager Specification 1.5
• DCMI Specification 1.5

O R
• APML Specification 1.04

D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
93 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 3

E -
MEGARAC SP-X Package Architecture
®

T R
SP-X Package is defined as a set of files and rules defining a specific feature of the Service processor. Multiple

E
SP-X packages together forms the entire functionality of the Service processor.

T
This document explains the architecture of the SP-X Packages, how the software and users can create and

O
manipulate these packages. This document is used by package developers and utility developers to create and

N IBU
use proper packages.

Types of Packages

O
SP-X Package consists of source files, binary files, rules etc packaged into an archive containing two gziped

R 2
tar files. The first tar file data.tar.gz (Called as Data Section) either consists of source files/build files or binary

D T 241
files depending upon the type of package. The second consists control.tar.gz (Called as Control section) of file
has control information which describes the package, rules how to build, install etc. Details of the internal are
explained in later sections. SP-X Packages has a filename extension .spx.

I S
When a SP-X package is extracted it creates two directories – data (Unzipped Data Section) and SP-X (Unzipped
Control Section).

D 30 8 1 n
a
Basically SP-X Packages can be separated into two different types of packages Source package and Binary
Package. Binary Packages are created by building Source Packages. The following sections explain the different

h
types of source and binary packages.

1 4 u s
For now on, both Source and System packages are treated as Source Package and Binary, Debug, Development,

e
Tools and Information packages are treated as binary packages.

0
Source Package

7 b h a l
n i i v s
A source package for a particular feature contains source files, make files, configuration files in the data section.

1 t
The control section contains information about the binary packages it will build and how to build the source
package into binary packages. A single source package may create one or more different types of binary package

a
(For example, openssl source package can create openssl tools, SSL libraries and SSL Development libraries).

h
System Package
s h
s da
This is a special type source package, but will not have any source files. It has script files which instruct the
package build tool to create a binary package using the binary files from a target. These types of packages are
essential for the system boot up and for many of the functionalities to work (So this is also sometimes referred

s a
as base packages).
One mandatory system package is one which creates a binary package which creates the initial root file system
with the basic necessary executable, libraries, scripts and configuration files.

94 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

There can be optional system packages which provide extra files for the target. For example if an application
package X requires to access ldap server for authentication, it will need some ldap libraries. So a system package
L which provides the necessary ldap libraries need to be installed. The application package X defines that it is
dependent on Package L. So, when package X is to be installed, then package L will also be installed.

Binary Package

E -
Binary Package is created from the source package or system package by the package build tool. Binary package
looks similar to the source package, except it has compiled executables and libraries instead of source and make

R
files. This has rules and scripts giving instructions where to install the binary files, create configurations files,
runtime scripts etc. It also has script which has to be run before and after installing the package and before
and after removing the package.

Debug Package

O T T E
This is exactly similar to a binary package, except this may have symbolic information for debugging purposes.

N IBU
Development Package
Along with Binary Package, this package also may be generated from Source Package. It is similar to the binary

O
package but it consists of header files and libraries. This package is used only for building source packages

R 2
which depend on these header files and libraries.

D T 241
Tools Package

I S
These packages contain the all tools required for building and installing SP-X packages. Mainly it contains the
tools chains. These packages are pre-built by AMI and available only in binary form.

D 30
Information Package
8 1 n
h a
These packages provide information about the hardware or ARCH, SOC, PLATFORM and OEM . These are
dummy packages (does not have data section) which helps the package builder tools to provide the association

1 4 u s
between hardware and the packages and determine which packages are to be compiled. Also it provides for
which target (ARCH/SOC/PLATFORM/OEM) the packages has to be build (Such packages are prefixed with

e
l
@).

70 i b h a
For example, @SOC_PILOT-IV selects dummy info packages called HW_KCS, HW_I2C etc. KCS_CORE
depends on HW_KCS and KCS_PILOT-IV depends on KCS_CORE. So selection of KCS is enabled because

s
1 t
the HW_KCS is selected by the PILOT_IV info package. In case of @SOC_G4 it does not select HW_KCS as

v
the G4 does not have KCS hardware. Since KCS_CORE depends on HW_KCS and HW_KCS package is not

n i
present in case of G4, KCS_CORE will not be shown as an option.

a h
Package Naming Format
h s
s da
A proper SP-X package name consists of the following parts in order separated by - (hyphen)
• Name of the Source or Binary (Taken from Source/Package entry from INFO of control section)

s a
• Version Number (Taken from Version entry from INFO of control section)
• Optional entries specific to the ARCH, SOC, PLATFORM or OEM (Taken from INFO)
• Ending Prefix

95 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• src for Source package

• ANY or ARCH (The architecture for which it is compiled) for binary package
• Ends with .spx extension

-
Name or optional entries should not have – (Hyphen). It can contain _ (underscore)
FORMAT : <NAME>-<VERSION>-<OPTIONAL>-<SRC/ARCH/ANY>.spx
Example:
Source packages:

R E
xyz-1.5.32-src.spx (Generic Source Package)

T E
abc-2.3.9-PILOT_IV-src.spx (SOC Specific Source Package)

T
term-1.0.5-src.spx (Generic Source Package)
Binary packages:


O
N IBU
libxyz-1.5.32-MIPS.spx
libxyz-1.5.32-SH4.spx
abc-2.3.9-PILOT_IV-ARM.spx
(Generic MIPS Binary Package)
(Generic SH4 Binary Package)
(SOC Specific Binary Package)

O R
D T 241 2
term-1.0.5-ANY.spx
@SOC_PILOT_IV-1.0.0-ANY.spx

Components of a Package
(Non-Arch specific Binary Package)
(Information Package)

section.
I S
D 30 8 1
All packages must have two gziped tar files and hereafter we refer these two files as data section and control

n
Data Section

h a
s
Section in Source Package

1 4 u
It contains either a pristine source got from open source / third party or it may be an AMI source tree. If it is

l e
a pristine source, it is not modified ever. If it is an AMI source tree, it can be modified only on a stable release

h
70
(We will talk about release procedure later)

i b s a
Data Section in Binary Package and Debug package

1 t v
It contains the binary files (executables and libraries) and configuration and scripts files – created from either

n i
the source package or system package.

a h
Data Section in Development Package

h s
s da
It contains the development files for the corresponding binary package which provides the dynamic libraries.
Development files includes header files, static libraries and documentation/man pages if any.

s a
Data Section in System Package
For system package, data section is not mandatory. It may or may not have this section. If it exists, it will be
having architecture independent files like script or configuration files.

96 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Data Section in Information Package

For information package, data section is empty.

Data Section in Tools Package

-
The data section contains all the tool related files (executables, libraries, scripts, header files etc.). In some cases
the whole tools may be kept as a single compressed file.

Control Section
E
R
The Control Section when extracted will create a directory SP-X. It consists of directories and files which give
the details about the packages, building the package, installing the package etc.

T E
T
Files and Directories in Control Section of all Source Packages

INFO
Name

FILES
O Type

N IBU
File
File
Req *
M
M
Information about the Package
Details

List of Files in Data Section with MD5 Checksum and Size

O
CHANGELOG File M Change History of Package

2
RULES.PY File M Rules about how to build the package
RULES.D
PATCHES
LICENSES R
D T 241
Dir
Dir
Dir
O
M
M
Multiple rules (If Rules is not sufficient)
Contains list of patch files to apply on Data Section
List of Licenses applicable to the source and binary packages
DEFCONFIG
P.CONFIG

I S
D 30
File

1
File

8
O

n
O
Default Configuration if any needed to build the package
Needed only if the DEFCONFIG can be modified by package configuration
tool
PACKAGES.D
BUGS
Dir
Dir

h a M **
O
List of Files needed to build Control section of the binary packages
List of Known Bugs – Either a single (BUGS.SRC) or list of files for each

s
binary package (BUGS.PkgName)
DOCS

1 4 Dir

h u
O

l e
List of useful documents – Design, User Manual, Porting Guides, Test
Plans

0
README File O Plain old README First
TODO
FAQ

1 7 t i b
File
File

s aO
O
List of things to be done on this package
Frequently Asked Questions!!

n i v
* Required = M(Mandatory) or O (Optional).

a h
** For each binary package that will be created, the following files are present in separate directories.

h s
SCRIPTS, DATA.

s da
Files and Directories in Control Section of all Binary Packages
Name Type Req * Details Source Location
INFO
FILES

s a File
File
M
M
Information about the Package INFO of Source package
List of Files in Data Section
with MD5 Checksum and size

97 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

LICENSES Dir M List of licenses applicable to LICENSES

the package
CHANGELOG File M Change History of Package CHANGELOG
SCRIPTS Dir M Scripts to be Run – PRE/ PACKAGES.D

DATA
BUILDCONFIG
Dir
File
E - O
M ***
POST Install and PRE/POST
Remove
Default runtime config files
Default Configuration needed
PACKAGES.D
**

BUGS

T R
File

E
O
to build the package
List of Known Bugs BUGS/BUGS.SRC or BUGS/BUGS.
PkgName

P.CONFIG O
N IBU T
* Required = M(Mandatory) or O (Optional)
** Overall configuration used to build this binary package – Combination of DEFCONFIG and user input via

*** Some pre-build binary packages like tools, target file system BUILDCONFIG is not present.

Source (Src) O
Format of INFO

R
D T 241
Package (Bin)
2 Source Package Name (This entry specifies it is a source package)
Binary Package Name
Version
SP-X Version
SP-X Format
I S
D 30 8 1 n
Major.Minor.BugFix
4.0
2.0 (SP-X Package Format version)
Provides (Bin) (Optional)

h a Virtual Package Name. Needed only if more than one package

provide Similar functionality
Builds (Src)

4
Section (Bin)

1 u s e
List of Binary packages build
App/ Lib/ Dev/ Tool/ Info/ Sys/ Dbg (Dbg only for App and Lib)

l
Group (Bin) This field is used by MDS for grouping packages based on

70
Build-Depends (Src)

i b h s a
functionality.
The packages which needs to be compiled before this package,
should be provided in this field.

1
Depends (Bin)

n t i v This package will be available for selection only when the packages
specified in this field are already selected by SPX project configurator.

Essential
h a
Required (Bin)

s h The packages specified in this field will be selected by SPX project

configurator upon selection of this package.
Yes/No (Yes=this package is essential. It is always selected) If Yes,

s da
ConfigTag (Bin) (Optional)
ConfigTag and Group are not used even if present.
Brief Info (max 64 characters) entered in this field will be displayed

a
in SPX Project Configuration menu.
Description Information about this package – This can be provided in multiple

s
Architecture
lines and ends with line containing period (.) as the first character.
Architecture for which the package belongs to (See Notes)

98 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Owner Company which owns this module (AMI/OEM)

Maintainer Name (Email address) of Maintainer
Source Location (Src) (Bin) This field specifies the exact location from where the source or
binary is taken from. This field value should be AMI for AMI
proprietary packages.
Source Version (Src) (Bin)

License

E - This fields specifies the exact version of the source or binary. This
field value should be 1.0.0 for AMI proprietary packages.
This field specifies the licensing information of the source or binary

R
included in the package.
SOC (optional) If the package is specific to an SOC, specify it here

T E
PLATFORM (optional) If the package is specific to an PLATFORM, specify it here
OEM (optional) If the package is specific to an OEM, specify it here

O
Urgency (optional)

N IBU T See changelog for details.

Feature-Required (Bin) Optional) The feature is needed for a particular package to be selected. The

Build-Order (Src) (Optional)

feature field should be like CONFIG_SPX_FEATURE_SAMPLE.
This field helps for selecting the build order of a package. The values
are NONE, FIRST and LAST.

O
Build-Precedence (Src)

R
D T 241
Notes on Architecture
• Source/System package:
2
Build-Precedence of the packages.

I S
ALL - Binary package can be created for all architectures.

1 n
(Build for ALL architectures)
ANY - Binary package created is arch-independent package. (Runs on ANY architecture)

D 30 8 h a
ARCH- Binary package can be created only for specified ARCH (arm, mips …)
• Binary/Development/Debug package:

1 4 u s
ANY - Arch-independent binary package (Created by Source Package ANY)

e
l
ARCH- Arch specific binary package. (Created by Source Package ALL or ARCH)

0 b h
• Information package:

7 i s a
t
ANY – Because it has only information, it is not associated with any architecture.

1 n
• Tool package:

i v
a h
Tools are run on host and so the Architecture is normally ANY. But if a tool is to be used only for building a
specific Architecture (Normally Cross Compilers), then the Architecture should include the ARCH.

h s
s da
Notes on Source Entries
These entries are required only if the package is derived from another source outside of AMI (i.e. Open source

s a
or third party).

Notes on Depends & Required

99 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• Package X is dependent on package Y

In the Depends or Build Depends field of INFO of Package X, package Y will be listed. So during configuration,
Package X will be shown to user only after selecting the Package Y. This will prevent installing Package X
without Package Y thus resulting either in runtime (Depends) or Build time (Build-Depends) error.

E -
• Package X requires Package Y
In the Required field of INFO of Package X, package Y is listed. During package configuration, Package X will
be shown to the user and Package Y will not be shown, Selecting Package X will automatically select Package

R
Y also. Note this is opposite of Depends and in most cases the Package Y does not provide any functionality
independent of Package X.

Notes on Group

O T T E
This is used to group the similar type of packages so that they will be displayed in the SP-X configuration tool
together under the same group menu. The order of defining the menus is provided by a group order number.

N IBU
The values for group and their group order number are pre-defined by the SP-X maintainer. And all packages
should follow this. Any new group can be added by requesting the SP-X maintainer.

Format of CHANGELOG

O R 2
It is a file containing a list of all the changes done in the package. The changes are represented by the below

D T 241
format. The changes are listed from the latest (top of the file) to the oldest (end of the file).
Package: Package Name (Version); urgency=<security/critical/high/medium/low/new>

Abstract:
I S
Blank Line

D 30 8 1 n
Blank Line

h a
< Brief description of the changes in this version>

1 4 u s
Files Modified: <List the Files>

e
l
* Change details

70 b h
Blank Line

i s a
1 t
Files Added: <List of Files>

a n i v
* Change details

h
Blank Line

h s
Files Removed: <List of Files>

s da * Change details
Blank Line


s a --Submitter (email) Date in RFC 822 (section 5) format
Blank Line

100 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Values for urgency

Security – Any security Fix
Critical - Fatal Failures

-
High - Some feature is broken always
Medium - Behavior is inconsistent – Usable and recoverable.
Low - Cosmetic changes
New - New Package

R E
T E
There can be multiple entries for Files Modified/Added/Removed. But at least one entry is mandatory.

T
Example:

Abstract:

O
Package: MySample (2.3.9) ; urgency = security

N IBU
Fix for Memory corruption in compression

O
D T 241 2
Files Modified: Data.c, data.h:

R
* Compress() function Returning local buffer to the caller is replaced with malloc memory
* based on callers size.

I S
D 30 1 n
Files Modified: process/Format.c :

8


h a
* Calling Compress with a buffer size and freeing the returned buffer after processing.
--Myself <[email protected]> Mon, 02 Jun 09 15:01:00 -5:30

1 4 u s e

Abstract:

70 b h a l
Package: MySample (2.3.8); urgency = low

1 n t i s
Error messages corrected.

i v

h a s h
Files Modified: screen.c
* Spelling mistake in error message Invalid data

s da --you ([email protected]) Fri, 13 Mar 09 10:35:13 -5:30

s a
101 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Format of FILES
All the files present in the Data Section should be listed as below format
<Relative Path of File as inside Data Section> <White Space> <Size in Bytes> <White Space> MD5SUM>

Format of LICENSES

E -
It is a directory containing licenses applicable to the packages. The license files are in the following format.
License: < Short description of License like AMI, GPLv2, BSD ….>
Blank line
Full Description:

T R E
Format of PATCHES
O
N IBU T
< Shows the full license information>

This contains two directories – FILES and SERIES. The FILES directory (and any subfolders) contains all the
patch files that will be applied to the data sections. SERIES directory has list of files named like 01, 02 to a

O
maximum of 99. Each of these series files (The file name matches the Bug Fix version) list the order of patch

R 2
files that need to be applied. The first character of each line is either a + or - or * or X. The second character is

D T 241
a blank. The file name follows the blank.
The series file can also list the name of the subfolder under the files directory, in which case the subfolder

S
should have files prefixed with 00 to 99. A special series file called 00 may be present in the SERIES directory

I
which specifies patch files that is present always (does not correspond to any bug fix version)

D 30 8 1 n
By default all the patches are applied to data directory with patch level -p1 option. This can be overridden by

a
optional third and optional fourth entries in each of the line in series file. The third argument is directory inside

h
the data where the patches to be applied and fourth is the patch level value to be used.
For example:

4
+ patchA . 1

1 u s e
< Apply patchA on data with –p2 option>

70 b h
+ patchB linux 2

a l < Apply patchB on data/linux with –p1 option>

i
All the patches except those listed in Series file 00 will be propagated to Source directory at stable releases

1 n t i v s
(Major/Minor updated and Bug Fix Version reset to 00). Series file 00 is used to keep patches which are applied
to pristine packages (open source or vendor provided) which we (AMI) don’t ever modify

a
A + indicate the patch to be applied and a - indicate the patch to be removed. - is useful to remove an incorrect

h s h
patch applied in earlier bug fix. Care should be taken when using -, because there may be intermediate patches
which may affect when removing an earlier patch.

s da
An X indicates the file is a shell script which has to be run on the data section. This is useful if you want to do
some operations on the data section like removing some files, execute some commands etc.

s a
A * is used to replace a file. In this case the file specified should be a normal file and not a patch file. This should
not be used unless really necessary. Packages using * will not be supported by AMI.

102 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Format of PACKAGES.D (Source Packages Only)

It consists of directories with every binary package name. Under each directory, the SCRITPS (Refer “Files
and Directories in Control Section of all Source Packages”) directory (Mandatory) and an DATA directory
(optional). These files are used as is for creating the binary packages.

E -
Format of SCRIPTS (Binary Packages Only)
Inside SCRIPTS directory there can be four shell script files are present – preinst, install, postinst, prerm,
remove and postrm, which are used to install/remove packages on a running system (Currently we don’t have
plans to support this).

T R
Along with this there is one more script called dev-install (Mandatory) which installs the package on a build

E
environment during development phase. It has two rules build-install and debug-install. These can be used to

T
install the binary package for build purposes and for debug purposes respectively. In these rules lines starting

O
with # are treated as comments and the blank line is treated as end of the rule.

N IBU
For example, Kernel Image is place inside output directory for build purposes and kept in tftp root for debug
purposes.

O
Format of BUGS

R
D T 241 2
This consists of one or more files containing the list of known bugs (and workaround if any) in the packages.
BUGS.SRC contains the known bugs in the entire packages. If the Bugs can be separated for each binary
package, then files are named BUGS.<Binary Package Name> for each package.

I S
Format of DEFCONFIG

D 30 8 1 n
DEFCONFIG contains default configuration to be used for building the package. These values can be

a
overridden by configuration tool if the P.CONFIG (Package Configuration Script) is provided. The format of
the DEFCONFIG is flexible. It can be either in the package specific format (for example, kernel , busy-box have

4 h
their own configuration format).

s
For other packages, SP-X defines the following format. DEFCONFIG consists of list of entries in the format as
below.

0 1 h u l e
CONFIG_SP-X_<Package_Name><Key_Name>=<Value>

1 7 t i b s a
This is similar to the .config files generated by Linux configuration tools except the prefix of the Keys are
CONFIG_SP-X_<Package_Name> instead of CONFIG_. A line starting with # is ignored and hence can be

n i v
used for comments. The Key should contain only alpha numeric characters and _ (underscore). Value can be
Boolean (y/n) or Numeric or String.

a
Format of P.CONFIG
h
h
s da s
This is a similar format of Kconfig files provided in Linux. For details refer “kconfig-language.txt” provided
with the Linux kernel source documentation. The major difference from Kconfig is each entry starts with the
CONFIG_SP-X_<Package_Name>_ instead of CONFIG_

s a
CONFIG_SP-X_GOAHEAD_KEEPALIVE
bool Support HTTP KeepAlive

103 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

default n
help
Enable if you want to support HTTP Keep Alive. If you are not sure set it to N

Format of BUILDCONFIG

E -
The BUILDCONFIG is either a copy of DEFCONFIG or the output from the Package Configuration tool
(if P.CONFIG is provided). The BUILDCONFIG file is bundled with the binary package. The format of the

T R
BUILDCONFIG is same as DEFCONFIG.

Format of RULES and RULES.D (Source Packages Only)

E
RULES is based on PYTHON file. But the rules are parsed and executed by the package builder (instead of the

O T
make utility). Error checking is done by the BuildSP-X parser and on errors in parsing or executing the parsed
rules will stop proceed with Build.

N IBU
RULES.D is optional and can have extra shell scripts and make files called/used from the main RULES script.
In RULES, lines starting with # are treated as comments. Rules should end with a blank line. There are some

O
mandatory rules and some optional rules.

mandatory.

R
D T 241
build_package-BIN_PKG
2
For each of the binary package (BIN_PKG) that will be created by the source package, the following entry is

I S
This will create a data directory with the necessary files and call PACKSP-X which builds the binary package.

1
(PACKSP-X might create either a normal package or debug package depend upon the user’s choice).

D 30 8 n
The optional rules are:
1. extract_source

h a
4 u s
Normally the source in data section is kept in tree structure. But it is not always the case and mostly it is kept
as compressed format. In such cases some extra steps to be done before patching and building. This rule should

1 e
convert such packages (may be uncompress) into an acceptable tree format.

0
2. build_source

7 b h a l
i
Apply the necessary configuration from the package configuration and build the package.

1
3. clean_source

n t i v s
Remote the object files and any files created during build source. At the end of cleansource, the package should

h a s h
return to the exact state after patches are applied.
Under these directories, the necessary packages will create subfolder with unique name specifying the

s da
package and installs the files required.
4. Under these directories, all packages create a sub folder names as the package name without the .spx
extension.

s a
104 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

File Types
.spx - SP-X Package (Binary or Source)
.PRJ - SP-X Project Configuration
.IMA - Rom Image

Package Configuration

E -
R
Package Configuration tools provides two functionality. First it goes thru all the packages and provides a menu
of packages to be selected. Then for all the packages selected by the user, features of the packages are shown to
customize the package. Once it is completed it creates a package configuration file. This file is used to build

O T T E
the necessary packages with the features selected.
Package Configuration tool is similar to the Linux configuration tool (menuconfig, gconfig). So the input script
(package configuration script) for the package configuration should be similar to that of Linux kconfig. For

N IBU
details refer “kconfig-language.txt” provided with the Linux kernel source documentation.
The major difference from Kconfig is each entry starts with the CONFIG_SP-X_ instead of CONFIG_.
CONFIG_SP-X_ will follow by a Package name and a Version Entry in the format (Major.Minor.BugFix). Also

O
package used in the entries select and depends on can have a Version check.

R
D T 241
CONFIG_SP-X_WSMAN(1.3.4)
bool Wsman Support 2
default n

I S
D 30 8 1 n
# Lines starting with # as first character are treated as comments

h
select QOM (==1.0.2)
a
depends on WEBSERVER (>=2.0.4)

help

1 4 u s e
Select Y if WSMAN support is needed. This will automatically enable QOM support.

0
Package Selection

7 b h a l
1 t i s
Package configuration script is dynamically created from the packages INFO file.

n i v
• Package/Source value used for config type is always bool. The option tags is taken from ConfigTag

h a s h
• Default is always no.
• Select values are taken from Required.

s da
• Depends on is taken from Depends.
• Help is taken from Description.

s a
Package will not be shown in the Configuration tool if ConfigTag is not present. In this case the default value is
still no. So only method this package is selected by adding this package under Required of some other package.
Package will also not be shown if Essential is set to YES. This denotes this package should be always selected.

105 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Package Grouping
Packages are grouped together inside a single menu item based on the Group Name. The menu heading will
be the Group Description. The order of the menu displayed is based on Group Order. Following is the list of
Group Values (more will be added as desired).

NONE
#Group

E - 0x0000
Group Order
“”
Description

PERIPHERAL
DEVICE
IPMI

T R E
0x0100
0x0200
0x0300
“Hardware Configuration”
“Device Configuration”
“IPMI Configuration”

T
USB 0x0400 “USB Configuration”

O
N IBU
Alternate Package Selection
The Provides field in the INFO file specifies what the package provides. For example the packages OpenSSH
and DropBrear provide the same feature SSH. In this case, the package’s Provides field should specify SSH, and

NONE
O
Project configuration will provide the user to select the desired SSH package. Following is the list of Provides

R
D T 241
# Provides 2
Values (more will be added as desired).

“”
Description

KERNEL
CROSSCC
TARGET
I S
D 30 8 1 n
“Linux Kernel”
“Cross tools”
“Root File System”
SOC
ARCH

h a “SOC”
“Architecture”

s
PLATFORM “Board/Platform”
OEM
WEBSERVER

1 4 h u l
“OEM Name”

e
“Web Server”
SSH

70 i b a
“Secure Shell Server”

Feature Selection for each Package

s
1 t v
Once a package is selected, features of the packages (if the package has P.CONFIG script) will be shown.

n i
Otherwise, no feature selection will be done and the default configuration (DEFCONFIG if present) is used.

h
INVOKE_MAKE a s h
Shell Script Macro Python Function
Py_RunMake(argstr,
Action
Inovkes Make file Command.

s da verbose=True)
Eg: Py_RunMake(“”)
Py_RunMake(“clean”)
INVOKE_SHELL

s a Py_RunShell(Script) Python function to run the shell script.

Eg: Py_RunShell(“tesh.sh”)

106 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CWD Py_Cwd(dirname) Change the current working directory.

Eg: Py_Cwd(“testdir”)
TOUCH Py_Touch(filename) Rule to touch the file.

MAKE_CHAR_NODE

E - Py_MknodChar(devname,
major, minor)
Eg: Py_Touch(“testfile.txt”)
Function to create the character device
file in ImageTree.

MAKE_BLOCK_NODE

T R E
Py_MknodBlock(devname,
major, minor
Eg: Py_MknodChar(“kcs”, 23, 0)
Function to create the block device file
in ImageTree.

T
Eg:Py_knodBlock(“mmcblock”, 43, 0)
MAKE_FIFO_NAME

MKDIR_NOCLEAN
O
N IBU
Py_MknodFifo(devname)

Py_Mkdir(dirname)
Function to create the fifo device node
in ImageTree.
Eg:Py_MknodFifo(“TestQ”)
Function to create the new directory

O R
D T 241
MKDIR_CLEAN
2 Py_MkdirClean(dirname)
if does not exist. If exists leaves the
content intact.
Eg:Py_Mkdir(“TestDir”)
Function to create the new directory

I S
D 30 8 1 n
if does not exit. If exists, clean the
directory empty.
Eg:Py_MkdirClean(“TestDir”)

DELETE

h a Py_Delete(nodename) Function to remove the file/directory.

1 4 u s e
Eg: Py_Delete(“TestDir”)
Py_Delete(“testfile.txt”)
INSTALL

70 b h a l Py_Install(dirname) Function to copy contents of current

working directory to <dirname>. The

1 n t i i v s
directory <dirname> will be created if
does not exists.
Eg: Py_Install(“ImageTree”)
COPY_DIR

h a s h Py_CopyDir(srcdir, destdir) Function to recursively copy contents of

<srcdir> to <destdir>. The destination
directory will be created if does not

s da exist.
Eg: Py_copyDir (“Include”, ”ImageTree/

s a conf ”)

107 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

COPY_FILE Py_CopyFile(srcfile, destfile) Function to copy the file content from

srcfile to destfile. The destination file
will be created if does not exist.
Eg: Py_CopyFile(“test1.txt”,”test2.txt”)
RENAME

E - Py_Rename(old, new) Function to rename or move the file/

directory.
Eg: Py_Rename(“text1.txt”, “test2.txt”)

UNTARBZ2

T R E
Py_UntarBz2(filename,
destdir)
Py_Rename(“test1”, “test2”)
Function to Extract the bzip format file
to destination directory.

UNTARGZ
O
N IBU T Eg: Py_UntarBz2(“linux-2.26.28.10.tar.
bz2”, “linux”)
Py_UntarGz(filename, destdir) Function to Extract the gzip format file
to destination directory.

O
Eg: Py_UntarGz(“test.tar.gz”, “test”)

2
TAR_GZ Py_Gzip_Web(fileexp, Function to create the gzipped tar

SET_PATH
R
D T 241
dirname)
Py_SetPath(newpath)
format from <dirname>
Function to update the PATH
Environment variable with <newpath >

I S
D 30 8 1 n
value.
Eg:
tools”)
Py_SetPath(“/usr/local/bin/spx/

ADD_MODULES

h a Py_AddModules(modname) Function to add the driver module

name in /etc/modules file if the entry
does not exist.

1 4 u s e
Eg: Py_AddModules(“platform”)

l
ADD_LIBRARY_LINKS Py_AddLiblinks(linkpath, Function to create the symbolic link for

70 i b h s a
libname) the shared library.
Eg: Py_AddLiblinks(“/usr/local/

1 n t i v
lib/”,”libusername”)
Function creates the symbolic link in

h a s h
path /usr/local/lib/ for libusername.so,
libusername.so.x, libusername.so.x.y,
libusername.so.x.y.z

s da
SET_VALUE Py_SetValue(Key, Value) Function to export the Environment
variable for key,value pair. The Key
value will be valid during the entire

s a build process.
Eg:
linux-”)
Py_SetValue(“CROSSCC”,”arm-

108 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

SET_INIT_SCRIPT Py_InitScript(scriptname) Function to copy the <scriptname>

to ImageTree/etc/init.d and create the
symbolic link for each runlevel specified
in the <scriptname> file.

-
PACK_SPX Py_PackSPX(*args) Function to create the SPX package
format file(.spx).

COPY_TO_CONF

R E Py_CopyConf(confname)
Eg: Py_PackSPX(“./”, “testpackage”)
Function to copy the file to /conf and /
etc/defconfig directory.

COPY_DIR_TO_CONF

O T T E Py_CopyDirConf(dirname,
filename)
Eg: Py_CopyConf(“hostname.conf ”)
Function to copy the file to specified
directory in /conf and /etc/defconfig.

N IBU
Eg: PyCopyDirConf(“license”, “vmedia.
license”)
This function copies the vmedia.license

EXECUTE
O R
D T 241 2 Py_Execute(Command)
file to /conf/license directory.
Function to execute the shell script
commands in dev_install/Rules script.
Eg: Py_Execute(“mkdir testnode”)

I S
CREATE_SYS_TREE

D 30 8 1 n
Py_CreateSysTree(listdir,
outdir, defdir)
Function to create the tree structured
directory based on the system package
rules

h a Eg: Py_CreateSysTree(“RULES.D”, “/
data/tree”, “data/defaults”)

1 4 u s e
This function creates the tree folder
based on the rules files inside the

l
RULES.D directory and it maintains the

70 i b h s a Py_AddToMacros(Key)
default directory <defdir> structure as
well.
Function to add the feature related

1 n t i v
macro and value in /etc/core_macros
file.

h a s h Eg: Py_AddToMacros(“CONFIG_SPX_
FEATURE_BIOS_COMPONENT_
SIZE”)

s da Py_AddToFeatures(Key) Function to add the feature macro in /

etc/core_features file.

s a Eg: Py_AddToFeatures(“CONFIG_
SPX_FEATURES_BIOS_COMP_
SUPPORTED”)

109 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

STRIP_UNNEEDED Py_StripUnneeded(argstr) Function to remove all the unneeded

symbols from the binary which will
result in reducing the size of the binary
During the build process, the below mentioned variables can be accessed by PRJVars Python List variable.

%PACKAGE

E -
SPX 1.0 Format Variable access SPX 2.0 Format Variable access
PrjVars[PACKAGE]
Description
Name of the Package (without the
version)
%PRJFILE

%PRJNAME

T R E
PrjVars[PRJFILE]

PrjVars[PRJNAME]
Project Configuration File Name
with .PRJ extension
Project Configuration Name from

T
PRJNAME.PRJ
%DEVAREA
%BUILDAREA

%STATUS
O
N IBU
PrjVars[DEVAREA]
PrjVars[BUILDAREA]

PrjVars[STATUS]
Location of the development area
Location of Project
(%DEVAREA/Build.%PRJNAME)
Location of Package Status (2)
Build

O
%TEMPDIR PrjVars[TEMPDIR] Location of Scratch Area (2)

%SOURCE
R
D T 241 2 PrjVars[SOURCE] Location of working copy of Source
(2)
%BINARY
%BUILD

I S
D 30 8 1 n
PrjVars[BINARY]
PrjVars[BUILD]
Location of the Binary Packages
Location where the source are build
(2) (%BUILDAREA/.build)
%SPXINC

%SPXLIB
h a PrjVars[SPXINC]

PrjVars[SPXLIB]
Location of the include files
directory (1)
Location of the library files

%TOOLDIR

1 4 u s e
PrjVars[TOOLDIR]
directory (1)
Location of build tools (1)
%TARGET

70 b h a l PrjVars[TARGET] Location of the Complete Root File

Ssytem
%KERNEL_SRC

1
%BOOT_SRC

n t i i v s
PrjVars[KERNEL_SRC]
PrjVars[BOOT_SRC]
Location of Kernel Build directory
Location of Bootloader
directory
Build

%TFTPBOOT
%OUTPUT

h a s h PrjVars[TFTPBOOT]
PrjVars[OUTPUT]
Location of TFTP Root
Location of the output
directory
files

s da
%KERNEL_BIN
%BOOT_SRC
PrjVars[KERNEL_BIN]
PrjVars[BOOT_SRC]
Location of Kernel Image
Location of Bootloader Build

%BOOT_BIN

s a PrjVars[BOOT_BIN]
directory
Location of Bootloader Image

110 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

%IMAGE_TREE PrjVars[IMAGE_TREE] Location of Final Image tree which

can be used for NFS root

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
111 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 4

E -
SP-X Development – Hands On

T R
This document is intended to be used by the developers who are involved in creating SP-X packages. It also
provides details of how to work and debug individual package based stack going forward.

E
SP-X package based source structure defines certain framework like directory structure etc to allow the

O
N IBU T
developers develop and debug their SP-X packages using NFS.
This document explains the source structure, build mechanism, and the root file system etc required to proceed
with the development.
There is a separate section that describes the hands-on details about how the packages, scripts and how to get

O
and build the tree and debug individually packaged modules.

R
D T 241 2
SP-X Package based stack – various components
MegaRAC® SP-X core source tree includes a set of SP-X packages’ repository, and a set of scripts used to build

S
the stack.

I
D 30 8 1
SP-X packages’ repository

n
SP-X packages’ repository is a complete list of SP-X packages available in a
single directory.

a
4 h
Below is an example of a typical listing of SP-X repository.

s
1 h u l e
@ARCH_ARM-1.0.0-ANY.spx Kernel_amiext-1.0.0-src.spx
@ARCH_i686-1.0.0-ANY.spx Kernel_arch_arm-1.0.0-src.spx

0
@ARCH_MIPS-1.0.0-ANY.spx

1 7 t i b s a
Kernel_bugfix-1.0.0-src.spx
@ARCH_SH4-1.0.0-ANY.spx Kernel_cpu_arm926ejs-1.0.0-src.spx
buildtools-1.0.0-ANY.spx Kernel_platform_aviator-1.0.0-src.spx

n i v
busybox-1.0.0-src.spx Kernel_Pristine-1.0.0-src.spx
crosscc-1.0.0-ARM.spx Kernel_soc_pilot_iv-1.0.0-src.spx

a h
crosscc-1.0.0-i686.spx Kernel_subarch_armv4-1.0.0-src.spx

h s
crosscc-1.0.0-MIPS.spx libdbgout-1.0.0-src.spx

s da
defaulthost-1.0.0-src.spx libhostname-1.0.0-src.spx
fmh_dev-1.0.0-ANY.spx libpwmtach-1.0.0-src.spx
global_dev-1.0.0-ANY.spx @PLATFORM_AVIATOR-1.0.0-ANY.spx

s a
helper-1.0.0-src.spx pwmtach-1.0.0-src.spx
hw_adc-1.0.0-ANY.spx pwmtach_hw-1.0.0-ARM-PILOT_IV-src.spx
hw_gpio-1.0.0-ANY.spx pwmtachtool-1.0.0-src.spx

112 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC
hw_i2c-1.0.0-ANY.spx rules-1.0.0-ANY.spx
hw_kcs-1.0.0-ANY.spx @SOC_PILOT_IV-1.0.0-ANY.spx
hw_peci-1.0.0-ANY.spx sys_base-1.0.0-src.spx
hw_pwmtach-1.0.0-ANY.spx target-1.0.0-ARM.spx
hw_usb-1.0.0-ANY.spx target-1.0.0-i686.spx

-
hw_videocap-1.0.0-ANY.spx target-1.0.0-MIPS.spx
hw_espi-1.0.0-ANY.spx hw_espimafs-1.0.0-ANY.spx

E
hw_espioob-1.0.0-ANY.spx Kernel-1.0.0-ARM-PILOT_IV-AVIATOR-src.spx

R
As it can be seen, all the modules of the stack, like Kernel, tool-chain, libraries, Boot-loader, device drivers,
and applications exist all together as individual packages. The final firmware image is a result of selecting the
required packages, building them, and putting them together in the image form.

Build Mechanism

O T T E
Build Mechanism includes a set of scripts that are used to build individual packages, and finally create the

N IBU
required developmental framework and the final firmware image.
Below is an example of a typical listing of Build scripts directory.

O
ApplyPatch.py BuildPRJ.py cfg.pyc ExecRules.pyc Image.py LoadPkg.py ParsePrj.py

R 2
ScanInfo.py ApplyPatch.pyc BuildSrc.py Depend.py GenImage Image.pyc LoadPkg.pyc

D T 241
ParsePrj.pyc ScanInfo.pyc BinPkg.py BuildSrc.pyc Depend.pyc helper.py IniParse.py

S
PackSP-X.py Rules.py Startup.py BinPkg.pyc cfg.py ExecRules.py helper.pyc

I
D 30 8 1
IniParse.pyc PackSP-X.pyc Rules.pyc Startup.pyc

a n
BuildPrj.py is the top-level script which in turn uses other scripts to perform the complete build. It can also
be used to build individual packages. BuildPrj.py can be used to build the stack, after any changes made to the
sources.

4 h s
The usage and examples will be explained in the hands-on section of this document.

1 u
SP-X Development – Hands-On

0 h l e
1 7 t i b s a
Getting the SP-X packaged source and build scripts
Source are maintained in git repository https://git.ami.com/. Every git project has the README

n i v
file. README file has the details on how to pull the source from the AMI git repository.
AMI MegaRAC SPX integration with Git by introducing git spx commands. All tools required to convert

a h
and build SPX image are integrated as a docker image that is internally triggered by the git spx plugin.

h
s da s
Recommended OS for Git spx.
• Git SPX is based on docker and its not OS dependent, Plugin can work with almost all linux distros.
•
•
s a
Plugin is tested in below platform and recommended to be used in one of these
Ubuntu 16

113 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• Ubuntu 18
• SLES
• Fedora

-
• Mint

R E
Building the SP-X packaged tree
Project configuration file (extension .PRJ)

O T T E
The current AST2600 based project configuration file (ast2600evb*.PRJ) is inside configs/ directory.
This file includes all the packages that are selected to configure the final build. It basically controls what goes in
the final build. This PRJ file will be generated by MDS. So, if you create a new package and want to include it in

N IBU
SP-X build, you need to update the entry in PRJ file using MDS.
A typical package entry in PRJ file would be as following.

O
CONFIG_SP-X_<Package Name>-1.0.0=YES

R
D T 241 2
The build process will build all the packages listed in this file. If your package depends on some package, that
package will be automatically built by the build process, based on the proper dependencies set by you in your
package. There is no need to add an entry for that package in the PRJ file.
For example,

I S
D 30 8 1 n
Let us say you have a package named A.spx which depends on package B.spx at build time, and a package C.spx

a
at run time.

h
Let us also say that you have properly configured the dependencies while creating the package A.spx. This
means that you have defined Build Depends for build time and Depend for the run-time in your package.

4 s
u
To make the package A.spx part of the build, all you need to do is, include A.spx in the PRJ file. Packages B.spx

0 1
Building the project
h a e
and C.spx will be automatically taken and used by the build process when building A.spx package.

l
7 i b
Using MDS – SP-X Builder

1 t v s
A MDS project can be created in SP-X builder using the PRJ file and the location of the packages. Please refer

a n h i
to SP-X Builder under MDS_UserGuide for more details on how to use MDS for SP-X.

Explaining workspace project directory

h
s da s
All the SP-X packages are extracted, built and kept inside the workspace directory. This directory also includes
the final root file system that goes in the final firmware image. This final root file system is also used for NFS
based development to NFS mount. There is no separate target directory for NFS based development.

• Build
s a
workspace directory includes the following three sub directories.

114 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• source
• tools
• links
• Software

Build
E -
Each of these directories are explained in the following sections.

T R
This directory contains all the binary packages built out of the packages included in the PRJ file, and all that is
required to be able to develop, debug and create the final image. This can be seen as the main development area.

E
The following directories exist in this directory. Not all the directories need to be touched for usual development.
• binary
• bootloader
• include
O
N IBU T
O
• kernel
• lib
• output
R
D T 241 2
S
• target
• tftpboot
binary
I
D 30 8 1 a n
This directory is the place holder for all the binary packages created out of the selected SP-X packages. We don’t

bootloader

4 h
need to touch this directory for usual development.

s
0 1 h u l e
This directory contains the uboot source. We don’t need to touch this directory for usual development, until
and unless there is a boot loader level change required.
include

1 7 t i b s a
v
This directory includes various modules’ folders that need to expose the header files to be used by other

a n h i
modules. You can think of this directory as a replacement of common/include in SP2 stack.
This directory also includes projdef.h file which includes all the project specific configuration details.

kernel h
s da s
This directory is available in Makefile using ${SP-XINC}.

This directory contains the Linux kernel source. We don’t need to touch this directory for usual development,

lib
s a
until and unless there is a Kernel level change required.

115 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC
This directory is a place holder for all the libraries that are required by other modules at build time. A library
source package needs to create its development package and needs to copy the built library modules into its
directory inside lib using the development package dev_install.
This directory is available inside dev_install using %SP-XLIB.

-
output
This directory contains two sub-directories: ImageTree and kernel

R E
kernel: contains the created uImage which can be used for NFS boot.
ImageTree: contains the final root file system to go into the firmware image. This is also used to NFS mount
during the development. Use this directory as nfsroot in your bootargs for NFS based development.
target

O T T E
This directory contains the extracted pristine target. We don’t need to touch this directory for usual development.

N IBU
tftpboot
This directory contains all the files like uImage, that need to go in your tftpboot folder on your development
machine.

source
O R
D T 241 2
This directory contains all the extracted source packages in their expanded form. As you can find, each source
package directory inside this directory will have data and SP-X sub-directories for that package.

tools

I S
D 30 8 1 n
This directory contains the extracted toolkit, build tools etc. It also contains the top level rules that are included in

Links
h a
individual Makefiles for various types of modules. We don’t need to touch this directory for usual development.

1 4 u s
This directory contains softlinks to the needed files.

e
Software

70 b h a l
This directory contains tools needed for SPX that can be run from X86 Architecture like flashing tools, VMCLI
tools etc.

1 n t i i v s
What after executing BuildPrj.py?

h a s h
It will build all the packages listed inside .PRJ file and place them in the root file system inside workspace/Build.
aviator/output/ImageTree directory. This can be mounted as NFS root to test the required functionality.

s da
Debugging the package and Making changes at the source level
As explained in the previous sections, all the packages are extracted and kept inside workspace/source directory.

s a
While debugging the package, you might require making the changes at the following levels.

Source files changes during the development

116 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

You can make the changes in the source files of your package directory inside workspace/source directory,
if needed and run BuildPrj.py again to build the stack or modified package alone. This will build and install
your package in ImageTree again which can be tested over the NFS. This should be done until we get the final
working source. There is no need to re-create the package each time you make a change in C or H source file.
If you are using MDS for the development, you can access the source files inside a package by expanding the

E -
package in the package explorer view on the left. Modifying and saving the source files here will directly make
changes in the package directory inside workspace/source directory. You can then build project using MDS
which will install your newly built module inside ImageTree which can be tested over the NFS.

T R
Recreating the package and testing using the new package

E
There could be two cases in which you might need to re-create the package.

T
First where the source files inside data directory of the package changed. Any C, H or Makefile changes belong
to this scenario.

O
N IBU
The second scenario could be where no source change was needed but the control information (inside SP-X
directory of the package) is changed. One example of control information change could be that you forgot
some dependency in your initially created package and now want to add it and re-create the package.

O
Re-creation of an SP-X package should always be done using MDS. “SP-X Builder” plug-in inside MDS must

R 2
be used to open an SP-X project and the packages inside that project.

D T 241
The following sections list out the steps that need to be followed in each of these two scenarios.

I S
Source changed (contents inside data directory of the package)

D 30 8 1 n
After debugging and testing at the source level, you may finally want to re-create the package and ensure that
it works in the intended format.

a
The following is an example of how you can re-create the package from your source.

h s
Say, you have a package named mypkg-1.0.0-src.spx, inside packages directory. When extracted, there will be

1 4
a directory named mypkg-1.0.0-src inside workspace/source directory. This is where you will have the final

u e
source to be used to re-create the package.

h l
0
• Using MDS project, you can simply right click on the package and select Repack option. This will

b a
recreate the package with the new source. Uncheck the Auto Increment option for version, if se-

7 i s
lected. We don’t want to change the version during the development. GIT commits already take care

1 n t
of versioning and we don’t have to change anything when creating the package. Auto Increment is

i v
useful for customers where they may want to maintain the versioning by some other means.

h a s h
• Go to workspace/.pristine directory (Note that it’s a hidden directory) and remove your package
directory.
#rm –rf mypkg-1.0.0-src/

s da
• Go to workspace/source directory and remove your package directory.

a
#rm –rf mypkg-1.0.0-src/

s
• Execute BuildPrj.py with BUILD option or use Build Project from MDS to build the stack. It will
freshly extract your new package, build and correspondingly install the build modules, development

117 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

headers etc as specified in your package.

Control information changed (contents inside SP-X directory of the pack-

age)
The following is an example of how you can change the control information and then re-create the package

E -
when there was no source change but control information was changed.
Say, you have a package named mypkg-1.0.0-src.spx, inside packages directory. When extracted, there will be
a directory named mypkg-1.0.0-src inside workspace/source directory. This is where you will have the final

T R
source to be used to re-create the package.
There will also be a directory named sp-x within your package directory inside workspace/source directory.

E
This is where the control information resides for your package.

directory. O
N IBU T
1. Using the MDS project, you can right click on the package and select Update Package Properties. This
will open the package in SP-X package editor. You can modify the control information as necessary and
click on “Repack Package” available on “Overview” tab. This will create the new package in your packages

2. Go to workspace/.pristine directory (Note that it’s a hidden directory) and remove your package direc
tory.

O R 2
#rm –rf mypkg-1.0.0-src/

D T 241
3. Go to workspace/source directory and remove your package directory.
#rm –rf mypkg-1.0.0-src/

I S
4. Execute BuildPrj.sh with REBUILD option or use Build Project from MDS to build the stack. It will

D 30 8 1 n
freshly extract your new package, build and correspondingly install the build modules, development head
ers etc as specified in your package.

h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
118 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 5

SP-X Based Project Creation

E -
T R
The following steps explains what needs to be done to start a SP-X based customer platform project.

E
1. Create @OEM_(NAME) package

T
- NAME is the OEM name to be used for the project handling. You will use the OEM

O
(NAME) tag to specify the difference between the generic and OEM modified packages

N IBU
2. Create @PLATFORM_(PLATFORM NAME) package
- PLATFORM NAME is the platform name to be used for the project. This package will be used to
select a specific platform for the .PRJ at build time.

O R
D T 241 2
3. Modify/Create the platform package i.e. platform-ARM-AST2300-AST2300EVB-src
- This driver package is used to configure the multiplexed functionality specific to the customer project.
4. Create the porting packages:
• libipmipar
•

I S
libipmipdk

D 30 8
• libipmipdkcmds
1 n
h a
- Add the contents of the generic porting packages into the new OEM/PLATFORM specific packages

1 4 u s
- In the package creation wizard for the OEM field type the (NAME) that was used for the

e
@OEM_(NAME) package and in the Platform field type the (PLATFORM NAME) that was used for

70 b h a l
the @PLATFORM_(PLATFORM NAME) package

1 i s
5. ipmipdk_dev and oempdk_dev may need to be created with the OEM and PLATFORM tags. These pack

t
ages contain all the headers used in the porting packages.

n i v
Note:

h a s h
- The customer Project can also be created by using MDS.

s da
- For more details about Customer project creation, refer MDS User’s guide -> Chapter 6
(SPX Builder) -> Creating SPX Customer Project .

s a
119 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 6

E -
Application Package Creation
R
This section provides the guidelines to create SP-X package of an application module. An example could be

T E
PWMTACHTOOL application module. The following sections will provide detailed instructions on how to
create a SP-X package for the application.

O
N IBU T
All the developers need to adhere to the steps provided in this document to ensure that all the created packages
fit into overall SP-X architecture scheme.

Prerequisites

O
1. Any header files that are used only within the application need to be copied in the application source

D T 241 2
directory itself, if outside the directory. For example; if a header file is kept in common/include but only

R
used by the application, we need to remove it from common/include and put it in the application direc
tory itself.
2. Any header files that are owned by an application and used by another application need to be identified.

I S
We should not have such header file. Report such instance, if existing.

1
3. All the C and H files must have copyright header.

D 30 8 n
a
/***************************************************************
** **
** (C) Copyright 2006-2009, American Megatrends Inc. **
**
**
**
**

4 h s
All Rights Reserved.
5555 Oakbrook Pkwy Suite 200, Norcross,
**
**
**
**
**
**
**

0 1 u l e
Georgia - 30093, USA. Phone-(770)-246-8600

h
**
**
**

a
***************************************************************/

7 i b s
4. Makefile needs to be cleaned up.

1 t v
Makefile

a n h i
Makefile should contain the following sections.

h
s da
Debug flag
DEBUG = n
s
s a
Finally built application module name
TARGET = <Application name>

120 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Source files to be compiled in the library

SRC = <Source File 1>.c <Source file 2>.c

Include CFLAGS to include the header files etc., if any, used by the library

E -
CFLAGS += -I${SP-XINC}/<Directory name>

Include the required library, if any, for the application

T R
LIBS += -L${SP-XLIB}/<Directory name> -l<Library Name without prefix lib>

Mandatory include of Rules.make.apps

E
include ${TOOLDIR}/rules/Rules.make.apps

DEBUG = n O
N IBU
TARGET = pwmtachtool
T
EXAMPLE: pwmtachtool application package Makefile

SRC

O
= pwmtachtool.c

R
D T 241 2
CFLAGS += -I${SP-XINC}/pwmtach
LIBS+= -L${SP-XLIB}/pwmtach –lpwmtach

I S
include ${TOOLDIR}/rules/Rules.make.apps

D 30 8 1 n
Using MDS SP-X package creator

h a
Please refer to MDS_ UserGuide for step by step instructions on how to use SP-X package creator in MDS. This
section will deal with how various fields/settings are configured to create a application package.

1 4 u s
Creating the SP-X package using MDS wizard

e
7 b h a l
1. File name for the new SP-X library package should be unique. For example; PWMTACHTOOL test ap

0
plication package can be named as pwmtachtool. Please note that this is not the actual SP-X package
name. It’s just an internal workspace container name within MDS for this package.

1 n t i i v s
2. Select package type as source and click ‘Next’ to enter SP-X package specific details. This is where we enter
the final SP-X package details.
Name: For the application, it should be the same as the application name. Example; pwmtachtool or adcapp.

a
Owner: Must be AMI.

h s h
s da
Maintainer and Maintainer’s Email: Your full name and AMI’s email address.
Source Location: AMI

s a
Source Version: 1.0.0
Description: Provide brief, accurate details about the library module.
Destination Directory: Provide the path where you want the final SP-X package to be created.

121 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

The following sub-sections explain each tab of the package creator in the order they need to be used.

Overview
The following five fields need to be set accordingly. All the other fields should not be modified.

Architecture
Essential

E -
Field Name
ALL
NO
Value

Config-Tags
Group
SOC

T R E
<Application Name> Application
NONE

T
Add Config-Tags fields as <Application Name> Test Application, if it’s indeed a test application. For example;

O
pwmtachtool application package can have its Config-Tags field as PWMTACHTOOL Test Application.

N IBU
If there is a known issue with the library, add it with proper notes.

Files

O
D T 241 2
1. Add all the source, header, and Makefile files in your application package. Do not use Add Folder to

R
include the source files at this time. Always use Add Files and then select all the source files that you
want to be part of the package.
2. Include any startup or INIT.D scripts if required by the application. For example; ipmi or defaulthost ap

S
plications have scripts installed in INIT.D directory.

I
D 30 8 1 n
Binary Packages (Note that we skipped ‘Build Details’ for now)

a
Each Application source package, when built, creates one binary package. For example; PWMTACHTOOL

4 h
application source package will create PWMTACHTOOL application binary package

s
This tab provides details on the binary package created out of this application source package.

0 1 h u l e
Follow the table below to create the binary package. None of the other fields should be modified, unless stated.

Name

1 7 t i b
Field Name

s a Application Binary package

<Application Name>
Example
pwmtachtool
Essential
Section
Config-Tag

a n h i v NO
app
<Application Name> Application PWMTACHTOOL Test

h s
Application
Group None

s da
Description
Scripts/dev_install
Provide brief details
Refer “Files and Directories in Control

Required
Depends
s a Section of all Binary Packages”
Refer “Format of INFO”
Refer “Format of INFO”

122 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Add Config-Tags fields as <Application Name> Test Application, if it’s indeed a test application.
Add known issues, if any. Provide details about the issues in the notes.

dev_install for application binary package

#Install Script

E -
Have it set to the following. Make changes as per your application details. Note the spaces carefully.

build-install:

T R
COPY_FILE ./<Application Name> %IMAGE_TREE/usr/local/bin

E
#Use the following to have the INIT script run at startup, if needed.

debug-install:
O
N IBU T
SET_INIT_SCRIPT ./<Script Name>

Each rule (build-install and debug-install) should end with an empty line.

O
Modifying init.d script

levels.
R
D T 241 2
The init script needs to be modified in a certain way for it to be installed and linked for the appropriate run-

The first line of your script needs to be as per the followings.

I S
#Runlevel : <Run Level> = <Order level>

D 30 8 1 n
Where Run level is S, or between 1 -7.

h a
Order level is in which order you want to execute this script in that run level.
For example; defaulthost application runs in run level S with Order level S37. So, the init.d script for defaulthost

1
#Runlevel : S = S37

u s
should contain the following as the first line.

4 e
0 h l
Required for application binary package

7 b a
n
Name: libpwmtach
i i v s
Add any library binary package that is required by the application binary at run time here.

1 t
Example: pwmtachtool binary application will include libpwmtach library binary package as following.

Operator: ==

h a
Version: 1.0.0

s h
s da
Depends for application binary package

a
Add any driver binary package that is the above included library binary package depends on at run time.

s
Example: libpwmtach library binary package depends on pwmtach driver binary package. So, we need to
include pwmtach driver binary package in pwmtachtool binary application Depends.
Name: pwmtach

123 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Operator: ==
Version: 1.0.0

Build Details

-
1. Add the following Build Depends entries.
crosscc == 1.0.0

E
global_dev == 1.0.0
rules == 1.0.0

R
Also add any other development package that is required by this application. For example; pwmtachtool
would require libpwmtach_dev development package for the APIs and data structures definitions.
2. Click on Global Rules to create the RULES file. This file includes the build rules for the source package

O T T E
and binary package that is created out of source package.
RULES should be set as following.

N IBU
#Extract Source in %SOURCE
extract_source:

O
#Build Source in %BUILD

2
build_source:

R
D T 241
CWD %BUILD/%PACKAGE/data
INVOKE_MAKE

#Clean Source
clean_source:

I S 1 n
CWD %BUILD/%PACKAGE/data

D 30 8
INVOKE_MAKE clean

h a
#--------------------- Mandatory Rules for every binary package -------
------------------

4 u s
# Rules to create <Application Name> package

1
build_package-<Application Name>:

70 b h a l
MKDIR_CLEAN %TEMPDIR/%PACKAGE/tmp
COPY_FILE %BUILD/%PACKAGE/data/<Application Name>

1 n t i
%TEMPDIR/%PACKAGE/tmp

i v s
#Include the script, if any, as following
COPY_FILE %BUILD/%PACKAGE/data/<Script Name>
%TEMPDIR/%PACKAGE/tmp

h a h
PACK_SP-X ./ %TEMPDIR/%PACKAGE/tmp

s
Create SP-X package and confirm that the intended SP-X package was created in the selected directory.

s da
3. Case Example:

a
Get the SP-X source from GIT and convert to spx using the command **git spx convert** and import

s
pwmtachtool-1.0.0-src.spx into MDS
Go through various tabs of the SP-X package editor once the package is loaded. You can refer to the
RULES, dev_install etc of the binary package, created out of pwmtachtool-1.0.0-src.spx application package.

124 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 7

E -
Common Driver Package Creation

T R
This section provides the guidelines to create SP-X packages of common driver module. An example could be
PWMTACH common device driver module. The following sections will provide detailed instructions on how

E
to create SP-X package for a common device driver module.

O T
All the developers need to adhere to the steps provided in this document to ensure that all the created packages
fit into overall SP-X architecture scheme.

N IBU
SP-X Package creation for a common driver module

O
Pre-requirements for a SP-X driver package

R
D T 241 2
1. All of the device drivers in SP-X stack are split into two driver modules: common and hardware. There
might be few exceptions like I2C driver. Any driver which is not in this form might need to be split into
common and hardware, and tested before converting them into SP-X package format.

S
2. Any header files that are used only within the driver need to be copied in the driver source directory

I
itself, if outside the directory. For example; if a header file is kept in common/include but only used by the

8 1 n
device driver, we need to remove it from common/include and put it in the device driver directory itself.

D 30
3. Any header files (for example; IOCTLs or data structures definition) that are used by the driver and an

a
other module (say another driver or library), need to be identified.

h
4. All the header files need to be cleaned up/split accordingly so that they fit into either of the above two

s
categories (point 2 and 3). No single header file contents should belong to both the categories.

4
5. All the C and H files must have copyright header.

0 1 h u l e
/****************************************************************
**
**

1 7 t i b s a
(C) Copyright 2006-2009, American Megatrends Inc.
**
**

v
** **
**
**

a n h i
All Rights Reserved. **
**

s
** 5555 Oakbrook Pkwy Suite 200, Norcross, **
**
**
**
h
s da
Georgia - 30093, USA. Phone-(770)-246-8600.
**
**
**

a
****************************************************************/

s
Makefile needs to be cleaned up.

125 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Makefile
Makefile should contain the following sections.

Debug flag
DEBUG := n

E -
Finally built driver module name (target)

R
TARGET := <Driver module name>

OBJ files to be created for each source file in the driver

OBJS

T E
:= <Source File 1>.o <Source file 2>.o

O T
Mandatory CFLAGS to include the other header files/rules etc. Always include these
two flags.

N IBU
EXTRA_CFLAGS += -I${SP-XINC}/global

O
EXTRA_CFLAGS += -I${SP-XINC}/helper

R
D T 241 2
Mandatory include of Rules.make.drivers
-include ${TOOLDIR}/rules/Rules.make.drivers

DEBUG := n
I S
EXAMPLE: pwmtach common driver package Makefile

D 30 8 1 n
TARGET := pwmtach
OBJS := pwmtachmain.o

h a
1 4 u s
EXTRA_CFLAGS += -I${SP-XINC}/global

e
EXTRA_CFLAGS += -I${SP-XINC}/helper

70 b h a l
-include ${TOOLDIR}/rules/Rules.make.drivers

n i i v s
Using MDS SP-X package creator

1 t
Please refer to MDS_UserGuide for step by step instructions on how to use SP-X package creator in MDS. This
section will deal with how various fields/settings are configured to create a SP-X common driver package.

h a s h
Common and hardware modules of a driver need to be converted into two separate SP-X driver packages. The
guidelines explained here apply to a common driver package creation.

s da
Creating the SP-X package using MDS wizard

a
1. File name for the new SP-X package should be unique and as per the driver. For example; PWMTACH

s
common driver can have it as pwmtach_common. Please note that this is not the actual SP-X package
name. It’s just an internal workspace container name within MDS for this package.
2. Select package type as source and click Next to enter SP-X package specific details. This is where we enter

126 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

the final SP-X package details.

3. Name: For common driver, it should be the same as the driver name like pwmtach or adc.
Owner: Must be AMI.
Maintainer and Maintainer’s Email: Your full name and AMI’s email address.
Source Location: AMI
Source Version: 1.0.0

E -
T R
Description: Provide brief, accurate details about the drive module.
Destination Directory: Provide the path where you want the final SP-X package to be created.

E
The following sub-sections explain each tab of the package creator in the order they need to be used.

Overview
O
N IBU T
The following five fields need to be set accordingly. All the other fields should not be modified.

Field Name Value

Architecture
Essential
Config-Tags
Group
O R
D T 241 2
ALL
NO
“<Driver name> Device Support”
DEVICE
SOC

I S
D 30 8 1 n
If there is a known issue with the driver, add it with proper notes.

Files

h a
1. Add all the source, header, and Makefile files in your driver directory. Do not use Add Folder to include

1 4
part of the package.

u s
the source files at this time. Always use Add Files and then select all the source files that you want to be

e
2. Also add any common header files (as specified in pre-requirements, point 4).

0 h l
Binary Packages (Note that we skipped ‘Build Details’ for now)

7 b a
n i i v s
Each source package, when built, creates one or more binary packages. For example; PWMTACH common

1 t
driver source package will create PWMTACH common binary driver package and PWMTACH driver
development package which will be used by library.

h a s h
This tab provides details on the binary packages created out of this source package.
For Common driver source package, two binary packages will be built. Follow the table below to create these

s da
two packages. None of the other fields should be modified, unless stated.

s a
127 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Field Name Binary driver package Driver development Example

package
Binary Driver Name <Driver Name> <Driver Name>_driver_dev pwmtach and pwmtach_
driver_dev

-
Essential NO NO
Section Sys Dev
Config-Tag

Group
Description
R E <Driver name> Device
Support
DEVICE
Provide brief details Provide brief details
Scripts/dev_install

O T T ERefer “Files
Directories in Control
Section of all Binary
Packages”
and Refer “Files and Directories in
Control Section of all Binary
Packages”

Depends

N IBU Refer “Format of INFO”

Add known issues, if any. Provide details about the issues in the notes.

O R 2
dev_install for binary driver package

D T 241
Have it set to the following. Make changes as per your driver and device details.
#Install Script

I
build-install:

S
COPY_DIR

D 30 8 1./

n
%IMAGE_TREE/lib/modules/2.6.28.10-ami/misc/

a
ADD_MODULES <Driver Name>
MAKE_CHAR_NODE <Device Node Name> <MAJOR> <MINOR>
debug-install:

4 h s
Note: In some cases MAKE_CHAR_NODE will be called by the hardware layer of the driver.

1 u e
Each rule (build-install and debug-install) should end with an empty line.

0 h l
7 i b s a
dev_install for driver development package
Have it set to the following. Make changes as per your driver and device details.

1 t
# Install Script
build-install:

a n h i v
MKDIR_NOCLEAN %SP-XINC/<Driver Name>

h s
COPY_DIR ./ %SP-XINC/<Driver Name>

s da
debug-install:
Each rule (build-install and debug-install) should end with an empty line.

s a
Depends for binary driver package
Add kernel package and helper as run-time dependencies for the binary driver package.
Name: kernel

128 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Operator: ==
Version: 1.0.0

Name: helper
Operator: ==
Version: 1.0.0

Build Details

E -
R
1. Add the following Build Depends entries.
crosscc == 1.0.0
global_dev == 1.0.0

T
kernel_dev == 1.0.0
rules == 1.0.0

O T E
helper_driver_dev == 1.0.0

N IBU
2. Click on Global Rules to create the RULES file. This file includes the build rules for the source package
and binary packages that are created out of source package.
RULES should be set as following.

O
#Extract Source in %SOURCE
extract_source:

R
D T 241
#Build Source in %BUILD 2
S
build_source:

I
CWD %BUILD/%PACKAGE/data
INVOKE_MAKE

D 30
#Clean Source
clean_source:
8 1 a n
INVOKE_MAKE clean

4 h
CWD %BUILD/%PACKAGE/data

s
1
---------------

0 h u l e
#--------------------- Mandatory Rules for every binary package ----------
# Rules to create <Driver Name> package

7
PACK_SP-X ./

1 t b
build_package-<Driver Name>:

i s a
%BUILD/%PACKAGE/data/<Driver Name>.ko

n i v
# Rules to create <Driver Name>_driver_dev package
build_package-<Driver Name>_driver_dev:

a h
MKDIR_CLEAN %TEMPDIR/%PACKAGE/tmp

etc.
h
s da s
# Do the following COPY_FILE for all the header files that need to be part
of development package which will be used by other modules like library
COPY_FILE %BUILD/%PACKAGE/data/<Header File> %TEMPDIR/%PACKAGE/tmp
PACK_SP-X ./ %TEMPDIR/%PACKAGE/tmp

a
3. Create SP-X package and confirm that the intended SP-X package was created in the selected directory.

s
129 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Case Example
Get the SP-X source from GIT and convert to spx using the command **git spx convert** and import
pwmtachtool-1.0.0-src.spx into MDS.
Go through various tabs of the SP-X package editor once the package is loaded. You can refer to the RULES,

-
dev_install etc of various packages that are created out of pwmtach-1.0.0-src.spx common driver package.

E
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
130 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 8

E -
Hardware Driver Package Creation
R
This section provides the guidelines to create SP-X package for hardware driver module. An example could be

T E
PWMTACH hardware device driver module. The following sections will provide detailed instructions on how
to create SP-X package for a hardware device driver module.

O
N IBU T
All the developers need to adhere to the steps provided in this document to ensure that all the created packages
fit into overall SP-X architecture scheme.

SP-X Package creation for a driver module

O
Pre-requirements for a SP-X driver package

R
D T 241 2
1. All of the device drivers in SP-X stack are split into two driver modules: common and hardware. There
might be few exceptions like I2C driver. Any driver which is not in this form might need to be split into
common and hardware, and tested before converting them into SP-X package format.

I S
2. Any header files that are used only within the driver need to be copied in the driver source directory it

1
self, if outside the directory. For example; if a header file is kept in common/include but only used by the

n
device driver, we need to remove it from common/include and put it in the device driver directory itself.

D 30 8 a
3. Any header files (for example; IOCTLs or data structures definition) that are used by the driver and an
other module (say another driver or library), need to be identified.

h
4. All the header files need to be cleaned up/split accordingly so that they fit into either of the above two cat

1 4 u s
egories (point 2 and 3). No single header file contents should belong to both the categories.
5. All the C and H files must have copyright header.

e
l
/****************************************************************
**
**

70 b h a
(C) Copyright 2006-2009, American Megatrends Inc.

i s
**
**

1 t
** **
**
**
**

a n h i v
All Rights Reserved.

5555 Oakbrook Pkwy Suite 200, Norcross,

**
**
**

h s
** **
** Georgia - 30093, USA. Phone-(770)-246-8600. **
**

s da **
****************************************************************/

a
6. Makefile needs to be cleaned up and changed.

s
131 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Makefile
Makefile should contain the following sections.

Debug flag
DEBUG := n

E -
Finally built driver module name (target)

OBJS
T R
TARGET := <Driver module name>

OBJ files to be created for each source file in the driver

E
:= <Source File 1>.o <Source file 2>.o

O
N IBU T
CFLAGS to include the other header files/rules etc

Mandatory CFLAGS: Always include them in your Makefile

EXTRA_CFLAGS += -I${SP-XINC}/global

O R
D T 241 2
EXTRA_CFLAGS += -I${SP-XINC}/helper

Also include the CFLAGS required to include header files provided by the common
driver

I S
EXTRA_CFLAGS += -I${SP-XINC}/<Common Driver module>

D 30 8 1 n
Mandatory include of Rules.make.drivers

a
-include ${TOOLDIR}/rules/Rules.make.drivers

h
DEBUG

1 4
:= n

u s
EXAMPLE: pwmtach_hw driver package Makefile

e
l
TARGET := pwmtach_hw
OBJS

70 i b h
:= pwmtachmain_hw.o

s a
t
EXTRA_CFLAGS += -I${SP-XINC}/global

1 n i v
EXTRA_CFLAGS += -I${SP-XINC}/helper
EXTRA_CFLAGS += -I${SP-XINC}/pwmtach

h a s h
-include ${TOOLDIR}/rules/Rules.make.drivers

s da
Using MDS SP-X package creator
Please refer to MDS_UserGuide for step by step instructions on how to use SP-X package creator in MDS. This

a
section will deal with how various fields/settings are configured to create a SP-X hardware driver package.

s
Common and hardware modules of a driver need to be converted into two separate SP-X driver packages. The
guidelines explained here apply to a hardware driver package creation.

132 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Creating the SP-X package using MDS wizard

1. File name for the new SP-X package should be unique and as per the driver. For example; PWMTACH
hardware driver can be named as pwmtach_pilot_iv_hw. Please note that this is not the actual SP-X pack
age name. It’s just an internal workspace container name within MDS for this package.

-
2. Select package type as source and click ‘Next’ to enter SP-X package specific details. This is where we enter
the final SP-X package details.

Owner: Must be AMI.

R E
3. Name: For hardware driver, append ‘_hw’ to the driver name. Examples; pwmtach_hw or adc_hw.

Maintainer and Maintainer’s Email: Your full name and AMI’s email address.

T E
Source Location: AMI

T
Source Version: 1.0.0

O
Description: Provide brief, accurate details about the drive module.

N IBU
Destination Directory: Provide the path where you want the final SP-X package to be created.
The following sub-sections explain each tab of the package creator in the order they need to be used.

Overview
O R
D T 241 2
The following five fields need to be set accordingly. All the other fields should not be modified.

S
Field Name Value
Architecture
Essential
Config-Tags
Group
I
D 30 8 1 a n
Select the proper architecture
YES

DEVICE
SOC

4 h s
Proper SoC should be selected
If there is a known issue with the driver, add it with proper notes.

Files

0 1 h u l e
7 i b s a
1. Add all the source, header, and Makefile files in your driver directory. Do not use Add Folder to include
the source files at this time. Always use Add Files and then select all the source files that you want to be

1 t v
part of the package.

a n h i
2. Also add any common header files (as specified in pre-requirements, point 4).
Binary Packages (Note that we skipped ‘Build Details’ for now)

h
s da s
Each Hardware driver source package, when built, creates one binary package. For example; PWMTACH
hardware driver source package will create PWMTACH hardware binary driver package.
This tab provides details on the binary package created out of this source package.

s a
133 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Follow the table below to create the binary driver package. None of the other fields should be modified, unless
stated.

Field Name Binary driver package Example

Binary Driver Name <Driver Name> pwmtach_hw
Essential
Section
Config-Tag

E - YES
Sys

R
Group DEVICE
Description Provide brief details

T E
Scripts/dev_install Refer “Files and Directories in Control
Section of all Binary Packages”
Depends

O
N IBU T Refer “Format of INFO”

Add known issues, if any. Provide details about the issues in the notes.

dev_install for binary driver package

O
Have it set to the following. Make changes as per your driver and device details.
# Install Script

build-install: R
D T 241 2
I S
COPY_DIR ./ %IMAGE_TREE/lib/modules/2.6.28.10-ami/misc/

1
ADD_MODULES <Driver Name>

D 30 8 n
debug-install:

h a
nodes.

1 u s
Note: MAKE_CHAR_NODE may be added here, if the driver needs to add hardware specific device

4 e
0 h l
Each rule (build-install and debug-install) should end with an empty line. Note that there is no device node
created for a hardware driver module, as it’s not required.

7 b a
1 n i i v s
Depends for binary driver package

t
Add the following packages as run-time dependencies for the binary driver package.

a
Name: kernel
Operator: ==

h
Version: 1.0.0

s h
s da
Name: helper
Operator: ==

s a
Version: 1.0.0

Name: Common Driver Package Name (For example; it will be pwmtach for PWMTACH

134 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

driver module)
Operator: ==
Version: 1.0.0

Build Details

crosscc == 1.0.0
global_dev == 1.0.0
E -
Add the following Build Depends entries.

rules == 1.0.0

T R
helper_driver_dev == 1.0.0
kernel_dev == 1.0.0

E
T
Click on Global Rules to create the RULES file. This file includes the build rules for the source package and

O
binary packages that are created out of source package.

N IBU
RULES should be set as following.
#Extract Source in %SOURCE
extract_source:

O R
#Build Source in %BUILD

D T 241
build_source:
2
CWD %BUILD/%PACKAGE/data

S
INVOKE_MAKE

I
#Clean Source

D 30
clean_source:

8 1 a n
CWD %BUILD/%PACKAGE/data
INVOKE_MAKE clean

4 h s
u
#--------------------- Mandatory Rules for every binary package ----------

0 1
---------------

h l e
# Rules to create <Driver Name> package

a
b
build_package-<Driver Name>:

1 7
PACK_SP-X ./

t i s
%BUILD/%PACKAGE/data/<Driver Name>.ko

v
Case Example
a n h i
Create SP-X package and confirm that the intended SP-X package was created in the selected directory.

h
s da s
Get the SP-X source from GIT and convert to spx using the command **git spx convert** and import pwmtach_
hw-1.0.0-src.spx into MDS.
Go through various tabs of the SP-X package editor once the package is loaded. You can refer to the RULES,

a
dev_install etc of various packages that are created out of pwmtach_hw-1.0.0-src.spx hardware driver package.

s
135 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 9

Library Package Creation

E -
R
This section provides the guidelines to create SP-X package of a library module. An example could be

T E
PWMTACH library module. The following sections will provide detailed instructions on how to create a SP-X
package for a library module.

O
N IBU T
All the developers need to adhere to the steps provided in this document to ensure that all the created packages
fit into overall SP-X architecture scheme.

SP-X Package creation for a library module

O
Pre-requirements for a library SP-X package

R
D T 241 2
1. Any header files that are used only within the library need to be copied in the library source directory
itself, if outside the directory. For example; if a header file is kept in common/include but only used by the
library, we need to remove it from common/include and put it in the library directory itself.

I S
2. Any header files (for example; library APIs or data structures definition) that are used by the library

1
and another module (say another application), need to be identified. These files will be exported as the

n
development binary package of this library source SP-X package.

D 30 8 a
3. All the header files need to be cleaned up/split accordingly so that they fit into either of the above two
categories (point 2 and 3). No single header file contents should belong to both the categories.

h
4. All the C and H files must have copyright header.

**

1 4 u s
/****************************************************************

e
**

l
** (C) Copyright 2006-2009, American Megatrends Inc. **
**
**

70 b h a
All Rights Reserved.

i s
**
**

t
** **
**
**
1 n i v
5555 Oakbrook Pkwy Suite 200, Norcross, **
**
**
**

h a s h
Georgia - 30093, USA. Phone-(770)-246-8600 **
**
****************************************************************/

s da
5. Makefile needs to be cleaned up.
Makefile

s a
Makefile should contain the following sections.

136 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Debug flag
DEBUG = n

Finally built library module name

E -
LIBRARY_NAME = <Library module name>

Source files to be compiled in the library

R
SRC = <Source File 1>.c <Source file 2>.c

Include CFLAGS to include the header files etc., if any, used by the library

O T T E
CFLAGS += -I${SP-XINC}/<Directory name>

Mandatory include of Rules.make.libs

N IBU
include ${TOOLDIR}/rules/Rules.make.libs

EXAMPLE: pwmtach library package Makefile

DEBUG = n

SRC
O R
D T 241
LIBRARY_NAME = libpwmtach
= pwmtach.c
2
I S
CFLAGS += -I${SP-XINC}/pwmtach

D 30 8 1 n
include ${TOOLDIR}/rules/Rules.make.libs

a
Using MDS SP-X package creator

h s
Please refer to MDS_UserGuide for step by step instructions on how to use SP-X package creator in MDS. This

1 4
section will deal with how various fields/settings are configured to create a SP-X library package.

u l e
Creating the SP-X package using MDS wizard

h
70 i b s a
1. File name for the new SP-X library package should be unique and should have a prefix of lib to differenti
ate it as a library package. For example; PWMTACH library package can be named as libpwmtach. Please

1 n t
note that this is not the actual SP-X package name. It’s just an internal workspace container name within

i
MDS for this package.

v
a
2. Package name should also be prefixed with lib for a library SP-X package.

h s h
3. Select package type as source and click ‘Next’ to enter SP-X package specific details. This is where we enter
the final SP-X package details.

s da
4. Name: For the library, it should be the same as the library name, prefixed with lib. Example; libpwmtach
or libadc.
Owner: Must be AMI.

s a
Maintainer and Maintainer’s Email: Your full name and AMI’s email address.
Source Location: AMI

137 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Source Version: 1.0.0

Description: Provide brief, accurate details about the library module.
Destination Directory: Provide the path where you want the final SP-X package to be created.

-
The following sub-sections explain each tab of the package creator in the order they need to be used.

Overview

R E
The following five fields need to be set accordingly. All the other fields should not be modified.

Field Name Value

T E
Architecture ALL
Essential NO
Config-Tags
Group
SOC O
N IBU T NONE

If there is a known issue with the library, add it with proper notes.

Files
O R
D T 241 2
1. Add all the source, header, and Makefile files in your library directory. Do not use Add Folder to include
the source files at this time. Always use Add Files and then select all the source files that you want to be

S
part of the package.

I
D 30 1
2. Also add any common header files (as specified in pre-requirements, point 4).

n
Binary Packages (Note that we skipped ‘Build Details’ for now)

8 a
Each library source package, when built, creates two or more binary packages. For example; PWMTACH

h
library source package will create PWMTACH library binary package and PWMTACH library development

s
package. The development package will be used by another module, say an application that uses this library.

4
0 1 h u
This tab provides details on the binary packages created out of this source package.

l e
Follow the table below to create these two binary packages. None of the other fields should be modified, unless
stated.

1 7
Field Name

t i b s a
Library Binary package Library development package Example
Name

Essential

a n NO

h i v
<Library Name> <Library Name>_dev

NO
libpwmtach
libpwmtach_dev
and

Section

h
s da
Config-Tag
Group
Description
s
lib

None
Provide brief details
Dev

Provide brief details

install
a
Scripts/dev_

s
Refer “Files and Directories in
Control Section of all Binary
Packages”
Refer “Files and Directories in
Control Section of all Binary
Packages”

138 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC
Add known issues, if any. Provide details about the issues in the notes.

dev-install.py for library binary package

Have it set to the following. Make changes as per your library details. Note the spaces carefully.
#!/usr/bin/env python
import PyRules
from
from

E -
#-------------------------------Import Rules Files ----------------------------
PyRules import PrjVars
PyRules import *
#------------------------------ Extra Python modules --------------------------

R
##-----------------------------------------------------------------------------

O T T E
#------------------------------------------------------------------------------
# Rules for Installing to ImageTree
#------------------------------------------------------------------------------
def build_install():

N IBU
IMAGETREE=PrjVars[“IMAGE_TREE”]
SPXLIB=PrjVars[“SPXLIB”]
PKG_MAJOR=PrjVars[“PKG_MAJOR”]
PKG_MINOR=PrjVars[“PKG_MINOR”]
PKG_AUX=PrjVars[“PKG_AUX”]

O
if retval != 0:

D T 241 2
retval = Py_MkdirClean(SPXLIB+”/uartlogging”)

Rreturn retval
retval = Py_CopyDir(“./”,IMAGETREE+”/usr/local/lib/”)
if retval != 0:

S
return retval

I
D 30 8 1
retval = Py_AddLiblinks(IMAGETREE+”/usr/local/lib/”,”libuartlogging.
if retval != 0:

a n
so.”+PKG_MAJOR+”.”+PKG_MINOR+”.”+PKG_AUX)
return retval

h
retval = Py_CopyFile(“./libuartlogging.so.”+PKG_MAJOR+”.”+PKG_
MINOR+”.”+PKG_AUX,SPXLIB+”/uartlogging/”)

s
if retval != 0:

1 4 return retval

u e
retval = Py_AddLiblinks(SPXLIB+”/uartlogging/”,”libuartlogging.

h l
so.”+PKG_MAJOR+”.”+PKG_MINOR+”.”+PKG_AUX)

70
if retval != 0:
return 0

i b s a
return retval

#
1 n t i v
#------------------------------------------------------------------------------
Rules for Debug Install
#------------------------------------------------------------------------------

h a
def debug_install():
return 0

s h
s da
Each rule (build-install and debug-install) should end with an empty line.

s a
dev_install.py for library development package
Have it set to the following. Make changes as per your library details. Note the spaces carefully.
#!/usr/bin/env python

139 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

#-----------------------------------------Import Rules Files ------------------

import PyRules
from PyRules import PrjVars
from PyRules import *
#--------------------------------------- Extra Python modules -----------------

-
#------------------------------------------------------------------------------

E
#------------------------------------------------------------------------------
# Rules for Installing to ImageTree
#------------------------------------------------------------------------------

def build_install():

T R
IMAGETREE=PrjVars[“IMAGE_TREE”]

E
SPXLIB=PrjVars[“SPXLIB”]
SPXINC=PrjVars[“SPXINC”]

T
PKG_MAJOR=PrjVars[“PKG_MAJOR”]

O
PKG_MINOR=PrjVars[“PKG_MINOR”]
PKG_AUX=PrjVars[“PKG_AUX”]

N IBU
retval = Py_Mkdir(SPXLIB+”/ipmiamioemsensorthresholdacrossresets”)
if retval != 0:
return retval

O
retval = Py_CopyFile(“./libipmiamioemsensorthresholdacrossresets.so.”+PKG_
MAJOR+”.”+PKG_MINOR+”.”+PKG_AUX, SPXLIB+”/ipmiamioemsensorthresholdacrossre-
sets/”)

R
D T 241
if retval != 0:
return retval
2
retval = Py_AddLiblinks(SPXLIB+”/ipmiamioemsensorthresholdacrossresets/”,

S
“libipmiamioemsensorthresholdacrossresets.so.”+PKG_MAJOR+”.”+PKG_MINOR+”.”+PKG_

I
AUX)

1
if retval != 0:

n
return retval

D 30 8 a
retval = Py_Mkdir(SPXINC+”/ipmiamioemsensorthresholdacrossresets”)
if retval != 0:
return retval

h s
retval = Py_CopyFile(“./IPMI_SensorThresholdAcrossResets.h”, SPXINC+”/ip-

4
miamioemsensorthresholdacrossresets”)

u
if retval != 0:

0 1
return retval

h l e
retval = Py_Execute(“rm -rf libipmiamioemsensorthresholdacrossresets.so.*”)
if retval != 0:

a
1 7 t b
return retval

i s
retval = Py_SoftLink(“../libipmiamioemsensorthresholdacrossresets.so.”+PKG_

v
MAJOR+”.”+PKG_MINOR+”.”+PKG_AUX, “libipmiamioemsensorthresholdacrossresets.

n
if retval != 0:

a
return retval

h i
so.”+PKG_MAJOR+”.”+PKG_MINOR+”.”+PKG_AUX)

h
return 0

s da s
#------------------------------------------------------------------------------
# Rules for Debug Install
#------------------------------------------------------------------------------
return 0

s a
def debug_install():

#------------------------------------------------------------------------------

140 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Each rule (build-install and debug-install) should end with an empty line.

Build Details
Add the following Build Depends entries.
crosscc == 1.0.0
global_dev == 1.0.0
rules == 1.0.0

E -
Also add any other development package that is required by this library. For example; libpwmtach would

T R
require PWMTACH driver development package for the IOCTL and data structures definitions.
Click on Global Rules to create the RULES.PY file. This file includes the build rules for the source package and

E
binary packages that are created out of source package.

extract_source: O
N IBU T
RULE.PYS should be set as following.
#Extract Source in %SOURCE

#!/usr/bin/env python

O
import PyRules
from
from 2
#-------------------------Import Rules Files ----------------------------------

R
D T 241
PyRules import PrjVars
PyRules import *
#------------------------------------------------------------------------------

import os
import glob

I S
#-------------------------Extra Pyhon modules ---------------------------------

D 30 8 1 n
#------------------------------------------------------------------------------

h a
#------------------------------------------------------------------------------
# Rules for Extracting Source

1 4
def extract_source():
return 0

u s
#------------------------------------------------------------------------------

e
#

70 b h a l
#------------------------------------------------------------------------------
Rules for Clean Source Directory

i s
#------------------------------------------------------------------------------

1 t
def clean_source():

n i v
BinDir = PrjVars[“BINARY”]
return Py_DeleteAll(BinDir,”Kernel_5_Pristine-*-*.spx”)

a h
h s
#------------------------------------------------------------------------------
# Rules for Building Source

s da
#------------------------------------------------------------------------------
def build_source():
retval=0

s a
Extension=”.tar.bz2”
# Scan data area to get Kernel name
PkgDir=”%s/%s”%(PrjVars[“BUILD”],PrjVars[“PACKAGE”])
KernList=glob.glob(PkgDir+”/data/*”+Extension)
if len(KernList) != 1:
# Default Compression type

141 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

print(“[ERROR] : Unable to find the proper Pristine kenrel”)

return 1
Name=os.path.basename(KernList[0]) # linux-5.2.14.tar.bz2
#Get Kenel Version
Prefix=Name.rstrip(Extension) # linux-5.2.14
Version = Prefix.split(“linux-”)[1] # 5.2.14

stall kernal and modules

E -
Py_AddMacro(“SPX_KERNEL_VERSION”,Version+”-ami”)

# Create kenrel souuce direcotry where it will be extracted

Kernel_Src=PrjVars[“KERNEL_SRC”]
# Used to build/in-

T
# UncompressR
retval = Py_MkdirClean(Kernel_Src)
if retval != 0:
return retval

E
retval = Py_UntarBz2(PkgDir+”/data/”+Name,Kernel_Src)

O
N IBU T
if retval != 0:
return retval
# Rename directory linux-version to linux
retval= Py_Rename(Kernel_Src+”/linux-”+Version,Kernel_Src+”/linux”)
if retval != 0:
return retval

O
return 0

R
D T 241 2
#------------------------------------------------------------------------------
# Rules for Creating (Packing) Binary Packge
#------------------------------------------------------------------------------
def build_package_Kernel_5_Pristine():

I S 1
return Py_PackSPX()

D 30 8 n
h a
#------------------------------------------------------------------------------
Create SP-X package and confirm that the intended SP-X package was created in the selected directory.

Case Example

1 4 u s e
Get the SP-X source from GIT and convert to spx using the command **git spx convert** and import pwmtach_

7 b h
hw-1.0.0-src.spx into MDS.

0 a l
Go through various tabs of the SP-X package editor once the package is loaded. You can refer to the RULES,

1 n i i v s
dev_install etc of various packages that are created out of libpwmtach-1.0.0-src.spx library package.

t
h a s h
s da
s a
142 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 10

E -
SP-X Web Customization HTML5

R
New HTML5 Web UI of SP-X core will have following packages.

T E
Note: The language strings syntax codes are implemented using the i18n plugin. User can create/modify the
below packages with any editor.
1. webui_html5-src

O
N IBU
2. webui_html5_libs-src
3. webui_scaffold-src
T
O
4. spx_restservice-src

R
D T 241
5. spx_restservice_ext.src

webui_html5-src
2
I S
Note: All the below syntax codes are implemented using i18n for language strings.

D 30 1 n
This Package contains SPX HTML5 web page related files. The Folders of the package are as follows.

8
•
•
h a
api – Contains page-wise application offline data
app- Contains the HTML pages.
•

1 4 u s
spx – Contains rules and Licenses

e
•

0 b h a l
Test – Contains unit test cases for REST_services
The app folder contents are as follows.

7
•

1
control.

n t i i v s
Models- It contains the interactive data, conversions, validations, computed properties, and access

a h
• Collection – a set of models make up the collection.
•

h s
Css- CSS stands for Cascading Style Sheets.CSS describes how HTML elements are to be displayed on
screen, paper, or in other media. CSS saves a lot of work. It can control the layout of multiple web pages all at

s da
once. External stylesheets are stored in CSS files
• fonts – this folder contains font properties define the font family, boldness, size, and the style of a text.
•
• a
images – contains application images.

s
less- contains libraries styles (style.less)

143 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• Libs- contains plugins for the applications.

• Strings- locale variables are defined in this folder.
• Styles-contains boiler template related styles.

-
• Templates- Contains HTML pages
• Views – files in this folder defines how model should look and what it should do.

Adding New Menu Item

R E
The Menu Bar is located at the left side of the MegaRAC® SP-X Web UI. It contains a list of menus as follows.
•
•
Dashboard
Sensor

O T T E
N IBU
• System Inventory
• FRU Information

O
• Logs and Reports
•
•
•
Settings

R
D T 241
Remote Control
Power Control
2
•

I S
Maintenance

D 30 8 1 n
A sample screenshot is shown as below.

h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a Dashboard

144 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

SP-X Web UI - Menu Item

To Add a Screen in UI without sub menu:
1. Step-1: Adding link under left-side menu bar

-
Goto app->templets-> layouts-> main.html and add a tag in main.html as shown below.

E
For Example:

R
<li>

<a href=”#sample”>

O T T E <i class=”fa fa-cog”></i>

<span><%=locale.sample%></span>

N IBU </a>

O R
</li>

2
2. Step-2: Create a new file in templates->sample.html using html5

D T 241
This .html file helps to overview the screen

S
1. Navigation is provided using content header
For example:

I
D 30 8 1 a n
<!-- Content Header (Page header) -->

<h1>

4 h
<section class=”content-header”>

s
0 1 h u l e
<%= locale.power_control %>

1 7 i b a
<small><%= locale.tag %></small>

t s
</h1>

a n h i v
<ol class=”breadcrumb”>

h
s da s
<li><a href=”#”><i class=”fa fa-home”></i> <%= locale.home %></a>

</li>

s a <li class=”active”>

<%= locale.power_control %>

145 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

</li>

</ol>

</section>

For example:

E -
2. Main content is given using div tags as shown below

R
<div class=”form-group” >

<label for=”bmc_reg”><%= locale.dns_settingsbmc_reg %></label>

O T T E
<div class=”form-control-static” id=”idbmc_reg”></div>

</div><div id=”display_registration”>

N IBU
</div><div class=”form-group”>

O
<hr/>

</div>

R
D T 241 2
Note: Locale variables should be declared in strings folder.

S
3. Step-3: Add sample.js files in strings folder

define({ I
D 30 8 1
The below mentioned content should be available in the sample.js under strings folder.

a n
“root”: true

4 h s
});

1 h u l e
Create one more file as sample.js in strings->root,

0
1 7
For example:

t i b s a
Here need to define all the locale variables that used in templates and views.

n i v
“dns_settingsbmc_reg”: “BMC Registration Settings”,

a h
4. Step-4: Add sample.js files in view folder

h
s da s
Events in this view file can be generated as follows.

events: {

s a
“click #save”: “saveConfirm”,

},

146 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

And the save function is defined in view file as

save: function() {

var this = that;

E -
context.model.save({

‘trigger_event_severity’: $(‘#idtrigger_event_severity’).
val(),

T R E
‘power_action’: $(‘#idpower_action’).val(),

T
}, {

fa-save”);
O
N IBU
success: function() {

context.$(“#save-icon”).removeClass().addClass(“fa

O R
D T 241 2 app.events.trigger(‘save_success’, context);

var back_url = location.hash.split(‘/’);

I S
D 30 8 1 n
back_url.pop();

back_url.pop();

h a app.router.navigate(back_url.join(‘/’), {

1 4 u s e
});},
trigger: true

70 b h a l
error: function() {

1
fa-save”);

n t i i v s context.$(“#save-icon”).removeClass().addClass(“fa

h a s h }
app.events.trigger(‘save_error’, context);

}); }

s da
5. Step-5: Add sample.js files in model folder

a
1. Model should be created in the following way

s
Var model= Backbone.Model.extend({

147 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

initialize: function(){

alert(“Hello AMI”);

});

var human = new model();

E -
Model

T R
Validations can be given in the following way

E
function($, _, Backbone, app, locale) {

O
N IBU T
var model = Backbone.Model.extend({

defaults: {},

validation: {

O R
D T 241 2
policy_group: {

required: true,

S
msg: locale.required_policy_group

I
D 30
}
}

8 1 a n
});

4 hs
});
return model;

0 1 h u l e
7 i b a
6. Step-6: Add sample.js files in collection folder (if data is in collection)

1 t s
v
Backbone collections are simply an ordered set of models. It can be used in situations such as;
•
n i
Model: Todo Item, Collection: Todo List
For Example:
a h
h
s da s
function($, _, Backbone, DnsRegistrationModel) {

var collection = Backbone.Collection.extend({

s aurl: function() {

return “/api/settings/dns/registration”

148 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

},

model: DnsRegistrationModel

});

});

E -
return new collection();

R
A sample screen shot of a screen without sub-menu

O T T E
N IBU
O R
D T 241 2
I S
D 30 8 1 n
h a
7. Step-7: Add the sample URL in router.js
Backbone routers are used for routing the applications URL’s when using hash tags (#). That is to change the

4
the particular route.

1 u s
URL while rendering the view. Defined routers should always contain at least one route and a function to map

e
70 b h a l
Backbone routes are simple objects which handle the incoming route value from the URL and invoke any
function. Example to create a very simple route class for our application is given below.

1
});
n t i s
var Router = Backbone.Router.extend({

i v
h a s
the appropriate view.
h
Then if the request is for any specific view, we will simply invoke the function which will take care of rendering

s da
Sample : function(event) {

s a this.setView(SampleView);

149 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC
Also note that router interpret anything after “#” tag in the URL. All links in your application should target “#/
action” or “#action”.
app/router.js (app/router.js) extend Backbone’s router. In the example below we are going to define a route that
is always called.

E -
define([“views/DashboardView”,”views/SampleView”],

function(DashboardView,SampleView) {

“use strict”;

T R E
// Defining the application router.

N IBU
routes: {
T
var Router = Backbone.Router.extend({

O“dashboard”: “dashboard”,

O
}, R
D T 241
“sample”: “sample”,

2
“”: “default”

I S 1
default: function() {

D 30 8 n
h a
this.navigate(“dashboard”, {

trigger: true

1 4 });

u s e
70
},

b h a l
i
dashboard: function(event) {

1 n t i v s
this.setView(DashboardView);

h a},

s h
sample: function(event) {

s da this.setView(SampleView);

s a},

setView: function(View) {

150 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

var view = new View();

app.layout.setView(“.right-side”, view).render();

app.lastActiveView = view;

});
}

E -
});
return Router;

T R E
O
exactly where we are now.

N IBU T
The Router detects changes to the URL — say, pressing the “Back” button and can tell the application

To navigate to the sample html page, we should use “#sample”. The router interpret anything after “#”
tag in the URL.

O R
D T 241
<a href=”#sample”>
2
In Html :

S
In View :

I 1 n
app.router.navigate(“sample”);

D 30 8 a
h
To Add a Screen in UI with sub menu:

1 u s
1. Step-1: Adding link under left-side menu bar

4 e
Follow the procedure as explained in To Add a Screen in UI without sub menu section.

0 h l
2. Step-2: Create a new template for sub-menu and add div tags as shown below

7 b a
</div>

1 n t i i v s
<div class=”col-md-3”>

h a s h <a href=”#settings/log” class=”big-button”>

s da
<div class=”icon”><i class=”ion-document-text”></i>

</div>

s a </a>
<span class=”name”><%=locale.log_settings%></span>

151 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

</div>

<div class=”col-md-3”>

<a href=”#settings/media” class=”big-button”>

E - <div class=”icon”><i class=”fa fa-hdd-o”></i>

</div>

span>

T R E
<span class=”name”><%=locale.media_redir_settings%></

T
</a>

O</div>

N IBU
3. Step-3: Similarly, create a new view file for sub-menu as shown below

O
define([‘jquery’, ‘underscore’, ‘backbone’,

R
D T 241 2
‘i18n!strings/nls/settings’,

‘text!templates/settings.html’

],

I S
D 30 8 1 n
h a
function($, _, Backbone, CommonStrings, SettingsTemplate) {

1 4 u s e
var view = Backbone.View.extend({

70 b h a l
1 n t i s
template: _.template(SettingsTemplate),

i v
h a s h
initialize: function() {

s da },

s a
152 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

events: {},

beforeRender: function() {

},

E -
afterRender: function() {

},

T R E
load: function(model, collection, xhr) {

O
},

N IBU T
serialize: function() {

return {

O R
D T 241 };2 locale: CommonStrings

I
});S
D 30
}

8 1 n
return view;

h a
});

1 4 u s
4. Step-4: Create new string files to define locale variables that used in template and View.

e
0 h l
A sample Screenshot of sub-menu is shown below.

7 b a
1 n t i i v s
h a s h
s da
s a
153 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
Note: Sub- menu can be created by using the procedure explained in To Add a Screen in UI in scaff_folder
section.
5. Step-5: Repeat the steps 2-6(of To Add a Screen in UI without sub menu) for implanting screen in sub-
menu.

O R
D T 241 2
6. Step-6: Refer “Step-7: Add the sample URL in router.js”

webui_html5_libs-src

I S
This package will contain bootstrap library like Tree view, time zone, chart, underscore, notify etc., which are

D 30 8 1 n
used in webui_html5 packages. This package is not customizable.

for example-

h a
User can add new bootstrap library in folder data/bower.json file as explained below.

4 u s
“bootstrap-treeview”: “~1.2.0”,

1 e
0
“select2”: “~4.0.0”,

7 b h a l
n i i v s
“moment-timezone”: “~0.4.0”

1 t
In webui_html5 package,config.main.js file need to be updated with newly added library in webui_html5_libs-
src package as mentioend below.
For example:

h a s h
s da
“tree-view”:”../vendor/bower/bootstrap-treeview/dist/bootstrap-treeview.
min”

a
“tree-view”:[“jquery”]

s
154 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Webui_Scaffolder
Note: All the below syntax codes are implemented using i18n for language strings.
SPXUI-Gen Scaffold is based on DRY principle. To make development fast, this tool has been created. This
document will describe the JSON key fields and its description and to implement a new screen using scaffolder.

E -
Some screens of settings and maintenance pages have been developed by scaff-folder.
This Package contains the following folders:
•
•
•
R
Data – This folder contains all JSON files.
Deprecated – This contains all deleted files from data folder

T E
Fns - This contains php files which load templates with its respective functionality eg: button, checkbox,

•
•
O
radio button etc

N IBU T
Spx – this folder contains all rules and Licenses.
Template- which contains HTML5 files

O
Webui_scaffolder contains following files:
•
•
R 2
Constants.php – contains placeholders

D T 241
Fn.php – This file generates the Output files for the JSON data passed from gen.php .

S
• Gen.php – this is the main file which passes JSON files one after another from data folder to fn.php.

I
D 30 8 1
JSON structure explained:

a n
reference (Root level or components level)

h
The value of this key is used to determine the name of the View, Model, Collection and/or Template files and
the objects as necessary.

4 s
0 1 h u l e
tpl_type (Root level or components level)
This key denotes the type of the template to be used. Accepted values are,
• page

1 7 t i b s a
•
•
form
list

a n h i v
s
• form_order
•
•
h
s da
form_img
form_collection
•
•
grid

s a
checklist

155 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• graph
• cpanel
• tablelist

-
strings (Root level or components level) {deprecated}

E
This key is used for localizing contents on a template. The localized contents will be under the language object.

R
“strings”: { “en”: { “key1”: “value1”, ...}, “fr”: {“key1”: value1 “,
...}}

T E
JSON structure for Page template

T
Localized string set is a JSON set of strings with key defining the language and value defining the string itself.

Sample Code: O
N IBU
O
“title”: {

R
D T 241 2
“en” : “Title”,

“zh-tw” : “現有 IP 規則”,

},
I S
“zh-cn” : “现有 IP 规则”

D 30 8 1 n
h a
“privilege_level”: “ADMIN”,

1
“models”: [{
u s
“collection”: [{….}]

4 e
….

70 b h a l
1 }]

n t i i
“components”: [{
v s
h a s h
“item_non_deletable”:false,

s da
“delete_confirm”: true,

“fieldset”: [

s a
156 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

“field_type”: “collection_field”,

“field_name”: “reg_ifc”,

“label”: {

E -
“en”: “BMC Interface”,

“zh-tw”: “BMC 介面”,

},

T R E
“zh-cn”: “BMC 界面”

O
N IBU T
“feature”: “<featurename>”,

“model_bind”: “reg_ifc”,

“short_help”: {

O R
D T 241 2
“en”: “Help in English.”,

“zh-tw”: “Help in Taiwan language”,

S
“zh-cn”: “Help in Chinese language”

},

I
D 30 8 1 a n
“alternate_value”: {

“”: {“en”: “None”}

4 h s
u
} ,

}]

0 1 h a l e
}]
title

1 7 t i b v s
hierarchy
a n h i
Localized string set to display Page Title

h s
This key is used to define breadcrumb for page template. The value must be Array of Objects. The Objects must

s da
have “label” and “url” field.

components

s a
“hierarchy”: [{“label”: {“en”:”value”, “fr”:”...”}, “url”: “#value”},...]

This key can be used in page template. This key holds an array of sub components that can placed in a page. Sub

157 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

component cannot be another page template. But it can be form, cpanel, grid, checklist or graph
JSON structure for CPanel template
navs
Array of objects defining the links to be embedded in the CPanel. Objects can have link, icon and label (localized
string)

E -
JSON structure for List template

R
list_item
Array of objects defining the list item itself
•
• field_name

O T T E
field_type Can be label, div, a, button or tag. Any HTML tag is also allowed

N IBU
• label Localized string. Will print only if en string is valid and not null.
• model_bind In case of label or div, model_bind must be a single string. In case of tag model_bind can be an
array of object with model attribute as key and localized string as value which will be displayed. The model

O
attribute must be a number and value must be greater than 0 for the tag to be displayed.
alternate_value

R
D T 241 2
An object that can map the possible model values to a different data. eg., 0 and 1 can be shown as “inactive” or

S
“active”. The value of each item must be a Localized string.
evaluate

I
D 30 8 1 n
A JavaScript snippet to surround and evaluate a value. Use %%value in the snippet to replace it with model_
bind value

a
table_list_item

4 h s
Array of objects defining the table list item. Note the field names are kept as same as possible, so that just by

1 h u
the order of the array itself.

0 l e
changing the type of the template a different page can be achieved with same data. The order of the column is

•
•

1 7 t i b s a
field_type - Can be label, tag, a, button, icon, div. Any HTML tag is also allowed
field_name - A name associated with the column of the table
•
•
n i v
label - Localized string. Title/Header of that column

a h
priority - Takes value high, low. This option decides which column to show and what to hide when the

•
h s
real estate is small. high means always show. low means always hide.

s da
model_bind - In case of label, icon, div, model_bind must be a string string. In case of tag, select, anchor,
model_bind can be an array of objects with model attribute as key and localized string as value which will
be displayed. The model attribute must be a number and value must be greater than 0 for the elements to

• a
be displayed

s
alternate_value - An object that can map to possible model values to a different data. eg., 0 and 1 can be
shown as “inactive” or “active”. The value of each item must be a Localized string

158 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• evaluate - A JavaScript snippet to surround and evaluate a value. Use %%value in the snippet to replace it
with model_bind value
• item_non_editable - Boolean value to show table item field edit button (Inverse! for backward compat-
ibility)
•
patibility).

E -
item_non_deletable - Boolean value to show table item field delete button (Inverse! for backward com-

table_list_item can have custom_item_actions which can be used to add upto 4 action buttons to the table.

T R
Limitation is to keep UI unclutter. This is an array of objects with following properties. By default all buttons
are hidden. Based on array count the buttons are shown (Only 4 values at max)

E
icon A font based icon to appear on the button
•
•

•
O T
tooltip A title to hover on button when hovered

N IBU
conditional_model_bind A conditional model bind property which must be int/boolean. This value
decides whether or not action button appears (optional) WIP
link A href attribute to navigate to. This can have a dynamic portion which must be “:id”. E.g. (#/settings/

O
service_sessions/:id) Here the :id will be replaced by the collection’s-model “id”. You can have another

R 2
json page at this location

D T 241
table_list_item also has another feature called group_table. This allows a data model to represent a filtered list
item in a table for the selected group. The group_table element must be of same level as the table_list_item. It

S
is not a child of table_list_item.
•
• I
D 30 8 1
enable:: Enable or disable the group option
enable

a n
group_field_name:: The dropdown box element name for group
group_field_name
•
•
h
group_model_bind:: The property in the model on which to groupby
group_model_bind

s
view_all_option:: An option to show “All” models without filter
view_all_option

4
•

1
group_label
list_icon

0 h u l e
group_label:: A localized string label for the group

7 i b a
An icon to be used in left side. Can be from font-awesome, ion icons pack

1 t s
add_item

n i v
Boolean value to enable or disable add button for this list
•
a h
JSON structure for Form template
heading
h
s da s
Localized string set to display Form heading
models

s a
This key denotes the all the models used for that component (or) root. Model contains the interactive data
as well as a large part of the logic surrounding it: conversions, validations, computed properties, and access

159 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

control
• location typically the directory name under model (optional)
• Reference - Refers the module name

-
• url mention the model URL

E
• properties mentions list of properties and their types in this model
• save_props mentions list of properties and their save nature. Nature can be pre_calc, field_value
•

T
“models”: [
R
pre_calc mentions list of saveable pre_calc syntax to be replaced.

E
{

O
N IBU T
“reference”: “ncsi”,

“location”: “”,

O R 2
“url”: “/api/settings/ncsi/mode”,

D T 241
“properties”: {

I S
“mode”: “number”,

D 30 8 1 n
“interface_name”: “string”,

a
“channel_number”: “number”,

h
},

1 u s
“package_id”: “number”

4 e
0
“save_props”: {

7 b h a l
1 n t i i v s “interface_name”: “field_value”,

“channel_number”: “field_value”,

h a s h “package_id”: “field_value”

},

s da
“validation”: {}

}]

s a
160 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Collection
Defines the Collection of model.
Example:

{
“collection”: [

E -
“location”: “”,

T R
“reference”: “ncsi_interfaces”,

E
O
N IBU T
“url”: “/api/settings/ncsi-interfaces”,

“model”: “ncsi_interface”,

“model_position”: 1

},

{ O R
D T 241 2
S
“reference”: “channels”,

I
“location”: “”,

D 30 8 1 a n
“url”: “/api/settings/channels”,

“model”: “channel”,

4 hs
u
“model_position”: 2

},

0 1 h a l e
{

1 7 t i b v s
“reference”: “packages”,

a n
“location”: “”,

h i
h s
“url”: “/api/settings/packages”,

s da
“model”: “package”,

}
s a
“model_position”: 3

161 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC
]
Validation
validation mentions list of properties that has to be validated. (Plugin used link) Additional properties added:
“greaterThan” and “lessThan” (to be used a keys) which validates the current attr value’s against another attr
(mentioned as value).
Example:1

“validation”: {
E -
“property1”: {

T R E
“required”: “true” or “false” or “conditional”,

O
N IBU T
“condition”: “expr”, (only if conditional),

“greaterThan”: “attr”,

“lessThan”: “attr”,

O R
“msg”: {

D T 241 2
“en”: “Property1 is required”,

}
I S
D 30 8
“fr”: “...”

1 n
},

h a
“property2”: {

1 4 u s e
}

70 b h a l
Example:2

1 n
“validation”: {
t i i v s

be added

h a s h
“server_addr”: // Field name for which the validation need to

s da {

s a
<= 65535))”,
en”: “”,
“specRule”: “ computedState.system_log == 1 && value
“msg”: {

162 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

“zh-tw”: “”,

“zh-cn”: “”

E -
R
specRule
The required validation will be given inside this specRule attribute, if the server_addr values satisfies

T T
From above example,

O E
the conditions, then it returns true else false.

N IBU
computedState.system_log: Refers the value of System-log field in the page.
value: Refers the value of server_addr field.
Msg

O R 2
This attribute contains the error message to be displayed when specRule returns true.

D T 241
strongSuccessMsg
Localized string set of the success message highlight (one or two words) to be displayed when this form is

successMsg
I S
stored successfully.

D 30 8 1 n
strongFailureMsg

h a
Localized string set of the full success message to be displayed when this form is stored successfully.

1
while saving
4 u s
Localized string set of the failure message highlight (one or two words) to be displayed when this form is failed

e
0
failureMsg

7 b h a l
i
Localized string set of the full failure message
toggle

1 n t i v s
Toggles a set of field’s visibility or editable mode based on the given model_bind property.
•

h a s h
visibility: Make fieldset given here invisible if the model_bind value is false or 0 or undefined model_
bind: Model property in any model that should be monitored for performing the toggle

s da
fieldset: Array of field_names

a
• editing: Make fieldset given here disabled if the model_bind value is false or 0 or undefined

s
model_bind: Model property in any model that should be monitored for performing the toggle
fieldset: Array of field_names

163 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

msg: A localized string set to be shown over the disabled item

“toggle”: {

“visibility”: {

E -
“model_bind”: “dns_status”,

“fieldset”: [“dns_manual”,”dns_interface”, “dns_server1”, “dns_

server2”, “dns_server3”]

},

T R E
O
“editing”: {

N IBU T
“model_bind”: “dns_status”,

“fieldset”: [“dns_manual”,”dns_interface”, “dns_server1”, “dns_

O
server2”, “dns_server3”],

R
D T 241
“msg: {
2
“en”: “Enable DNS to configure server settings”

}
I
}

S
D 30 8 1 n
}

h a
saveable

1 4 u s
Have a save button in form field

e
70
save_label

b h a l
Localized string set for save button label

1
save_confirm

n t i i v s
Boolean to show a confirmation during save

h a
save_confirm_text

s h
Localized string set for confirmation box
silent
s da
a
Boolean value to saves the model/collection in silent mode. Does not reflect the changes done during save pre-
calculation while saving the form.
deletion
s
164 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Boolean value to show or hide delete button for the list item.
delete_label
Localized string that goes on the delete button for the list item.

-
download

E
Create a download button in the form for doing file download
download_label

download_url

T R
Localized string that goes on the download button.

E
T
Specify the file url to be downloaded. This URL must output data with header Content-Disposition: attachment.

O
In SPX REST service, you can also use STATIC_FILE method with download option set to true.

N IBU
save_before_download
Boolean value to send save request before downloading the file
refreshable

O R
D T 241 2
Have a refresh button in form field
refresh_label

short_help

I S
Localized string set for refresh button label

D 30 8 1 n
a
This attribute should be given under each field, which is used to display help content for the respective fields.
field_name

hs
Defines the name of the field created. This name will be used as the element id.

4
model_bind

0 1 h u l e
Binds the model value with the field. In the above example, reg_tsig is the model variable, which value will be

1 7
delete_confirm

t i b
displayed in the field.

s a
n i v
Confirmation message will be displayed in alert box while deleting the component.

a h
h
privilege_level

s da s
Defines the privilege level of the user. If the value is admin , only admin can view/edit the configuration.
Feature

s a
The field will be displayed only when the mentioned feature is enabled. If the feature name starts with “!”, that
means the field will be displayed only when feature is not enabled.
notify_err_msg

165 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

This attribute is used under file Type fields, which refers the error message to be displayed for invalid
file.
valid_files
This attribute is used under file Type fields, in which the valid file type can be defined as follows.

“valid_files”:{

“0”:”pem”,
E -
“1”:”cert”

T R E
featurebased_enable

O
N IBU T
This attribute is used under checkbox field. The checkbox will be enabled only when the given feature
is enabled, else the checkbox will be disabled and non-editable.

O
featurebased_disable

R 2
This attribute is used under checkbox field. The checkbox will be disabled and non-editable when the

D T 241
given feature is enabled.
field_visibility

I S
This attribute can be used under Checked / Unchecked attribute of checkbox field.

D 30 1 n
“checked”: {“field_visibility”: {“file_size”: true}},

a
File_size field will be visible on selecting the checkbox

h
s
“unchecked”: {“field_visibility”: {file_size”: false}}

fieldset
1 4 h u
file_size field will be hided on unselecting the checkbox

l e
0 b a
This key contains an array of fields used in a form template

7 i s
•

1 t
field_type: Possible values date, time, select, text, textarea, checkbox, radiogroup, separator, file, pass-
field_type:

v
word, readonly, button, img, checkall

n i
a
• field_src:: An end-point URI for the image source. This field is applicable only when field_type is img
field_src
•

h s h
field_name:: Name the field for nicer code
field_name
•

s da
label:: Localized label for each field
label

“label”: {“en”: “Label Item”, “fr”: “...”}

•
•
s a
model_bind:: Model property to bind with. More than one field can bind to same model property
model_bind
options:: Default values for the field. In case of select field_type, the value can be array or a collection
options

166 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

(start with ‘&’) or can point to another file which contains the options (start with ‘#’)
“values”: “#timezone.json”
“values”: “&collection_name”

-
• group: In case of radio button, label and values must be an array of objects assigned to the group key.
group:
The object can also have field_visibility to set the show or hide status of other fields. field_visibility is also

E
an array of object with field-name as key and boolean value to set show or hide (true=show, false=hide).
The object can also have field_editable set to boolean value for disabling or enabling other fields based on

R
the value set. Radio group can also have line_break set to boolean value for breaking the radio buttons to
multiple lines. conditional_visbility is one other option applicable on radio group, which helps in hiding
one or more radio element based on other HTML element’s value.
•

T
checked/unchecked:

O T E
checked/unchecked: In case of checkbox, checked/unchecked property contains field_visibility object to
dynamically show and hide elements (or) field_editable object to dynamically change read-only mode on
elements.
•
•
placeholder

N IBU
placeholder:: In case of input type text, a placeholder can be set. Placeholder must be a Localized string
upload_location:: Files can be uploaded to a specific URL pointed by this property
upload_location
•

•
O
D T 241 2
action: Button fields can have an action to do AJAX calls associated with it. This must be an object con-
action:

R
taining the URL, type, data (array of field values to post), success_msg (Localized string), failure_msg
(Localized string).
conditional_hide:: Hide the element based on its value
conditional_hide
• feature:

I S 1
feature: This field when set to a value, shows this particular element only if Project configuration has the

n
feature. To reverse the effect, include ! before the name.

D 30 8
• runtime_feature

h a
runtime_feature:: This field is similar to feature, but based on runtime configuration.

JSON structure for Form Order template

1 4 u s
fieldset can contain “order” field_type with model_bind and label_bind keys. This field_type is used for sortable

e
element and will save all the model in a collection.

70 b h a l
JSON structure for Form_Collection template

collection
n t i i v s
This template allows a form to hold collection data and choose between the models in collection through an

1
index field. Special properties include

a h
Can have reference, location, url, model, comparator

h s
s da
• model: Reference of the model object in models array
• model_position: Position of model in models array
•

s a
comparator: If collection has to be sorted, then mention the sort field name to automatically sort
whenever a new model is added to collection

167 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

linked_collection
Use this for referencing already generated collection without overwriting them. Can have reference, location
properties
Fieldset must have a field_type collection_field which will be the index for switching between models. This will

E -
be rendered as a select field.
Field set can also have secondary_collection_field field_type to have multiple collections in a form collection.
Each of these field set must have a field_collection property which is of string type, mentioning the collection

R
reference key.
It can also have a list of field names which will be affected when changing the secondary collection select box.

T E
This list should be a json object assigned to “affected_fields_array” property. The json object’s key must be
model_bind’s value of the target fieldset and value must be the field_name’s value of the target fieldset.

O T
To introduce additional filter along with the model_bind property so that there can be a secondary index

N IBU
match against the original collection, a “secondary_index” property can be used. This property accepts a json
object with the key as model property name and value as field name. This will check the model property value
against the field name’s value while filtering the chosen model from select box. E.g.,

O R
D T 241 2
“field_type”: “secondary_collection_field”,

S
“field_name”: “ipv6_index”,

I
D 30 8 1
“label”: {

a n “en”: “IPv6 Index”

4
},
h s
u
“field_collection”: “ipv6_static”,

0 1 h l e
“affected_fields_array”: {“ipv6_address”:”ipv6_address”},

a
1 7 t i b s
“model_bind”: “ipv6_index”,

v
n i
“secondary_index”: {“interface_name”:”interface_name”},

h a s h
“feature”: “IPV6_SUPPORT”,

“short_help”: {“en”: “Choose the IPv6 Index”}

}
s da
a
Template Tips & Tricks

s
Default template used is Twitter bootstrap 3 based. It can be modified by creating a new folder under templates
directory and replicating each and every template file in the default directory.

168 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

%% marker is used in templates which will be replaced by either string which can be localized by Javascript or
with a sub template generated. (eg. %%components can be replaced with the generated component tpl)
<%= %> marker is used for processing any JS variable passed at run-time. The JS value will be coming through
serialized object

E -
<%= strongSuccessMsg %> marker is used to assign one or two words success message like Ok, Good etc..
<%= successMsg %> marker is used to assign the remaining explanation of the success message
<%= strongFailureMsg %> marker is used to assign one or two words failure message like Not Ok, Warning
etc..

T R E
<%= successMsg %> marker is used to assign the remaining explanation of the failure message

T
To Add a Screen in UI:

O
1. Step-1: Adding link under left-side menu bar

N IBU
Goto WebUI HTML5 ->app -> templates-> layouts-> main.html and add a tag in main.html as shown below.
For Exmaple:

O R
D T 241 2
<li>

<a href=”# maintenance “>

I S
D 30 8 1 n
<i class=”fa fa-cog”></i>

<span><%=locale. maintenance %></span>

h a </a>

s
</li>

1 4 h u
2. Step-2: Adding Submenu links in JSON file

l e
If user wants to provide a sub-link in maintenance and settings modules, edit corresponding json files like

70
For Example:

i s a
maintenance.json as follows according to the above explained JSON structure and format.

b
{
1 n t i v
a h
“reference”: “maintenance”,

h s
s da
“tpl_type”: “page”,

“location”: “”,

s a
“hierarchy”: [],

“title”: {

169 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

“en”: “Maintenance”

},

“components”: [{

E -
“reference”: “maintenance”,

“tpl_type”: “cpanel”,

“navs”: [{

T R E
“link”: “#maintenance/system_admin”,

O
N IBU T
“icon”: “ion-ribbon-b”,

“label”: {

“en”: “System Administrator”

O }

R
D T 241
}, { 2
S
“link”: “#maintenance/fwinfo”,

I
D 30 8 1 a
“label”: {
n
“icon”: “ion-information-circled”,

4 h
“en”: “Firmware Information”

s
0 1
}

h u
“en”: “Preserve Configuration”
l e
1 7 t
}

i b s a
n
}, {

a h i v
“link”: “#maintenance/firmware_update”,

h
s da s
“icon”: “fa fa-toggle-up”,

“feature”: “FIRMWARE_FLASH_SUPPORT”,

s a “label”: {

“en”: “Firmware Update”

170 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

}, {

“link”: “#maintenance/bmc_recovery”,

E -
“icon”: “fa fa-toggle-up”,

“feature”: “BMC_RECOVERY”,

T R
“label”: {

E
“en”: “BMC Recovery”

}]
}]
O
}

N IBU T
}

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s Maintenance

h a s h
The Maintenance section contains many sub menu ‘s like system- administration, Bmc- recovery etc
3. Step-3: To create a JSON file for implementing a new screen/page under sub menu

s da
For Example system administration page JSON file has been created under maintenance as below.

s a
“reference”: “system_admin”,

171 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

“tpl_type”: “page”,

“location”: “maintenance”,

“hierarchy”: [

{“label”: {

“en”: “Settings”
E -

],

T R
}, “url”: “#maintenance”}

E

“title”: {

},
O
N IBU T
“en” : “System Administrator”

O R
“components”: [{

D T 241 2
“reference”: “system_admin”,

“heading”: {
I S
“tpl_type”: “form”,

D 30 8 1 n
“en”: “”

h a
s
},

1 4 u
“models”: [

h l e
{

70 i b s a
t
“reference”: “system_admin”,

1 n
“location”: “”,

i v
a h
“url”: “/api/maintenance/system_admin”,

h s
s da
“properties”: {

“username”: “string”,

s a
“enable_user_access”: “number”,

“enable_change_password”: “number”,

172 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

“password”: “string”,

“cpassword”: “string”

},

“save_props”: {

E - “password”: “field_value”,

},

T R E
“cpassword”: “field_value”

},
O
“pre_calc”: {

N IBU T
O R
“validation”: {

D T 241
“password”: { 2
I S
“required”: “conditional”,

D 30 8 1 n
“condition”: “enable_change_password == 1”,

“msg”: {

h a
s
“en”: “Password field must be 8 characters
atleast”

},
1 4 h u l e
70 i b
“minLength”: 8

s a
1
},

n t i v
h a
“cpassword”: {

s h
“required”: “conditional”,

s da
“equalTo”: “password”,

s a
“condition”: “enable_change_password == 1”,

“msg”: {

173 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

“en”: “Password and Confirm Password do

not match”

E -
}

],

T R E

O
N IBU T
“strongSuccessMsg”: {

“en”: “Saved!”

},

O R
D T 241 2
“successMsg”: {

“en”: “That was easy ain’t it?”

},

I S
D 30 8 1 n

h a
“strongFailureMsg”: {

“en”: “Oh Snap!”

},

1 4 u s e

70 b h
“failureMsg”: {

a l
i
“en”: “I’ll try to reason out the error”

},
1 n t i v s

h a s h
“saveable”: true,

“refreshable”: false,

s da “save_label”: {

},
s a
“en”: “Save”

174 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

“fieldset”: [

“field_type”: “readonly”,

E - “field_name”: “username”,

“label”: {“en”: “Username”},

R
“model_bind”: “username”,

T E
“short_help”: {“en”: “Username of System Administrator

},

{
N IBU T
is displayed (read only).”}

O

O R
D T 241 2
“field_type”: “checkbox”,

“field_name”: “enable_user_access”,

“label”: {“en”: “Enable User Access”},

I S 1
“model_bind”: “enable_user_access”,

D 30 8 n

a
“short_help”: {“en”: “Check this option to enable user

h
access for system administrator.”}

},

1 4 u s e
70 b h a l
“field_type”: “checkbox”,

1 n t i i v s“field_name”: “enable_change_password”,

“label”: {“en”: “Change Password”},

h a s h
“model_bind”: “enable_change_password”,

s da “short_help”: {“en”: “check

option. This will enable the password fields.”},
the ‘Change Password’

s a
“checked”: {

“field_editable”: {

175 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

“password”: true,

“cpassword”: true

},

“unchecked”: {
E -
T R
“password”: false,

E
“field_editable”: {

}
O
N IBU T
“cpassword”: false

},

{ O R
D T 241 2
I S
D 30 8 1
“field_type”: “password”,

n
“field_name”: “password”,

a
“label”: {“en”: “Password”},

h s
“model_bind”: “password”,

},

1 4 h u l e
{

70 i b s a
t
“field_type”: “password”,

1 n i v “field_name”: “cpassword”,

h a s h “label”: {“en”: “Confirm Password”},

s da
“model_bind”: “cpassword”,

}]
s a
176 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

}
Note: The scaff_folder JSON file should be followed as above explained JSON structure and format.

E -
T R E
O
N IBU T
O R
D T 241 2
Server-Side Processing of REST API
Example screen

Overview

I S
D 30 8 1 n
This document provides how the REST API is being called from the client side and how the response are being

a
delivered from the server side for MegaRAC SPX stack. spx_restservice package will contain the REST API
calls.

Client Side – BackboneJS

4 h s
0 1 h u
Backbone.js gives structure to web applications by providing models with key-value binding and

l e
custom events, collections with a rich API of enumerable functions, views with declarative event handling, and
connects it all to your existing API over a RESTful JSON interface.

Ajax

1 7 t i b s a
n i v
The Client server communication will be done through AJAX . Backbone.js invokes the REST API
through AJAX Calls. The JQuery $.ajax function is wrapped in a Backbone.js class called Sync.

a h
Backbone.js methods like model.create and model.destroy call this sync method which in turn make an ajax
call.

h
s da s
Each REST API will be mapped to a Backbone.Model class.

a
Backbone Model :

s
Backbone.Model provides CRUD (Create, Retrieve, Update, Delete ) operation in the server side using the
following methods.

177 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• save() will create or update it

• fetch() will read it
• destroy() will delete it.

-
These methods will call Backbone.sync which encapsulates the details about how to communicate with the
server.

API Integration

R E
Backbone is pre-configured to sync with a RESTful API. Simply create a new Collection with the url of your
resource endpoint:

T T E
var Settings = Backbone.Collection.extend({

O
url: ‘/settings’

});
N IBU
The collection and model components together form a direct mapping of REST resources using the following
methods:

O R
D T 241 2
GET / settings/ ... collection.fetch();

S
POST / settings/.... collection.create();

I
D 30 8 1 a n
GET / settings /1 ... model.fetch();

PUT / settings /1 ... model.save();

FETCH ( )

4 h
DEL / settings /1 ... model.destroy();

s
1 u e
This function will create a request to the server and fetch the response data

0 h l
Example:

1 7 t i b s a
var DNS = Backbone.Model.extend({

n i v
urlRoot: ‘/api/configuration’

a h
h s
});

s da
This urlRoot will set as a base url. Then if you were to instantiate this and call fetch():
var context = new DNS ({id: ‘abcd1234’});

s a
context.fetch();
GET http://ip/api/configuration/abcd1234
SAVE ( )

178 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

This function is used to save the given data in the server .

Model.save({datas},{options});
Example:

context.model.save(

E -
}, {

T R
‘email_id’: $(‘#idemail_id’).val(),

E

O
N IBU T
Success : function() {

console.log(“Save Success”);

},

O R
D T 241 2
error: function() {

console.log(“Error inn Saving”);

S
}

});

I
D 30 8 1 a n
PUT http://ip/api/configuration/abcd1234
DELETE ( )

hs
When you call Model.destroy(), Backbone.js by default sends a DELETE request to your server. If you don’t

4 u
specify a url in your model, it will notify an error message.
Example :

0 1 h a l e
7 i b s
var settings = Backbone.Model.extend( { ... } );

1 t
settings.destroy( {

v
a n h i
contentType : ‘application/json’,

h s
success : function () {

s da console.log(‘success’);

},

s a
error : function () {

179 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

console.log(‘error’);

} );
JQuery Ajax :

E -
Apart From the default BackboneJs methods (Save , Fetch , Delete), we have also used Jquery AJAX method to
communicate with the Server .
Example :

$.ajax({

T R E
O
N IBU T
url: “api /delete”,

type: ‘DELETE’,

dataType: ‘json’,

O R
D T 241 2
data: object,

processData: false,

I S
D 30 8 1
contentType: ‘application/json’,

n
success: function(data, status, xhr) {

h a alert(‘Deleted Successfully’);

s
},

1 4 h u e
error: function(xhr, status, err) {

l
70 i b }

s a
alert(‘Error while deleting. Try again later’);

1 n t });

i v
h a s h
Server Side Actions Based On the Client Call
The following functions will be called in REST API when respective URLs are invoked from client side.

s da
For Updating Collection (GET Method):

s a
START_AUTHORIZED_COLLECTION (getActDirUsers,
directory-users”, 4, matches, true)

{
GET, “/settings/active-

180 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

//code to update collection of models

// Request to ipmi server

// Error Handlers

// Return
E -
THROW_ COLLECTION _ERROR(STATUS_500, “Error adding new AD user”)

reponse to the client

T R
}END_AUTHORIZED_COLLECTION

E
For Updating Collection (POST Method):

O
N IBU T
START_AUTHORIZED_COLLECTION (getActDirUsers,
directory-users”, 4, matches, true)

{
POST, “/settings/active-

\
O
//code to update collection of models

R
D T 241
// Error Handlers
2
I S 1
THROW_ COLLECTION _ERROR(STATUS_500, “Error adding new AD user”)

D 30 8 n
a
// Return reponse to the client

h
}END_AUTHORIZED_COLLECTION

s
For Updating Model (POST Method):

4
0 1
START_AUTHORIZED_MODEL

h u l e
(addActDirUsers,
directory-users”, 4, matches, true)
POST, “/settings/active-

1 7 t i b s a
n i v
// Request to ipmi server

a h
// Error Handlers

h
s da s
THROW_MODEL_ERROR(STATUS_500, “Error adding new AD user”)

// Return reponse to the client

s a
}END_AUTHORIZED_MODEL
For Updating Model (PUT Method):

181 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

START_AUTHORIZED_MODEL (modifyActDirUsers, PUT, “/settings/active-

directory-users/([[:digit:]]+)”, 2, matches, true)

// Error Handlers

E -
// Request to ipmi server

// Return
R
THROW_MODEL_ERROR(STATUS_500, “Error adding new AD user”)

T E
reponse to the client

T
}END_AUTHORIZED_MODEL

O
For Updating Model (DELETE Method):

N IBU
START_AUTHORIZED_MODEL (deleteActDirUsers, DELETE,
directory-users/([[:digit:]]+)”, 2, matches, true)
“/settings/active-

{
O R
D T 241 2
// Request to ipmi server

I S
// Error Handlers

D 30 8 1 n
THROW_MODEL_ERROR(STATUS_500, “Error adding new AD user”)

// Return

h a
reponse to the client

s
}END_AUTHORIZED_MODEL

1 4
spx_restservice_ext.src

h u l e
0
This is binary package and extension package for spx_restservice package. This package structure is same as

1 t i b s a
REST service package. This package contains customer defined API calls only.

7
User can create their own API calls (RESTFull calls) in this package as explained below.
For Example

a n h
http:/ip/ext/sample/get
i v
h
s da s
RESTFull API call should contain the /ext/ in the every call. Client processing and Server processing are same
as REST service package.
Error codes can be added in the spx_resrt_ext.h file where user can add new error codes in “REST_EXT_

a
ERROR_CODES” area.

s
This package lightpd_ext.conf file will be included dynamically as part of REST service lightpd.conf file.

182 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

SP-X Web UI Customization for implementing

Content Security Policy
The below procedure will explain how to implement the Content Security Policy in WEB REST layer to prevent

E -
cross-site scripting (XSS), click jacking and other code injection attacks resulting from execution of malicious
content in the trusted web page context.

Overview

T
Configuring with lighttpdR
This section provides how to configure Content Security Policy.

E
For example: O
N IBU T
1. We have implemented via adding a CSP header in Every Response Header hence added in lighttpd.conf
configuration file as mentioned below.

setenv.add-response-header += ( “Content-Security-Policy” => “default-src

O
‘self’;object-src ‘none’;connect-src *;style-src ‘self’;script-src ‘self’; img-

R 2
src ‘self’ blob:;frame-ancestors ‘self’;font-src ‘self’”)

D T 241
CSP header and directives

S
The HTTP Content-Security-Policy (CSP) default-src directive serves as a fall back for the other CSP fetch

• I
directives. For each of the following directives that are absent, the user agent will look for the default-src

D 30 8 1
connect-src

a n
directive and will use this value for it:

•
•
font-src

4
img-src
h
s
•
•

0 1
object-src

h
script-src u l e
1 7
•

i b
style-src

t s a
Self:

a n i v
Refers to the origin from which the protected document is being served, including the same URL scheme and

h
port number. You must include the single quotes. Some browsers specifically exclude blob and file system from

h
s da
object-src
s
source directives. Sites needing to allow these content types can specify them using the Data attribute.

The HTTP Content-Security-Policy object-src directive specifies valid sources for the <object>, <embed>, and

none

s a
<applet> elements.

Refers to the empty set; that is, no URLs match. The single quotes are required.

183 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

style-src
The HTTP Content-Security-Policy (CSP) style-src directive specifies valid sources for sources for style sheets.
script-src

-
The HTTP Content-Security-Policy (CSP) script-src directive specifies valid sources for JavaScript. This
includes not only URLs loaded directly into <script> elements, but also things like inline script event handlers

E
(onclick) and XSLT style sheets which can trigger script execution.

R
img-src
The HTTP Content-Security-Policy: img-src directive specifies valid sources of images and favicons.

O T T E
A schema such as ‘http:’ or ‘https:’. The colon is required, single quotes shouldn’t be used.
mediastream: Allows mediastream: URIs to be used as a content source.

N IBU
• blob: Allows blob: URIs to be used as a content source.
• filesystem: Allows filesystem: URIs to be used as a content source.
connect-src

•
O R
D T 241 2
The HTTP Content-Security-Policy (CSP) connect-src directive restricts the URLs which can be loaded using
script interfaces. The APIs that are restricted are:
<a> ping,
•
•
S
Fetch,

I 1
XMLHttpRequest,

D 30 8 n
•
•
WebSocket, and
EventSource.

h a
1 4 u s
How to adopt the CSP implementation in our stack

e
Following are limitations if we are using CSP
•

70 h a l
- Eval and related functions are disabled

b
1
•
•
i v s
- Inline JavaScript and CSS (Styles) will not be executed

t
- Only local script and and object resources are loaded

n i
a
CSP attacks inject in Templates (HTML file) only so before CSP implementation we used underscore _.template

h s h
function to generate HTML templates at runtime. Due to CSP limitations in built _.template function, we
have replaced existing template generation plugin with undertemplate plugin and customized code as per our

s da
requirement. Refer the following link for more details.
https://github.com/silvermine/undertemplate

a
Following are example code snippets of before, after CSP code changes handled in our stack.

s
184 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

How to handle Inline JavaScript:

Before CSP:
<td>
<div class=’user_name’><%= model.get(‘user_name’) %></div>
</td>
After CSP:

E -
R
Fetch the data in view file append in template (using id or class) means all html templates should not contain
any runtime evaluation to render data and those things should be moved to corresponding view, template file
accordingly as explained below.
View file:-

O T T E
this.$(‘.user_name’).html(this.model.get(‘user_name’));

N IBU
Template file:-
<td>

O
<div class=’user_name’></div>
</td>

R
D T 241
How to handle Inline CSS:
2
All template files should not contain any inline styles if there then those should be moved to external CSS file

Before CSP:

I S
as explained below.

D 30 8 1 n
h a
<div id=”id_map_inner” style=”background-image: url(./images/world.png);”>
<div id=”map_x”></div>

s
<div id=”map_y”></div>
</div>
After CSP:-

1 4 h u l e
70 i b s a
Adding styles in separate file using selector to change the style.

t
#id_map_inner{

1 n i v
background-image: url(./images/world.png);
}

h a s h
<div id=”id_map_inner”>

s da
<div id=”map_x”></div>
<div id=”map_y”></div>
</div>
-

s a
These CSP implementations has been handled in webui_scaffold package as explained above and
changes has been done in fn.php file accordingly.

185 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

How to Validate the CSP Implementation

We can verify/observe the CSP attributes in response headers of every request in browser development tool
under Network tab. Refer sample screen shot for the same.

E -
T R E
O
N IBU T
O R
D T 241 2 CSP Implementation

S
Validate using chrome browser extension tool

extension.
I
D 30 8 1
Please use below CSP validator chrome plugin for validating CSP issues and use below link to integrate

a n
https://chrome.google.com/webstore/detail/csp-evaluator/fjohamlofnakbnbfjkohkbdigoodcejf

4 h s
0 1 h u l e
1 7 t i b s a
a n h i v
h
s da s
s a CSP Evaluator

186 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

SP-X Web Customization HTML5 Using i18next

Plugin
The below procedures will explain how to migrate i18n plugin to i18next plugin for supporting multiple

•
-
language support (more than two excluding English).

E
webui_html5-src (except Language string changes follow the steps/procedure which are already explained
in Web Customization ““webui_html5-src”
““webui_html5-src” section)

Overview

T R
i18n plugin migration to i18next

E
O
N IBU
Registering namespace T
This section provides how to use i18next plugin and the migration example from i18n to i18next.

If you wanted to use string files in modules, it must be registered in config.main.js.

For example:

O R
D T 241
requirejs.config({
2
S
i18next: {

I
D 30 8 1
lng: ‘en’,

a n
lowerCaseLng : true,

4 h
fallbackLng: ‘en’,

s
u
supportedLngs: {

0 1 h l e
“en”: [“model_errors”, “videolog”],

a
});
1
}

7 t i b v s
n i
Now, we can use model_errors.json and videolog.json in modules.

a h
h s
Note:

s da
The videolog is the String file name (EN/CN/TW or etc.) of the video module. If any new language
strings are added in the webui_html5-src page, those string file name should be mentioned here.

a
If any new language strings are added in the “Webui_Scaffolder” page, the reference name of the
JSON file should be mentioned here.

s
187 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Loading locale with additional namespaces

With i18next you can load multiple namespaces and refer to them when calling translate with a key.
For example:

define([“some/module”,
i18n) {

E - “i18n!:namespace1,namespace2”], function(module,

R
// The additional namespaces “namespace1” and “namespace2” are now
loaded

O T T E
// So right now we can for example call i18n.t(“namespace1:some_key”)

// to get the translation for “some_key” in namespace “namespace1”

}); N IBU
// (See the i18next docs for more details)

O R
D T 241 2
Call i18n.t(“namespace1:some_key”) to get the translation for “some_key” in namespace “namespace1”

Path and format of string files

With i18next, its default path to find string files is ./locales/lng/namespace.json. and all string files need to be

{
I
valid json type.

S
D 30 8 1 n
“fru” : “FRU”,

h a
}

1 u s
“field_replaceunit” : “Field Replacable Units”

4 e
0 h l
Note: lng is configured in config.main.js

7 b a
1
For example:

n i i v s
Using string file in template

t
<!--

h a s h
Content Header (Page header) -->

s da
<section class=”content-header”>

<h1>

s a
<%=locale.t(“settings:settings”)%>

188 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

<small><%=locale.t(“settings:config_bmcoption”)%></small>

</h1>

<ol class=”breadcrumb”>

a>

E -
<li><a href=”#”><i class=”fa fa-home”></i> <%=locale.t(“settings:home”)%></

</li>

T R E
<li class=”active”>

T
<%=locale.t(“settings:settings”)%>

</ol>
O
N IBU
</li>

</section>

O R
D T 241 2
<%=locale.t(“settings:settings”)%>
It will load ./locales/lng/settings.json and find “settings” translate.

I S
Note: First “settings” is according to view ‘i18n!:settings’, which loaded string file and render this template.

1
Migration from i18n to i18next

D 30 8 n
For example:
In templates:

h a
4
#<%=locale.date_time%>

1 u s e
0
//change to

7 b h a l
1
In moudles:

n i i v s
#<%=locale.t(“settings:date_time”)%>

t
h
//change toa s h
‘i18n!strings/nls/dual_image_config’,

s da
‘i18n!:dual_image_config’,

a
In string files:
stats.js

s
189 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

define({

“new_scripts”: “Available Scripts”,

“more_info” : “More info “,

E
“up_time” : “ Up Time”, -
“power_cycle” : “Power Cycle “,

T R
“pending_activities” : “Pending Activities”,

E
“pending_assertions” : “Pending Deassertions”,

});
change to
O
N IBU T
“new_audit_issue” : “Access Logs”

O
stats.json

R
D T 241 2
“new_scripts”: “Available Scripts”,

I S
“more_info” : “More info “,

D 30 8 1 n
“power_cycle” : “Power Cycle “,

h
“up_time” : “ Up Time”,
a
1 4 u s
“pending_activities” : “Pending Activities”,

e
70 b h a l
“pending_assertions” : “Pending Deassertions”,

“new_audit_issue” : “Access Logs”

1 n t i i v s
Note: Finally, remember to register namespace in config.main.js.

h a s h
s da
s a
190 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Enabling favicon Customization in SPX Web UI

HTML5
Following steps need to be followed for enabling or displaying the favicon (.ico) in HTML5 Web UI. Since

-
favicon icons are varied for different customers hence customization steps have been provided for adapting
these code changes as per customer requirements.

R E
Make sure that favicon (.ico) should be present in webui_html5-src/data/ package as per the requirement.

Step1: Perform following changes in webui_html5-src/data/index.html file.

T E
<link rel=”shortcut icon” href=”/favicon.ico” type=”image/x-icon”/>

O T
N IBU
O R
D T 241 2
I S
D 30 8 1 n
h a Favicon code

1 4 u s
Step2: Add below code changes in webui_html5-src/spx/RULES.py file.

e
Py_CopyFile(build_dir+’/dist/favicon.ico’, tmp_dir)

70 b h a l
1 n t i i v s
h a s h
Favicon code
Step3: Add below code changes in webui_html5-src/data/GruntFile.js under Copy Grunt task in both release

s da
and debug area.
copy: {

a
release: {

s
files: [

191 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC
,{
expand: true,
src: “favicon.ico”,
flatten: true,

-
filter: ‘isFile’,
dest: “dist/”
}
debug: {
files: [

R E
,{

O
expand: true,T T E
N IBU
src: “favicon.ico”,
flatten: true,
filter: ‘isFile’,

}
O
dest: “dist/”

R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
192 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
Favicon code

7
1. Add mime type

b h a l
Step4: Add below changes in spx_restservice-src/data/ lighttpd.conf file

0
1
“.ico”

n t i s
=> “image/x-icon”

i v
2. Add as part of response header as like below.

a h
$HTTP[“url”] =~ “^/api|^/archive|\.png|\.ico$”

h s
s da
s a
193 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a Favicon code

1 4 u s e
Once code changes are done, newly created image should display favicon in all latest Chrome and Firefox

Note:

7 b h
browsers as per functionality.

0 a l
1 n t i i v s
In IE11, Edge browsers favicon displaying may not work as expected. For IE11, we need to add BMC IP in
Trusted source (Internet Settings->Security->Trusted Sites) due to limitation in IE browsers with self-signed
certificate. If we have valid verified certificate, then may not have any issues to view favicon in IE11/Edge.

h a s h
s da
A sample screenshot is displayed below with customized favicon icon in latest Chrome browser.

s a
194 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E - Favicon in Chrome Browser

A sample screenshot is displayed below with customized favicon icon in latest Firefox browser.

T R E
O
N IBU T Favicon in Firefox Browser

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
195 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Customization of Upload File Handler API in SP-X

REST Service
This section guides the user to change file upload size if its crossing more than predefined file size. Each

E -
authorized file upload handler API call will have file size parameter to declare default upload file size.
There are some cases for specific customers where uploaded file size greater than default size which may lead
to issue of invalid content length error. So in this case, user can modify the already defined size with required

T R
file size as per the requirement.
For ex: The below handler having default size as 512KB which is MAXSIZEBYTES value.

E
1.START_HANDLER_AUTHORIZED_UPLOAD (uploadRestoreConfig, POST, “/maintenance/upload_

below.
Ex:
O
N IBU T
restore”, 4, matches, true, TEMP_LOCATION, 512 * 1024 , 0)
User can increase file upload size as per the requirement for above corresponding file upload handler like

O
1.START_HANDLER_AUTHORIZED_UPLOAD (uploadRestoreConfig, POST, “/maintenance/upload_

to

D T 241 2
restore”, 4, matches, true, TEMP_LOCATION, 512 * 1024 , 0)

R
1.START_HANDLER_AUTHORIZED_UPLOAD (uploadRestoreConfig, POST, “/maintenance/upload_

S
restore”, 4, matches, true, TEMP_LOCATION, 600 * 1024 , 0)

I 1
Note: User can modify file upload size for all file upload handler API’s wherever applicable based on the
customer requirement.

D 30 8 a n
4 h s
0 1 h u l e
1 7 t i b s a
a n h i v
h
s da s
s a
196 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 11

Signing JAR Files

E -
T R
The Signing JAR Files allows you to create a keystore, generate a Code Signing certificate, sign the JAR files and

E
verify the JAR files to sign JAR files in SPX stack.

T
Note:

O
Java Development Kit (JDK) version 1.8.0_172 or higher needs to be used to prevent signing JAR files

N IBU
with weaker algorithm.
If the JAR files were signed using a weaker algorithm, then the JRE (Java Runtime Environment) signature

O
verification operations will ignore the signature and treat the JAR files as unsigned. So JRE will block JAR files

2
execution even if the JAR files are properly signed.

R
D T 241
In the generic release, AMI provides signed JAR files that is signed by an AMI signed keystore. AMI does not
provide the signed keystore. In order to sign the JAR files, which is required if REBUILD_JAVA_APPS feature
is selected, follow the steps below.

I S
Creating JAR Signing Key Store

D 30 8 1 n
a
The following command helps the user to create a keystore, and generate a pair of public and private keys, with
the public key in a certificate.

4 h
keytool -genkey -alias keyAlias -keyalg keyAlgorithm -keysize keySize

s
-keystore JViewerKey -validity days

1 u e
Example: keytool -genkey -alias keyAlias -keyalg RSA -keysize 2048 -keystore JViewerKey -validity 90

0 h l
a
The command details are given as follows
•
•
1 7 t i b v s
genkey - It is the command used to generate the keys
alias - It is used to specify the alias name that is to be used in future to refer to the keystore entry that

•
a n h i
contains the keys that will be generated.
keyalg - It specifies the algorithm to be used to generate the key pair. (E.g. RSA)
•
• h
s da s
keysize - It specifies the size of each key to be generated. (E.g. 2048)
keystore - It is used to specify the name of the keystore that is being created.
•

s a
validity – It tells the number of days for which the certificate should be considered valid. (E.g. 90)

197 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Procedure
1. Enter a Keystore password, once the command is executed.
2. Enter the organization details.
3. Enter a key password.

E -
Note: The password will be used for the private key.

Creating Certificate Signing Request

T R
The following command can be used to create a Certification request.

E
keytool -certreq -v -alias keyAlias -file mycsr.pem -keystore JViewerKey

Procedure
•
O
N IBU T
Enter the keystore password. Once the password is entered, the certificate request will be created and
stored in file mycsr.pem in the current directory. This file should be submitted to the certificate author-
ity, to purchase a code signing certificate.

O R
Creating Certificate File

D T 241 2
Once the code signing certificate is issued, You will receive emails with links to download the code signing
certificate.

Procedure

I S
D 30 8 1 n
1. Select the certificate given in pkcs7 format.

a
2. Save the contents in a file with .cer format, for example myCert.cer.

h s
Note:

1 4 h u
Copy the contents from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----

l e
Ensure that no extra spaces or new lines are added in the content.

70 i b a
Importing Certificate to Key Store

s
1 t v
The Code signing certificate should be installed in the keystore which is created. The following command can

n i
be used for this purpose.

h a s h
keytool -import -trustcacerts -keystore JViewerKey -storepass keypass
-alias keyAlias -file myCert.cer

s da
Here you assume that the keystore name is JViewerKey, keystore password is keypass, alias name is keyAlias,
and the certificate file name is myCert.cer (from previous examples).

s a
After Importing the Certificate to Key Store, the Keystore JViewerKey can be used for signing JAR files.
Signing JAR Files in SPX Stack

198 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

The sign.sh script in JViewer_signkey package has been modified to sign the JAR files with valid key if it is
available. Otherwise a self signed key, provided inside the JViewer_signkey package will be used to sign the
JAR files. The two methods are explained as follows.

Signing with a Valid Key

E -
If a valid JAR signing key is available, the keystore file should be placed inside a directory JavaSigning. The
JavaSigning directory will be available in the same path as the BuildPRJ directory in which the build workspace
is created. In the case of MDS, it needs to be created under MDS/spx/utils/. Along with the keystore file, there is

R
another file will also be available in the JavaSigning directory, with the name KeyCredentials. This file should
contain the keystore password and the keystore alias name in the following format. The details used below are
based on the previous examples used in the document.

O T
storepass:keyspass

T
aliasname:keyAlias E
N IBU
Note: No spaces should be given before or after the separator character (:)
While building JViewer related packages, the sign script will be invoked after creating the JAR files. The

O
sign script will check whether the valid keystore file and the KeyCredentials file are available in the Java

2
Signing directory. If the files are available, the sign script will use a valid key to sign the JAR files.

R
D T 241
Signing with Self Signed Key
If a valid JAR signing key is not found, the sign script will use a self signed key to sign the JAR files. The self

I S
signed key is created by AMI and placed inside the data section of the JViewer_signkey package.

D 30 8 1 n
Verifying Keystore (JAR Sign Key)

a
To inspect the keystore (JAR Sign Key) which is used to sign the JAR files, you can use the following command.

h
1 u s
keytool -list -v -keystore <full path to JAR Sign Key >

4
The output will display the information about the keystore (JAR Sign Key) such as sign key algorithm etc.

e
0 h
Verifying Signed JAR Files

7 b a l
1 n t i
To verify whether the JAR files are signed properly, you can use the following command

i v s
jarsigner –verify –verbose –certs <Path to JAR File>

a h
The output will display the information about the keystore used to sign the JAR files.

h
s da s
Re-signing JAR Files
Following steps explains how to re-sign a JAR file manually (assuming the JAR file has been signed already).
The procedure is intended for debugging purpose only.

s a
1. Remove following files from each JAR file.
• META-INF/*.SF

199 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• META-INF/*.RSA
• META-INF/*.DSA
• META-INF/SIG-*

-
2. Re-sign the JAR using latest / desired JDK version by issuing following command

E
jarsigner -keystore <full path to JAR Sign Key> -storepass <keystore
password> <full path to JAR file> <alias name>

References
R
O T T E
http://docs.oracle.com/javase/tutorial/security/toolsign/step3.html
http://support.godaddy.com/help/article/4780/signing-java-code

N IBU
https://docs.oracle.com/javase/8/docs/technotes/tools/unix/jarsigner.html
https://www.java.com/en/jre-jdk-cryptoroadmap.html

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
200 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER12

JDK Upgrade Guide

E -
T R
Upgrading Java Development Kit (JDK) in SPX stack involves following activities.

E
1. REBUILD_JAVA_APPS feature needs to be selection in PRJ configuration.

O T
2. JDK-ANY package contains the Java binary (Usually a tar.gz archive file). Replace the binary inside JDK-
ANY package with desired JDK binary (archive).

N IBU
3. Update the JDK-ANY package properties accordingly (Example: LICENSE, Source Location, Source
Version etc.)

O
4. Modify the dev-install script accordingly so that the contents of the JDK binary will be extracted in the

D T 241
%TOOLDIR/JDK/*
2
following directory format.

R
5. Update the JAVA_PATH environment variable inside dev-install script with following value

I S
%TOOLDIR/JDK/bin

D 30 8 1 n
6. Remove the JDK binary (archive) file after the contents are extracted successfully.

h a
7. Compile and update Vmedia libraries (Vmedia_*.spx) using same JDK version for supported platforms
(Windows, Linux, and Mac)

build-install:

1 u s
8. Following is a sample dev-install script used for JDK version 1.8.0_172

4 e
DELETE %TOOLDIR/JDK

0 b h a l
COPY_FILE zulu8.30.0.1-jdk8.0.172-linux_x64.tar.gz %TOOLDIR/

7
n i i
SETPATH %$TOOLDIR/JDK/bin
v s
UNTAR_GZ %TOOLDIR/zulu8.30.0.1-jdk8.0.172-linux_x64.tar.gz %TOOLDIR/

1 t
RENAME %TOOLDIR/zulu8.30.0.1-jdk8.0.172-linux_x64 %TOOLDIR/JDK/

h a s h
SET_VALUE JAVA_PATH %TOOLDIR/JDK/bin
DELETE %TOOLDIR/zulu8.30.0.1-jdk8.0.172-linux_x64.tar.gz

s da
Things to be considered while upgrading JDK version

s a
API Deprecation
1. Some Java classes and methods used in the earlier JDK may have been deprecated in the later JDK versions.
Inspect for possible code references to deprecated methods/classes.

201 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

2. Either of the following approaches can be used to resolve API deprecation issues (if any)

a. Use the new alternatives offered as part of the Java API.

b. Use a generic code in a way that same functionality is achieved regardless of Java version used (most

-
preferred way).

Procedure To Upgrade JDK

R E
Follow the below steps for upgrading JDK in SPX stack.
1. Download latest Java 8 64-bit binary (.TAR format)

O T T E
N IBU
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
2. Import JDK-ANY SP-X package into MDS.
Downloading JDK Binary Files

70 b h a l
1 n t i i v s
h a s h
s da
s a
202 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
Importing SP-X Package - Step 1

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h Importing SP-X Package - Step 2

s da
s a
203 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
Importing SP-X Package - Step 3

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h Importing SP-X Package - Step 4
3. Replace the current JDK binary with the newly downloaded JDK binary.

s da
s a
204 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
Old JDK Binary

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h New JDK Binary
4. Modify the dev-install to the use new downloaded version of JDK.

s da
s a
205 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
Build Details

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h JDK Dev Install

s da
Note: In older code bases, package build scripts referring to JDK path value will have specific JDK version
like %TOOLDIR/JDK/jdk1.5.0_01/bin. So it is recommended to modify the JDK path in package build
scripts to generic name such as %TOOLDIR/JDK/bin. This will prevent modifying package build script files

s a
when upgrading JDK in the future.
Example: Updating sign.sh script in JViewer_signkey-ANY package
Before

206 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

${TOOLDIR}/JDK/jdk1.5.0_01/bin/jarsigner -keystore $keystore -storepass $storepass $JARFULLPATH

$aliasname
After
${TOOLDIR}/JDK/bin/jarsigner -keystore $keystore -storepass $storepass $JARFULLPATH $aliasname

-
5. Update the JDK-ANY package properties (LICENSE, Source Location, Source Version, etc) accordingly.

E
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n JDKPackage Properties

h a
Note: OPENJDK license is available in MDS release 12.0.2 onwards. For older versions of MDS need to add
the new license manually.

1 4
License Name : OPENJDK

u s e
70 b h a l
URL : https://openjdk.java.net/legal/gplv2+ce.html

1 n t i i v s
h a s h
s da
s a
207 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E Adding OpenJDK License in MDS - Step 1

O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a Adding OpenJDK License in MDS - Step 2

1 4 u s e
70 b h a l
6. Create the JDK-ANY SP-X package.

1 n t i i v s
h a s h
s da
s a
208 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 Creating JDK-ANY SP-X Package
7. Compile VMedia libraries using the same JDK version for supported platforms (Windows, Linux and Mac).
Update Vmedia_*.spx package with newly compiled binaries. Refer chapter Software Configuration for

S
further information.

I
D 30 8 1
8. Open the PRJ Configurator and select “REBUILD_JAVA_APPS”, save the PRJ file and BUILD.

n
Note: To rebuild and sign the JAR files with this feature, a ‘JViewerKey’ keystore, with a trusted code signed

a
certificate needs to be created. AMI does not provide the signed JViewerKey keystore. Once the JViewerKey

directory.

4 h
keystore has been created, then the keystore and a file KeyCredentials need to be placed into the JavaSigning

s
0 1 h u l e
1 7 t i b s a
a n h i v
h
s da s
s a
209 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

JViewer Binary Package Maintenance

SPX 13 stack follows Single JViewer JAR design for the ease of maintenance and deployment. Kindly refer
“MegaRAC® SP-X Firmware JViewer Single JAR Support” document for detailed information on the design
changes.

E -
JViewer_StandAloneApplication-{SOC}-src package will be the only package contains JViewer binary. This
same binary will be used for both StandAlone / (JNLP) Web deployments.

T R
If any of the following source package is updated, then the binary in JViewer_StandAloneApplication-{SOC}-
src package should be updated.

E
For example, if JViewer_AVIStream-src is changed, then the JViewer.jar binary inside JViewer_

O T
StandAloneApplication-{SOC}-src package should be updated.

N IBU
Refer Steps to build JViewer Binary packages topic below.

O R
D T 241 2
Source Package
JViewer_common-src
JViewer_AVIStream-src
JViewer_OEM-src

S
JViewer-ARM-SOC-src

I
JViewer_FolderRedir-src

D 30 8 1 a n Table - JViewer Packages

4 h s Source / Binary Package

u
JViewer_StandAloneApplication-ARM-{SOC}-src

0 1 h l e
Table-JViewer StandAlone Application Packages

a
1 7 t i b v s Source Package

a n h i Vmedia_Linux_64-src
Vmedia_Mac_64-src

h s
Vmedia_Win64-src

s da Table - VMedia Library Packages

If there is change in JDK-ANY, then all the above package (Refer table JViewer packages, JViewer

s a
StandAloneApplication packages and VMedia library packages) should be updated.

Steps to build JViewer Binary Packages

210 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

1. Check if Rebuild Java App option is enabled in PRJ configuration. If Rebuild Java Apps option is not
enabled, JViewer binary packages will not be updated during build time.
2. Enable folder redirection support in PRJ. This will include the Folder redirection changes into JViewer

-
standalone Application binary.
3. Do the necessary changes in the JViewer source packages.
•

•
R E
Increment the currentVersion variable in JViewerApp.java (i.e., JViewer_common-src package
version) and build the workspace.
If JViewer-ARM-{SOC}-src package is modified then update the currentVersion variable in

O T T E
SOCManager.java file and build the workspace.
4. Copy the required binary from <workspace>/Build/binary/ to commit.

Note:

N IBU
O
Whenever there is a change in JViewer_common-src / JViewer-ARM-{SOC}-src, the currentVersion variable

2
should be updated to reflect the next package version. And build the workspace again.

R
D T 241
JViewer_common-src, JViewer StandAloneApplication packages (src and binary for available SOC) should
have same version.

I S
D 30 8 1 n
Launching JViewer From Eclipse

h a
1. Enable “Rebuild Java Apps” feature in PRJ before building the workspace.

1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a PRJ Config - Rebuild Java Apps
If “Rebuild Java Apps” feature is enabled in PRJ, JViewer source files will be available in source folder. User can

211 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

modify JViewer source code and build the workspace. The source code changes will be reflected in the binary.
2. Download and install eclipse from https://www.eclipse.org/. Choose “Eclipse IDE for Java Developers”
edition.
3. Launch Eclipse.

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n Launch Eclipse

h a
4. Create a new “Java Project”. Click File -> New -> Java Project.
5. Enter a project name and click Finish.

1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
212 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 t i v s Create Java Project
6. Copy ws\source\JViewer_AVIStream-13.2.0.0.0-src\data\src\com folder

n i
h a s h
s da
s a
213 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 Copy Source
7. In Eclipse, click on Java Project, right click src folder and then select Paste.

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a Java Project

214 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

8. Similarly copy ws\source\JViewer_common-13.29.0.0.0-src\data\src\com,

ws\source\JViewer_FolderRedir-13.5.0.0.0-src\data\src\com,
ws\source\JViewer_OEM-13.4.0.0.0-src\data\src\com,

E -
ws\source\JViewer-13.6.0.0.0-ARM-AST-src\data\src\com to eclipse java project src folder.
Incase of Pilot SOC, the JViewer-13.6.0.0.0-ARM-AST-src will be “JViewer-<VERSION>-ARM-PILOT-src”.
When asked with question to overwrite, click overwrite all.

T R E
O
N IBU T
O R
D T 241 2 Overwrite

I S
9. (This step is Windows Client Specific. If you are using linux client then skip step 9 , 10 and follow step 11

D 30 8 1 n
and continue) In eclipse, right click src folder, New -> package. Input package name as “com.ami.kvm.

a
jviewer.lib.win64” and click finish.

4 h s
0 1 h u l e
1 7 t i b s a
a n h i v
h
s da s
s a
215 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a Java Package
10. (Windows client specific) Copy “javacdromwrapper.dll”, “javaclientconfwrapper.dll” and

1 4 u s
“javaharddiskwrapper.dll” from ws\source\Vmedia_Win64-13.2.0.0.0-src\data to “com.ami.kvm.jviewer.
lib.win64” src folder of eclipse Java project.

e
70 b h a l
1 n t i i v s
h a s h
s da
a
Windows Client Specific

s
11. (This step is Linux Client Specific. If you are using Windows client and followed step 9 and 10 then skip step
11, 12 and continue). Copy “libjavacdromwrapper.so”, “libjavaclientconfwrapper.so” and

216 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

“libjavaharddiskwrapper.so” from “ws\source\Vmedia_Linux_64-13.1.0.0.0-src\data” to src folder of eclipse

Java project.
12. (Linux client specific ) Do the following code changes in CDROMRedir.java, ClientConfig.java and
HarddiskRedir.java as show below and save the files.

E -
T R E
O
N IBU T
O R
D T 241 2
Client Config 1

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s Client Config 2

h a s h
s da
s a
217 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T Client Config 3
13. In eclipse, click on Run -> Run configurations

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h Run Config

s da
14. In Run Configurations, click on Java application and select New configuration

s a
218 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 New Configuration

I S
15. In New Configuration, select search to choose Main class and select “com.ami.kvm.jviewer.JViewer”

D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a Select Main Type
16. Rename Configuration name to Project name for convenience. And finally select Run.
17. JViewer Standalone dialog will be shown. Input the required details.

219 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
Host IP Address : BMC IP ADDRESS
Secure Web Port : WEB PORT ADDRESS (usually 443)
Launch

I S
Username: IPMI username

D 30 8 1
Password: IPMI password

n
And then click on Launch.

h a
s
18. Select Yes for the following dialog.

1 4 h u l e
70 i b s a
1 n t i v
h a s h
s da
s a Untrusted Connection

220 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

19. JViewer is launched successfully.

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a JViewer Launched
20. Instead of entering the host ip address, web port address, username and password everytime we run the

s
project. We can configure the default arguments passed to the java project. Select Run -> Run configurations,

1 4
select the Java application name, click on Arguments and input the details as shown in the following
screenshot.

h u l e
70 i b s a
1 n t i v
h a s h
s da
s a
221 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
21. Click on Apply and then Run.
Program Arguements

22. The arguments value will be filled when the Standalone dialog is shown.

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da Arguements

s a
222 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Debugging JViewer In Eclipse

1. Add System.out.println(“JViewer App”) in source code to print the text “JViewer App” in console. Upon
running the project the console will be printed with “JViewer App”

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
JViewer APP Console
2. To print existing Debug.out.println() prints to console, change “MODE = RELEASE” to “MODE = DEBUG”

a
in function private Debug() in com.ami.kvm.jviewer.Debug.java file.

4 h s
0 1 h u l e
1 7 t i b s a
a n h i v
h
s da s Coding

s a
223 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 Debugging JViewer
3. Debug.out.println() prints in the source code will be printed in the console.
4. To write the Debug.out.println() prints to a file, change “MODE = RELEASE” to “MODE = CREATE_LOG”.

I
in windows.
S
5. JViewer_log _18-04-2022_at_19-20-26-640.log file will be created in user home folder. C:\Users\username

D 30 8 1 n
a
6. We can add debug points by placing cursor in a line and pressing CTRL + SHIFT + b. Or right click the blue
line shown before the line number and select toggle breakpoint.

h
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a Toggle Breakpoint

224 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

7. Execute the project in debug instead of run. Run -> Debug configuration -> Debug.

E -
T R E
O
N IBU T Confirm Switch
8. Select Remember my decision and click switch

O
9. The project will be paused in the breakpoint. We can view the variable value by hovering over the variable

2
name.

R
D T 241
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h Variables

s da
10. Common techniques used for debugging java application in eclipse can be used for debugging JViewer in
eclipse. Refer https://www.eclipse.org/community/eclipse_newsletter/2017/june/article1.php

s a
225 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 13

IPMI Configuration
E -
LAN Configuration

T R E
IPMI will get the LAN configuration details from the PDK Hook PDK_GETLANCONFIGURATIONS to

O T
communicate with LAN interface. This PDK hook will have the LAN configuration table LANIFCConfig_T to
configure the interface details to be used in IPMI LAN interface. OEM can modify this table according to their

N IBU
need. Below example will explain the details of the LAN configuration table.
LANIFCConfig_T m_LANConfigTbl2 [MAX_LAN_CHANNELS] =
{

O
{“eth0”,
R
D T 241
/*Ifcname,
2
Channel Type Enable
LAN_RMCP_CHANNEL1_TYPE, 0,
,Channel Num
1,
EthIndex
0, 0
Status */
},
{“eth1”,

I S
{“bond0”,

D 30 8
LAN_RMCP_CHANNEL2_TYPE, 0,

1 n
LAN_RMCP_CHANNEL1_TYPE, 0,
8,
1,
1,
0,
0
0
},
}
};

h a
Multiple entries can be added to this table if more than one LAN interface is supported.

Ifcname

1
ChannelType
4 u s Interface name to be used for the LAN channel.

e
Channel type to be used for the LAN channel.
Enable

0
ChannelNum

7 b h a l Enable status of the interface(this will be updated in the boot time).

Channel number.
Ethindex

1
Status

n t i i v s
Ethindex to be used for the LAN Channel.
Link UP/Down status of the interface. (This will be updated in the boot
time).”

h a s h
s da
s a
226 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 14

E
LibusbGadget Porting Guide
-
R
This document provides details on libusbgadget and how to use it for client application. The libusbgadget

T E
is a library developed based on Gadget Driver. The development purpose is to allow the client application
developer implement upper layer without knowing the Gadget Driver. The client application developers should

References
•
O
N IBU T
use this document when porting to a new client application.

Existing Gadget Driver architecture

•

O
Linux USB Gadget configured through configfs https://www.kernel.org/doc/Documentation/usb/gad-

R
get_configfs.txt

D T 241
Supported APIs
2
hid_open I S
D 30 8 1
This secion explain all the APIs that are required to be supported by the Libusbgadget

n
Input argument(s):

h a
Output:

1 u s
req_process: request to initialized HID devices process name

4 e
l
Return code of type Integer

70 b h
zero (0), if success.
-1, if something error

i s a
1
Description:

n t i v
This function used to initialize HID Composite Device and plugin to the vhub.

Hid_stop

h a
Input argument(s):
s h
s da
req_process: request to stop HID devices process name

a
Output:
Return code of type Integer

s
zero (0), if success.
-1, if something error

227 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Description:
This function used to stop HID Composite Device.

SendMouseData
Input argument(s):

E -
buf: mouse data description as follow:

Byte
Descriptor
Byte0

T
Button
R E
Byte1
X
Byte2 Byte3
Y
Byte4 Byte5
wheel

T
Button:

O
Bit 0: Left Button

N IBU
Bit 1: Right Button
Bit 2: Middle Button

O R
D T 241 2
Bit 3-7: Padding Bits.
Bit7-3: Padding Bits
X:

I S
Byte1: High Byte

1
Byte2: Low Bytes

D 30 8 n
Y:
Byte3: High Byte
h a
1 4
Byte4: Low Bytes

u s e
l
Output:

70 b h
Return code of type Integer
zero (0), if success.

i s a
t
-1, if something error

1
Description:

n i v
a h
This function used to send mouse move data

h
SendKeybdData

s da
Input argument(s): s
buf: keyboard data description as follow:

Byte

s a Byte0 Byte1 Byte2 Byte3 Byte4 Byte5 Byte6 Byte7

228 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Descriptor Modifier Reserved Key1 Key2 Key3 Key4 Key5 Key6

Keys

-
Modifier keys:

E
Bit 0: Left Ctrl
Bit 1: Left Shift
Bit 2: Left Alt

T
Bit 3: Left GUIR E
T
Bit 4: Right Ctrl

O
Bit 5: Right Shift

N IBU
Bit 6: Right ALT
Bit 7: GUI
Output:

O R
D T 241 2
Return code of type Integer
zero (0), if success.
-1, if something error
Description:

I S
D 30 8 1 n
This function used to stop HID Composite Device.

ResetLEDStatus
Input argument(s):
h a
None

1 4 u s e
Output:

0
None

7 b h a l
1
Description:

n t i i v s
The BMC side keeps a LED status. This function used to reset it.

h a
ReadLEDStatus
Input argument(s):
s h
s da
Status: the LED status, see follow description

a
no_wait: zero(0), read LED status on Wait mode

s 1, readl LED status on No Wait mode

LED status description:

229 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Bit 0: NumLock
Bit 1: CapsLock
Bit 2: ScrollLock
Bit 3: Compose
Bit 4: Kana
Bit 5-7: Constant
E -
Output:

T R
Return code of type Integer

E
zero (0), if success.

T
-1, if something error
Description:

O
N IBU
This function used to initialize HID Composite Device and plugin to the vhub.

changeMouseRel2Abs

O R
Input argument(s):

Output:
None

D T 241 2
I S
Return code of type Integer

1
zero (0), if success.

D 30
-1, if something error

8 n
Description:

h a
This function used to change mouse to absolute mode

1 4
getCurrentMouseMode

u s e
Input argument(s):

0 b h a l
MouseModeStatus: 1, ABSOLUTE_MOUSE_MODE

7
Output:

1 n t i i v s
Return code of type Integer
zero (0), if success.

h
Description:
a s h
-1, if something error

s da
This function used to get current mouse mode status

cdrom_init

s a
Input argument(s):
num_instance: Maximum number of CD instance to be configured. The valid range is 1 ~ 4

230 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Output:
Return code of type Integer
zero (0), if success.
-1, if something error

-
Description:
This function used to initialized CDROM gadget configured.

cdrom_exit
Input argument(s):

R E
Output:
None

O T T E
Return code of type Integer

N IBU
zero (0), if success.
-1, if something error
Description:

cdrom_start O R
D T 241
Input argument(s):
2
This function used to unbind CDROM gadget from UDC and free allocated resources.

Output:
I S
file: file path to be loaded into gadget

D 30 8 1 n
a
Return code of type Integer
Positive value, if success then return instance number

h
-1, if something error
Description:

1 4 u s e
l
This function used to loads the given medium into gadget

70
cdrom_stop

i b h s a
1 n t
Input argument(s):

i v
instance: Gadget instance number provided by cdrom_start() API

Output:

h a s h
Return code of type Integer

s da
zero (0), if success.
-1, if something error

a
Description:

s
This function used to stop CDROM session for given instance.

cdrom_eject_status

231 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Input argument(s):
instance: Gadget CDROM instance number

Output:

E -
Return code of type Integer
zero (0), if medium present.
-1, if something error
1, if medium is eject.
Description:

T R E
This function used to provides host eject event status for the given instance.

vmedia_cd_connect

Output:
None O
N IBU
Input argument(s):
T
O
Return code of type Integer

R
D T 241
zero (0), if success.

2
-1, if something error
Description:

I S
This function used to bind CDROM Gadget

D 30 8
vmedia_cd_disconnect
1 n
Input argument(s):

h a
s
None
Output:

1 4 u
Return code of type Integer

h l e
0
zero (0), if success.

Description:

1 t i b
-1, if something error

7 s a
n i v
This function used to clean UDC information for unbind CDROM Gadget.

hdisk_init
a h
Output:
h
Input argument(s):

s da s
num_instance: Maximum number of HD instance needs to be configured. The valid range is 1 ~ 4.

s a
Return code of type Integer
zero (0), if success.
-1, if something error

232 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Description:
This function used to initialize the Gadget hdisk configuration.

hdisk_exit
Input argument(s):

Output:
None

E -
T R
Return code of type Integer
zero (0), if success.

E
-1, if something error
Description:

O
N IBU T
This function used to unbind hdisk Gadget from UDC and free allocated resource.

hdisk_start

O
Input argument(s):

Output:
R
D T 241 2
File: file path to be loaded into Gadget

Return code of type Integer

S
Positive value, if success then return instance number

Description:
I
-1, if something error

D 30 8 1 a n
This function used to loads the given medium into Gadget.

hdisk_stop

4 h s
u
Input argument(s):

0 1 h l e
instance: Gadget instance number provided by hdisk_start() API

a
b
Output:

1 7 t i v
zero (0), if success.
s
Return code of type Integer

Description:

a n h i
-1, if something error

h
s da
hdisk_eject_status
Input argument(s):
s
This function used to stop hdisk session for given instance.

Output:
s a
Instance: Gadget hdisk instance number.

zero (0), if medium present.

233 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

-1, if something error

1, if medium is eject.
Description:
This function used to stop HID Composite Device.

hdisk_readonly
Input argument(s):
E -

Output:
R
status: 1, means read only.

T E
Zero(0), means read/write

O
N IBU T
Return code of type Integer
zero (0), if success.
-1, if something error
Description:

O
This function used to configure read only status. Need to be called before hdisk_start()

hdisk_removable
Input argument(s):R
D T 241 2

I S
status: 0x0, as fixed

D 30 1 n
0x80, as removable. This parameter need to set as removable.

8
Output:

h a
Return code of type Integer
zero (0), if success.

1
Description:
4 u s
-1, if something error

e
0 h l
This function used to configure removable status.

7 b a
vmedia_hd_connect

1 n t
Input argument(s):i i v s
Output:
None

h a s h
Return code of type Integer

s da
zero (0), if success.
-1, if something error
Description:

s a
This function used to bind harddisk Gadget

vmedia_hd_disconnect

234 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Input argument(s):
None
Output:
Return code of type Integer
zero (0), if success.

E -
-1, if something error
Description:

eth_open

T R
This function used to clean UDC information for unbind harddisk Gadget.

E
Input argument(s):

Output:
None
O
N IBU T
Return code of type Integer

O
zero (0), if success.

2
-1, if something error
Description:

R
D T 241
This function used to initialize Ethernet device and plugin to the vhub

eth_stop

I S
Input argument(s):

D 30 8 1 n
Output:
None

h a
1 u
zero (0), if success.
s
Return code of type Integer

4 e
l
-1, if something error

70
Description:

i b h s a
This function used to stop Ethernet device

1 n t
set_power_saving_mode

i v
h a
Input argument(s):

s h
cmd: zero(0), disable power saving mode

Output:
s da 1, enable power saving mode

s a
Return code of type Integer
zero (0), if success.
-1, if something error

235 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Description:
This function used to setting power saving mode.

get_usb_vhub_connect_status
Input argument(s):

E -
status: zero(0), USB devices disconnected to the Host

R
1, USB devices connected to the Host
Output:

T E
Return code of type Integer
zero (0), if success.

Description:
O
N IBU T
-1, if something error

This function used to getting virtual hub connect status.

O R
D T 241 2
USB Port B Feature Support
This section explains how to enable port B Host Controller Driver / Device Driver Support.

I S
PRJ Configuration

D 30 8 1 n
To enable USB port B feature, need to enable USB port B feature first. User can enable the required features on

a
the basis of need. A sample screenshot is displayed below.

h
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
236 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
PRJ Configuration for USB Port B Feature

a
1. USB Port B Host Controller Driver(EHCI) support.

h
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
237 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
USB Port B Host Controller

a
2. USB Port B Device Driver support

h
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
238 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
USB Port B Device Driver

USB Port B Supported APIs

h a
This section only included USB port B device drivers APIs. Please reference follow:

1 4
port_b_hdisk_init

u s e
Input argument(s):

0 b h a l
num_instance: Maximum number of port B HD instance need to be configured. The valid value is 1.

7
1
Output:

n t i i v s
Return code of type Integer

h a s h
Zero (0), if success.
-1, if something error.

s da
Description:
This function used to initialize the Gadget port B hdisk configuration.

s a
port_b_hdisk_exit
Input argument(s):

239 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

None
Output:
Return code of type Integer

-
Zero (0), if success.
-1, if something error

Description:

R E
This function used to unbind port B hdisk Gadget from UDC and free allocated resource.

port_b_hdisk_start
Input arguments(s):

O T T E
N IBU
File: file path to be loaded into Gadget
Output:
Return code of type Integer.

O R
D T 241 2
Positive value, if success then return instance number
-1, if something error

Description:

I S
This function used to loads the given medium into port B hdisk Gadget.

port_b_hdisk_stop

D 30 8 1 n
Input argument(s):

h a
s
Instance: Gadget instance number provided by hdisk_start() API.
Output:

1 4 h u l e
Return code of type Integer.

70 i b
Zero (0), if success.

s
-1, if something error
a
1
Description:

n t i v
h a s h
This function used to stop port B hdisk session for given instance.

port_b_hdisk_eject_status

s da
Input argument(s):

a
Instance: port B Gadget hdisk instance number.
Output:

s
Zero (0): if medium present.

240 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

-1, if something error.

1, if medium is eject.

Description:

-
This function used to get Host eject event status for the given instance.

port_b_hdisk_readonly_status
Input argument(s):

R E
Status: 1 means read only.

Output:
T E
0 means read/write.

O T
N IBU
Return code of type Integer.
Zero (0), if success.
-1, if something error.

Description:
O R
D T 241 2
This function used to configure read only status. Need to be called before port_b_hdisk_start().

port_b_hdisk_removeable_status

I S
Input argument(s):

D 30 8 1
Status: 0x0 as fixed.
n

h a
0x80, as removeable. This parameter need to set as remoeable.
Output:

1 4 u s
Return code of type Integer.

e
b h
Zero (0), if success.

0 a
-1, if something error.

7 l
1
Description:

n t i i v s
This function used to configure removeable status.

h a
Input argument(s):
s h
port_b_vmedia_hd_connect

s da
None
Output:

s a
Return code of type Integer.
Zero (0), if success.

241 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

-1, if something error

Description:
This function used to bind port B harddisk Gadget.

port_b_vmedia_hd_disconnect
Input argument(s):

E -
Output:
None

T R E
Return code of type Integer.

Description: O
N IBU T
Zero (0), if success.
-1, if something error.

This function used to clean UDC information for unbind port B harddisk Gadget.

O
port_b_eth_open

R
D T 241
Input argument(s): 2
Output:
None

I S
D 30 8 1 n
a
Return code of type Integer

h
Zero (0), if success.
-1, if something error.

Description:

1 4 u s e
7
port_b_eth_stop
b h a l
This function used to initialize port B Ethernet device.

0
1 t
Input argument(s):
None
n i i v s
Output:

h a s h
s da
Return code of type Integer.
Zero (0), if success.

a
-1, if something error.

s
Description:
This function used to stop port B Ethernet device.

242 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 15

E -
T R
Reset Hardware Porting Guide
This section of the document enables users to understand the hardware interface exposed by the Reset HW

E
driver module. Device-driver developers should use this document when porting to a new hardware. This

T
document specifies guiding principles for the implementation of the Reset HW driver module. The hardware-

O
level driver should load independently of any other driver modules.

N IBU
Helper Data Structures and Functions
The following Helper functions are used by the HW-level driver module:

O
D T 241 2
1. int register_hw_hal_module (hw_hal_t *phw_hal, void **pcore_funcs);

R
2. int unregister_hw_hal_module (ehal_dev_type dev_type, unsigned char dev_id);
The data structure passed at the time of registration hw_hal_t is declared as follows:
typedef struct
{

I S
D 30 8 1 n
ehal_dev_type dev_type;
struct module *owner;

h a
const char *devname;
unsigned char num_instances;

s
void *phal_ops;
} hw_hal_t;

1 4 u l e
The registration function returns the function pointer to the RESET core functions that can be used by the HW

h
70
driver module.

i b a
The device type ehal_dev_type is an enum and dev_type must be EDEV_TYPE_RESET when calling the two

s
1
functions.

n t i v
Files to be included are: reset.h and driver_hal.h.

a h
Common Data Structures and Interface Functions

h s
s da
The HW driver module uses the data structures that declare the core functions and the HAL functions.
typedef struct
{

a
int (*process_reset_intr) (int dev_id);

s
} reset_core_funcs_t;
The function process_reset_intr gets called when a Reset interrupt occurs.
typedef struct

243 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

{
} reset_hal_operations_t;
The Reset HW driver module does not provide any interface functions currently.

Initialization and Cleanup

E -
The HW driver module does the following actions at the time of loading and unloading.

int __init lpcreset_hw_init (void);

T R
This function registers its HW functions with the higher level module using register_hw_hal_module. It
registers its interrupt handling routine for the reset interrupt line. Depending on the interrupt lines, this will

E
need to be a shared interrupt (SA_SHIRQ) or local interrupts will need to be disabled (SA_INTERRUPT). It

T
then enables the reset interrupts.
Inputs:
None
Return: O
N IBU
0 on success, -1 on failure

O
void __exit lpcreset_hw_exit (void);

R
D T 241 2
This function disables the reset interrupts. It frees the IRQ that was requested during initialization. It unregisters
its HW functions by calling unregister_hw_hal_module.

S
Inputs:

I
None
Return:
None

References
D 30 8 1 a n
h s
• LPC Reset hardware datasheet.

4
0 1 h u l e
1 7 t i b s a
a n h i v
h
s da s
s a
244 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 16

Hardware Watchdog Usage

E -
T R
This section of document describe the usage of hardware watchdog devices available. The watchdog device
on timeout can reset the modules configured in the watchdog reset enable register. The application designers

E
can make use of watchdog device to recover from software or hardware hangs. BMC manufacturers started

T
incorporating multiple watchdog devices. The kernel watchdog driver module is modified to support multiple

O
devices. Programmers can set the watchdog device they want to use using driver module parameter (/sys/module/

N IBU
watchdog_hw/parameters/current_wdt_device) or libwatchdog APIs SetCurrentWdtDev/GetCurrentWdtDev.
It’s advised to reset the current watchdog device number to its previous value to maintain backward compatibility.
The libwatchdog library implements GetWatchdogMutexLock/ReleaseWatchdogMutexLock API to provide
atomic access to watchdog device and to prevent race conditions. The libwatchdog library also implements

O
APIs SetCurrentWdtDevResetMask/GetCurrentWdtDevResetMask in order to provide a way to configure

R 2
enable reset register associated with current watchdog device.

D T 241
The programmers should follow below sequence while making use of multiple watchdog devices.

I S
GetWatchdogMutexLock ()

D 30 8 1 n
prevdev = GetCurrentWdtDev()

a
SetCurrentWdtDev(curwdtdev)

h
1
TriggerWatchdog()

u s
SetCurrentWdtDevResetMask()

4 e
70 b h a l
SetCurrentWdtDev(prevdev)

1 t i s
ReleaseWatchdogMutexLock()

n i v
h a s h
s da
s a
245 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 17

eSPI
E -
R
This document helps users to understand the hardware interface exposed by the eSPI hardware level drivers.

T E
There are 3 hardware level drivers, one for Peripheral and Virtual Wire channels, one for OOB channel and the
other for MAFS channel. Except the driver for Peripheral and VW channels diver is essential to cmminicate

O
N IBU T
with PCH, others are selected depends on what channel should be supported. Device-driver developers
should use this document when porting to a new hardware. This document specifies guiding principles for
the implementation of the hardware-level eSPI driver and contains the data structures and interface functions
between the common and hardware driver modules. The helper driver functions and data structures used
are also described in the document. The hardware-level driver should load independently of any other driver

O
modules.

R
Initialization and Cleanup

D T 241 2
The HW drivers module does the following actions at the time of loading and unloading by module_init and
module_exit.

I S
D 30 8 1
int __init espi_hw_init(void);

n
int __init espioob_hw_init(void);

h a
int __init espimafs_hw_init(void);

1 4 u s
These functions begin by fetching kernel space memory that need for its operation. All call register_hw_hal_
module to register the HW function pointers with the higher level module. By registering its IRQ handler,

e
l
drivers can handle interrupts that occur on the eSPI interrupt line. And also install its reset function when a

Inputs:

70
reset is detected.

i b h s a
1
None
Return:

n t
0 on success

i v
h a
-1 on failure

s h
void __exit espi_hw_exit(void);

s da
void __exit espioob_hw_exit(void);

s a
void __exit espimafs_hw_exit(void);
These functions disable the eSPI interrupts, free the IRQ for eSPI interrupts. Beside, unregister hardware
functions from the higher level module by using unregister_hw_hal_module. It uninstalls its reset function,

246 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

and finally frees all memory that it had requested earlier.

Inputs:
None
Return:

-
None

Helper Data Structures and Functions

R E
1. int register_hw_hal_module (hw_hal_t *phw_hal, void **pcore_funcs);
2. int unregister_hw_hal_module (ehal_dev_type dev_type, unsigned char dev_id);

typedef struct
{

O T T E
The data structure passed at the time of registration ‘hw_hal_t’ is declared as follows:

N IBU
ehal_dev_type dev_type;
struct module *owner;
const char *devname;

O
unsigned char num_instances;

} hw_hal_t;

R
void *phal_ops;

D T 241 2
The registration function returns the function pointer to the espi/espioob/espimafs core functions that can be
used by the HW driver module. The device type ‘ehal_dev_type’ is an enum and dev_type must be EDEV_

I S
TYPE_ESPI/ EDEV_TYPE_ESPIOOB/ EDEV_TYPE_ESPIMAFS when calling the two functions.

D 30 8 1 n
Files to be included are: espi.h/espioob.h/espimafs.h and driver_hal.h.

a
Common Data Structures and Interface Functions

hs
The HW driver module uses the data structures that declare the core functions and the HAL functions.

1 4
In espi.h file
typedef struct

h u l e
{

70 i b a
void (*get_espi_core_data) ( int dev_id );

s
1
typedef struct

n t
} espi_core_funcs_t;

i v
{

h a s h
unsigned char (*num_espi_ch) (void);

s da
void (*set_vw_bmc2host_group_val) (u8 ind, u8 val);
void (*get_vw_host2bmc_group_val) (u8 ind, u8 *buf);
void (*get_channel_status) (u32 *gen_status, u32 *ch_status, u32 *Peripher

a
alChMaxReadReqSize, u32 *PeripheralChMaxPayloadSizeSelected, u32 *Periph
eralChMaxPayloadSizeSupported );

s
} espi_hal_operations_t;

247 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

In espioob.h file
typedef struct
{
void (*get_espioob_core_data) ( int dev_id );

-
} espioob_core_funcs_t;
typedef struct

E
{
unsigned char (*num_espioob_ch) (void);

T R
void (*oob_read) (struct espioob_data_t *espioob_data);
void (*oob_write) (struct espioob_data_t *espioob_data);

E
void (*oob_writeread) (struct espioob_data_t *espioob_data);
void (*get_channel_status) (u32 *gen_status, u32 *ch_status, u32 *OOBChMax

T
PayloadSizeSelected, u32 *OOBChMaxPayloadSizeSupported);

In espimafs.h file
typedef struct
O
} espioob_hal_operations_t;

N IBU
{

O R
D T 241 2
void (*get_espimafs_core_data) ( int dev_id );
} espimafs_core_funcs_t;

S
typedef struct
{

I
D 30 8 1 a n
unsigned char (*num_espimafs_ch) (void);
int (*flashmafs_read) (uint32_t addr, uint32_t *len, u8 *data);
int (*flashmafs_write) (uint32_t addr, uint32_t len, u8 *data);

4 h
int (*flashmafs_erase) (uint32_t addr, uint32_t eraseblocksize);

s
void (*get_channel_status) (uint32_t *gen_status, uint32_t *ch_status,
uint32_t *FlashAccChMaxReadReqSize, uint32_t *FlashAccChMaxPayloadSizeSe

1 u
*FlashAccChEraseSize);

0 h
} espimafs_hal_operations_t;

l e
lected, uint32_t *FlashAccChMaxPayloadSizeSupported, uint32_t

1 7 t i b s a
v
The interface functions implemented by the HW driver module are as follows:

n i
unsigned char num_espi_ch(void);

a h
h s
This function returns number of channels, peripheral or virtual wire channel.

s da
Inputs:
None
Return:

s a
Number of espi channels

void set_vw_bmc2host_group_val) (u8 ind, u8 val);

This function sets virtual wire event from BMC to host.

248 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Inputs:
ind, number of vw index
val, value of vw index
Return:
None

E -
void get_vw_host2bmc_group_val (u8 ind, u8 *buf);
This function gets virtual wire event from host to BMC.
Inputs:

T R
ind, number of vw index

E
buf, value of vw index
Return:
None

O
N IBU T
void get_channel_status (u32 *gen_status, u32 *ch_status, u32 *Periph-
eralChMaxReadReqSize, u32 *PeripheralChMaxPayloadSizeSelected, u32
*PeripheralChMaxPayloadSizeSupported );

Inputs:
O
D T 241 2
This function gets channel status of peripheral and vw channels.

R
gen_status, status of general capabilities and configuration
ch_status, support peripheral and vw channel or not

I S
PeripheralChMaxReadReqSize, peripheral max read request size

1
PeripheralChMaxPayloadSizeSelected, peripheral max payload size selected

D 30 8 n
PeripheralChMaxPayloadSizeSupported, peripheral max payload size support
ed
Return:
None

h a
1 4 u s
unsigned char num_espioob_ch(void);

e
Inputs:

7 b h a l
This function returns number of channel, oob channel.

0
None

1
Return:

n t i i v s
Number of espi oob channels

h a s h
void oob_read(struct espioob_data_t *espioob_data);
This function reads oob channel data from host to BMC.
Inputs:

s da
espioob_data, header, buf_len and buffer data sturcture
Return:
None

s a
void oob_write(struct espioob_data_t *espioob_data);

249 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

This function writes oob channel from BMC to host.

Inputs:
espioob_data, header, buf_len and buffer data sturcture
Return:

-
None

void oob_writeread(struct espioob_data_t *espioob_data);

Inputs:

R E
This function write oob channel from BMC to host and read oob channel from host to BMC.

espioob_data, header, buf_len and buffer data sturcture

Return:
None

O T T E
void get_channel_status (u32 *gen_status, u32 *ch_status, u32 *OOBCh-

N IBU
MaxPayloadSizeSelected, u32 *OOBChMaxPayloadSizeSupported);
This function gets channel status of oob channel.
Inputs:

O R 2
gen_status, status of general capabilities and configuration

D T 241
ch_status, support oob channel or not
OOBChMaxPayloadSizeSelected, oob max payload size selected
OOBChMaxPayloadSizeSupported, oob max payload size supported
Return:
None

I S
D 30 8 1 n
h a
unsigned char num_espimafs_ch(void);
This function returns number of channel, mafs channel.
Inputs:
None
Return:

1 4 u s e
70 b h a l
Number of espi mafs channels

int flashmafs_read (uint32_t addr, uint32_t *len, u8 *data);

1
Inputs:

n t i i v s
This function reads flash channel data from host to BMC.

h a s
len, read length
h
addr, flash address

data, data from host to BMC

Return:

s da
0 - success

s a
None 0 - failure

int flashmafs_write (uint32_t addr, uint32_t *len, u8 *data);

250 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

This function writes flash channel data from BMC to host.

Inputs:
addr, flash address
len, read length

-
data, data from BMC to host
Return:
0 - success
None 0 - failure

R E
int flashmafs_erase (uint32_t addr, uint32_t eraseblocksize);

Inputs:

O T
addr, flash address

T E
This function erases flash channel data from BMC to host.

N IBU
eraseblocksize, erase block size
Return:
0 - success

O
None 0 - failure

R
D T 241 2
void get_channel_status (uint32_t *gen_status, uint32_t *ch_status,
uint32_t *FlashAccChMaxReadReqSize, uint32_t *FlashAccChMaxPay-
loadSizeSelected, uint32_t *FlashAccChMaxPayloadSizeSupported,

I S
uint32_t *FlashAccChEraseSize);

D 30 8 1 n
This function gets channel status of flash access channel.
Inputs:

h a
gen_status, status of general capabilities and configuration
ch_status, support flash channel or not

1 4 u s
FlashAccChMaxReadReqSize, flash access max read request size
FlashAccChMaxPayloadSizeSelected, flash access max payload size selected

e
7 b h a l
FlashAccChMaxPayloadSizeSupported, flash access max payload size supported

0
FlashAccChEraseSize, flash block erase size

i
Return:

1
None

n t i v s
irqreturn_t espi_reset_handler (int irq, void *dev_id);

h a s h
This is the interrupt handler for the espi reset interrupt. It gets registered when the request is made for the IRQ.

irqreturn_t espi_handler (int irq, void *dev_id);

s da
This is the interrupt handler for the espi peripheral and vw interrupt. It gets registered when the request is
made for the IRQ.

s a
irqreturn_t espioob_handler (int irq, void *dev_id);
This is the interrupt handler for the espi oob interrupt. It gets registered when the request is made for the IRQ.

251 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

irqreturn_t espimafs_handler (int irq, void *dev_id);

This is the interrupt handler for the espi flash interrupt. It gets registered when the request is made for the IRQ.

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
252 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 18

E -
VGA Memory Size Configuration (AST2600)

T R
Using OTP tool user can configure the VGA memory size for AST2600 SOC. Recommended VGA memory

E
size is (32/64 MB**) for supporting higher host resolutions in latest Linux distributions (kernel 5.6 and higher).

T
(**Data reference - ASPEED Application Note A2600-07)

O
OTP tool commands can be executed under u-boot.

N IBU
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s VGA Memory Size
Refer ASPEED SDK User Guide > OTP Utility [AST2600] for detailed information on tool usage and

h a
configuration.

s h
Note: OTP configuration attempts are limited. It’s recommended to proceed with caution since modification

s da
is permanent and cannot be reverted after exhausting all the attempts.

s a
253 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 19

Device Drivers
E -
S.No

T R E Driver Name Regular LTS 13 – 2600 Kernel 5

1
2
3
4
5
ADC
GPIO
I2C
KCS O
N IBU
PWMTACH
T Built-in
Built-in
Built-in
Built-in
Built-in
6
7
8
9
OSNOOP

R
RESET

D T 241
Watchdog
2
Platform (pinctrl)
Built-in
AMI
Built-in
Built-in

S
10 UART Route AMI

I
11 Netmon AMI
12
13
14
PECI

D 30
USB
CPLD
8 1 a n
Built-in
Built-in
Built-in
15
16
17

4
JTAG
CDROM
HDISK hs
Built-in
Built-in
Built-in
18
19

0 1 NCSI
NIC

h u l e Built-in
Built-in
20
21

1 7
SPI

i
UART

t b s a Built-in
Built-in

v
22 Video AMI
23

a nHelper

h i AMI

h
s da s
s a
254 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 20

Secure Boot
E -
R
Secured Boot helps to make sure that the BMC boots using only the firmware trusted by the manufacturer.

T E
When BMC starts, the firmware checks the signature of each piece of boot software like U-boot, Kernel and
Root file system. If the signatures are good then BMC firmware boots as expected. This feature requires some

O
N IBU
PRJ Configuration T
setups on both PRJ configurator and ImageSigning Tool.

To enable secure boot certain features need to be selected, please follow the screenshot given below to enable
this feature.

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h PRJ Configuration

s da
Required Packages

Package Name Added or Modified

s
flasher-src
a
Bootloader_20XX_amiext-src

sys_cryptsetup-src
Modified
Modified
Modified

255 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

ImageSigning Tool Configuration

• ImageSigning Tool - This tool is used to embed public keys for secured boot, signed hashed image, back-
up and restore configuration support and the corresponding encrypted hash to SPX firmware images.

-
ImageSigning Tool settings can be setup and changed by modifying the content of configuration.ini file.

E
ImageSigning Tool Options
ImageSigning Tool has below explained options via configuration file. This tool needs to be executed at terminal.
Command Syntax

T R E
./ImageSigningTool –ini <configuration file>

O
N IBU T Image Signing Tool Options

O R
Sample Configuration File

D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 t i v s
Configuration Setting Description

n i
Configuration.ini

h a
GLOBAL Section

s h
fwimagepath - This section holds the location of the input firmware image
•
s da
Output – Location of where signed images need to be

SECURED BOOT SUPPORT Section

s a
This section contains the vital information for secured boot and extended secured boot support.
• publickey : location of the public key in your build machine

256 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• privatekey : location of the private key in your build machine

• extended_uboot : This option enables extended uboot hash generation. Separate hash for uboot and
backup uboot will be calculated and stored in firmware info section. This can be used by the loader mod-
ules to validate the integrity of the uboot and backup uboot. This option is used only if the firmware has
backup uboot
•
-
include_uboot : This option is to include UBOOT also for secured boot validation. This option is used

E
only when include uboot option is enabled in BMC firmware configuration (PRJ).

R
Note: Secured boot support only works with 2048 bit keys.

SPL_SUPPORT SUPPORT Section

O T T E
This section contains the vital information for ast2600 hardware secure boot signature mode support.
rsakey1private - The name of the file containing RSA key 1 private portion. This is used to sign the en-

N IBU
crypted SPL image, and the unencrypted U-boot image
• rsakey1public - The name of the file containing RSA key 1 public portion

O
• sign_script - This option indicates the name of the script file to be used for signing. The default is “extspl.

2
sh”

R
D T 241
Note: Secured boot support only works with 2048 bit keys.

SECURED BOOT SUPPORT Encryption Section

I S
This section contains the vital information for secured boot encryption mode support.

D 30 8 1 n
Note: Secured boot Encryption mode support only works with AES 256 keys.

a
SIGNED HASH SUPPORT Section

h s
This section contains vital information for appending Signed hash to the input image.
•

1 4 h u
publickey : location of the public key in your build machine

l e
0
• privatekey : location of the private key in your build machine
•

7 b a
Hash type: This option accepts following algorithms: SHA1, SHA224, SHA256 and SHA512

1 t i s
n i v
BACKUP AND RESTORE KEY Section
This section contains vital information for embedding AES KEY and AES IV to the input image.
•
a h
aeskey : location of the AES key in your build machine
•
h
s da s
aesiv : location of the AES IV in your build machine
Note:

s a
If input image is not HPM based image, then “_enc” will be appended to the output file name. This image
can be used by Web Interface and YAFUFlash.
If input image is raw SPX image, then this tool generates additional file which will be of the same name men-

257 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

tioned in output parameter.

This file will not have encrypted hash appended to it. This image should be used for factory pro-gramming of
BMC SPI.
If input image is an HPM image, then all the components present in the HPM image will be signed and

Signed Hash Support

E -
stored in the output file.

T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a Signed Hash Support Flow

258 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Note:
Signed Hash image is one suffix with "_enc" on output image name.
When signed hash support is enabled in Image Signing Tool config file one output image with suffix "_enc"
image (signed hash image) is generated.

Secured Boot Support

E -
T R E
O
N IBU T Secured Boot Support Flow

Note: O R
D T 241 2
When secure boot support is enabled in the Image Signing Tool config file only output image (secure boot

S
image) is generated.

I
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
259 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Signed Hash and Secure Boot Support

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da Signed Hash and Secure Boot Support Flow
Note:

s a
Secured Signed Hash image is one suffix with _enc on output image name.

260 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

When signed hash support + secure boot support is enabled in the Image Signing Tool config file both output
image (Secure signed image) and output image with suffix "_enc" (Secure signed hash image) are generated.

Multiplatform and FIT Image Support

E -
This section describes the Fit image Architecture with multiple DTB. It explains the configuration and PRJ
Configuration required for user to do.

PRJ Configuration

T R E
To enable Fit image, user need to use latest MDS 13.4 and make sure following Configuration must be there in

O T
PRJ. Make sure that OSIMAGE file must be named as below figure. Also, the DTB section must be removed.

N IBU
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s PRJ Configuration

h a s h
s da
Required Packages (Modified)
Patches are added to Bootloader and Bootloader OEM packages. Bootloader_amiext patch updated for loading

s a
the DTB file set in uboot environment.
Also added patch for selecting DTB as per platform. This patch is portable and customizable as per customer
platform.

261 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Kernel Packages
Kernel_5_Config-ARM-AST2600-AST2600EVB-src
Kernel_5_Config-ARM-AST2600-ArcherCity-src

Bootloader Packages

E -
Bootloader_20XX_amiext-src

R
Bootloader_20XX_platform_ast2600evb-src

Kernel configuration

O T T E
The developer should configure the following file as per there requirement. The file content looks like as below.
User can Port the Highlighted part as per there DTB file.

N IBU
Kernel_5_Config-ARM-AST2600-AST2600EVB-src/data/kernel.its
/dts-v1/;

/ {

O R
D T 241 2
description = "U-Boot fitImage for LTS13 SPX/5.4.85-ami/ast2600";
#address-cells = <1>;

I S
images {

D 30 8 1 n
kernel@1 {

h a description = "Linux kernel";

data = /incbin/("arch/arm/boot/zImage");

1 4 u s e
type = "kernel";
arch = "arm";

70 b h a l os = "linux";
compression = "none";

1 n t i i v s
load = <0x80001000>;
entry = <0x80001000>;
hash@1 {

h a s h };
algo = "sha256";

s da };
fdt@ast2600evb_a1.dtb {

s a description = "Flattened Device Tree blob";

data = /incbin/("arch/arm/boot/dts/ast2600evb_a1.dtb");
type = "flat_dt";

262 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

arch = "arm";
compression = "none";

hash@1 {

};

E - };
algo = "sha256";

T R
fdt@ast2600evb_a1_1.dtb {

E
description = "Flattened Device Tree blob";
data = /incbin/("arch/arm/boot/dts/ast2600evb_a1_1.

T
dtb");

O
type = "flat_dt";

N IBU
arch = "arm";
compression = "none";

O R
D T 241 2 hash@1 {

};
algo = "sha256";

S
};

I
D 30 8 1 a n
fdt@ast2600evb_dualspi.dtb {
description = "Flattened Device Tree blob";
data = /incbin/("arch/arm/boot/dts/ast2600evb_dualspi.
dtb");

h s
type = "flat_dt";

4 u
arch = "arm";

0 1 h a l e
compression = "none";

1 7 t i b v s
hash@1 {
algo = "sha256";

a n h
};
i };

h
s da
};
s
s a
configurations {
default = "conf@ast2600evb_a1.dtb";
conf@ast2600evb_a1.dtb {

263 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

description = "1 Linux kernel, FDT blob";

kernel = "kernel@1";
fdt = "fdt@ast2600evb_a1.dtb";

E - hash@1 {
algo = "sha256";

T R
};

E
};

O
N IBU T conf@ast2600evb_a1_1.dtb {
description = "0 Linux kernel, FDT blob";
kernel = "kernel@1";
fdt = "fdt@ast2600evb_a1_1.dtb";

O R
D T 241 2 hash@1 {

};
algo = "sha256";

I S
D 30 8 1
};

n
a
conf@ast2600evb_dualspi.dtb {
description = "0 Linux kernel, FDT blob";

4 h s
kernel = "kernel@1";
fdt = "fdt@ast2600evb_dualspi.dtb";

0 1 h u l e
1 7 t i b s a hash@1 {
algo = "sha256";

a n h i
};
v };

}; h};

s da s
a
NOTE: - Currently this file needs to modify by user manually. In next Release will update it to Autogenerate.

s
264 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Kernel FIT Image Creation

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da Kernel FIT Image

s a
265 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Kernel Fit Image Flowchart

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da Kernel FIT Image Boot Flow

s a
266 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
Multiplatform Porting Guide
This section enables user to understand the platform specific porting for selecting DTB as per platform.

R
Developer must port the following patch, as per platform required. Developer must port following API.
+int Get_DTB_From_Soc_ID(char *dtbfile)

T E
O T
The API will return the selected DTB name, which needs to be loaded with the
current Platform. The return file name must be without .dtb extension.

N IBU
The following Patch must be ported by Developer. Here is the Example for the
same. Developer must recreate the patch.

O R
D T 241
Patch File : -
2
Bootloader_20XX_platform_ast2600evb-src/data/002-multiple_dtb_support.patch

multidtb.c

I S
diff -Naur uboot/oem/ami/multidtb/multidtb.c uboot_new/oem/ami/multidtb/

D 30 8 1 n
a
--- uboot/oem/ami/multidtb/multidtb.c 1970-01-01 05:30:00.000000000 +0530
+++ uboot_new/oem/ami/multidtb/multidtb.c 2021-08-13 16:33:25.413165500
+0530

4
@@ -0,0 +1,124 @@
h s
0 1
+#include <common.h>
+#include <errno.h>

h u l e
1 7
+#include <asm/io.h>

t i b s a
+#include <asm/arch/aspeed_scu_info.h>
+
+
+
a n h i v
h
s da s
+#define AST2600_A0 0x0500030305000303
+#define AST2600_A1 0x0501030305010303
+#define AST2620_A1 0x0501020305010203

s a
+#define AST2600_A2 0x0502030305010303
+#define AST2620_A2 0x0502020305010203
+#define AST2605_A2 0x0502010305010103

267 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

+#define AST2600_A3 0x0503030305030303

+
+#define DTB_FILE_A0 "ast2600evb"
+#define DTB_FILE_A1 "ast2600evb_a1"

E -
+#define DTB_FILE_A1_1 "ast2600evb_a1_1"
+#define DTB_FILE_A1_DUAL "ast2600evb_dualspi"
+#define DTB_ARCHERCITY "ArcherCity"

T R
+#define DTB_WHITLEY "Whitley"
+

E
+#define CONFIG_SOL_NUMBER CONFIG_SPX_FEATURE_NUM_SOL_SERIAL_PORTS
+

+{
+
O
N IBU T
+int Get_DTB_From_Soc_ID(char *dtbfile)

int retval=-1;
+
+
+
+
O
u64 rev_id;

R
D T 241 2
rev_id = readl(ASPEED_REVISION_ID0);
rev_id = ((u64)readl(ASPEED_REVISION_ID1) << 32) | rev_id;
+
+

I S 1 n
if(rev_id == AST2600_A0)

D 30 8 a
+ {
+ retval = snprintf(dtbfile,128,"%s",DTB_FILE_A0);
+
+

4 { h
if(retval < 0 || retval >= 128)

s
+
+

0 1 h u l e
printf("\n error in copying data");
return retval;
+
+

1 7 }

t i b
}

s a
n i v
+#ifdef CONFIG_SPX_FEATURE_AST2600EVB_PLATFORM_SUPPORT

a h
+#ifdef CONFIG_SPX_FEATURE_GLOBAL_DUAL_IMAGE_SUPPORT

h s
+#ifdef CONFIG_SPX_FEATURE_HW_FAILSAFE_BOOT
+ if(rev_id == AST2600_A1 || rev_id == AST2620_A1 || rev_id == AST2600_A2

+
s da
|| rev_id == AST2620_A2 || rev_id == AST2605_A2 || rev_id == AST2600_A3)
{

+
+
a
+ retval = snprintf(dtbfile,128,"%s",DTB_FILE_A1_DUAL);

s if(retval < 0 || retval >= 128)

{

268 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

+ printf("\n error in copying data");

+ return retval;
+ }
+ }
+#else

E -
+if(rev_id == AST2600_A1 || rev_id == AST2620_A1 || rev_id == AST2600_A2 ||
rev_id == AST2620_A2 || rev_id == AST2605_A2 || rev_id == AST2600_A3)
+

+
{

T R
+ retval = snprintf(dtbfile,128,"%s",DTB_FILE_A1);

E
if(retval < 0 || retval >= 128)

T
+ {
+
+
+
O
N IBU
}
printf("\n error in copying data");
return retval;

O
+ }
+#endif
+#else

R
D T 241
+if(CONFIG_SOL_NUMBER > 12 )

S
+{

+
I 8 1
+#ifdef CONFIG_SPX_FEATURE_HW_EMMC_BOOT

D 30 n
if(rev_id == AST2600_A1 || rev_id == AST2620_A1 || rev_id == AST2600_A2

a
|| rev_id == AST2620_A2 || rev_id == AST2605_A2 || rev_id == AST2600_A3)
+ {

h s
+ retval = snprintf(dtbfile,128,"%s",DTB_FILE_A1);

4 u
+ if(retval < 0 || retval >= 128)
+
+

0 1 {

h a l e
printf("\n error in copying data");
+
+

1 7 t i b
}

v s
return retval;

+
+#else
}

a n h i
+

+ h
s da s
if(rev_id == AST2600_A1 || rev_id == AST2620_A1 || rev_id == AST2600_A2
|| rev_id == AST2620_A2 || rev_id == AST2605_A2 || rev_id == AST2600_A3)
{
+ retval = snprintf(dtbfile,128,"%s",DTB_FILE_A1_1);
+
+
+ s a if(retval < 0 || retval >= 128)
{
printf("\n error in copying data");

269 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

+ return retval;
+ }
+ }
+#endif
+}
+else
+{

E -
+

+ {

T R
if(rev_id == AST2600_A1 || rev_id == AST2620_A1 || rev_id == AST2600_A2
|| rev_id == AST2620_A2 || rev_id == AST2605_A2 || rev_id == AST2600_A3)

E
T
+ retval = snprintf(dtbfile,128,"%s",DTB_FILE_A1);
+
+
+
O if(retval < 0 || retval >= 128)

N IBU
{
printf("\n error in copying data");

O
+ return retval;
+
+
+}
}

R
D T 241
}

2
S
+#endif
+#endif
+
I
D 30 8 1 a n
+#ifdef CONFIG_SPX_FEATURE_PLATFORM_ARCHERCITY
+

4 h s
+ retval = snprintf(dtbfile,128,"%s",DTB_ARCHERCITY);
+
+

0 1 {

h u l e
if(retval < 0 || retval >= 128)

+
+

1 7 t i b s a printf("\n error in copying data");

return retval;
+
+#endif

a n
}

h i v
+#ifdef CONFIG_SPX_FEATURE_PLATFORM_WHITLEY
+

+
h
s da s
+ retval = snprintf(dtbfile,128,"%s",DTB_WHITLEY);
if(retval < 0 || retval >= 128)
+
+
+
s a {
printf("\n error in copying data");
return retval;

270 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

+ }
+#endif
+ return retval;
+}

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
271 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 21

IPMI over USB Support

E -
This document describes the usage of IPMI over USB (internally uses Ethernet over USB) which we support

T R
for accessing the BMC via USB interface from Host. The following points will provide more details on why we
prefer this method of communication rather than using the older IPMI over USB (internally uses iSCSI).

E
As Ethernet over USB is session based, we need to provide valid credentials to establish connection be-

T
tween BMC and Host.
•
• O
Existing cipher suites used for IPMI communication can be leveraged here for added security as well.

N IBU
Ethernet over USB is already been adapted by the industry also been used with Redfish communication
as well.

O
The only difference between IPMI over LAN and IPMI over USB is that IPMI over USB uses Ethernet over USB

R 2
and can be tested only from the Host alone.

D T 241
Once the BMC is flashed with image having IPMI over LAN support enabled in PRJ, Static USB address will
be set as “169.254.0.17” by default as shown in the screenshot below. User can check this with ifconfig usb0

S
command on the BMC debug console.

I
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1
Pre-requisite
n t i i v s IF Config

•
a h
Ensure connection to Host via USB cable in case of ast2600 evaluation board communication

h s
s da
• Host should be up and running and the following steps have been tested on different host operating sys-
tem [Ubuntu Server (18.04 LTS), RHEL 8.4, and Windows server 2019].

Configuration

s a
BMC Configuration
Navigate to Settings > Media Redirection Settings > VMedia Instance Settings and disable power save mode

272 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

via BMC Web UI and save the settings, so that the USB device/interface will emulate in the Host operating
system.

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
VMedia Instance Settings

h a
Host Configuration using Graphical User Interface [GUI]

1 4 u s
After Power save mode is disabled via BMC WebUI, USB interface will get emulate in Host operating system.

e
We must set an IPv4 Link Local address (RFC3927) for the USB interface.

0 h
Ubuntu Server (18.04 LTS)

7 b a l
n i i v s
Follow the below steps to set IPv4 Link Local series IP address to the host:

1 t
1. Click on the Settings > Network and click on to the settings icon of the “USB Ethernet” interface as shown
in the below screenshot.

h a s h
s da
s a
273 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T Host Configuration using GUI

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s Host Configuration using GUI

a
2. Under IPv4 settings, change the method from “Automatic” (DHCP) to “Link-Local Only” method and
click Apply.

h s h
s da
s a
274 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T Link Local Only

O R
D T 241 2
3. After few seconds, the IPv4 Link Local IP will be assigned to the USB Ethernet Interface and hence the IPv4
address can be verified as shown in the below screenshot.

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da IPV4 Address Verification

a
4. IPv4 Link Local address will be set for Host Operating System. User will be able to check the IPv4 Address
using,

s
• Click on the Settings > Network and click on to the settings icon of the “USB Ethernet” interface.
Renamed “usb0” host name will be available under Identity > MAC Address.

275 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
• O R
D T 241 2 IPV4 Address Verification
User can check the assigned IPv4 Address using “ifconfig” on terminal as well

I S
D 30 8 1 n
h a
1 4 u s e IPV4 Address Verification

70 b h a l
1 n i i v s
Red Hat Enterprise Linux (RHEL 8.4)

t
Follow the below steps to set IPv4 Link Local series IP address to the host:

a h
1. Click on the Settings > Network and click on to the Add icon of the “USB Ethernet” interface as shown in
the below screenshot.

h s
s da
s a
276 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T RedHat Terminal

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l Network Settings

1
click Add.

n t i i v s
2. Under IPv4 settings, change the method from “Automatic” (DHCP) to “Link-Local Only” method and

h a s h
s da
s a
277 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 Link Local Only

I S
3. After few seconds, the IPv4 Link Local IP will be assigned to the USB Ethernet Interface and hence the IPv4

1
address can be verified as shown in the below screenshot.

D 30 8 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
278 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 IPV4 Address Verification

I S
4. IPv4 Link Local address will be set for Host Operating System. User will be able to check the IPv4 Address

1
using "ifconfig usb0" on terminal as shown in the below screenshot.

D 30 8 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
279 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
IPV4 Address Verification

h a
Windows Server 2019 - AMI NDIS Driver
AMI NDIS driver reference as follow:

1 4 u s
https://git.ami.com/core/lts/spx-13/core/common/-/tree/LTS-v13/packages/rndisinf-ANY

e
Follow the below steps to update/install the AMI NDIS driver:

70
screenshot.

b h a l
1. Click on the Device Manager > Other devices and Uninstall the unknown device as shown in the below

1 n t i i v s
h a s h
s da
s a
280 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
S
Other Devices and Uninstall Device

I
D 30 8 1 a n
2. Navigate to Control Panel. Under Hardware click on to the View Device and Printers.

4 h s
0 1 h u l e
1 7 t i b s a
a n h i v
h
s da s
s a
281 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 Control Panel

I S 1
3. Further locate USB Serial device under Unspecified devices and double click on it.

D 30 8 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
282 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 Devices and Printers

I S
Note: Copy the required AMI_NDIS Driver.rar, BMC Flash image(.ima) and latest Yafutool into the host us-

1
ing WinSCP or pen drive.

D 30 8 n
4. Select Hardware > Properties > Driver > Update Driver (Choose the location of the driver on the host
system)
•
h a
Update the driver with “AMI_NDIS_20xxDriver.rar”[will be provided alone with the Firmware re-

•
lease]

1 4 u s e
Driver will be updated successfully as below screenshot

70 b h a l
1 n t i i v s
h a s h
s da
s a
283 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 Updated Driver

•
I S
5. Confirm the Network adaptor “AMI_NDIS_20xx” Driver installation as shown in the below screenshot

1 n
Click Control Panel > View device and printers > AMI Remote NDIS6 based Device and then right

D 30 8
click on it Properties > Hardware user will be able to notice the AMI Network adaptor installed.
•

h a
Device manager > Network adapters AMI Remote NDIS6 based Devices will be available.

1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
284 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
s
Device Manager

1 4 h u l e
70 i b s a
1 n t i v
h a s h
s da
s a
285 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 Network Adapter

I S
D 30 8 1 n
Follow the below steps to set static IP in the host

a
1. Navigate to Control Panel > Network and Internet as shown in the below screenshot.

h
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
286 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 Network and Internet
2. Select View Network Status and Tasks as shown in the below screenshot.

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a View network status and tasks

287 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

3. Navigate to Change Adapter Settings and double click on to it as shown in the below screenshot.

E -
T R E
O
N IBU T
O R
D T 241 2 Change Adapter Settings

I S
D 30 8 1 n
4. Locate the AMI NIC port in the network connection and set the required IPv4 Link Local series IP address

•
on the host.

h a
Double click on the Ethernet “AMI Remote NDIS6 based Device” > Properties > Internet Protocol Ver-

s
sion 4 (TCP/IP) > Properties > Select use the following IP address
•
•
1 4
IP address
Subnet mask

h u
: 169.254.0.19

l e
: 255.255.0.0
•

70 b a
Default gateway : 169.254.0.1

i s
•

1 t
Once the desired static IP is set and click OK.

n i v
h a s h
s da
s a
288 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 Network Connection

I S
5. Open the windows Start menu and search for "cmd" and press Enter.

D 30 8 1 n
Check for the “ipconfig” in command prompt for USB Interface IP.

h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
289 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 IP Config

I S
Host Configuration Using Command Line

D 30 8 1 n
Note: Manual method may affect the current running Networking process is recommended if the host OS

a
doesn’t have a Network Manager installed/enabled. If it already has a Network Manager Support, please
use the GUI method as mentioned above.

4 h
After Power save mode is disabled via BMC WebUI, USB interface will get emulate in Host operating system.

s
We must set static IP for this interface manually as “169.254.0.18” (Any IPv4 Link Local IP address is fine).

1 u
Ubuntu Server (18.04 LTS)

0 h l e
1 7 t i b s a
User can get the USB interface name in Host Operating System with command “dmesg | grep usb0”.

a n h i v
s
Host Configuration Using Terminal

h
s da
Following test steps are based on interface with name “enp0s20f0u2u3c2” one need to replace with their host
name for “usb0”.

s a
Follow the below steps to set static IP in host
• Service Networking Stop: Stop the network service before making the changes.

290 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

• vi /etc/network/interfaces
• After entering in the interfaces file, along with the already available interface add the static IP, net mask
for USB interface also as given below
#USB interface
auto enp0s2pf0u2u3c2

E -
iface enp0s2pf0u2u3c2 inet static

R
address 169.254.0.18
netmask 255.255.0.0

O T T E
N IBU
O R
D T 241 2
I S
D 30 8 1 n
Host Config Using Terminal

a
Service Networking Restart: Once user make changes in the server network configuration file, then it is
required to restart the server networking service in order to reflect the changes.

h
1 u s
Red Hat Enterprise Linux (RHEL 8.4)

4 e
Follow the below steps to set static IP in host
•

0 h l
ifconfig usb0 < Any IPv4 Link Local IP address > netmask 255.255.0.0 up

7 b a
i
• Service Networking Restart: Once the user makes changes in the server network configuration file, it is

1 t s
required to restart the server networking service in order to reflect the changes.

n i v
h a s h
s da
s a
291 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
Validation of IPMI over USB communication
Red Hat Linux

•
I S
For both GUI and Manual methods, verify BMC communication using the Static USB0 address “169.254.0.17”

1 n
Must be able to ping to the BMC via “usb0” IPv4 address from the host

D 30 8
•
•

h a
Must be able to launch the BMC WebUI using https://169.254.0.17 from the host
Copy the required Flash image and Yafutool into the host using pen drive, scp or winscp.
•

4 s
Must be able to flash, display existing firmware details using Yafuflash Tool.

1 u e
l
./Yafuflash -nw -ip 169.254.0.17 -u admin -p admin123 <image.ima> -info

70 i b h s a
1 n t i v
h a s h
s da
s a
292 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
Validation of IPMI Over USB on RHEL 8.4

h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h Validation of IPMI Over USB on Ubuntu 18.04

s da
s a
293 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1
Validation of IPMI Over USB on Windows Server 2019

n
a
Note: Ping response would be absorbed based on the PRJ configuration “Disable Ping Support”

4 h s
0 1 h u l e
1 7 t i b s a
a n h i v Disable Ping Support

h
s da s
s a
294 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 22

E -
Built-in Core Level "Thermal Management
Support"

T R E
in the server. O
N IBU T
Core level thermal management support is enabled in AST2500 and PILOT-IV. The Thermal Management
Module resides in BMC, which ensures that the appropriate temperature/heat level and airflow are maintained

AMI inbuilt thermal management supports the CRB platforms and are customizable to customer’s platforms.

O
amithermalconfig-src is CRB platform porting configuration. This package is required to be modified for other

R 2
CRB/Customer platform configuration.

D T 241
I S
Required Packages

D 30 8 1 n
Following lists of packages are required for this feature.

h a
Package Name
amithermalconfig-ARM-AST2600-ArcherCity-src Added
Added or Modified

s
Libamithermal-src Added

1 4
libthermal_core-src
thermalmgr-src

h u l e
Added
Added

0
libipmihalhw-src Modified
libipmihalapi-src

1 7 t i b s a Modified

n
PRJ Configuration

a h i v
The core level thermal management support has the following configurations. This feature can be enabled in
MDS.

h
s da s
MDS > Features Configuration > Thermal Management Support

s a
295 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU
Know Limitations/Issues
T Thermal Management Support

NA.
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
296 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 23

E -
T R
LAN and DRAM Test Support in U-boot

E
This feature enables to test LAN and memory functionalities from U-boot and will be helpful during system

T
bring up.

Required Packages
O
N IBU
Following lists of packages are required for this feature.

O R
D T 241
Package Name
@PLATFORM_ArcherCity-ANY

2
Bootloader_20XX_platform_archercity-src
Bootloader_20XX_Pristine-src
Bootloader_20XX_amiext-src
Modified
Modified
Modified
Modified
Added or Modified

I S
Bootloader_20XX_oem-src

D 30 8 1 n
Bootloader_20XX_Config-ARM-AST2600-ArcherCity-src
Modified
Modified

PRJ Configuration
h a
1 4 u s
Please follow the below screenshots to enable this feature.

e
70 b h a l
1 n t i i v s
h a s h
s da
s a LAN and DRAM Test Support in U-boot

297 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2 LAN and DRAM Test Support

N/A

I S
Known Limitations/Issues

D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
298 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 24

LLDP Support
E -
R
The full form of LLDP is Link Layer Discovery Protocol. It simplifies the deployment of access devices and
enhances endpoint mapping, troubleshooting and management. LLDP is an IEEE standard and hence it can be
used in multi-vendor networks (which is the case with most networks).

Required Packages
O T T E
N IBU
Following lists of packages are required for this feature.

Package Name Added or Modified

sys_lldp-src

O R
D T 241 2
lldpd_jessietargetoverride-ANY
sys_net_snmp-src
lldpd_bustertargetoverride-ANY
Added
Added
Related Package
Added

PRJ Configuration
I S
D 30 8 1 n
a
This feature can be configurable or enabled as given below in MDS for selected PRJ.

h
s
MDS > Feature Configuration > LLDP (Link Layer Discovery Protocol)

1 4 h u l e
70 i b s a
1 n t i v
h a s h
s da
s a
299 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

LLDP Support

Known Limitations/Issues
N/A

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
300 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 25

E -
Automation Engine Support in HTML5 using Web
UI

T R E
This feature is enabled in HTML5 Web UI. This feature allows creating Tasks & Events and uploading the

O T
Scripts. You can create the Tasks/schedule for different events. These created tasks are shown in Calendar View
on Dashboard page. You can upload the script by using upload option in Script screen. You can run/execute

N IBU
the existing scripts/newly uploaded script on Task creation/edit screen.

O
Required Packages

R
D T 241 2
Following lists of packages are required for this feature.

Package Name Added or Modified

Python26-ANY
I S
AutomationEngine-src

D 30 8 1
AutomationEngineScripts-src

n
Added
Added
Added
Python27-ANY
pyinstaller-ARM

h a Added
Added

s
python_bitstring-src Added

1 4
python_epydoc-ANY
python_txjsonrpc-src
sys_libsqlite3-src

h u l e
Added
Added
Added

70
sys_python_argparse-src

i b
sys_python_dateutil-src

s a
Added
Added

1 n
Python2716-ANY t
sys_python_twisted-src

i v
sys_python_zopeinterface-src
Added
Added
Added

h a
pyinstaller35-ARM

s h Added

s da
PRJ Configuration

s a
This feature can be configurable or enabled as follows in MDS for selected PRJ.
MDS-> Feature Configuration-> Automation Engine

301 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T Automation Engine Support

N/A O
Known Limitations/Issues

R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
302 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 26

E
Hardware Encryption Support
-
T R
Hardware Encryption support is enabled only for PILOT-IV.

E
Encryption is the process of encoding messages or information in such a way that only authorized parties can

T
read it. Encryption does not prevent interception by itself, but denies the message content to the interceptor.

O
Hardware Encryption:

N IBU
Hardware--board security to perform encryption and decryption. It is self-contained and does not require the
help of any additional software. Therefore, it is essentially free from the possibility of contamination, malicious

O
code infection, or vulnerability.

R
AMI OPENSSL Engine Info

D T 241 2
It’s a hardware independent engine and this engine directly sending command to /dev/enc and /dev/enc is
communicating with crypto hardware driver then the hardware driver is communicating with real crypto

I S
accelerator hardware.
Engine id: hwcrypto

D 30 8 1 n
h a
Engine Name: AMI Hardware Crypto Engine
Lib location: /lib/engines/libhwcrypto.so

1 4 u s
Note: If hardware crypto is not enabled in kernel, /dev/enc will work as software crypto only.

e
DTS and Kernel Configuration

70 b h
1. In aspeed-g6.dtsi file:

a l
1 t i
hace: hace@1e6d0000 {

n i v s
compatible = "aspeed,ast2600-hace";

a h
reg = <0x1e6d0000 0x200>;

h s
interrupts = <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>;

s da
clocks = <&syscon ASPEED_CLK_GATE_YCLK>;
clock-names = "yclk";
resets = <&syscon ASPEED_RESET_HACE>;

};

s a
status = "disabled";

303 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

acry: acry@1e6fa000 {
compatible = "aspeed,ast2600-acry";
reg = <0x1e6fa000 0x400 0x1e710000 0x1800>;
interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>;

E -
clocks = <&syscon ASPEED_CLK_GATE_RSACLK>;
clock-names = "rsaclk";
status = "disabled";
};

&hace {

T R
2. In ast2600evb_a1.dts file:

E
status = "okay";
};
&acry {
status = "okay";
O
N IBU T
};

O R
D T 241
3. Kernel config:
2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t
PRJ Configuration
i i v s Kernel Configuration

h a s h
Need to select Hardware Encryption Support in PRJ as shown below.

s da
s a
304 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E PRJ Configuration

O
N IBU T
Packages Used in AMI Crypto Engine Support

O
Kernel_5_Config-ARM-AST2600-AST2600EVB-src -> DTS and Kernel config changes

R 2
Kernel_5_ext-src -> ASPEED crypto hardware driver and /dev/enc driver layer patch

D T 241
openssl_V1_1_bustertargetoverride-ANY -> Used to add missing header file in target.

S
libcrypto-src -> generic AMI OPENSSL engine
Test apps:

I
D 30 8 1 n
cryptoapp-src -> Used to Verify /dev/enc helper driver is working or not.

a
h
Aesapp-src src -> Used to Verify OPENSSL AMI dynamic Engine

Known Limitations/Issues
N/A

1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
305 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 27

Multi-SOL Support
E -
R
Since IPMI v2.0 is released, Serial over LAN (SOL) is integrated into the part of IPMI specification. Serial over

T E
LAN provide a mechanism that enables the serial controller of managed system to be redirected over an IPMI
session over IP.

PRJ Configuration O
N IBU T
Multi-Sol feature provides the solution that you can activate the different SOL connection at same time

This feature can be configurable or enabled as follows in MDS for selected PRJ.

Ports
O R
D T 241 2
MDS -> Projection Configuration -> IPMI Configuration -> SOL Configuration -> Number of SOL Serial

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s PRJ Configuration

h a
External Super IO

s h
MDS -> Development Kits Configuration -> SOL and Serial Port Sharing Configuration -> SOL with

s da
s a
306 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T SOL and Serial Port Sharing Configuration

O
MDS -> IPMI configuration -> Enable IPMI SOL Support

R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l IPMI SOL Support

1 t i
Known Limitations/Issues

n i v s
The UART DMA feature is supported in AST2500/AST2530. While doing 100M data-transferring test, the

h a s h
UART DMA is enabled to reduce the data missing issue occurred. Depend on the SOC performance, the
Max Number of SOL connections are needed to be cautious and configured to reduce the data missing issue
occurred. In the 100M data-transferring test, the ast2530evb with three SOL connections are activated.

s da
s a
307 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 28

E -
T R
Precision Time Protocol IEEE 1588 Support

E
The Precision Time Protocol (PTP) is a protocol used to synchronize clocks throughout a computer network.

T
On a local area network, it achieves clock accuracy in the sub-microsecond range, making it suitable for

Required Packages O
measurement and control systems. PTP can be configured in BMC firmware using Legacy and HTML5 UI.

N IBU
Following lists of packages are required for this feature.

Libptpconf-src
O
libipmiamioemptp-src
libipmimsghndlr-src R
D T 241 2
Package Name
Added
Added
Modified
Added or Modified

ipmi_dev-src

libipmi-src
I S
libfeaturedefine-src

D 30 8 1 n
Modified
Modified
Modified
sys_ntpcfg-src

h a Modified

1 4
PRJ Configuration

u s e
Support

7 b h a l
This feature can be enabled in MDS by selecting Features Configuration -> Precision Time Protocol Server

0
1 n t i i v s
h a s h
s da
s a
308 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
Known Limitations/Issues
PRJ Configuration

O
For proper functionality NIC should support hardware time stamping. Software time stamping should be

R 2
enabled when NIC doesn’t support hardware time stamping. Eth tool present in BMC can be used to check

D T 241
whether NIC support hardware times stamping or not.
You must provide a hardware master clock or a software clock synchronized with NTP.

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
309 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 29

Boot Logo Support

E -
Required Packages
T R
Boot Logo Support displays logo on the screen when the HOST VGA feed is missing.

E
bootlogo-src
O T
Following lists of packages are required for this feature.

N IBU
Package Name
Added
Added or Modified

O
fbapp-src Added

2
Bootloader_20XX_Config-ARM-AST2600-ArcherCity-src Modified

R
D T 241
Bootloader_20XX_amiext-src Modified

I S
PRJ Configuration

D 30 8 1 n
This feature can be enabled as following the below mentioned procedure. The sample screenshots are displayed
below.

h a
1. Check the boot logo support.

1 4 u s
Features Configuration -> Boot Logo Support.

e
70 b h a l
1 n t i i v s
h a s h
s da
s a PRJ Configuration

310 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

2. Check the boot logo support.

Test Tools Configuration -> FB Test Tool

E -
T R E
O
N IBU T
3. Check the frame buffer driver support.
FB Test Tool

O R 2
Archercity Configuration -> Frame Buffer Driver Support.

D T 241
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s Frame Buffer Driver Support

a
4. The section to configure the image map will be displayed for configuration automatically in PRJ when

h s h
“Boot Logo Support” is enabled in PRJ.

s da
s a
311 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T Boot Logo Support

O
Known Limitations/Issues

R
D T 241 2
The feature will not show LOGO on the screen automatically when there is “NO HOST VIDEO” feed.
By default, BootLogo support is disabled. Please refer “MegaRAC SP-X - FP1 FP Firmware Release Document.
pdf ” for further details.

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
312 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 30

E -
HTML5 based SOL

T R E
SOL(Serial Over LAN) feature without IPMI on HTML5 with terminal-like interface for SPX.

Required Packages

O
N IBU T
Following lists of packages are required for this feature.

Package Name Added or Modified

O
webui_html5-13.176.0.0.0-src.spx Modified

R 2
spx_restservice-13.111.0.0.0-src.spx

D T 241
sol_agent-13.6.0.0.0-src.spx
mod_websocket-13.21.0.0.0-src.spx
libwebsocket-13.5.0.0.0-src.spx
Modified
Added
Modified
Added

I S
D 30
PRJ Configuration
8 1 n
h a
Select MDS -> Development Kits Configuration -> SOL and Serial Port Sharing Configuration. And then
choose SOL with External Super IO.

1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a PRJ Configuration

313 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Select MDS -> Web Configuration, and then choose HTML5 SOL Agent.

E -
T R E
O
N IBU T
Note:
O R
D T 241 2
HTML5 SOL Agent

sol.conf file which is part of sol_agent-src package will be used to support bit rate setting manually for HTML
SOL.

I S
D 30 8 1
As per design, the HTML5 SOL will refer to Bit-rate via IPMI sol info.

n
If IPMI SOL is in disabled mode, HTML5 SOL will set or get Bit-rate from sol.conf.

HTML SOL Enable

h a IPMI SOL Enable
IPMI bit rate
IPMI SOL Disable
HTML SOL bit rate (sol.conf)

1 4
HTML SOL Disable

u s e
IPMI bit rate No page displayed

Known Limitations/Issues

0 b h a l
It can't support full of ANSI/Vt100 code and only support single SOL.

7
1 n t i i v s
h a s h
s da
s a
314 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 31

E -
T R
Customization Logo Support for HTML5

E
This feature allows to do Logo and Copyright Override porting in JViewer, HTML5 and Legacy WebUI.

Required Packages

O
N IBU T
Following lists of packages are required for this feature.

Package Name Added or Modified

O
webui_html5-13.176.0.0.0-src.spx Modified

R
D T 241 2
spx_restservice-13.111.0.0.0-src.spx
liblogostatic-13.3.0.0.0-src.spx
Modified
Added

I
PRJ Configuration
S
D 30 8 1 n
Enable Logo and Copyright Override through MDS

a
The below steps explain you how to enable logo and copyright override feature.

h
s
1. Select Features Configuration > Dynamic change OEM logo and copyright files in SPX project

1 4
configuration option.

h u l e
70 i b s a
1 n t i v
h a s h
s da
s a PRJ Configuration

315 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Procedure To Change The Logo

1. ChangeWebBannerBackground.sh, ChangeWebBannerLeftImage.sh, ChangeWebBannerRightImage.sh
into fwmutility-x.x.x/ folder. You can find these files under your build path/software/liblogostatic-x.x.x-src.

ReplaceLogoUtils/.

E -
The fwmutility or ReplaceLogoUtils is in the buildpath/software/fwmutility-x.x.x/ or buildpath/software/

R
2. Copy spi image “rom.ima” inside fwmutility-x.x.x or ReplaceLogoUtils folder.
3. Open terminal and go to buildpath/software/fwmutility-x.x.x/ or buildpath/software/ReplaceLogoUtils/

T T E
folder and execute the commands as follows.
To Change Web UI banner left side image use below command

O
N IBU
• ./ ChangeWebBannerLeftImage.sh <path/to/ima> <path/to/new logo>
To Change Web UI banner right side image use below command
• ./ ChangeWebBannerRightImage.sh <path/to/ima> <path/to/ new logo>

O R 2
To Change Web UI JViewer’s / H5Viewer Logo image use below command
•

D T 241
./ ChangeJViewerLogo.sh <path/to/ima> <path/to/ new logo>

•
I S
D 30 8 1
Known Limitations/Issues

n
ReplaceLogo utility requires the replacement logo images of the exact size as of default logo images. The

• a
default logo image sizes are listed as following.

h
Left banner (h5banner_left.png) --- size should be 4553 bytes
•

4 s
Right banner (h5banner_right.png) --- size should be 4019 bytes

1 u e
•
•

0 b h a l
JViewer Logo (jviewerlogo.jpg) --- size should be 3280 bytes
As usual, MDS can always be used to replace the logos, as needed, in the firmware image.

7
•

1 t i s
ReplaceLogo utility works fine on Wolf Pass image with replacement images of a variable/different size.

n i v
h a s h
s da
s a
316 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 32

E -
BMC Version Format

T R E
We were supported only numbers in Major, Minor & Auxiliary version of the BMC. Now, Auxiliary version

T
alone supports in three types of format.
•
•
•
Decimal
Hexa-Decimal
String
O
N IBU
O
D T 241 2
In MDS, developer can add a new OemKeys in the PRJ file. The OemKey value should be "AuxFormat", and

R
add the format type in the newly exposed text field (AuxFormat). The format type should be decimal, hexa and
string to represent the respective format.
The range for each format is listed below.
•
•
I S
Decimal - It should be number alone and the range is between 0 and 4294967295

D 30 8 1 n
Hexa-Decimal - It should be 8 characters(0-9, a-f) and the range is between 0 and 0xFFFFFFFF
•
a
String - It should be 4 characters(0-9, a-z)

hs
.

1 4 h u l e
70 i b s a
1 n t i v
h a s h
s da
s a BMC Version Format

317 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T
O R
D T 241 2
Auxiliary Version Format

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
318 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 33

E -
T R
AST2620 SOC Build Guide

E
There is no VGA support in AST2620 SOC. We need to disable the Video related support in our LTS-v13 stack

T
for the AST2620 Build. Below are the steps to disable the Video related support in PRJ file.

PRJ Configuration
O
N IBU
Disable Video Related Support through MDS

O
1. Select KVM Configuration and deselect the Video Library, Auto Video Recording Support, Extended

2
Privilege Support, Java KVM Client Support, JViewer Folder Redirection Support, VMedia Support

R
D T 241
for Linux 32-bit Clients, VMedia Support for Linux 64-bit Clients, VMedia Support for Mac 64-bit
Clients, VMedia Support for Windows 32-bit Clients, and VMedia Support for Windows 64-bit Clients.

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s KVM Configuration
2. Select Device Configuration and deselect the Video Device Support.

h a s h
s da
s a
319 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
O
N IBU T Device Configuration

O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
320 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

CHAPTER 34

E -
T R
Enable/Disable TCP Socket

E
Yafuflash Flasher utility is used to connect BMC at TCP Socket on IPMI Port 623. TCP Socket on IPMI Port

T
623 is open and available even when client does not require to connect BMC at TCP Port 623. If Yafuflash

O
utility is not required, then TCP Socket can be disabled at Port 623. We have implemented hidden PRJ option
“FEATURE_DISABLE_TCP_SOCKET” to enable/disable TCP Socket but not available as PRJ configurable.

N IBU
Please follow below steps to Enable/Disable TCP Socket on Port 623.

Enable TCP Socket

O R
D T 241 2
To enable TCP Socket on Port 623, modify default parameter value to “n” under section “config FEATURE_
DISABLE_TCP_SOCKET” in P.CONFIG file (File location: libipmilan-src/spx/P.CONFIG, libipmilan-src/
spx/PACKAGES.D/libipmilan/P.CONFIG) as shown in the below screenshot.

I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t
Disable TCP Socketi i v s Enable TCP Socket P.Config

h a s h
To disable TCP Socket on Port 623, modify default parameter value to “y” under section “config FEATURE_
DISABLE_TCP_SOCKET” in P.CONFIG file (File location: libipmilan-src/spx/P.CONFIG, libipmilan-src/

s da
spx/PACKAGES.D/libipmilan/P.CONFIG) as shown in the below screenshot.

s a
321 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

E -
T R E
Disable TCP Socket P.Config

O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
322 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

APPENDIX

Ports Usage
E -
Port #

T R
Owner Module

E
Usage

80

443 O
N IBU T
Web server (lighttpd)

Web server (lighttpd)

Listening for network connections on HTTP://

Listening for secured network connections on HTTPS://

22

23 O R
D T 241
Secure Shell (sshd)

2
Telnet
Secure SMASH-Lite session

Telnet session

S
5120 CD Media Server To accept regular CD media redirection connections

5124

7582
I
D 30 8 1 a n
CD Media Server

KVM server (adviser)

To accept secular (SSL based) CD media redirection
connections

To accept secure (SSL based) KVM redirection connections

623

4 h
IPMI
s LAN interface

1900

0 1 h u l e
uPnP discovery Used for uPnP based BMC discovery

49152

1 7 t i b s a
uPnP discovery Used for uPnP based BMC discovery

427

a n i
SLPD

h v Service Locater

123

161
h
s da sNTP

SNMP
Network Time Protocol (NTP) - used for time
synchronization (UDP Connection)

SNMP listens on this port for incoming SNMP requests.

a
(UDP)

199
s SNMP
SNMP listens on this port for incoming connect requests
(from the SMUX peers and various other TCP end-points
connected to SMUX peers to exchange SMUX PDUs)

323 Software R&D DPG

MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

DHCPv6 clients listen for DHCP messages on this port

546 DHCPv6
(UDP)

7578 KVM Server (Adviser) To accept regular KVM redirection connections

E -
T R E
O
N IBU T
O R
D T 241 2
I S
D 30 8 1 n
h a
1 4 u s e
70 b h a l
1 n t i i v s
h a s h
s da
s a
324 Software R&D DPG
MegaRAC® SP-X-Developer’s Guide
Copyright © American Megatrends International LLC

Index Package Configuration 105

Package Naming Format 95
Package Selection 105
Prerequisites 120
A
S

E -
Alternate Package Selection 106
Auto Video Recording Configuration 67
Signing Jar Files 197
Source Package 94
SPX packages’ repository 112
System Package 94

R
Binary Package 95
Build Mechanism 113 T

T E
C Tools Package 95

Control Section 97

D
Data Section 96
Debug Package 95 O
N IBU
Development Package 95
T
F
File Types 105

O R
D T 241
Format of BUGS 103
Format of BUILDCONFIG 104
Format of DEFCONFIG 103
2
S
Format of FILES 102

I
Format of LICENSES 102

Format of P.CONFIG 103

D 30 8 1
Format of PACKAGES.D (Source Packages Only) 103

a n
Format of RULES and RULES.D 104
Format of SCRIPTS 103

4
Information Package 95
hs
K

0 1 h u
KVM Default Configuration 68

l e
L

1 7 t i b s
Library Package Creation 136 a
M

a n
Macros for Rules 104

h i v
h s
Makefile 120
MDS SPX package creator 121

s da
MEGARAC SP-X 11

s a
Notes on Depends & Required 99
Notes on Group 100
Notes on Source Entries 99

325 Software R&D DPG