API Reference: Libraries

Top

# MSMST

#### NAME

> MSMST - Kontron MSMST target specific documentation

#### INTRODUCTION

> This board support package (BSP) is designed to run on the Kontron MSMST boards.

> This reference entry provides board-specific information necessary to run VxWorks for the Kontron MSMST BSP. Before using a board with VxWorks, verify that the board runs in the factory configuration by using vendor-supplied ROMs and jumper settings and checking the RS-232 connection.

> This BSP doesn't support Symmetric Multiprocessing (SMP).

#### System Requirements for release R01.00

> BIOS:
> - Save & Exit -> Restore Defaults
> - Save & Exit -> Save Changes
> - Advanced -> Launch PXE OpROM: Enabled
> - Save & Exit -> Save Changes and Reset
> The network will be used by default in this case.

#### Jumpers & Switches

> Please refer to the board vendor's documentation.

#### BOOT PROCESS

> The target board is capable of booting from the onboard Ethernet adapters (PXE) or SATA hard disk drives.

#### Booting a Romable Image from a Disk Device

> In the standard configuration the BIOS loads and executes the bootstrap loader located in the boot sector of a hard disk. The VxWorks bootstrap loader looks for the bootrom.sys file, loads it into memory, and transfers execution to it.

#### Booting a VxWorks Image using the boot loader

> Booting is normally a two step process during development. In the first step, the VxWorks boot loader is started. In the second step, the VxWorks image is loaded and started by the boot loader. In the table below you can find the boot devices which are supported. Note that not all boot devices are included in the default configuration.

> Boot device | Description
> --- | ---
> gei0 | Gigabit Ethernet Interface
> ata[=x,x] | SATA Disk Device

#### SUPPORTED IMAGES

> The BSP support the following images.

> Image Name | Description | Built in | Device | Compressed | Loads Into
> --- | --- | --- | --- | --- | ---
> bootrom.bin | bootrom | IDE/BSP | Disk | Yes | High Memory
> bootrom.pxe | bootrom | IDE/BSP | Net | Yes | High Memory
> vxWorks | loadable VxWorks | IDE | Net/Disk | No | Low Memory

> (The binary images *.bin are used for creation of the appropriate bootrom.sys file)

> To build a boot loader or a VxWorks image you should use the Wind River Workbench. If the default configuration is not appropriate for your application you can change it by editing the file config.h in the BSP directory (for the boot loader) or with help of the Wind River Workbench (for VxWorks image).

> For instructions on how to configure and compile a bootable image from the Wind River Workbench see Wind River Workbench User's Guide: Projects. ( Please keep in mind that Low Memory boot images are limited to approximately 640KB in size due to the constraints of the processor running in real mode.)

> The configuration of the boot loader can only be changed by modifying the file config.h in the BSP directory.

#### PREPARING A BOOT DEVICE

#### Getting the board running VxWorks

> When the board is powered on, the system BIOS code loads and executes the bootstrap loader. The bootstrap loader is written in 8088 16-bit assembly language. The BIOS obtains the bootstrap loader from the boot sector, which may be in one of several locations: an USB 2.0 key, a hard disk, or some other alternatives. When the BIOS finds the bootstrap loader, it transfers execution to it. The bootstrap loader finds the bootrom.sys file, loads it into memory, and transfers execution to romInit.

> 1. Make bootable USB key

> 1) Creating a bootrom image.
> Create VxWorks "System Image" project with PROFILE_BOOTAPP profile.
> Choose "default_RomCompress" as active build specification and build vxWorks_romCompress.bin.BIN file.

> 2) Make boot device.
> Download free software mkbt20 from ftp://dl.xs4all.nl/pub/mirror/nu2files/mkbt20.zip,
> or http://ftp.rz.tu-bs.de/pub/mirror/www.nu2.nu/nu2files/mkbt20.zip and extract it to
> BSP directory, Insert an USB 2.0 key to PC (USB 1.x key is not supported), format it
> to FAT file system. (assume the drive name is g:),
> also in the BSP directory run the following command:

>             mkbt -x bootsect.bin g:

> Following information will be shown :

>             * Expert mode (-x)
>             * Warning different filesystem ID
>             Size=0bytes OEM="MSDOS5.0" VolLabel="NO NAME" FileSys="FAT16"

> Then run this command to copy the generated bootrom.bin to the USB key.

