DM816x AM389x PSP User Guide

DM816x AM389x PSP User Guide

Linux PSP

IMPORTANT

DM816x refers to DM816x/AM389x devices unless specified.
DM814x refers to DM814x/AM387x devices unless specified.
DM81xx refers to both DM816x, DM814x and DM813x.

Read This First

• The parameter passed to mkfs.jffs2 while creating JFFS2 image has changed, please refer "Creating JFFS2 File-system" section under "U-Boot NAND Support" in U-Boot User Guide.
• The steps for flashing jffs2 image to NAND from U-Boot has changed, please refer "Flashing File-system from U-Boot" section under "U-Boot NAND Support" in U-Boot User Guide.

In addition, note following changes applicable for release 04.00.00.09 onwards:

• The kernel NAND driver uses 1-bit h/w ECC and U-Boot is also updated accordingly. So it is mandatory to re-flash the latest U-Boot along with kernel and filesystem (if using NAND based kernel and/or filesystem) before proceeding to boot the kernel.
  
• The serial console device names to be used are changed from 'ttySx' to 'ttyOx'. This means you will need to change the boot arguments passed to kernel and the /etc/inittab file in the filesystem accordingly. Please refer Using The Correct Console Device section.
  
• The kernel in release will not boot with U-Boot from release(s) earlier to 04.00.00.06, unless 'machid' environment variable is set correctly. Please refer Setting up Machine ID section for more details.
  
• You might need to update the DHCP script in your filesystem when using network mounted root filesystem with the kernel from this release. Please refer Updating the DHCP Script section.
  
• HDVPSS binaries are no longer packaged with release tar ball, instead they can be downloaded from the PSP Software Download page

About this Manual

This document describes how to install and work with Texas Instruments' Platform Support Package (PSP) for the DM8168/AM389x platform. This PSP provides a fundamental software platform for development, deployment and execution on DM8168 EVM with daughter card (for second instance Ethernet port and NOR). It abstracts the functionality provided by the hardware. The product forms the basis for all application development on this platform.

In this context, the document contains instructions to:

• Install the release
• Build the sources contained in the release

The document also provides detailed description of drivers and modules specific to this platform - as implemented in the PSP.

Important
This release has been tested on DM8168/AM389x EVM (Base board + daughter card required to verify second Ethernet port and NOR)

Installation

Prerequisites

Before you begin with the installation of the package please make sure you have met the following system requirements:

• Windows machine
• Host machine running a version of Linux such as RedHat Enterprise Linux or Ubuntu.
• DM8168/AM389x EVM

The Windows machine is used for running CCSv4/v5, which will be used to build flash writers and also to burn the boot images (U-Boot) onto the flash using the flash writers provided.

The Linux host is used for the following:

• Recompiling U-Boot and the Linux kernel.
• Hosting the NFS server to boot the EVM with NFS as root filesystem

You can use either the Windows machine or the Linux host for

• Hosting the TFTP server required for downloading kernel and file system images from U-Boot using Ethernet.
• Running a serial console terminal application

Software Overview

To begin developing applications, you need to install PSP package and the toolchain.

Package Contents

Important
The values of MM, mm, pp and bb in this illustration will vary across the releases and actually depends on individual component versions

Extract the contents of release package on your Linux host with the following command:

$ tar -xvzf  TI816x-LINUX-PSP-MM.mm.pp.bb.tgz

This creates a directory TI816x-LINUX-PSP-MM.mm.pp.bb with the following contents:

