Skip to content

Internals

Andrea Barisani edited this page Feb 18, 2020 · 17 revisions

Key concepts

  • Go applications built with TamaGo run on bare metal, without any underlying OS. All required support is provided by the Go runtime and driver packages, also written in Go. The TamaGo ELF image is executed directly by a bootloader such as U-Boot, responsible for the initial hardware configuration.

Go compiler changes

  • TamaGo modifications to the Go Runtime are minimal to ease maintainability and potential upstream acceptance.

  • TamaGo support is implemented with a clean separation from other OSes, all modifications are conditional to compilation option GOOS=tamago and do not affect other architectures.

Go runtime changes

  • The core support is implemented in os_tamago_arm.go the supporting board drivers need to define the following functions to support the runtime:

    • hwinit()
    • printk(byte) to provide standard output (typically on a serial console) (example)
    • initRNG() to initialize random number generation (example)
    • getRandomData([]byte) to provide hardware backed random number generation (example)
    • nanotime() int64 to provide hardware based ticks (example)
  • The memory allocation is identical to plan9 with the exception of the brk call which is not required.

  • There is no support for threads, just like for Go NaCl or js/wasm, and locking is identical to js/wasm.

  • The only supported, and required, syscall is write which allows only stdout and stderr file descriptors.

  • The crypto/rand support is delegated to the supporting SoC driver, for example with the imx6 packages support for the [RNGB]((https://github.com/f-secure-foundry/tamago/tree/master/imx6/rngb.go) True Random Number Generator.

  • The file system support is identical to NaCl and provides a volatile in-memory emulated disk, the file descriptor support is therefore also identical to NaCl to support it.

Go application limitations

TamaGo is in early stages of development, the following limitations apply:

  • Almost every standard library package can be imported, with very few exceptions. It is likely that we missed some required stubs or +build tamago tags in certain packages that otherwise would work fine, if this happens please open a GitHub issue for us to fix.

  • Applications which import packages that rely on unsupported system calls will not compile (for instance terminal prompt packages will not be able to access syscall.SYS_IOCTL).

  • There is no thread support and GOMAXPROCS is fixed to 1, therefore remember to avoid starving the scheduler.

  • Just like Go js/wasm blocking functions which are not executed in a new goroutine, while no other goroutine is running, will cause a deadlock (similar to this and this. As long as you never sleep in your main() function without anything else going on this is quite natural to avoid.

  • Due to the intrinsic nature of a bare metal application: there is no OS, there are no users, there are no signals, there are no environment variables.

  • Currently only ARMv7 is supported with GOOS=tamago.

  • Importing libraries that require cgo triggers external linking, which is not supported. Internal linking is forced with GO_EXTLINK_ENABLED=0, however this entails that external functions (e.g. malloc()) will be referenced but not found. Therefore compiling C code with cgo is possible, however the C code must be self standing and without calls to external functions or system calls.

imx6

  • There are currently no media storage support drivers, file operations are done in volatile memory with an emulated filesystem.

  • There are currently no networking drivers, therefore I/O is limited to serial communication (console, BLE).

Memory layout

  +----------------------------------+ 0000 0000
  |                                  |
  |                                  |
  |                                  |
  |                                  |
  |                                  |
  +----------------------------------+ runtime.ramStart
  |                                  |
  |  INTERRUPT VECTOR TABLE (16 kB)  |
  |                                  |
  +----------------------------------+ runtime.ramStart + 0x4000 (16 kB)
  |                                  |
  |        L1 PAGE TABLE (16 kB)     |
  |                                  |
  +----------------------------------+ runtime.ramStart + 0x8000 (32 kB)
  |                                  |
  |       EXCEPTION STACK (16 kB)    |
  |                                  |
  +----------------------------------+ runtime.ramStart + 0xC000 (48 kB)
  |                                  |
  |           UNUSED (16 kB)         |
  |                                  |
  +----------------------------------+ runtime.ramStart + 0x10000 (64 kB)
  |                                  |
  | .text                            |
  |                                  |
  | .noptrdata                       |
  |                Go application    |
  | .data                            |
  |                                  |
  | .bss                             |
  |                                  |
  | .noptrbss                        |
  |                                  |
  +----------------------------------+
  |                                  |
  |                                  |
  |                                  |
  |                                  |
  |              HEAP                |
  |                                  |
  |                                  |
  |                                  |
  |                                  |
  +----------------------------------+ runtime.g0.stack.lo (runtime.go.stack.hi - 0x10000)
  |                                  |
  |                                  |
  |           STACK (64 kB)          |
  |                                  |
  |                                  |
  +----------------------------------+ runtime.go.stack.hi (runtime.ramStart + runtime.ramSize - runtime.stackOffset)
  |                                  |
  |             UNUSED               |
  |                                  |
  +----------------------------------+ runtime.ramStart + runtime.ramSize
  |                                  |
  |                                  |
  +----------------------------------+ FFFF FFFF

Board support packages

SoC support packages

Clone this wiki locally
You can’t perform that action at this time.