Intel Apollolake-i BSP
1. About this document
======================
This is the intel-apollolake-i BSP, only provide 64 bit support current.
This document describes common and non-hardware specific information.
Please refer to README.hardware for hardware specific information.
Dependencies
------------
This layer depends on the oe-core version supplied with Wind River
Linux and the wr-kernel layer.
Maintenance
-----------
This layer is maintained by Wind River Systems, Inc.
Contact <support@windriver.com> or your support representative for more
information on submitting changes.
Building the intel-x86 layer
----------------------------------
This layer and the wr-kernel layer should be added to bblayers.conf. This
is done automatically when using the Wind River configure wrapper.
Note:
To build a 64-bit kernel + 64-bit rootfs, use:
--enable-board=intel-apollolake-i-64
License
-------
Copyright (C) 2016 Wind River Systems, Inc.
The right to copy, distribute or otherwise make use of this software may
be licensed only pursuant to the terms of an applicable Wind River license
agreement. No license to Wind River intellectual properly rights is granted
herein. All rights not licensed by Wind River are reserved by Wind River.
Source code included in the tree for individual recipes is under the LICENSE
stated in each recipe (.bb file) unless otherwise stated.
2. BSP Kernel and RootFS Combination
====================================
The validity of WindRiver Linux kernel and RootFS combination for this BSP is
in the table.
The leftmost column of the table is the kernel type, and the top line is the
RootFS type.
'Y' in each content cell stands for the combination is supported; 'N' stands
for not supported:
--------------------------------------------------------------------
| kernel/rootfs | glibc-std | glibc-small | glibc-cgl | glibc-tiny |
--------------------------------------------------------------------
| standard | Y | Y | N | N |
--------------------------------------------------------------------
| preempt-rt | Y | Y | N | N |
--------------------------------------------------------------------
| cgl | N | N | N | N |
--------------------------------------------------------------------
Note: with regard to the kernel and RootFS type, please refer to WindRiver Linux
specification for details.
3. BSP Specific Patches
=======================
To get a list of patches applied to the kernel specific to this BSP along with
patch descriptions use git-whatchanged on the default kernel
(git-whatchanged <kernel_type>..<bsp_name>). For example:
%> cd build/linux-windriver-<version>/linux
%> git whatchanged standard/base..
4. Boot Instructions
====================
4.1 Boot methods
================
4.1.1 EFI
---------
To enable the EFI boot method, for example, use an USB device formated to FAT32
filesystem as storage, then copy the kernel file to /EFI/wrl/bzImage.efi
on the USB device. Note that the kernel filename must end in .efi, and kernel
file must be stored in its own subdirectory of the /EFI directory on storage.
The last step is to create a script named startup.nsh with the following
content:
fs0:\EFI\wrl\bzImage.efi <kernel_parameters>
EFI Shell will automatically execute startup.nsh to load bzImage.efi, and
the built-in boot loader within bzImage.efi will boot the kernel to pass the
system control to linux OS.
Please contact the manufacturer to update firmware if the screen hangs
when startup.sh is invoked.
4.2 Rootfs methods
==================
The SATA/SAS hard disk, USB storage device and NFS are enabled in the kernel as
potential root filesystem devices.
4.2.1 SATA/SAS
--------------
Use SATA hard disk as rootfs with this kernel parameter:
root=/dev/sd<x><y> rw ip=dhcp
For example:
root=/dev/sda1 rw ip=dhcp
In the example shown above, the first SATA hard disk detected by linux is
used as the device having rootfs, and the first partition inside it is used
as rootfs.
4.2.2 USB
---------
Use a USB storage device as rootfs with this kernel parameter:
root=/dev/sd<x><y> rw ip=dhcp rootwait
For example:
root=/dev/sdc1 rw ip=dhcp rootwait
This is similar to SATA rootfs. "rootwait" tells the kernel to wait for the
root device become available before attempting to mount the rootfs. This
option is useful for certain targets with slow USB response times.
4.2.3 NFS
---------
Use NFS as rootfs with this kernel parameter:
root=/dev/nfs rw nfsroot=<nfs_server_ip>:<path_to_rootfs> ip=dhcp
For example:
root=/dev/nfs rw nfsroot=192.168.0.1:/export/pxeboot/boards/rootfs ip=dhcp
In the example shown above, an nfs server is located at 192.168.0.1, and the
exported mount point via nfs makes /export/pxeboot/boards/rootfs available.
4.3 Boot from the Live Images
=============================
WRLinux supports the ISO and HDD images boot, and all of those images support both
legacy PCBIOS and UEFI boot.
4.3.2 ISO Image
----------------
There are two ways to get the ISO image.
The first one is by enable a project configure option
"--enable-bootimage=iso", and then "make fs", after that, you can access the ISO image in
<project_dir>/export/ directory, such as export/intel-x86-64-wrlinux-image-glibc-std-standard-dist.iso.
The second one is by running "make iso-image" under your <project_dir> without adding the configure
option "--enable-bootimage=iso". This can produce export/bootimage.iso under your <project_dir>.
After you get the ISO image, you can burn it onto an optical disk or "dd" it onto a flash
disk to boot on your board just as the USB image does.
4.3.3 HDD Image
-----------------
To get a HDD image, you must add the configure option "--enable-bootimage=hdd" to your project configure line.
After you run "make fs", you will get it under <project_dir>/export directory,such as:
export/intel-x86-64-wrlinux-image-glibc-std-standard-dist.hddimg.
The method of deploying this image is the same as USB image does.
5. Features
===========
This section describes common features which are available on most targets.
5.1 Standby (ACPI S1), Suspend to RAM (ACPI S3) & Suspend to Disk (ACPI S4)
===========================================================================
5.1.1 Introduction
------------------
These features allow the system to enter sleep states which reduce power
consumption.
5.1.2 System requirements
-------------------------
5.1.3 Usage and verification
----------------------------
1) Put the system in the ACPI S1 state until a specified wakeup time.
$ rtcwake -m standby -s 20
The system will resume its normal state after 20 seconds.
2) Put the system in the ACPI S3 state until a specified wakeup time.
$ rtcwake -m mem -s 20
The system will resume its normal state after 20 seconds.
3) Set up ACPI S4 as the following steps.
$ create a swap partition on disk. For example, use /dev/sda2.
$ mkswap /dev/sda2
$ attach "resume=/dev/sda2" kernel parameter and then reboot.
$ swapon /dev/sda2
$ echo disk >/sys/power/state
ACPI S4 requires more time to recover to a normal state.
Note: If ACPI S3 functionality is enabled, NFS root cannot be used. Only
disk based roots (sata/sas/raid/etc) are stable when combined with ACPI S3.
5.2 CPU Hot Plug
================
5.2.1 Introduction
------------------
This feature allows turning CPUs off and on. CPUs can be controlled through
/sys/devices/system/cpu.
5.2.2 Usage and verification
----------------------------
1) Unplug non-bootstrap CPUs from system:
$ for i in `seq 1 <x>`; do echo 0 > /sys/devices/system/cpu/cpu$i/online; done
where <x> indicates the last logical CPU id in your machine.
2) Check the result to see the status of non-bootstrap CPUs:
$ for i in `seq 1 <x>`; do cat /sys/devices/system/cpu/cpu$i/online; done
If step 1 successes, the result will return all zeros, indicating that the CPUs
are removed from system.
3) Replug non-bootstrap CPUs:
$ for i in `seq 1 <x>`; do echo 1 > /sys/devices/system/cpu/cpu$i/online; done
4) Check the result to see the status of non-bootstrap CPUs again:
$ for i in `seq 1 <x>`; do cat /sys/devices/system/cpu/cpu$i/online; done
The expected result will return all 1s, indicating that the CPUs are online now.
5.2.3 Target Notes
------------------
Bootstrap CPU is always numbered with zero and does *NOT* support CPU Hot Plug.
5.3 CPUidle (ACPI C-states)
===========================
5.3.1 Introduction
------------------
CPU idle is a generic framework for supporting software-controlled idle
processor power management. It includes modular cross-platform governors that
can be swapped during runtime. For the x86 architecture, a generic cpuidle
driver called acpi_idle is provided to support ACPI-enabled machines.
Furthermore, an intel_idle driver that includes knowledge of native Intel
hardware idle features is provided. Note that the acpi_idle driver can be
configured at the same time, in order to handle processors that intel_idle
does not support.
5.3.2 Usage and verification
----------------------------
You must use "cpuidle_sysfs_switch" in your kernel parameters, and then
follow the step below:
$ cat /sys/devices/system/cpu/cpu0/cpuidle/*/usage
where the each line of results represents the number of times this state was
entered.
5.4 CPUfreq (Intel P state)
===========================
5.4.1 Introduction
------------------
The intel_pstate driver provides the internal governor that implements
the scaling driver for Goldmont processors. intel_pstate replaces the existing
acpi pstates drivers, and is the preferred scaling driver for these class of
systems.
5.4.2 Usage and verification
------------------------------
1) Check the intel_pstate driver:
$ cd /sys/devices/system/cpu
$ cat cpu0/cpufreq/scaling_driver
"intel_pstate" will be returned.
2) Check with the availability of governor:
$ cat cpu0/cpufreq/scaling_available_governors
"powersave" and "performance" will be returned.
3) Degrade all CPUs in the system:
$ for i in `seq 0 <x>`; do echo powersave > cpu$i/cpufreq/scaling_governor; done
where <x> indicates the last logical CPU id in your system.
4) Check the current frequency:
$ cat cpu0/cpufreq/cpuinfo_cur_freq
699000
In this example the CPU is running at 700MHz after changing the frequency.
5) Get the performance using a tight loop:
$ time for i in `seq 100000`; do echo a > /dev/null; done
real 0m1.968s
user 0m0.703s
sys 0m1.182s
6) Upgrade all CPUs on the system:
$ for i in `seq 0 <x>`; do echo performance > cpu$i/cpufreq/scaling_governor; done
7) Check the current frequency again:
$ cat cpu0/cpufreq/cpuinfo_cur_freq
1200000
In this example the CPU is running at 1200MHz after changing the frequency.
8) Get the performance using a tight loop for comparison:
$ time for i in `seq 100000`; do echo a > /dev/null; done
real 0m1.960s
user 0m0.642s
sys 0m1.224s
5.5 SATA (AHCI)
===============
5.5.1 Introduction
------------------
The AHCI SATA controllers offers selectable modes of operation: legacy Parallel
ATA emulation (IDE), standard AHCI mode, and vendor-specific RAID (which
generally enables AHCI in order to take advantage of its capabilities). This
BSP supports the later 2 modes.
5.5.2 System requirements
-------------------------
You must configure the BIOS properly to enable the standard
AHCI mode. Using Intel Sabino Canyon as an example, follow this path and
setting:
Advanced -> PCH-IO Configuration -> SATA Configuration
SATA Controller(s) [Enabled]
SATA Mode Selection [AHCI]
5.5.3 Usage and verification
----------------------------
1) Use a SATA hard disk as boot device and install rootfs to it.
2) eSATA supports hot plugging, so the cable can be disconnected and then
reconnected at runtime.
5.6 USB xHCI Host and USB 3.0 Storage Device
============================================
5.6.1 Introduction
------------------
The eXtensible Host Controller Interface (xHCI) is standard for USB 3.0
"SuperSpeed" host controller hardware.
5.6.2 System requirements
-------------------------
An USB 3.0 stroage device is required.
5.6.3 Usage and verification
----------------------------
1) Use hdparm to benchmark the performance between USB 2.0 and 3.0:
$ hdparm -tT /dev/sdc /dev/sdd
/dev/sdc:
Timing cached reads: 11072 MB in 2.00 seconds = 5542.04 MB/sec
Timing buffered disk reads: 28 MB in 3.11 seconds = 9.01 MB/sec
/dev/sdd:
Timing cached reads: 12274 MB in 2.00 seconds = 6144.48 MB/sec
Timing buffered disk reads: 234 MB in 3.01 seconds = 77.64 MB/sec
Note:
/dev/sdc is a USB 2.0 storage device attached on USB 2.0 port.
/dev/sdd is a USB 3.0 storage device attached on USB 3.0 port.
2) Use an USB 3.0 storage device as boot device and install rootfs on it:
5.7 Intel HDA
==============
5.7.1 Introduction
-------------------
This feature supports Intel "High Definition Audio" (Azalia) and
compatible devices. The driver enables the HD-audio controller. The
appropriate codec drivers are necessary to enable Realtek HD-audio codec
support such as ALC887/888 and HDMI/DisplayPort HD-audio.
5.7.2 Usage and verification
-----------------------------
1) List the available playback devices.
$ aplay -l
**** List of PLAYBACK Hardware Devices ****
card 0: MID [HDA Intel MID], device 3: HDMI 0 [HDMI 0]
Subdevices: 1/1
Subdevice #0: subdevice #0
card 0: MID [HDA Intel MID], device 7: HDMI 1 [HDMI 1]
Subdevices: 1/1
Subdevice #0: subdevice #0
card 0: MID [HDA Intel MID], device 8: HDMI 2 [HDMI 2]
Subdevices: 1/1
Subdevice #0: subdevice #0
card 1: PCH [HDA Intel PCH], device 0: ALC262 Analog [ALC262 Analog]
Subdevices: 1/1
Subdevice #0: subdevice #0
card 1: PCH [HDA Intel PCH], device 1: ALC262 Digital [ALC262 Digital]
Subdevices: 1/1
Subdevice #0: subdevice #0
In this example, the ALC888 audio effect chip is used with the on-board HD Audio
Jack. Three DP/HDMI codec ports are available as well.
2) Set the card control contents:
$ amixer cset name='Master Playback Switch' 1
$ amixer cset name='Master Playback Volume' 80%
$ amixer cset name='Headphone Playback Switch' 1
3) Play the audio file via ALC888:
$ aplay -Dhw:1,0 test.wav
Playing WAVE 'test.wav' : Signed 16 bit Little Endian, Rate 44100 Hz, Stereo
This command uses card 0 and device 0 for playback:
4) Play the audio file via DP or HDMI:
$ aplay -Dhw:0,7 test.wav
Playing WAVE 'test.wav' : Signed 16 bit Little Endian, Rate 44100 Hz, Stereo
This command uses card 0 and device 7 for playback.
Note:
HDMI and DP do not support record feature. Only Stereo 44100 Hz PCM format is
validated.
5.8 SMBus
==========
5.8.1 Introduction
-------------------
Intel 801 family of mainboard I2C interfaces.
5.8.2 Usage and verification
-----------------------------
Check the SMBus device:
$ i2cdetect -l
5.8.3 Target Notes
-------------------
On some boards an ACPI resource conflicts with SMBus. By default, the
functionality of SMBus is disabled. To enable SMBus, please append
"acpi_enforce_resources=lax" to your kenrel parameters.
5.9 kexec/kdump
================
5.9.1 Introduction
-------------------
kexec is a system call that implements the ability to shutdown your current
kernel (so-called system kernel) and start another kernel (so-called dump-
capture kernel). kdump features a generation of crash dump after being started
by kexec.
5.9.2 Usage and verification
-----------------------------
To add kexec/kdump kernel features and the tools to rootfs, use the following options
to the configure command :
--with-template=feature/kexec,feature/kdump
when boot the target, it is necessary to append "crashkernel=Y@X" parameter with
proper value to specify the load address of dump-capture kernel. Please refer to
Documentation/kdump/kdump.txt to know how to set "crashkernel=Y@X" parameter properly.
A dump-capture kernel should be prepared as well. Enabling kdump should be
normally only set in special dump-capture kernel which are loaded in the system
kernel with kexec-tools into a specially reserved region and then later
executed after a crash by kdump/kexec.
When system kernel starts up, use the following command to load a dump-capture
kernel, and ensure using bzImage as dump-capture kernel:
$ kexec -p <path_to_dump_capture_kernel> --append="<kernel_parameters>"
Then, issue a kernel crash:
$ echo c > /proc/sysrq-trigger
After dump-capture kernel starts up, run makedumpfile to dump kernel core file
for analysis.
5.10 Intel_rapl
===============
The RAPL driver is implemented as a power cap driver.
Show intel_rapl status via sysfs:
$ cat /sys/class/powercap/intel-rapl:0/name
package-0
$ cat /sys/class/powercap/intel-rapl/intel-rapl\:0/enabled
1
$ cat /sys/class/powercap/intel-rapl/intel-rapl\:0/constraint_*
15000000
long_term
15000000
28000000
0
short_term
25000000
2441