\---TI816x-LINUX-PSP-MM.mm.pp.bb
 |----TI816xPSP_Software_Manifest.doc
 +----docs
 |    |----DM816x_AM389x_PSP_Flashing_Tools_Guide.pdf
 |    |----DM816x_AM389x_PSP_U-Boot.pdf
 |    |----DM81xx_AM38xx_PSP_NOR_Driver_Guide.pdf
 |    |----DM81xx_AM38xx_PSP_McSPI_Driver_Guide.pdf
 |    |----DM81xx_AM38xx_Audio_Driver_User_Guide.pdf
 |    |----DM81xx_AM38xx_EDMA_Driver_User_Guide.pdf
 |    |----DM816x_AM389x_VPSS_Video_Driver_User_Guide_PSP_MM.mm.pp.bb.pdf
 |    |----DM816x_AM389x_HDMI_User_Guide.pdf
 |    |----DM816x_AM389x_AVS_User_Guide.pdf
 |    |----DM816x_AM389x_PSP_EMAC_Boot.pdf
 |    |----DM81xx_AM38xx_PSP_MMC_SD_Support.pdf
 |    |----DM81xx_AM38xx_PCI_Express_Root_Complex_Driver_User_Guide.pdf
 |    |----DM81xx_AM38xx_PCI_Express_Endpoint_Boot_Driver_User_Guide.pdf
 |    |----DM81xx_AM38xx_PSP_WDT_Support.pdf
 |    |----DM81xx_AM38xx_USB_User_Guide.pdf
 |    |----DM816x_AM389x_PSP_MM.mm.pp.bb_Release_Notes.pdf
 |    |----DM816x_AM389x_PSP_User_Guide.pdf
 |    |----DM816x_AM389x_PSP_MM.mm.pp.bb_Feature_Performance_Guide.pdf
 +----host-tools
 |    |----nand-flash-writer.out
 |    |----norflash-writer.out
 |    |----spi-flash-writer.out
 |    |----mksd-ti816x.sh
 |    |----DM816x.gel
 |    +----src
 |    |    |----nandflash-MM.mm.pp.bb.tar.gz
 |    |    |----norflash-MM.mm.pp.bb.tar.gz
 |    |    |----spiflash-MM.mm.pp.bb.tar.gz
 +----images
 |    +----kernel
 |    |    +----ti816x
 |    |    |    |----uImage
 |    +----u-boot
 |    |    |----ti816x
 |    |    |    |----u-boot.bin
 |    |    |    |----u-boot.noxip.bin
 |    |    |    |----MLO
 |    +----examples
 |    |    |----pcie
 |    |    |    |----boot.scr
 |    |    |    |----saBootApp
 +----src
 |    +----kernel
 |    |    |----ChangeLog-MM.mm.pp.bb
 |    |    |----diffstat-MM.mm.pp.bb
 |    |    |----kernel-patches-MM.mm.pp.bb.tar.gz
 |    |    |----linux-MM.mm.pp.bb.tar.gz
 |    |    |----ShortLog
 |    |    |----Unified-patch-MM.mm.pp.bb.gz
 |    +----u-boot
 |    |    |----ChangeLog-MM.mm.pp.bb
 |    |    |----diffstat-MM.mm.pp.bb
 |    |    |----ShortLog
 |    |    |----u-boot-patches-MM.mm.pp.bb.tar.gz
 |    |    |----u-boot-MM.mm.pp.bb.tar.gz
 |    |    |----Unified-patch-MM.mm.pp.bb.gz
 |    +----examples
 |    |    |----examples.tar.gz
 |    |    |----pcie
 |    |    |    |----bootscript.txt
 |    |    |    |----saBootApp.c
 |    |    |    |----Makefile
 |    |    |    |----README
 |    |    |----watchdog
 |    |    |    |----Makefile
 |    |    |    |----saWatchdog.c

Few points to note about the above structure:

Assuming the release package is extracted inside directory represented as $TI816X-PSP-DIR:

• U-Boot source tarball is u-boot-MM.mm.pp.bb.tar.gz needs to be extracted on Linux build host. This will create U-Boot source base for TI816X

$ cd $TI816X-PSP-DIR/TI816x-LINUX-PSP-MM.mm.pp.bb/src/u-boot
$ tar -xvzf u-boot-MM.mm.pp.bb.tar.gz

• Similarly kernel source tarball linux-MM.mm.pp.bb.tar.gz from TI816x-LINUX-PSP-MM.mm.pp.bb/src/kernel directory needs to be extracted to have kernel source directory setup for building kernel and/or modules

$ cd $TI816X-PSP-DIR/TI816x-LINUX-PSP-MM.mm.pp.bb/src/kernel
$ tar -xvzf linux-MM.mm.pp.bb.tar.gz

• Various Video and Audio example sources are included inside $TI816X-PSP-DIR/examples/examples.tar.gz
• Additionally, Watchdog timer and PCIe Endpoint boot applications are provided in respective directories inside $TI816X-PSP-DIR/examples

Toolchain

To build U-Boot and the Linux kernel, you will need to download and install CodeSourcery ARM tool chain version 2009-q1. For additional documentation on installing the CodeSourcery tools, please visit https://sourcery.mentor.com/sgpp/portal/release858.

To help you get started quickly the PSP package comes with pre-built binaries. However, after making any changes to U-Boot and Linux Kernel you need to cross-compile them using the CodeSourcery toolchain and use the new binaries that are generated

Environment Setup

After you have installed the CodeSourcery toolchain you need to setup the environment in the Linux host.

1. Set the environment variable PATH to contain the binaries of the CodeSourcery cross-compiler tool-chain.

   For example, in bash:

   $ export PATH=/opt/toolchain/2009-q1/bin:$PATH

2. Add the location of U-Boot tools directory to the PATH environment variable (required for mkimage utility that is built as part of U-Boot build process and is needed to generate uImage when building the kernel)

   For example, in bash:

   $ export PATH=/opt/u-boot/tools:$PATH

