README

This README file contains information on building the meta-acpi BSP
layer. Please see the corresponding sections below for details.

Dependencies
============

This layer depends on:

  URI: git://git.yoctoproject.org/poky.git
  branch: krogoth

  URI: git://git.yoctoproject.org/meta-intel
  branch: krogoth

Table of Contents
=================

  I. Overview
  II. Building the meta-acpi BSP layer
  III. ACPI tables
  IV. Sample ACPI tables

I. Overview
===========

This layer provides extended support for Intel ACPI enabled development
boards such as Minnowboard, Minnowboard MAX, Galileo Gen 2, Joule and
Edison *).

The driving force here is that the BIOS shipped with these boards cannot
possibly support all possible devices you can connect them. For example
Minnowboard MAX has a low speed expansion connector providing access to
I2C, SPI and UART buses. It is up to the developer to connect additional
devices to the board.

This layer makes it possible to include ACPI tables with the image. Each
table contains description of one device connected to the board. The
kernel loads these tables during boot and is able to enumerate devices
included in those.

We include sample ACPI tables for each board that can be used as base
for the actual devices the developer wants to connect to these boards.

*) Edison does not ship with a BIOS. Certain ACPI tables are provided
through U-Boot instead. To take advantage of the tables from meta-acpi
you need to add a BSP providing U-Boot >= 2019.04-rc2 and linux >= 5.0.0
both configured for Edison.

II. Building the meta-acpi BSP layer
===========================================

This layer builds on top of meta-intel (see dependencies above) so you
need to download it first.

Having done that, and assuming you extracted the BSP tarball contents at
the top-level of your yocto build tree, you can build an image by adding
the location of the meta-acpi layer to bblayers.conf, along with any
other layers needed (to access common metadata shared between BSPs)
e.g.:

  /path/to/poky/meta-intel \
  /path/to/poky/meta-acpi \

Currently supported boards include Galileo Gen 2, Minnowboard, MinnowBoard
MAX, Minnowboard Turbot, Joule and Edison. You can pick the board including
default ACPI tables by setting MACHINE in local.conf either of:

  MACHINE = "galileo-gen2"
  MACHINE = "minnowboard"
  MACHINE = "minnowboard-max"
  MACHINE = "joule"
  MACHINE = "edison"

Depending on the board*).

You should then be able to build an image as such:

  % source oe-init-build-env
  % bitbake core-image-base

At the end of a successful build, you should have a live image that you
can boot from a USB flash drive.

In order to write the image to the USB flash drive, you can do
something like this:

  % dd if=core-image-base-minnowboard.hddimg of=/dev/sdf bs=1M

You may need to run this as root using sudo but before doing that, make
sure you have the right device in place of /dev/sdf.

*) As for Edison you need to add the bsp layer, which will build several
artefacts as U-Boot, kernel with initramfs, building and flashing involve
additional steps depending on the tool you use. A suitable layer that
provides a bsp and a rootfs is meta-intel-edison as found here:

  https://github.com/edison-fw/meta-intel-edison

Detailed instructions for building and flashing from this layer can be
found here:

  https://edison-fw.github.io/meta-intel-edison/

III. ACPI tables
================

