API Reference: Libraries

Top

# kontron_ktus

#### NAME

> kontron_ktus - Kontron KTUS15/mITX Atom Z5x0 based board

#### INTRODUCTION

> This reference entry provides board-specific information necessary to run VxWorks for the Kontron KTUS15/mITX 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.

> Symmetric I/O Mode is not supported with this BSP as VxWorks doesn't support HyperThreading technology (available with Z530 only).

#### Jumpers & Switches

> Please refer to the board vendor's documentation.

#### 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 KTUS15/mITX
>             Version: VxWorks 6.8
>             BSP version: R00.00
>             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
>          1 /tyCo/2
>          1 /tyCo/3
>          3 /ata0a
>          6 bootHost:
>          3 /ahci00:1
>          3 /bd0

>             [VxWorks Boot]: ?

> You will see some information as following:

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

>            Boot Flags:
>              0x02 -   load local system symbols
>              0x04 -   don't autoboot
>              0x08 -   quick autoboot (no countdown)
>              0x80 -   use tftp to get boot image

>            Available Boot Devices:
>              Filesystem Devices:  /ata0a /ahci00:1 /bd0  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_JMICRON_AHCI or INCLUDE_ATA(can't enable both).
> 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
>               2 /tyCo/0
>               2 /tyCo/1
>               4 /ahci00:1
>               5 /ahci00:2
>               5 /ahci00:3
>               5 /ahci00:4
>               6 /bd0
>               host:
>               10 /vio

> 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

>            Device Formats:
>              boot device: ahci[=ctrl,drive]    file name: /ahci00:1/vxWorks
>              boot device: usb                  file name: /bdx/vxWorks

>            Boot Flags:
>              0x02 -   load local system symbols
>              0x04 -   don't autoboot
>              0x08 -   quick autoboot (no countdown)
>              0x80 -   use tftp to get boot image

>            Available Boot Devices:
>              Filesystem Devices:  /ahci00:1 /bd0
>              Enhanced Network Devices:
>            [VxWorks Boot]:

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

#### 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 | PCIe | vxbNs16550Sio.c | SUPPORTED
> 1GB-ETHERNET:0 | PCIe | gei825xxVxbEnd.c | SUPPORTED
> SATA | on-chip | vxbIntelAhciStorageK.c | SUPPORTED
> PATA | on-chip | ataDrvK.c | SUPPORTED
> GRAPHICS | on-chip | vxbM6845Vga.c | SUPPORTED
> PS2 | on-chip | vxbI8042KbdK.c | SUPPORTED
> TIMER | on-chip | vxbI8253Timer.c | SUPPORTED
> RTC | on-chip | vxbMc146818RtcK.c | SUPPORTED
> GPIO/thermal sensors | on-chip | vxbW83627dhgK.c | SUPPORTED
> USB2-HOST | on-chip | USB EHCI driver | SUPPORTED
> USB2-DEVICE | on-chip | n/a | UNSUPPORTED
> USB1-HOST | on-chip | n/a | UNSUPPORTED
> SD/MMC-CARD | on-chip | n/a | UNSUPPORTED
> VIDEO-DECODE | 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.

#### HARDWARE DETAILS

> This section documents the details of the hardware elements.

#### Memory Maps

> The following table describes the Atom default memory map.

> Start | Size | End | Access to
> --- | --- | --- | ---
> 0x0000_0000 | 640k | 0x0009_FFFF | lower memory
> 0x000A_0000 | 128k | 0x000B_FFFF | Flat videobuffer
> 0x000C_0000 | 128k | 0x000D_FFFF | Expansion area
> 0x000E_0000 | 64k | 0x000E_FFFF | Extended BIOS (LPC)
> 0x000F_0000 | 64k | 0x000F_FFFF | BIOS (LPC)
> 0x0010_0000 | 2G-1M | sysPhysMemTop( ) - 0x100000 | upper memory
> 0x8000_0000 | 2G | 0xFFFF_FFFF | PCI memory
> Check Intel(R) System Controller Hub documentation (doc id # 319537) for more details.

#### Network Configuration

> This BSP provides support for VxBus drivers, including network drivers. The list of VxBus network drivers available for PCIe devices includes the following:

>         INCLUDE_FEI8255X_VXB_END
>         INCLUDE_GEI825XX_VXB_END
>         INCLUDE_RTL8169_VXB_END
>         INCLUDE_END

> For command line builds and for building bootrom, the config.h file must be modified to define above macros, corresponding to the desired driver.

#### PC_CONSOLE

> This function will use PC monitor as VxWorks console. To use these controllers the INCLUDE_PC_CONSOLE directive must be enabled in config.h. Only PS2 keyboard is supported.

#### HAL driver

> This component (DRV_MULTI_HAL) serves as an abstraction layer to obtain hardware specific information about the board in use.

#### ataDrvK and ataShow

> Driver for the IDE/ATA hard disk controller. To use this driver, the INCLUDE_ATA directive must be enabled in config.h. Note that the old INCLUDE_IDE directive is replaced by INCLUDE_ATA.

#### vxbIntelAhciStorageK

> Vxbus Driver for the SATA hard disk controller. To use this driver, the DRV_STORAGE_JMICRON_AHCI must be enabled in config.h.

#### 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.

#### vxbMc146818RtcK

> This is the additional driver for the real time clock, it supports Get/Set current date/time functions. To use RTC as a timer, default RTC driver (DRV_TIMER_MC146818) should be applied.

#### vxbW83627dhgK

> This component includes W83627 sensor driver.

#### 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 controller is 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)
> ata0a | - ATA/IDE drive
> ahci00:1 | - SATA Hard disk
> usb | - USB disk

#### 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

#### 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