Note
Actual commands to be used for setting the environment variables will depend upon your shell and location of the tools

Flashing Tools

On DM8168 EVM, the Cortex-A8 core boots up first. On boot-up, the ARM core runs the U-Boot image which need to be present in the flash memory of the EVM.

The flash-writers are a part of the PSP package. Instructions on how to use the flash-writers in CCSv4/v5 can be found in PSP Flashing Tools Guide (DM816x_AM389x_PSP_Flashing_Tools_Guide.pdf).

U-Boot

Please refer to U-Boot User Guide for details about U-Boot in the context of DM816x.

Linux Kernel

This chapter describes the steps required to build and configure the Linux kernel. It also provides basic steps to boot kernel on the EVM.

Compiling Linux Kernel

Change to the base of the Linux source directory.

Choose default kernel configuration for your platform.

$ make CROSS_COMPILE=arm-none-linux-gnueabi- ARCH=arm ti8168_evm_defconfig

Initiate the build.

$ make CROSS_COMPILE=arm-none-linux-gnueabi- ARCH=arm uImage

Note
For the kernel image (uImage) to be built, mkimage utility must be included in the path. mkimage utility is generated (under tools folder of U-Boot) while building the U-Boot binary.

On successful completion, file uImage will be created in the directory ./arch/arm/boot.

Copy this file to the root directory of your TFTP server.

Modifying Kernel Configuration

DM8168 EVM

This section describes the steps to configure the kernel for DM8168 EVM and illustrates related configuration items for reference.

Start with the default configuration for your platform

$ make CROSS_COMPILE=arm-none-linux-gnueabi- ARCH=arm ti8168_evm_defconfig

To view configuration interactively:

$ make CROSS_COMPILE=arm-none-linux-gnueabi- ARCH=arm menuconfig

From the onscreen menu, select System Type and press ENTER:

   General setup  --->
[*] Enable loadable module support  --->
-*- Enable the block layer  --->
   System Type  --->
   Bus support  --->
   Kernel Features  --->
   ...
   ...

Select ARM system type

ARM system type (TI OMAP)  --->   
TI OMAP Common Features  --->
TI OMAP2/3/4 Specific Features  ---> 

You will be presented with various ARM based SoCs. Select OMAP as

(X) TI OMAP

After pressing ENTER, you will be presented earlier menu. Select "TI OMAP2/3/4 Specific Features" and press ENTER. Select various options as shown below (marked with '[*]') by pressing Y on each item after selecting it.

[*] Typical OMAP configuration 
[ ] TI OMAP2
[ ] TI OMAP3
[ ] TI OMAP4
[*] TI 81XX
[*] TI816X support
...
    *** TI81XX Board Type ***
[*] TI8168 Evaluation Module

Note that the "TI816X support" option will be shown only if you enable "TI 81XX". Similarly, "TI8168 Evaluation Module" option will be presented only after selecting "TI816X support"

Choose Exit successively to return to previous menu(s) and eventually back to the shell. Make sure to save the changes you have made when prompted at exit.

Some of the key drivers which may be enabled in the default configuration are:

• Serial port
• SATA
• Ethernet
• PCI Express Root Complex
• MMC/SD
• I2C
• GPIO
• Video Display
• Audio
• NAND
• Touchscreen
• Keypad
• PCI Express Root Complex
• PCI Express Boot Driver
• PCI Express EP Driver (mutually exclusive with RC driver)

If you are looking for some particular functionality please double-check that it is enabled in the config options.

Also, please refer individual driver documentation about enabling particular driver and various configurations and dependencies as applicable.

Auto detection of Kernel Load Address and Run Time RAM Base Determination

Note: This section is only applicable to 04.00.02.14 DM816x and onwards release of Linux kernel.

By default, the DM816x kernel is built to be loaded at physical address 0x80008000 in RAM and take start of RAM as 0x80000000.

It is possible to load the kernel at a different location in RAM with kernel automatically determining RAM base depending upon the load address.

This is achieved by the combination of two features added the kernel:

1. Run time PHYS_OFFSET determination: This feature enables determining physical to virtual translations dynamically depending upon the position of kernel in system memory.
2. Auto calculation of address for uncompressed kernel: This feature enables the compressed kernel entry code (part of kernel zImage) to determine the address to uncompress the kernel depending upon the location it is loaded (started from).

Subsequent sub-sections assume that you have already downloaded and extracted the kernel snapshot from above mentioned link/page or set up git working directory with latest PSP kernel from repository associated with the above page. It is also assumed that the environment for kernel build is setup and 'mkimage' executable utility from U-Boot is available in the PATH (this utility gets built with U-Boot and available inside 'tools' directory form U-Boot source base).

Configuring the Kernel