>             copy vxWorks_romCompress.bin g:bootrom.sys

> Insert the USB key to Atom board and reset. Change the BIOS setting to
> boot from the USB. After the VxWorks bootrom boots up, you will see following:

>                                 VxWorks System Boot

>             Copyright 1984-2008  Wind River Systems, Inc.

>             CPU:  Kontron MSMST
>             Version: VxWorks 6.8
>             BSP version: R00.00 (prototype)
>             Creation date: Aug 11 2010, 10:12:59

>             Press any key to stop auto-boot...

>             [VxWorks Boot]:

> If you want to boot vxWorks image from usb key, enable INCLUDE_USB
> in config.h (default is enable), re-make the bootrom and copy vxWorks image to
> USB key.
> When bootrom boot up it can enumerate out the USB key, sometimes you need to
> plug out and plug in it again, because of some USB key's compatibility isn't good.
> Enter following command in VxWorks Boot Shell,

>             [VxWorks Boot]: devs

> You will see following:

>         drv name
>          0 /null
>          1 /tyCo/0
>          1 /tyCo/1
>          6 host:
>          4 /s0p1:1
>          3 /s0p1:2
>          4 /s0p1:3
>          4 /s0p1:4
>          4 /s0p1:5
>          4 /s0p1:6
>          4 /s0p1:7

>             [VxWorks Boot]: ?

> You will see some information as following:

>                File System Boot Device Formats:
>                      boot device: fs
>              file name: /FileSystemDeviceName/vxWorks
>              other: network device name

>              boot device: usb                      file name: /bdx/vxWorks

>            Boot Flags:
>              0x0002 -   load local system symbols
>              0x0004 -   don't autoboot
>              0x0008 -   quick autoboot (no countdown)
>              0x0080 -   use tftp to get boot image

>            Available Boot Devices:
>              Filesystem Devices: /s0p1:1  bd0
>              Enhanced Network Devices:  gei0

>            [VxWorks Boot]:

> The "/bd0" shows vxWorks bootrom found the USB key, Then enter c command in
> VxWorks Boot Shell to change boot device to "usb", file name to "/bd0/vxWorks",
> save it. Finally, enter @ command to start vxWorks image, and you'll see vxWorks
> shell.

> 2. Make bootable hard disk
> There are two ways to make the bootable hard disk.

> 1) Connect hard disk to PC through IDE to USB convertor or by other ways,
> Format a partition less than 2GB to FAT file system, assume the drive name is g:,
> then followed the same steps of make bootable USB key.

> 2) Boot VxWorks by network and type some commands in the target shell.
> a. Start Workbench 3.1.
> b. Create a VxWorks Image Project, Include the following components
> through the Kernel Configuration window:
> DRV_STORAGE_SI31XX,
> INCLUDE_XBD, INCLUDE_XBD_BLK_DEV, INCLUDE_XBD_PART_LIB, INCLUDE_XBD_RAMDRV.
> INCLUDE_DOSFS.
> INCLUDE_FS_MONITOR.
> Other optional components such as, INCLUDE_SHELL, etc.
> c. Import the file mkboot.c (in the BSP directory)
> d. Build the project to create the vxWorks image. This image has the
> tools to partition and format disk.
> e. Load the generated vxWorks image into the target
> f. From the target shell prompt, enter the command:

>              -> xbdCreatePartition  "/ahci00", 4, 33, 33, 33

> Note: Any bootable hard disk partition should not exceed 2 GB. The
> parameters "4, 33, 33, 33" specifies that there should be 4
> partitions, part0, part1, part2, part3. The partitions part1, 2,
> and 3 are created with "33 percent" of the disk capacity and the
> rest would be allocated to part0. The command does not specify the
> amount of the first partition size.

> With a 80GB drive. The above command creates 4 partitions, the
> last of partitions with sizes of 33%, 33%, 33% respectively. The
> bootable partition gets 1% (i.e. 100 minus 33 minus 33 minus 33 = 1%),
> which is less than 2GB on a 80 GB hard disk.

> g. From the target shell prompt, enter the command:

>               ->devs
>               drv name
>               0 /null
>               1 /tyCo/0
>               1 /tyCo/1
>               6 host:
>               4 /s0p1:1
>               3 /s0p1:2
>               4 /s0p1:3
>               4 /s0p1:4
>               4 /s0p1:5
>               4 /s0p1:6
>               4 /s0p1:7

