github.com/f-secure-foundry/tamago@v0.0.0-20220307101044-d73fcdd7f11b/README.md (about)

     1  TamaGo - bare metal Go for ARM SoCs
     2  ===================================
     3  
     4  tamago | https://github.com/f-secure-foundry/tamago  
     5  
     6  Copyright (c) F-Secure Corporation  
     7  https://foundry.f-secure.com
     8  
     9  ![TamaGo gopher](https://github.com/f-secure-foundry/tamago/wiki/images/tamago.svg?sanitize=true)
    10  
    11  Authors
    12  =======
    13  
    14  Andrea Barisani  
    15  andrea.barisani@f-secure.com | andrea@inversepath.com  
    16  
    17  Andrej Rosano  
    18  andrej.rosano@f-secure.com   | andrej@inversepath.com  
    19  
    20  Introduction
    21  ============
    22  
    23  TamaGo is a framework that enables compilation and execution of unencumbered Go
    24  applications on bare metal ARM System-on-Chip (SoC) components.
    25  
    26  The projects spawns from the desire of reducing the attack surface of embedded
    27  systems firmware by removing any runtime dependency on C code and Operating
    28  Systems.
    29  
    30  The TamaGo framework consists of the following components:
    31  
    32   - A modified [Go distribution](https://github.com/f-secure-foundry/tamago-go)
    33     which extends `GOOS` support to the `tamago` target, allowing bare metal
    34     execution.
    35  
    36   - Go packages for SoC driver support.
    37  
    38   - Go packages for board support.
    39  
    40  The modifications are meant to be minimal for both the Go distribution (< ~4000
    41  LOC changed) and the target application (one import required), with a clean
    42  separation from other architectures.
    43  
    44  Strong emphasis is placed on code re-use from existing architectures already
    45  included within the standard Go runtime, see
    46  [Internals](https://github.com/f-secure-foundry/tamago/wiki/Internals).
    47  
    48  Both aspects are motivated by the desire of providing a framework that allows
    49  secure Go firmware development on embedded systems.
    50  
    51  Current release level
    52  =====================
    53  [![GitHub release](https://img.shields.io/github/v/release/f-secure-foundry/tamago-go)](https://github.com/f-secure-foundry/tamago-go/tree/latest) [![Build Status](https://github.com/f-secure-foundry/tamago-go/workflows/Build%20Go%20compiler/badge.svg)](https://github.com/f-secure-foundry/tamago-go/actions)
    54  
    55  The current release for the [TamaGo modified Go distribution](https://github.com/f-secure-foundry/tamago-go) is
    56  [tamago1.17.8](https://github.com/f-secure-foundry/tamago-go/tree/tamago1.17.8),
    57  which [adds](https://github.com/golang/go/compare/go1.17.8...f-secure-foundry:tamago1.17.8)
    58  `GOOS=tamago` support to go1.17.8.
    59  
    60  Binary releases for amd64 and armv7l Linux hosts [are available](https://github.com/f-secure-foundry/tamago-go/releases/latest).
    61  
    62  Documentation
    63  =============
    64  
    65  The main documentation can be found on the
    66  [project wiki](https://github.com/f-secure-foundry/tamago/wiki).
    67  
    68  The package API documentation can be found on
    69  [pkg.go.dev](https://pkg.go.dev/github.com/f-secure-foundry/tamago).
    70  
    71  Supported hardware
    72  ==================
    73  
    74  The following table summarizes currently supported SoCs and boards.
    75  
    76  | SoC           | Board                                                                                                                                                                                | SoC package                                                                   | Board package                                                                                          |
    77  |---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
    78  | NXP i.MX6ULZ  | [USB armory Mk II](https://github.com/f-secure-foundry/usbarmory/wiki)                                                                                                               | [imx6](https://github.com/f-secure-foundry/tamago/tree/master/soc/imx6)       | [usbarmory/mark-two](https://github.com/f-secure-foundry/tamago/tree/master/board/f-secure/usbarmory)  |
    79  | NXP i.MX6ULL  | [MCIMX6ULL-EVK](https://www.nxp.com/design/development-boards/i-mx-evaluation-and-development-boards/evaluation-kit-for-the-i-mx-6ull-and-6ulz-applications-processor:MCIMX6ULL-EVK) | [imx6](https://github.com/f-secure-foundry/tamago/tree/master/soc/imx6)       | [mx6ullevk](https://github.com/f-secure-foundry/tamago/tree/master/board/nxp/mx6ullevk)                |
    80  | BCM2835       | [Raspberry Pi Zero](https://www.raspberrypi.org/products/raspberry-pi-zero)                                                                                                          | [bcm2835](https://github.com/f-secure-foundry/tamago/tree/master/soc/bcm2835) | [pi/pizero](https://github.com/f-secure-foundry/tamago/tree/master/board/raspberrypi)                  |
    81  | BCM2835       | [Raspberry Pi 1 Model A+](https://www.raspberrypi.org/products/raspberry-pi-1-model-a-plus/)                                                                                         | [bcm2835](https://github.com/f-secure-foundry/tamago/tree/master/soc/bcm2835) | [pi/pi1](https://github.com/f-secure-foundry/tamago/tree/master/board/raspberrypi)                     |
    82  | BCM2835       | [Raspberry Pi 1 Model B+](https://www.raspberrypi.org/products/raspberry-pi-1-model-b-plus/)                                                                                         | [bcm2835](https://github.com/f-secure-foundry/tamago/tree/master/soc/bcm2835) | [pi/pi1](https://github.com/f-secure-foundry/tamago/tree/master/board/raspberrypi)                     |
    83  | BCM2836       | [Raspberry Pi 2 Model B](https://www.raspberrypi.org/products/raspberry-pi-2-model-b)                                                                                                | [bcm2835](https://github.com/f-secure-foundry/tamago/tree/master/soc/bcm2835) | [pi/pi2](https://github.com/f-secure-foundry/tamago/tree/master/board/raspberrypi)                     |
    84  
    85  Compiling
    86  =========
    87  
    88  Go applications are simply required to import, the relevant board package to
    89  ensure that hardware initialization and runtime support takes place:
    90  
    91  ```golang
    92  import (
    93  	// Example for USB armory Mk II
    94  	_ "github.com/f-secure-foundry/tamago/board/f-secure/usbarmory/mark-two"
    95  )
    96  ```
    97  
    98  Build the [TamaGo compiler](https://github.com/f-secure-foundry/tamago-go)
    99  (or use the [latest binary release](https://github.com/f-secure-foundry/tamago-go/releases/latest)):
   100  
   101  ```
   102  wget https://github.com/f-secure-foundry/tamago-go/archive/refs/tags/latest.zip
   103  unzip latest.zip
   104  cd tamago-go-latest/src && ./all.bash
   105  cd ../bin && export TAMAGO=`pwd`/go
   106  ```
   107  
   108  Go applications can be compiled with the compiler built in the previous step,
   109  with the addition of a few flags/variables:
   110  
   111  ```
   112  # Example for USB armory Mk II
   113  GO_EXTLINK_ENABLED=0 CGO_ENABLED=0 GOOS=tamago GOARM=7 GOARCH=arm \
   114    ${TAMAGO} build -ldflags "-T 0x80010000  -E _rt0_arm_tamago -R 0x1000"
   115  ```
   116  
   117  See the respective board package README file for compilation information for
   118  each specific target.
   119  
   120  Executing and debugging
   121  =======================
   122  
   123  See the respective board package README file for execution and debugging
   124  information for each specific target (real or emulated).
   125  
   126  The [example application](https://github.com/f-secure-foundry/tamago-example)
   127  provides sample driver usage and instructions for native as well as emulated
   128  execution.
   129  
   130  License
   131  =======
   132  
   133  tamago | https://github.com/f-secure-foundry/tamago  
   134  Copyright (c) F-Secure Corporation
   135  
   136  These source files are distributed under the BSD-style license found in the
   137  [LICENSE](https://github.com/f-secure-foundry/tamago/blob/master/LICENSE) file.
   138  
   139  The TamaGo logo is adapted from the Go gopher designed by Renee French and
   140  licensed under the Creative Commons 3.0 Attributions license. Go Gopher vector
   141  illustration by Hugo Arganda.