Note: The run time physical offset support is treated as EXPERIMENTAL feature currently. The default kernel configurations for DM8168 EVM have this feature enabled in latest source. You can follow steps similar to those described below and build the kernel to enable this support for any custom board as well as to view/disable this feature as per the need.

Generate default config for the Board

For DM8168 EVM:

BUILDHOST$ make ARCH=arm ti8168_evm_defconfig

The above steps should configure the kernel to include run time physical to virtual translation support (CONFIG_ARM_PATCH_PHYS_VIRT=y) and auto detection of load address (CONFIG_AUTO_ZRELADDR=y).

If you desire to view the exact configuration options to be controlled to enable or disable these features, read the next steps.

Enter the configuration menu

BUILDHOST$ make ARCH=arm menuconfig

You will be presented with configuration menu as shown below:

[*] Patch physical to virtual translations at run time (EXPERIMENTAL)
General setup  --->
[*] Enable loadable module support  --->
...
Kernel Features  --->
Boot options  --->

Enable/Disable runtime physical to virtual translation feature
Ensure that the "Patch physical to virtual translations..." option is highlighted and press 'n' key (without quotes) to disable it (the default kernel configuration done in the earlier step had enabled this option).

[ ] Patch physical to virtual translations at runtime (EXPERIMENTAL)
General setup  --->
[*] Enable loadable module support  --->
...

Pressing 'y' on this option will (again) enable it.

Enable/Disable auto calculation of decompressed kernel location
Now navigate to "Boot options --->" option by using DOWN arrow key and press SPACE to enter the sub-menu shown below.

Here, using DOWN ARROW key, navigate to the option "Auto calculation..." and press 'y' to enable or 'n' to disable it. You should see a '*' in the box '[ ]' in front of that option when 'y' is pressed (enable) otherwise the box will be empty (disabled) when 'n' is pressed.

(0) Compressed ROM boot loader base address
(0) Compressed ROM boot loader BSS address
()  Default kernel command string
[ ] Kernel Execute-In-Place from ROM
[ ] Kexec system call (EXPERIMENTAL)
[*] Auto calculation of the decompressed kernel image address

Using RIGHT arrow key, highlight the 'Exit' option on the menu page and press ENTER key subsequently till you are asked to save the configuration. Now ensure that 'Yes' is highlighted and press ENTER again to save and exit the configuration.

Building the Kernel

Use following command to build the kernel:

BUILDHOST$ make ARCH=arm zImage

Notice that we are building the standard zImage (compressed kernel image) instead of usual uImage. This is so because the uImage built as part of kernel build will have the load address and entry point @0x80008000 by default while, in this case we desire to load the kernel at different load address. Hence we build a zImage and then pass the desired address to 'mkimage' to get uImage as shown below.

Here we use 0x90008000 as the kernel load address and entry point.

Note: You can chose any other address as per your requirement and available RAM space but please refer next section Points to Note/Restrictions for various important points and constraints.

Use 'mkimage' to generate uImage. Note that the command is run from the kernel source base after zImage is built successfully.

BUILDHOST$ mkimage -A arm -O linux -T kernel -C none -a 0x90008000 -e 0x90008000 -n 'Linux-2.6.37' -d arch/arm/boot/zImage uImage
    Image Name:   Linux-2.6.37
    Created:      Mon Oct 29 21:05:21 2011
    Image Type:   ARM Linux Kernel Image (uncompressed)
    Data Size:    2570504 Bytes = 2510.26 kB = 2.45 MB
    Load Address: 90008000
    Entry Point:  90008000

You can build the zImage once and just execute the 'mkimage' step for different load address requirements with same kernel.

Alternate Method: Single Step Build

You can still achieve the above in single step as part of kernel build by passing zreladdr-y=<desired-load-address> to make when building the uImage.

For example, to build the uImage with load address 0x90008000 considered in earlier case:

BUILDHOST$ make ARCH=arm zreladdr-y=0x90008000 uImage

The above command will build the kernel zImage and then uImage by internally invoking 'mkimage' with the specified load address (passed as zreladdr-y).

Note: In any case, you need to rebuild the uImage for specific load address.

Points to Note/Restrictions

• Load address and entry point parameter passed to 'mkimage' must be same, that is, values passed for '-a' and '-e' must be same.
• The auto address calculation of load address is only possible when using compressed kernel image (zImage) and thus, the uImage must be built from zImage - using uncompressed kernel image (Image) will not support this feature.
• The run time physical RAM base calculation support (called as p2v) adds a string "p2v8" to module version and thus the modules built without p2v support cannot be loaded on the kernel built with p2v support enabled and vice verse. This prevents incompatible modules being loaded mistakenly.
• This feature may not be used with XIP kernels.
• Run time physical offset determination feature is an EXPERIMENTAL feature presently.
• The kernel compressed entry code which determines the address for loading uncompressed kernel considers that the compressed kernel image (zImage) is loaded within first 128MB of the RAM, this also means that the RAM base is determined by masking least significant (LS) 27 bits of the load address.
• There must be at least 32KiB space available *after* the determined RAM base (see above point) and *before* the kernel load address specified when preparing uImage.