> h. Each of the partitions that begin with "/ahciXXX", execute the command
> "dosFsVolFormat" command:

>              -> dosFsVolFormat "/ahci00:1"
>              -> dosFsVolFormat "/ahci00:2"
>              -> dosFsVolFormat "/ahci00:3"
>              -> dosFsVolFormat "/ahci00:4"

> i. Now, execute a command to transfer the Master Boot Record and
> bootrom.sys to the just formatted hard drive partition: (assuming
> that the hard drive is connected to the controller 0 and the drive is
> 0, then do the following.

>              -> cp "/bd0/bootrom.sys","/ahci00:1"
>              -> mkMbrAhci 0, 0

> j. Make the bootable hard drive.

>             -> cd "/ahci00:1"
>             -> mkbootAhci 0, 0, "bootrom.sys"

> k. Reboot the target board, change the BIOS settings to boot from the hard disk.

> If you want to boot vxWorks image from hard disk, #define INCLUDE_BOOT_ATA_LOADER
> in config.h and re-make the bootrom and copy vxWorks to hard disk.
> When vxWorks bootrom boot up, enter '?'command in VxWorks Boot Shell.
> you will see

>                File System Boot Device Formats:
>                      boot device: fs
>              file name: /FileSystemDeviceName/vxWorks
>              other: network device name

>              boot device: usb                      file name: /bdx/vxWorks

>            Boot Flags:
>              0x0002 -   load local system symbols
>              0x0004 -   don't autoboot
>              0x0008 -   quick autoboot (no countdown)
>              0x0080 -   use tftp to get boot image

>            Available Boot Devices:
>              Filesystem Devices: /s0p1:1  bd0
>              Enhanced Network Devices:  gei0

>            [VxWorks Boot]:

> The available boot device shows "s0p1:1", we used c command to change
> boot device to "ahci00:1", file name to "/s0p1:1/vxWorks",save it, and use @
> command to load vxWorks image, and you'll see vxWorks shell.

#### HARDWARE DETAILS

> For a detailed description of the hardware features and configuration options available please refer to the target board Hardware User's Guide.

#### FEATURES

> This section describes all features of the board, supported or not. It documents all configurations of the board and the interaction between features and configuration items.

> List of Hardware Features

>   Hardware Interface | Controller | Driver/Component | Status
>   --- | --- | --- | ---
>   UART:0 | external | VxWorks 6.8 standard | SUPPORTED
>   1GB-ETHERNET | on-chip | INCLUDE_GEI825XX_VXB_END | SUPPORTED
>   SATA | on-chip | DRV_STORAGE_SI31XX | SUPPORTED
>   VGA console | on-chip | VxWorks 6.8 standard | SUPPORTED
>   USB Keyboard | on-chip | VxWorks 6.8 standard | unstable
>   TIMER | on-chip | VxWorks 6.8 standard | SUPPORTED
>   RTC | on-chip | VxWorks 6.8 standard | SUPPORTED
>   USB2-HOST | on-chip | n/a | UNSUPPORTED
>   USB2-HOST | on-chip | n/a | UNSUPPORTED
>   SD/MMC-CARD | on-chip | n/a | UNSUPPORTED
>   AUDIO | on-chip | n/a | UNSUPPORTED
>   LPC | on-chip | n/a | UNSUPPORTED

> Feature Interactions

>   Refer to the board vendor's documentation.

#### BSP Library

> There are different functional components additionally provided to configure this BSP. The components can be included into the VxWorks image either with help of the Wind River Workbench project facility (recommended) or by changing macro definitions in the file config.h.

> The components described below utilize the drivers which are delivered as a part of the BSP library, but also the standard drivers which are provided in the VxWorks installation.

> For more information on supported functions of the different components please follow the link to the online documentation.

> INCLUDE_PC_CONSOLE

>   This function will use VGA monitor and USB keyboard as VxWorks console.

>   USB keyboards be used. To initialize the USB stack and attach a USB keyboard to the PC console, the macro PC_KBD_TYPE must be set to USB_KBD. This macro definition can be found in the file config.h. USB legacy support must be disabled in BIOS setup.

>   NOTE: enabling INCLUDE_PC_CONSOLE in bootloader still causes unstable behaviour
>   it is recommended to use it only for VxWorks image.

>   The default setting of the serial interface (independent of including PC console) is 115200 baud, 8 data bits, 1 stop bit, no parity and no flow control.

> DRV_STORAGE_SI31XX

>   This component includes SATA host controller driver.

> vxbI8253Timer

>   This library contains a board-independent interface for manipulating the timer functions on Intel 8253 and compatible timer chip devices. Timer 0 is used as system clock, According to different applications, timer 1,2 has different usage.

> vxbIntelTimestamp

>   This is the driver for the timestamp on Intel chipsets to use the timestamp feature, the macro INCLUDE_TIMESTAMP must be defined in config.h.

> i8259Intr

>   Driver for the Intel 8259A Programmable Interrupt Controller (PIC). IRQs 0 - 7 are handled by PIC1 and IRQs 8 - 15 by PIC2. PIC2 interrupts are cascaded into PIC1 at IRQ2 .The Fully Nested Mode is used in the default configuration of this BSP.

> USB Host Support

>   A standard USB EHCI and OHCI controllers are supported in this BSP. Please refer to Wind River's USB documents.

> Boot Devices

>   The supported boot devices are:

>   gei0 | - Primary Ethernet (10baseT, 100baseTX, or 1000baseT)
>   s0p0:1 | - SATA Hard disk
>   usb | - USB disk (unsupported, BIOS can download bootrom.sys)

> Boot Methods

>   The boot methods are affected by the boot parameters. If no password is specified, RSH (remote shell) protocol is used. If a password is specified, FTP protocol is used, or, if the flag is set to 0x80, TFTP protocol is used.

#### SPECIAL CONSIDERATIONS

#### Make Targets

> The make targets are listed as the names of object-format files. Other images not listed here may not be tested.

> bootrom
> bootrom.bin
> vxWorks (with vxWorks.sym)
> vxWorks.st

#### BSP Bootloaders and Bootroms

> Bootloader/Bootrom | Status
> --- | ---
> BIOS (pre-flashed) | SUPPORTED
> bootrom | SUPPORTED
> bootrom_uncmp | UNSUPPORTED
> vxWorks | SUPPORTED
> vxWorks_rom | UNSUPPORTED
> vxWorks_romCompress | UNSUPPORTED
> vxWorks_romResident | UNSUPPORTED

#### BSP Validated Tools

> Tool | Connection/Type | Status
> --- | --- | ---
> Workbench Debugger | ETHERNET/WDB | SUPPORTED
> Workbench System Viewer | ETHERNET/WDB | SUPPORTED
> Workbench MemScope | ETHERNET/WDB | SUPPORTED
> Workbench ProfileScope | ETHERNET/WDB | SUPPORTED
> Workbench StethoScope | ETHERNET/WDB | SUPPORTED
> Workbench CoverageScope | ETHERNET/WDB | SUPPORTED
> Workbench Core File Analysis | ETHERNET/WDB | UNVALIDATED
> Workbench Sensor Points | ETHERNET/WDB | UNVALIDATED
> Workbench OCD Debugger | JTAG | UNSUPPORTED
> Workbench OCD Flash | JTAG | UNSUPPORTED

#### Special Routines

> The following routines are specific to this BSP and are available to the user. They are written in assembly code in sysALib.s. For further details, please refer to following entries:

> sysInByte( ) | input one byte from I/O space
> sysInWord( ) | input one word from I/O space
> sysInLong( ) | input one long-word from I/O space
> sysOutByte( ) | output one byte to I/O space
> sysOutWord( ) | output one word to I/O space
> sysOutLong( ) | output one long-word to I/O space
> sysInWordString( ) | input word string from I/O space
> sysInLongString( ) | input long string from I/O space
> sysOutWordString( ) | output word string to I/O space
> sysOutLongString( ) | output long string to I/O space

#### KNOWN PROBLEMS and LIMITATIONS

> USB is not supported

#### BIBLIOGRAPHY

> Intel Architecture Software Developer's Manual, Volume 1: Basic Architecture

> Intel Architecture Software Developer's Manual, Volume 2: Instruction Set Reference

> Intel Architecture Software Developer's Manual, Volume 3: System Programming Guide

> AP-485, Intel Processor Identification and the CPUID Instruction

> PCI System Architecture, Fourth Edition, Addison-Wesley, 1999, ISBN 0-201-30974-2

#### SEE ALSO

> VxWorks User's Guide: Getting Started, VxWorks Programmer's Guide: Configuration, VxWorks Programmer's Guide: Architecture Supplement