README
¶
TamaGo - bare metal Go for ARM SoCs - i.MX 6UL support
tamago | https://github.com/usbarmory/tamago
Copyright (c) WithSecure Corporation
https://foundry.withsecure.com
Authors
Andrea Barisani
andrea.barisani@withsecure.com | andrea@inversepath.com
Andrej Rosano
andrej.rosano@withsecure.com | andrej@inversepath.com
Introduction
TamaGo is a framework that enables compilation and execution of unencumbered Go applications on bare metal ARM/RISC-V System-on-Chip (SoC) components.
The imx6ul package provides support for the NXP i.MX 6UL series of System-on-Chip (SoCs) parts.
Documentation
For TamaGo see its repository and project wiki for information.
The package API documentation can be found on pkg.go.dev.
Supported hardware
| SoC | Related board packages | Peripheral drivers |
|---|---|---|
| NXP i.MX 6ULZ/i.MX6UL | usbarmory/mk2 | BEE, CAAM, CSU, DCP, ENET, GPIO, I2C, OCOTP, RNGB, TEMPMON, UART, USB, USDHC, WDOG, GIC, TZASC |
| NXP i.MX 6ULL/i.MX6ULZ | nxp/mx6ullevk | BEE, CAAM, CSU, DCP, ENET, GPIO, I2C, OCOTP, RNGB, TEMPMON, UART, USB, USDHC, WDOG, GIC, TZASC |
License
tamago | https://github.com/usbarmory/tamago
Copyright (c) WithSecure Corporation
These source files are distributed under the BSD-style license found in the LICENSE file.
The TamaGo logo is adapted from the Go gopher designed by Renee French and licensed under the Creative Commons 3.0 Attributions license. Go Gopher vector illustration by Hugo Arganda.
Documentation
¶
Overview ¶
Package imx6ul provides support to Go bare metal unikernels, written using the TamaGo framework, on the NXP i.MX6UL family of System-on-Chip (SoC) application processors.
The package implements initialization and drivers for NXP i.MX6UL/i.MX6ULL/i.MX6ULZ SoCs, adopting the following reference specifications:
- IMX6ULCEC - i.MX6UL Data Sheet - Rev 2.2 2015/05
- IMX6ULLCEC - i.MX6ULL Data Sheet - Rev 1.2 2017/11
- IMX6ULZCEC - i.MX6ULZ Data Sheet - Rev 0 2018/09
- IMX6ULRM - i.MX 6UL Applications Processor Reference Manual - Rev 1 2016/04
- IMX6ULLRM - i.MX 6ULL Applications Processor Reference Manual - Rev 1 2017/11
- IMX6ULZRM - i.MX 6ULZ Applications Processor Reference Manual - Rev 0 2018/10
This package is only meant to be used with `GOOS=tamago GOARCH=arm` as supported by the TamaGo framework for bare metal Go on ARM SoCs, see https://github.com/usbarmory/tamago.
Index ¶
- Constants
- Variables
- func ARMCoreDiv() (div float32)
- func ARMFreq() (hz uint32)
- func ARMPLLDiv() (div float32)
- func Debug(enable bool)
- func EnableENETPLL(index int) (err error)
- func EnableUSBPLL(index int) (err error)
- func GetHighFrequencyClock() uint32
- func GetPFD(pll int, pfd int) (div uint32, hz uint32)
- func GetPeripheralClock() uint32
- func GetUARTClock() uint32
- func GetUSDHCClock(index int) (podf uint32, clksel uint32, clock uint32)
- func Init()
- func Model() (model string)
- func PersistSecondaryBoot(enable bool)
- func Reset()
- func SetARMFreq(mhz uint32) (err error)
- func SetPFD(pll uint32, pfd uint32, div uint32) error
- func SetUSDHCClock(index int, podf uint32, clksel uint32) (err error)
- func SetWarmReset(enable bool)
- func SiliconVersion() (sv, family, revMajor, revMinor uint32)
- func UniqueID() (uid [8]byte)
Constants ¶
const ( CCM_CACRR = 0x020c4010 CACRR_ARM_PODF = 0 CCM_CBCDR = 0x020c4014 CBCDR_IPG_PODF = 8 CCM_CSCDR1 = 0x020c4024 CSCDR1_USDHC2_PODF = 16 CSCDR1_USDHC1_PODF = 11 CSCDR1_UART_CLK_SEL = 6 CSCDR1_UART_CLK_PODF = 0 CCM_CSCMR1 = 0x020c401c CSCMR1_USDHC2_CLK_SEL = 17 CSCMR1_USDHC1_CLK_SEL = 16 CSCMR1_PERCLK_SEL = 6 CSCMR1_PERCLK_PODF = 0 CCM_ANALOG_PLL_ARM = 0x020c8000 PLL_LOCK = 31 PLL_BYPASS = 16 PLL_BYPASS_CLK_SRC = 14 PLL_ENABLE = 13 PLL_POWER = 12 PLL_DIV_SELECT = 0 CCM_ANALOG_PLL_USB1 = CCM_ANALOG_PLL_ARM + 0x10 CCM_ANALOG_PLL_USB2 = CCM_ANALOG_PLL_ARM + 0x20 PLL_EN_USB_CLKS = 6 CCM_ANALOG_PLL_ENET = CCM_ANALOG_PLL_ARM + 0xe0 PLL_ENET2_125M_EN = 20 PLL_ENET1_125M_EN = 13 PLL_ENET1_DIV_SELECT = 2 PLL_ENET0_DIV_SELECT = 0 CCM_ANALOG_PFD_480 = 0x020c80f0 CCM_ANALOG_PFD_528 = 0x020c8100 ANALOG_PFD3_CLKGATE = 31 ANALOG_PFD3_FRAC = 24 ANALOG_PFD2_CLKGATE = 23 ANALOG_PFD2_FRAC = 16 ANALOG_PFD1_CLKGATE = 15 ANALOG_PFD1_FRAC = 8 ANALOG_PFD0_CLKGATE = 7 ANALOG_PFD0_FRAC = 0 PMU_REG_CORE = 0x020c8140 CORE_REG2_TARG = 18 CORE_REG0_TARG = 0 CCM_CCGR0 = 0x020c4068 CCM_CCGR1 = 0x020c406c CCM_CCGR2 = 0x020c4070 CCM_CCGR3 = 0x020c4074 CCM_CCGR5 = 0x020c407c CCM_CCGR6 = 0x020c4080 CCGRx_CG15 = 30 CCGRx_CG14 = 28 CCGRx_CG13 = 26 CCGRx_CG12 = 24 CCGRx_CG11 = 22 CCGRx_CG10 = 20 CCGRx_CG9 = 18 CCGRx_CG8 = 16 CCGRx_CG7 = 14 CCGRx_CG6 = 12 CCGRx_CG5 = 10 CCGRx_CG4 = 8 CCGRx_CG3 = 6 CCGRx_CG2 = 4 CCGRx_CG1 = 2 CCGRx_CG0 = 0 )
Clock registers
const ( IOMUXC_GPR_GPR1 = 0x020e4004 ENET2_TX_CLK_DIR = 18 ENET1_TX_CLK_DIR = 17 ENET2_CLK_SEL = 14 ENET1_CLK_SEL = 13 )
const ( OSC_FREQ = 24000000 PLL2_FREQ = 528000000 PLL3_FREQ = 480000000 )
Oscillator frequencies
const ( FreqMax = Freq900 Freq900 = 900 Freq792 = 792 Freq528 = 528 Freq396 = 396 Freq198 = 198 FreqLow = Freq198 )
Operating ARM core frequencies in MHz (care must be taken as not all P/Ns support the entire range) (p24, Table 10. Operating Ranges, IMX6ULLCEC).
const ( IPG_FREQ = 66000000 AHB_FREQ = 132000000 )
Clocks at boot time (p261, Table 8-4. Normal frequency clocks configuration, IMX6ULLRM)
const ( IOMUXC_GPR_GPR10 = 0x020e4028 GPR10_DBG_CLK_EN = 1 GPR10_DBG_EN = 0 )
const ( // Bus Encryption Engine (UL only) BEE_BASE = 0x02044000 // Cryptographic Acceleration and Assurance Module (UL only) CAAM_BASE = 0x02140000 // Central Security Unit CSU_BASE = 0x021c0000 // Data Co-Processor (ULL/ULZ only) DCP_BASE = 0x02280000 // General Interrupt Controller GIC_BASE = 0x00a00000 // General Purpose I/O GPIO1_BASE = 0x0209c000 GPIO2_BASE = 0x020a0000 GPIO3_BASE = 0x020a4000 GPIO4_BASE = 0x020a8000 GPIO5_BASE = 0x020ac000 // Ethernet MAC (UL/ULL only) ENET1_BASE = 0x02188000 ENET2_BASE = 0x020b4000 // Ethernet MAC interrupts ENET1_IRQ = 32 + 118 ENET2_IRQ = 32 + 120 // I2C I2C1_BASE = 0x021a0000 I2C2_BASE = 0x021a4000 // Multi Mode DDR Controller MMDC_BASE = 0x80000000 // On-Chip OTP Controller OCOTP_BASE = 0x021bc000 OCOTP_BANK_BASE = 0x021bc400 // On-Chip Random-Access Memory OCRAM_START = 0x00900000 OCRAM_SIZE = 0x20000 // True Random Number Generator (ULL/ULZ only) RNGB_BASE = 0x02284000 // Secure Non-Volatile Storage SNVS_HP_BASE = 0x020cc000 SNVS_LP_BASE = 0x020b0000 // Temperature Monitor TEMPMON_BASE = 0x020c8180 // TrustZone Address Space Controller TZASC_BASE = 0x021d0000 TZASC_BYPASS = 0x020e4024 GPR1_TZASC1_BOOT_LOCK = 23 // Serial ports UART1_BASE = 0x02020000 UART2_BASE = 0x021e8000 UART3_BASE = 0x021ec000 UART4_BASE = 0x021f0000 // USB 2.0 controller USB_ANALOG1_BASE = 0x020c81a0 USB_ANALOG2_BASE = 0x020c8200 USB_ANALOG_DIGPROG = 0x020c8260 USBPHY1_BASE = 0x020c9000 USBPHY2_BASE = 0x020ca000 USB1_BASE = 0x02184000 USB2_BASE = 0x02184200 // USB 2.0 controller interrupts USB1_IRQ = 32 + 43 USB2_IRQ = 32 + 42 // SD/MMC USDHC1_BASE = 0x02190000 USDHC2_BASE = 0x02194000 // Watchdog Timers WDOG1_BASE = 0x020bc000 WDOG2_BASE = 0x020c0000 WDOG3_BASE = 0x021e4000 // Watchdog Timer interrupts WDOG1_IRQ = 32 + 80 WDOG2_IRQ = 32 + 81 WDOG3_IRQ = 32 + 11 )
Peripheral registers
const ( IMX6UL = 0x64 IMX6ULL = 0x65 )
i.MX processor families
const ( SRC_SCR = 0x020d8000 SCR_WARM_RESET_ENABLE = 0 SRC_GPR10 = SRC_SCR + 0x44 GPR10_PERSIST_SECONDARY_BOOT = 30 )
System Reset Controller registers
const SYS_CNT_BASE = 0x021dc000
Timer registers (p178, Table 2-3, IMX6ULLRM)
Variables ¶
var ( // ARM core ARM = &arm.CPU{} // Bus Encryption Engine (UL only) BEE *bee.BEE // Cryptographic Acceleration and Assurance Module (UL only) CAAM *caam.CAAM // Central Security Unit CSU = &csu.CSU{ Base: CSU_BASE, CCGR: CCM_CCGR1, CG: CCGRx_CG14, } // Data Co-Processor (ULL/ULZ only) DCP *dcp.DCP // Generic Interrupt Controller GIC = &gic.GIC{ Base: GIC_BASE, } // GPIO controller 1 GPIO1 = &gpio.GPIO{ Index: 1, Base: GPIO1_BASE, CCGR: CCM_CCGR1, CG: CCGRx_CG13, } // GPIO controller 2 GPIO2 = &gpio.GPIO{ Index: 2, Base: GPIO2_BASE, CCGR: CCM_CCGR0, CG: CCGRx_CG15, } // GPIO controller 3 GPIO3 = &gpio.GPIO{ Index: 3, Base: GPIO3_BASE, CCGR: CCM_CCGR2, CG: CCGRx_CG13, } // GPIO controller 4 GPIO4 = &gpio.GPIO{ Index: 4, Base: GPIO4_BASE, CCGR: CCM_CCGR3, CG: CCGRx_CG6, } // GPIO controller 5 GPIO5 = &gpio.GPIO{ Index: 5, Base: GPIO5_BASE, CCGR: CCM_CCGR1, CG: CCGRx_CG15, } // Ethernet MAC 1 (UL/ULL only) ENET1 *enet.ENET ENET2 *enet.ENET // I2C controller 1 I2C1 = &i2c.I2C{ Index: 1, Base: I2C1_BASE, CCGR: CCM_CCGR2, CG: CCGRx_CG3, } // I2C controller 2 I2C2 = &i2c.I2C{ Index: 2, Base: I2C2_BASE, CCGR: CCM_CCGR2, CG: CCGRx_CG5, } // On-Chip OTP Controller OCOTP = &ocotp.OCOTP{ Base: OCOTP_BASE, BankBase: OCOTP_BANK_BASE, CCGR: CCM_CCGR2, CG: CCGRx_CG6, } // True Random Number Generator (ULL/ULZ only) RNGB *rngb.RNGB // Secure Non-Volatile Storage SNVS = &snvs.SNVS{ Base: SNVS_HP_BASE, CCGR: CCM_CCGR5, CG: CCGRx_CG9, } // Temperature Monitor TEMPMON = &tempmon.TEMPMON{ Base: TEMPMON_BASE, } // TrustZone Address Space Controller TZASC = &tzc380.TZASC{ Base: TZASC_BASE, Bypass: TZASC_BYPASS, SecureBootLockReg: IOMUXC_GPR_GPR1, SecureBootLockPos: GPR1_TZASC1_BOOT_LOCK, } // Serial port 1 UART1 = &uart.UART{ Index: 1, Base: UART1_BASE, CCGR: CCM_CCGR5, CG: CCGRx_CG12, Clock: GetUARTClock, } // Serial port 2 UART2 = &uart.UART{ Index: 2, Base: UART2_BASE, CCGR: CCM_CCGR0, CG: CCGRx_CG14, Clock: GetUARTClock, } // USB controller 1 USB1 = &usb.USB{ Index: 1, Base: USB1_BASE, CCGR: CCM_CCGR6, CG: CCGRx_CG0, Analog: USB_ANALOG1_BASE, PHY: USBPHY1_BASE, IRQ: USB1_IRQ, EnablePLL: EnableUSBPLL, } // USB controller 2 USB2 = &usb.USB{ Index: 2, Base: USB2_BASE, CCGR: CCM_CCGR6, CG: CCGRx_CG0, Analog: USB_ANALOG2_BASE, PHY: USBPHY2_BASE, IRQ: USB2_IRQ, EnablePLL: EnableUSBPLL, } // SD/MMC controller 1 USDHC1 = &usdhc.USDHC{ Index: 1, Base: USDHC1_BASE, CCGR: CCM_CCGR6, CG: CCGRx_CG1, SetClock: SetUSDHCClock, } // SD/MMC controller 2 USDHC2 = &usdhc.USDHC{ Index: 2, Base: USDHC2_BASE, CCGR: CCM_CCGR6, CG: CCGRx_CG2, SetClock: SetUSDHCClock, } // Watchdog Timer 1 WDOG1 = &wdog.WDOG{ Index: 1, Base: WDOG1_BASE, CCGR: CCM_CCGR3, CG: CCGRx_CG8, IRQ: WDOG1_IRQ, } // Watchdog Timer 2 WDOG2 = &wdog.WDOG{ Index: 2, Base: WDOG2_BASE, CCGR: CCM_CCGR5, CG: CCGRx_CG5, IRQ: WDOG2_IRQ, } // TrustZone Watchdog TZ_WDOG = WDOG2 // Watchdog Timer 3 WDOG3 = &wdog.WDOG{ Index: 3, Base: WDOG3_BASE, CCGR: CCM_CCGR6, CG: CCGRx_CG10, IRQ: WDOG3_IRQ, } )
Peripheral instances
var ( // Processor family Family uint32 // Flag native or emulated processor Native bool // SDP flags whether Serial Download Protocol over USB has been used to // boot this runtime. The value is always false on non-secure (e.g. // TrustZone Normal World) processor modes. SDP bool )
Functions ¶
func ARMCoreDiv ¶
func ARMCoreDiv() (div float32)
ARMCoreDiv returns the ARM core divider value (p665, 18.6.5 CCM Arm Clock Root Register, IMX6ULLRM).
func ARMPLLDiv ¶
func ARMPLLDiv() (div float32)
ARMPLLDiv returns the ARM PLL divider value (p714, 18.7.1 Analog ARM PLL control Register, IMX6ULLRM).
func Debug ¶
func Debug(enable bool)
Debug controls ARM invasive and non-invasive debug functionalities.
func EnableENETPLL ¶
EnableENETPLL enables the Ethernet MAC 50MHz PLL.
func EnableUSBPLL ¶
EnableUSBPLL enables the USBPHY0 480MHz PLL.
func GetHighFrequencyClock ¶
func GetHighFrequencyClock() uint32
GetHighFrequencyClock returns the PERCLK_CLK_ROOT frequency, (p629, Figure 18-2. Clock Tree - Part 1, IMX6ULLRM).
func GetPFD ¶
GetPFD returns the fractional divider and frequency in Hz of a PLL PFD (p734, 18.7.15 480MHz Clock (PLL3) Phase Fractional Divider Control Register, IMX6ULLRM) (p736, 18.7.16 480MHz Clock (PLL2) Phase Fractional Divider Control Register, IMX6ULLRM).
func GetPeripheralClock ¶
func GetPeripheralClock() uint32
GetPeripheralClock returns the IPG_CLK_ROOT frequency, (p629, Figure 18-2. Clock Tree - Part 1, IMX6ULLRM).
func GetUARTClock ¶
func GetUARTClock() uint32
GetUARTClock returns the UART_CLK_ROOT frequency, (p630, Figure 18-3. Clock Tree - Part 2, IMX6ULLRM).
func GetUSDHCClock ¶
GetUSDHCClock returns the USDHCx_CLK_ROOT clock by reading CSCMR1[USDHCx_CLK_SEL] and CSCDR1[USDHCx_PODF] (p629, Figure 18-2. Clock Tree - Part 1, IMX6ULLRM)
func Init ¶
func Init()
Init takes care of the lower level SoC initialization triggered early in runtime setup (e.g. runtime.hwinit).
func PersistSecondaryBoot ¶
func PersistSecondaryBoot(enable bool)
PersistSecondaryBoot controls whether the primary (false) or secondary boot image (true) should be selected after a software reset.
func Reset ¶
func Reset()
Reset asserts the global watchdog reset causing the SoC to restart with a cold reset.
Note that only the SoC itself is guaranteed to restart as, depending on the board hardware layout, the system might remain powered (which might not be desirable). See respective board packages for cold reset options.
func SetARMFreq ¶
SetARMFreq changes the ARM core frequency, see `Freq*` constants for supported values. This function allows overclocking as it does not verify P/N compatibility with the desired frequency.
func SetPFD ¶
SetPFD sets the fractional divider of a PPL PFD (p734, 18.7.15 480MHz Clock (PLL3) Phase Fractional Divider Control Register, IMX6ULLRM) (p736, 18.7.16 480MHz Clock (PLL2) Phase Fractional Divider Control Register, IMX6ULLRM).
func SetUSDHCClock ¶
SetUSDHCClock controls the USDHCx_CLK_ROOT clock by setting CSCMR1[USDHCx_CLK_SEL] and CSCDR1[USDHCx_PODF] (p629, Figure 18-2. Clock Tree - Part 1, IMX6ULLRM).
func SetWarmReset ¶
func SetWarmReset(enable bool)
SetWarmReset controls whether warm reset sources are enabled (true) or if they should generate a cold reset (false).
func SiliconVersion ¶
func SiliconVersion() (sv, family, revMajor, revMinor uint32)
SiliconVersion returns the SoC silicon version information (p3945, 57.4.11 Chip Silicon Version (USB_ANALOG_DIGPROG), IMX6ULLRM).
Types ¶
This section is empty.
Source Files