Refer Choosing Load Address and Determination of RAM Base section below for details and examples.

Choosing Load Address and Determination of RAM Base

As mentioned earlier, the load address must be chosen such that it leaves at least 32KiB space below it from the RAM base. This is required since the kernel uses this region of RAM below the image to store page tables (in normal execution as well as during decompress).

Also note that since the RAM base is calculated by truncating to the nearest 128MiB boundary (masking LS 27 bits of the load address), the LS bits getting masked need to evaluate to at least 32K offset from the RAM base (that is, 0x8000 minimum).

Following are some examples of correct load addresses (with automatically calculated RAM base) followed by a few incorrect ones:

Correct Load Addresses

Load Address	Calculated RAM Base
0x90008000	0x90000000
0x90010000	0x90000000
0x91000000	0x90000000
0x98100000	0x98000000
0x98104000	0x98000000
0x80008000	0x80000000
0x88100000	0x88000000

Incorrect Load Addresses

Following addresses would result into a non bootable kernel (kernel will hang/halt during boot):

Load Address	Problem Area
0x90000000	Calculated RAM base = 0x90000000 (masking to 0xF8000000), which means the 32KiB requirement for load address is not met
0x98000000	RAM base = 0x98000000, 32KiB requirement not met
0x98004000	RAM base = 0x98000000, only 16KiB available below the load address

Modifying Pin Mux settings

On DM816x device, the default pin multiplexing is set to Mode 0 (FUNCTION 1) configuration on reset. If you desire to use a particular pin to any other function than Mode 0 or override any pin mode which was already set in U-Boot, the kernel needs to be modified and rebuilt.

You can change default mux mode by adding specific mux entry in the beginning of board_mux array in arch/arm/mach-omap2/board-ti8168evm.c or calling omap_mux_init_signal() during initialization (e.g., in device specific initialization function called from omap2_init_devices() in arch/arm/mach-omap2/devices.c).

The names of multiplexed signals are specified in arch/arm/mach-omap2/mux81xx.c file in kernel source directory.

e.g., To set up mtsi_dclk pin (mode 0) to gmii1_rxclk (mode 1) on DM816x, add

TI816X_MUX(MTSI_DCLK,OMAP_MUX_MODE1 | OMAP_PULL_UP)

to board_mux structure in board file or call

omap_mux_init_signal("gmii1_rxclk", OMAP_PULL_UP)

from module specific init function (in arch/arm/mach-omap2/devices.c). Build the kernel after this change.

To disable pull up/down you will need to set bit-3, e.g., use

omap_mux_init_signal("gmii1_rxclk", 1 << 3)

One could also pass mode0_name.desired_mode_name format string to set specific pin to desired functionality:

omap_mux_init_signal("mtsi_dclk.gmii1_rxclk", 1 << 3)

The API approach is useful if you desire to set the pin-mux run time depending upon the board/hardware detected without need of maintaining separate kernel binaries.

Alternatively, you can set particular pins by passing respective pinmux details to kernel command line in following format

omap_mux=<mode0_name>.<signal_name>=<value>,<mode0_name>.<signal_name>=<value>

E.g., to set tsi1_dclk (mode 0) pin to vout1_b_cb_c3 and disable pull up/down (set bit 3), append following to kernel command line passed from the boot loader:

omap_mux=tsi1_dclk.vout1_b_cb_c3=0x8

You can pass configuration for multiple pins separated by comma.

For details about this boot parameter, refer Documentation/kernel-parameters.txt in kernel source directory.

Clock details

H/W Details

DM816x has two on chip oscillators which are the main source of clock, OSC0 and OSC1. By default OSC0(27 MHz) provides the input clock source for all FAPLLs.These PLLs are configured to generate higher frequencies required for interface and functional clocks of various modules on the device.Clock out from PLLs is distributed to various modules as per the hardware connections and requirements, with divider at place where lower frequencies are required.

Clock Framework Overview and Usage

For clock framework software implementation, features and usage refer to Clock Framework User Guide

Using The Correct Console Device

On the latest kernel packaged in this release, the serial device names are changed from ttySx to ttyOx. Thus, the serial port associated with UART2 is now referred as ttyO2.

• This means you will need to update 'bootargs' as passed to kernel to use ttyS2 as console. For example, change

console=ttyS2,115200n8 

to,

console=ttyO2,115200n8