The recipes-bsp/acpi-tables/samples/${MACHINE}/* includes sample ACPI
tables for each board. The default configuration enables some of those.
For example if you build for Minnowboard the
conf/machine/minnowboard.conf has following line by default:

  ACPI_TABLES ?= "buttons.asl leds.asl"

This asks acpi-tables package to include following sample ACPI tables:

  recipes-bsp/acpi-tables/samples/minnowboard/buttons.asl
  recipes-bsp/acpi-tables/samples/minnowboard/leds.asl

These effectively create two new devices: A GPIO Buttons input device
and a GPIO LEDS device. When you an image created with this
configuration, you should see that the on board LED0 starts blinking
approximately at human heartbeat rate. Also if you insert a SD-card, the
LED1 on the board blinks as long as there is some I/O happening.

You can use your own devices instead by overriding ACPI_TABLES in
your local.conf. For example we can add a custom device to our
Minnowboard like:

  ACPI_TABLES = "${TOPDIR}/acpi-tables/device.asl"

This includes only device.asl and nothing more. Leaving ACPI_TABLES
empty means no devices will be added.

When you make changes to the device.asl or edit the ACPI_TABLES variable,
in order for the changes to take effect, you need to clean and rebuild
core-image-base. Otherwise, the changes to acpi-tables are not copied
to the initramfs on the image.

  % bitbake -c clean core-image-base
  % bitbake core-image-base

When you are adding your own devices, it is important that you look at
the original ACPI tables of the board in question. Typically host
controllers, like SPI and I2C, might have different path from board to
board.

When you are adding you own devices remember that paths and devices
(host controller, like SPI and I2C) differ from board to board so it is
important that you look at the actual ACPI tables of the board in
question. For example here is one way you can dissasemble ACPI DSDT
table.

Run this on the target machine (acpidump is included with this meta
layer):

  # acpidump -o acpi.dump

Copy this file to your host (you can use SSH for example). Then on the
host you can run:

  % acpixtract acpi.dump
  % iasl -d dsdt.dat

The resulting dsdt.dsl contains ASL code of the DSDT table. By
inspecting this DSDT you should be able to figure out where to connect
your device.

IV. Sample ACPI tables
======================

Here is a description of the sample ACPI tables for each supported
board. You can use these directly by just specifying the filename in
ACPI_TABLES variable.

All these live under recipes-bsp/acpi-tables/samples directory.

Note, the *.asli files can be used in custom configurations when specific
devices are connected to the same platform.

Galileo Gen 2
-------------

Galileo Gen 2 has rather peculiar way of muxing pins. It uses several discrete
mux chips and GPIOs to control them. We provide gpiomux-*.asl files
which provide both names to GPIOs and pin muxing accordingly. User can
select which buses are muxed on the pins of the board.

On Galileo Gen 2 we can define an additional variable:

ACPI_FEATURES ?= ""

 *   MUX_I2C - This muxes out I2C from SCL/SDA pins of the board
 *   MUX_SPI - This muxes out SPI from pins I010/IO11/IO12/IO13 of the board
 *   MUX_UART0 - This muxes out UART0 from pins IO0/IO1
 *   MUX_UART1 - This muxes out UART1 from pins IO2/IO3

Depending on the features set (i2c, spi, uart0) `iasl` will compile the
asl with certain defines set 'MUX_UART0', 'MUX_I2C', 'MUX_SPI'.
This allows selecting features for tables from a higher level layer
by setting ACPI_FEATURES in the conf file.

  gpiomux.asl - Just adds names to GPIOs, no muxing is done, unless selected
                by ACPI_FEATURES
  gpiomux-i2c.asl - Adds names to GPIOs and muxes out native I2C.
  gpiomux-spi.asl - Adds names to GPIOs and muxes out native SPI.
  gpiomux-uart0.asl - Adds names to GPIOs and muxes out UART0.
  gpiomux-all.asl - Adds names to GPIOs and muxes out native
                    I2C, SPI and UART0.
  spidev.asl - Adds raw access SPI test device to the SPI bus using the
               GPIO chip select.
  at25.asl - Adds Atmel AT25 compatible 1k EEPROM device connected to
             the GPIO chip select.

Note this uses some features (like GPIO hogging) not yet available in
the mainline kernel. We are working to get these upstreamed.

Minnowboard
-----------

  buttons.asl - Adds GPIO buttons device for all 4 buttons available
                on the board.
  leds.asl - Adds GPIO LEDs device for the two user programmable LEDs
             available on the board and connects heartbeat and mmc
             triggers to them.

Minnowboard MAX / Turbot
------------------------

  at25.asl - Adds Atmel AT25 compatible 1k EEPROM device connected to
             the first chip select on the SPI bus of the low speed
             connector.
  m25p80.asl - Adds M25P80 compatible SPI-NOR flash connected to the
               first chip select on the SPI bus of the low speed
               connector.
  spidev.asl - Adds raw access SPI test device to the first chip select
               on the SPI bus of the low speed connector.
  leds.asl - Adds GPIO LEDs device for the D2 LED available on
             Minnowboard Turbot.

Joule
-----

  am2315.asl - Adds Aosong AM2315 temperature and humidity sensor to the
               first I2C bus available on breakout #1 header.
  at25.asl - Adds Atmel AT25 compatible 1k EEPROM device to the first
             chip select on the SPI bus of breakout #1 header.
  buttons.asl - Adds GPIO buttons device for the button labeled "GP BTN"
                on the board.
  i2c1.asl - Configures the first I2C bus to use 100 kHz standard mode
             instead of the default 400 kHz.
  isl29125.asl - Adds Intersil isl29125 RGB color sensor to the second
                 I2C bus available on Intel Joule Gumstix Sensor board.
  leds.asl - Adds GPIO LEDs device for all 4 user programmable LEDs on
             the board. First and second LEDs have default triggers for
             hearbeat and mmc respectively.
  spidev0.asl - Adds raw access SPI test device to the first chip
                select on the SPI bus of breakout #1 header.
  spidev2.asl - Adds raw access SPI test device to the third chip
                select on the SPI bus of breakout #1 header.

Edison
------

On Edison we define an additional variable:

ACPI_FEATURES_edison ?= "uart_2w spi i2c"

Depending on the features set `iasl` will compile the asl with certain
defines set 'MUX_UART_2WIRE', MUX_UART_4WIRE', 'MUX_I2C', 'MUX_SPI'.
This works will when building chainloadable tables. For the solution
tables (combination of multiple function into one table), suitable
defines have already been set and ACPI_FEATURES_edison should be unset:

ACPI_FEATURES_edison = ""

Chainloadable:
  74x164.asl -  This adds 74X164 8-bits shift register GPIO expander to the SPI
                host controller available on Edison I/O connector.
  arduino.asl - Adds Edison/Arduino board external muxes and level translators
                and depending on defines enables UART in 2W or 4W mode,
                I2C-6 and SPI.
  leds.asl -    Requires arduino.asl without "spi". Without this table
                the Edison-Arduino ds2 LED can be toggled from user space,
                with this table is controlled by the kernel. The default
                trigger is 'heartbeat'.
  pca9633.asl - This adds NXP PCA9633 LED to the I2C6 bus available on
                Edison/Arduino header. Requires arduino.asl.
  spidev.asl -  This adds raw SPI test device to the SPI host controller
                available on Edison I/O connector.

Solution:
  adafruit-mi0283qt.asl - Provides support for Adafruit 2.8" TFT display with
                capacitive touchscreen and micro-SD card slot on Edison/Arduino
                board with I2c and SPI enabled.
  arduino-all.asl - Adds arduino board external muxes and level translators
                with enabled UART in 4W mode, I2C-6 and SPI.
  arduino-audio-no-codec.asl - Enables I²C and I²S musing on Edison/Arduino to
                be able to use for audio without any codec connected.
  arduino-leds-ds2.asl - Combined arduino and leds in one solution table. By default
                no defines are set.
  enc28j60.asl - Combined arduino with support for Microchip ENC28J60 ethernet on
                Edison/Arduino board with SPI enabled.
  hd44780.asl - Combined arduino with support for 16x2 HD44780 Character LCD
                to the GPIOs available on Edison/Arduino header with I2C and SPI
                enabled.
  sparkfun-ssd1306.asl - Combined SSD1306 and buttons found on SparkFun DEV-13035
                addition card.