.. SPDX-License-Identifier: GPL-2.0+

Summary
=======

The Kontron SMARC-sAL28 board is a TSN-enabled dual-core ARM A72
processor module with an on-chip 6-port TSN switch and a 3D GPU.


Quickstart
==========

Compile U-Boot
--------------

Configure and compile the binary::

 $ make kontron_sl28_defconfig
 $ CROSS_COMPILE=aarch64-linux-gnu make

Copy u-boot.rom to a TFTP server.

Install the bootloader on the board
-----------------------------------

Please note, this bootloader doesn't support the builtin watchdog (yet),
therefore you have to disable it, see below. Otherwise you'll end up in
the failsafe bootloader on every reset::

 > tftp path/to/u-boot.rom
 > sf probe 0
 > sf update $fileaddr 0x210000 $filesize

The board is fully failsafe, you can't break anything. But because you've
disabled the builtin watchdog you might have to manually enter failsafe
mode by asserting the ``FORCE_RECOV#`` line during board reset.

Disable the builtin watchdog
----------------------------

- boot into the failsafe bootloader, either by asserting the
  ``FORCE_RECOV#`` line or if you still have the original bootloader
  installed you can use the command::

  > wdt dev cpld_watchdog@4a; wdt expire 1

- in the failsafe bootloader use the "sl28 nvm" command to disable
  the automatic start of the builtin watchdog::

  > sl28 nvm 0008

- power-cycle the board


Useful I2C tricks
=================

The board has a board management controller which is not supported in
u-boot (yet). But you can use the i2c command to access it.

- reset into failsafe bootloader::

  > i2c mw 4a 5.1 0; i2c mw 4a 6.1 6b; i2c mw 4a 4.1 42

- read board management controller version::

  > i2c md 4a 3.1 1


Non-volatile Board Configuration Bits
=====================================

The board has 16 configuration bits which are stored in the CPLD and are
non-volatile. These can be changed by the `sl28 nvm` command.

===  ===============================================================
Bit  Description
===  ===============================================================
  0  Power-on inhibit
  1  Enable eMMC boot
  2  Enable watchdog by default
  3  Disable failsafe watchdog by default
  4  Clock generator selection bit 0
  5  Clock generator selection bit 1
  6  Disable CPU SerDes clock #2 and PCIe-A clock output
  7  Disable PCIe-B and PCIe-C clock output
  8  Keep onboard PHYs in reset
  9  Keep USB hub in reset
 10  Keep eDP-to-LVDS converter in reset
 11  Enable I2C stuck recovery on I2C PM and I2C GP busses
 12  Enable automatic onboard PHY H/W reset
 13  reserved
 14  Used by the RCW to determine boot source
 15  Used by the RCW to determine boot source
===  ===============================================================

Please note, that if the board is in failsafe mode, the bits will have the
factory defaults, ie. all bits are off.

Power-On Inhibit
----------------

If this is set, the board doesn't automatically turn on when power is
applied. Instead, the user has to either toggle the ``PWR_BTN#`` line or
use any other wake-up source such as RTC alarm or Wake-on-LAN.

eMMC Boot
---------

If this is set, the RCW will be fetched from the on-board eMMC at offset
1MiB. For further details, have a look at the `Reset Configuration Word
Documentation`_.

Watchdog
--------

By default, the CPLD watchdog is enabled in failsafe mode. Using bits 2 and
3, the user can change its mode or disable it altogether.

=====  =====  ===============================
Bit 2  Bit 3  Description
=====  =====  ===============================
    0      0  Watchdog enabled, failsafe mode
    0      1  Watchdog disabled
    1      0  Watchdog enabled, failsafe mode
    1      1  Watchdog enabled, normal mode
=====  =====  ===============================

Clock Generator Select
----------------------

The board is prepared to supply different SerDes clock speeds. But for now,
only setting 0 is supported, otherwise the CPU will hang because the PLL
will not lock.

Clock Output Disable And Keep Devices In Reset
----------------------------------------------

To safe power, the user might disable different devices and clock output of
the board. It is not supported to disable the "CPU SerDes clock #2" for
now, otherwise the CPU will hang because the PLL will not lock.

Automatic reset of the onboard PHYs
-----------------------------------

By default, there is no hardware reset of the onboard PHY. This is because
for Wake-on-LAN, some registers have to retain their values. If you don't
use the WOL feature and a soft reset of the PHY is not enough you can
enable the hardware reset. The onboard PHY hardware reset follows the
power-on reset.


Further documentation
=====================

- `Vendor Documentation`_
- `Reset Configuration Word Documentation`_

.. _Reset Configuration Word Documentation: https://raw.githubusercontent.com/kontron/rcw-smarc-sal28/master/README.md
.. _Vendor Documentation: https://raw.githubusercontent.com/kontron/u-boot-smarc-sal28/master/board/kontron/sl28/README.md