• The subsequent example 'bootargs' use the new console name and will not work with kernel from older releases.
• Similarly, you will need to update the /etc/inittab file in the filesystem used for kernel by replacing lines with 'ttySx' by 'ttyOx'. For example, replace following

S:2345:respawn:/sbin/getty 115200 ttyS2

by,

S:2345:respawn:/sbin/getty 115200 ttyO2

Note: The character 'O' in the serial port names stands for "OMAP UART Port".

Updating the DHCP Script

The latest kernel has changed the entry for root filesystem name as appear in /proc/mounts file. This might impact boot process if some of the init scripts in your filesystem read this entry to determine the root device type.

The existing scripts checking /proc/mounts may not work as intended.

One such case is the /etc/udhcpc.d/50default script in the filesystem, which skips sending DHCP requests if the root device is a network mounted filesystem.

If you face any issue where the filesystem is mounted successfully but hangs after showing udhcpc related prints. The issue is most likely with incompatibility between latest kernel and the udhcpc script.

To fix this, open the /etc/udhcpc.d/50default in your DM8168 filesystem and check if a check like the one shown below exists:

 root_is_nfs() {
       grep -qe '^/dev/root.*\(nfs\|smbfs\|ncp\|coda\) .*' /proc/mounts
 }

Update the above fragment by replacing the check as below:

 root_is_nfs() {
       grep -qe 'nfs\|smbfs\|ncp\|coda.*' /proc/mounts
 }

The above change will be required even when you want to (manually) run 'udhcpc' client after booting.

Setting up Machine ID

The description below needs to be followed only if you are using U-Boot from earlier releases or have 'machid' environment variable set to a value different than 'af0'.

Kernel in this release uses different machine id - hexadecimal 'af0' - to recognize DM8168 EVM, than the earlier releases. The U-Boot in this release has also been updated to pass this value when booting the kernel on EVM. If you want to continue using older U-Boot (which used to pass '7d9' as machine id), you need to perform following steps at U-Boot prompt before proceeding to boot the kernel:

TI8168_EVM# setenv machid af0
TI8168_EVM# saveenv

Booting Linux Kernel

Kernel along with root filesystem can either be booted from on board storage device or can be fetched over the Ethernet to RAM using TFTP and booted from there. Also, the root filesystem can be formatted as JFFS2 or UBIFS, flashed and then mounted. Please refer U-Boot User Guide for details about flashing and supported storage devices.

Following sections describe various kernel boot options possible.

Note: The offsets and MTD partition numbers used in examples below may vary depending upon actual partition layout used on particular storage device. Also, selecting multiple storage device support in kernel (e.g., NAND & SPI) may change the effective partition number to be used as root partition.

Boot from NAND

Make sure the Boot Mode/Configuration Select Switch is set for the NAND boot mode as described in the U-Boot User Guide

Power on EVM and wait for U-Boot to come up on the serial console.

When kernel uImage and JFFS2 or UBIFS filesystem are flashed on the NAND device:

TI8168_EVM# nand read.i 0x81000000 280000 500000

For JFFS2 file system:
TI8168_EVM# setenv bootargs 'mem=128M console=ttyO2,115200n8 noinitrd root=/dev/mtdblock7 rw rootfstype=jffs2 ip=dhcp'

For UBIFS file system:
TI8168_EVM# setenv bootargs 'console=ttyO2,115200n8 noinitrd ip=off mem=256M rw ubi.mtd=7,2048 rootfstype=ubifs 
root=ubi0:rootfs init=/init'

TI8168_EVM# bootm 0x81000000

When kernel image is flashed on the NAND device, and NFS mounted filesystem is being used:

TI8168_EVM# nand read.i 0x81000000 280000 500000
TI8168_EVM# setenv bootargs 'console=ttyO2,115200n8 root=/dev/nfs nfsroot=172.24.179.98:/nfs_root,nolock rw mem=128M'
TI8168_EVM# bootm 0x81000000

Boot from NOR

Make sure the Boot Mode/Configuration Select Switch is set for the NOR boot mode as described in U-Boot User Guide.

Power on EVM and wait for U-Boot to come up on the serial console.

Assuming kernel uImage and JFFS2 filesystem are flashed on the NOR device @0x08060000 (Partition 2) and @0x08460000 (Partition 3) respectively:

TI8168_EVM# cp.w 0x08060000 0x81000000 0x200000
TI8168_EVM# setenv bootargs 'mem=128M console=ttyO2,115200n8 noinitrd root=/dev/mtdblock3 rw rootfstype=jffs2 ip=dhcp'
TI8168_EVM# bootm 0x81000000

Boot from SPI

Make sure the Boot Mode/Configuration Select Switch is set for the SPI boot mode as described in U-Boot User Guide.

Power on EVM and wait for U-Boot to come up on the serial console.

Assuming kernel uImage is flashed on the SPI flash @0x42000 and using NFS based root filesystem:

TI8168_EVM# sf read 0x81000000 0x42000 0x200000
TI8168_EVM# setenv bootargs 'console=ttyO2,115200n8 root=/dev/nfs nfsroot=172.24.179.98:/nfs_root,nolock rw mem=128M'
TI8168_EVM# bootm 0x81000000

Boot from SD Card

Make sure the Boot Mode/Configuration Select Switch is set for the SD boot mode as described in U-Boot User Guide.

Power on EVM and wait for U-Boot to come up on the serial console.

The example below assumes kernel uImage is available in first partition of the SD card and second partition contains ext3 formatted filesystem. Please refer "Setting Up Boot Environment on SD Card" section from DM81xx U-Boot User Guide.

TI8168_EVM# mmc init
TI8168_EVM# fatload mmc 1 0x81000000 uImage
TI8168_EVM# setenv bootargs 'console=ttyO2,115200n8 root=/dev/mmcblk0p2 mem=128M rootwait'
TI8168_EVM# bootm 0x81000000

Boot over Network (Ethernet)

When kernel image and ramdisk image are fetched from a tftp server:

• Ensure that the EVM is connected to network with DHCP and TFTP server set up
• Set 'ethaddr' U-Boot environment variable with proper ethernet address in format 'xx:xx:xx:xx:xx:xx' (replace 'xx' with proper hexadecimal values)
• Copy kernel image and ramdisk to TFTP server's root directory.
• Execute follwing commands at U-Boot prompt. We assume kernel image name as 'uImage' and ramdisk file name as 'ramdisk.gz'

TI8168_EVM# setenv autoload no
TI8168_EVM# dhcp
TI8168_EVM# setenv serverip <Server IP Address>
TI8168_EVM# tftp 0x81000000 uImage
TI8168_EVM# tftp 0x82000000 ramdisk.gz
TI8168_EVM# setenv bootargs 'mem=200M console=ttyO2,115200n8 root=/dev/ram0 initrd=0x82000000,40M ramdisk_size=45000 ip=dhcp'
TI8168_EVM# bootm 0x81000000

• Alternatively, kernel can be made to use the same IP address as assigned to U-Boot instead of doing DHCP request again by setting U-Boot parameters as follows:

TI8168_EVM# print ethaddr                          <-- Check if MAC address is assigned and is unique
TI8168_EVM# setenv ethaddr <unique-MAC-address>    <-- Set only if not present already, format xx:yy:zz:aa:bb:cc
TI8168_EVM# setenv bootcmd 'dhcp;run addip; tftp 81000000 uImage;bootm'
TI8168_EVM# setenv hostname <unique-hostname>
TI8168_EVM# setenv addip 'setenv bootargs ${bootargs} ip=${ipaddr}:${nfsserver}:${gatewayip}:${netmask}:${hostname}:eth0:off'
TI8168_EVM# setenv autoload no
TI8168_EVM# setenv nfsserver <nfs-server-ip>         <-- Make sure the same NFS server IP is used below
TI8168_EVM# setenv bootargs 'console=ttyO2,115200n8 root=/dev/nfs nfsroot=<nfs-server-ip>:<path-to-nfs-share>,nolock rw mem=128M'
TI8168_EVM# setenv serverip <tftp-server-ip>
TI8168_EVM# saveenv
TI8168_EVM# boot

• After saving the environment variables, you need not set them again on reboot unless a change is required.
• Note that the above example uses NFS mounted root file system accessed over 'eth0' interface (as available on the base EVM)
• You will need to use 'eth1' instead of 'eth0' in case the 2nd Ethernet interface is used to connect to the network (e.g., on daughter card). For example, update 'addip' in the example above,

TI8168_EVM# setenv addip 'setenv bootargs ${bootargs} ip=${ipaddr}:${nfsserver}:${gatewayip}:${netmask}:${hostname}:eth1:off'

Note: You need not set 'ethaddr' for devices having valid MAC IDs set. In such cases, U-Boot will automatically detect and set the ethernt address (should show message like "Detected MACID:...").

Setting Memory Holes For System RAM

The default kernel configuration support setting up holes in system RAM. That is, the bootargs can be set to indicate kernel to map RAM regions with hole in between.

As an example, the bootargs used for network boot as shown above are modified to have two RAM regions for kernel mapping with 32MB starting form 0x80000000 followed by 96MB from 0x88200000. Note that, this change can be used for any of the other boot modes described above with 'mem' arguments as shown below:

TI8168_EVM# setenv bootargs 'console=ttyO2,115200n8 root=/dev/nfs nfsroot=<nfs-server-ip>:<path-to-nfs-share>,nolock rw mem=32M@0x80000000 mem=96M@0x88200000'

GPIO Driver

DM816x has two GPIO modules provides 32 dedicated general-purpose pins with input and output capabilities, total 0 - 127 pins are available for usage.

GPIO Driver User Guide have more details of driver usage

EDMA3 Driver

EDMA Driver User Guide

AVS Driver

The AVS driver is available for DM816x platform. For more details on the usage, refer AVS User Guide.

• AVS Driver User Guide 

Audio Driver

The audio driver in the PSP package conforms to the ASoC framework in the Linux kernel. The current driver supports audio capture and playback using the AIC3106 codec on the EVM. For more details on the audio driver refer online.

SATA Driver

The SATA subsystem supports 2 - 3Gbps SATA host ports each capable of supporting Port Multiplier and direct connect SATA devices.

SATA driver in the Linux kernel has support for

• HDD
• CD/DVD
• Port Multiplier

NOTE: In case of external RAID storage towers (via ahci), the storage tower should be configured using the windows/Linux(x86) tool before connecting it to TI8168 EVM

Feature Not Supported

• Power Management

Note: Refer SATA FAQ for more information.

USB Driver

The USB subsystem includes two USB(mentor) controller. There are independent usb ports for two controller musb0 and musb1 can be configured to host/device mode operation. The PG 1.0 version of TI816x silicon supports only point-point configuration in Mentor USB IP core and hence hub is not supported. Hence only one device can be connected to each port of USB.

USB_ID configuration for DM816X: The USB0_ID/USB1_ID pin is always configured through software in DM816X silicon revisions. This configuration is done by chosing appropriate configuration through USBx_ID menuconfig selection. more information refers to USB Configuration Page.

Please refer DM81xx-PSP-USB-User-Guide for more details.

• DM81xx AM38XX USB User Guide 

VPSS Video Driver

VPSS Video Driver User Guide

VPSS Video Capture driver

VPSS Video Capture Driver User Guide

NOTE: V4L2 capture driver is added in PSP04.00.01.13 for DM816x class of devices and PSP04.01.00.06 for DM814x class of devices.

HDMI Driver

HDMI Driver User Guide

Sii9022a External HDMI Transmitter Driver

Sii9022a external HDMI Transmitter UserGuide

McSPI Driver

Please refer DM81xx_AM38xx_PSP_McSPI_Driver_Guide.pdf in the release package or refer online McSPI Driver Guide.

NOR Flash Support

Please refer DM81xx_AM38xx_PSP_NOR_Driver_Guide.pdf in the release package or refer online NOR Driver Guide.

SD driver

SD Driver supports SD/SDHC/uSD cards. HSMMC peripheral (and driver) has support for 4 data lines at the max operating frequency of 48MHz. HSMMC is a slave DMA peripheral and uses EDMA to move data between SD card and system memory.

Supported Features

• SD
• SDHC
• uSD
• uSDHC

Not supported Features

• PIO mode of operation

Please refer MMC/SD guide.

PCI Express Root Complex Driver

Please refer the PCIe RC Driver User Guide for particular release in PDF format from the release package. The latest document is available online.

PCI Express Endpoint Boot Driver

Please refer the PCIe Boot Driver User Guide in PDF format from the release package for details about booting DM816x PCIe Endpoint connected to DM816x/DM814x or x86 Linux PCIe Root complex using PCIe boot driver (running on RC). The latest document is available online.

PCI Express Endpoint Driver

Please refer the PCIe Endpoint Driver User Guide in PDF format from the release package for details about using this driver on DM816x PCIe Endpoint part of PCIe topology. The latest document is available online.

Watchdog Timer (WDT)

The following document covers the details regarding the watchdog timer in DM81xx:

Please refer WDT guide.

TILER

TILER driver has dependency on Multimedia. TILER support is disabled in defconfig. TILER driver can be enabled from,

  Device Drivers  ---> 
    <*> Multimedia support  ---> 
        <*>   TI TILER support  ---> 
                --- TI TILER support                                  
                (128) Allocation granularity (2^n) (NEW)              
                (4096) Allocation alignment (2^n) (NEW)               
                (40)  Memory limit to cache free pages in MBytes (NEW)
                (1)   Process security (NEW)                          
                (0)   Use SSPtr for id (NEW)                          
                [ ]   Secure TILER build (NEW)                        
                [*]   Expose SSPtr to userspace (NEW)                 
                                                      
                                      

Leave the default values as those are the one's which were validated for this release.

Following features are supported in the current TILER driver,

• Single PAT and run-time memory allocation

Features not supported,

• Dual PAT
• PAT by-pass mode

IOMMU

Please refer DM81xx_AM38xx_PSP_IOMMU_Driver_Guide.pdf in the release package or refer online IOMMU Driver Guide.