github.com/usbarmory/tamago@v0.0.0-20240508072735-8612bbe1e454/board/nxp/mx6ullevk/README.md (about)

     1  TamaGo - bare metal Go for ARM SoCs - MCIMX6ULL-EVK support
     2  ===========================================================
     3  
     4  tamago | https://github.com/usbarmory/tamago  
     5  
     6  Copyright (c) WithSecure Corporation  
     7  https://foundry.withsecure.com
     8  
     9  ![TamaGo gopher](https://github.com/usbarmory/tamago/wiki/images/tamago.svg?sanitize=true)
    10  
    11  Authors
    12  =======
    13  
    14  Andrea Barisani  
    15  andrea.barisani@withsecure.com | andrea@inversepath.com  
    16  
    17  Andrej Rosano  
    18  andrej.rosano@withsecure.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/RISC-V System-on-Chip (SoC) components.
    25  
    26  The [mx6ullevk](https://github.com/usbarmory/tamago/tree/master/board/nxp/mx6ullevk)
    27  package provides support for the [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) development board.
    28  
    29  Documentation
    30  =============
    31  
    32  For more information about TamaGo see its
    33  [repository](https://github.com/usbarmory/tamago) and
    34  [project wiki](https://github.com/usbarmory/tamago/wiki).
    35  
    36  For the underlying driver support for this board see package
    37  [imx6ul](https://github.com/usbarmory/tamago/tree/master/soc/nxp/imx6ul).
    38  
    39  The package API documentation can be found on
    40  [pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/tamago).
    41  
    42  Supported hardware
    43  ==================
    44  
    45  | SoC          | Board                                                                                                                                                                                | SoC package                                                              | Board package                                                                    |
    46  |--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------|
    47  | 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) | [imx6ul](https://github.com/usbarmory/tamago/tree/master/soc/nxp/imx6ul) | [mx6ullevk](https://github.com/usbarmory/tamago/tree/master/board/nxp/mx6ullevk) |
    48  
    49  Compiling
    50  =========
    51  
    52  Go applications are simply required to import, the relevant board package to
    53  ensure that hardware initialization and runtime support takes place:
    54  
    55  ```golang
    56  import (
    57  	_ "github.com/usbarmory/tamago/board/nxp/mx6ullevk"
    58  )
    59  ```
    60  
    61  Build the [TamaGo compiler](https://github.com/usbarmory/tamago-go)
    62  (or use the [latest binary release](https://github.com/usbarmory/tamago-go/releases/latest)):
    63  
    64  ```
    65  wget https://github.com/usbarmory/tamago-go/archive/refs/tags/latest.zip
    66  unzip latest.zip
    67  cd tamago-go-latest/src && ./all.bash
    68  cd ../bin && export TAMAGO=`pwd`/go
    69  ```
    70  
    71  Go applications can be compiled as usual, using the compiler built in the
    72  previous step, but with the addition of the following flags/variables and
    73  ensuring that the required SoC and board packages are available in `GOPATH`:
    74  
    75  ```
    76  GO_EXTLINK_ENABLED=0 CGO_ENABLED=0 GOOS=tamago GOARM=7 GOARCH=arm \
    77    ${TAMAGO} build -ldflags "-T 0x80010000 -E _rt0_arm_tamago -R 0x1000"
    78  ```
    79  
    80  An example application, targeting the MCIMX6ULL-EVK platform,
    81  is [available](https://github.com/usbarmory/tamago-example).
    82  
    83  Executing and debugging
    84  =======================
    85  
    86  The [example application](https://github.com/usbarmory/tamago-example)
    87  provides reference usage and a Makefile target for automatic creation of an ELF
    88  as well as `imx` image for flashing.
    89  
    90  Native hardware: imx image over USB
    91  -----------------------------------
    92  
    93  Follow [the SDP procedure](https://github.com/usbarmory/usbarmory/wiki/Boot-Modes-(Mk-II)#serial-download-protocol-sdp)
    94  using the built `imx` image.
    95  
    96  Native hardware: imx image on microSD
    97  -------------------------------------
    98  
    99  Copy the built `imx` image to a microSD as follows:
   100  
   101  ```
   102  sudo dd if=<path to imx file> of=/dev/sdX bs=1M conv=fsync
   103  ```
   104  *IMPORTANT*: /dev/sdX must be replaced with your microSD device (not eventual
   105  microSD partitions), ensure that you are specifying the correct one. Errors in
   106  target specification will result in disk corruption.
   107  
   108  Ensure the `SW601` boot switches on the processor board are set to microSD boot
   109  mode:
   110  
   111  | switch | position |
   112  |--------|----------|
   113  | 1      | OFF      |
   114  | 2      | OFF      |
   115  | 3      | ON       |
   116  | 4      | OFF      |
   117  
   118  Standard output
   119  ---------------
   120  
   121  The standard output can be accessed through the debug console found
   122  on micro USB connector J1901 and the following `picocom` configuration:
   123  
   124  ```
   125  picocom -b 115200 -eb /dev/ttyUSB0 --imap lfcrlf
   126  ```
   127  
   128  Debugging
   129  ---------
   130  
   131  The application can be debugged with GDB over JTAG using `openocd` (version >
   132  0.11.0) and the `gdbinit` debugging helper published
   133  [here](https://github.com/usbarmory/tamago/tree/master/_dev).
   134  
   135  ```
   136  # start openocd daemon
   137  openocd -f interface/ftdi/jtagkey.cfg -f target/imx6ul.cfg -c "adapter speed 1000"
   138  
   139  # connect to the OpenOCD command line
   140  telnet localhost 4444
   141  
   142  # debug with GDB
   143  arm-none-eabi-gdb -x gdbinit example
   144  ```
   145  
   146  Hardware breakpoints can be set in the usual way:
   147  
   148  ```
   149  hb ecdsa.Verify
   150  continue
   151  ```
   152  
   153  QEMU
   154  ----
   155  
   156  The target can be executed under emulation as follows:
   157  
   158  ```
   159  qemu-system-arm \
   160  	-machine mcimx6ul-evk -cpu cortex-a7 -m 512M \
   161  	-nographic -monitor none -serial null -serial stdio -net none \
   162  	-kernel example -semihosting
   163  ```
   164  
   165  The emulated target can be debugged with GDB by adding the `-S -s` flags to the
   166  previous execution command, this will make qemu waiting for a GDB connection
   167  that can be launched as follows:
   168  
   169  ```
   170  arm-none-eabi-gdb -ex "target remote 127.0.0.1:1234" example
   171  ```
   172  
   173  Breakpoints can be set in the usual way:
   174  
   175  ```
   176  b ecdsa.Verify
   177  continue
   178  ```
   179  
   180  License
   181  =======
   182  
   183  tamago | https://github.com/usbarmory/tamago  
   184  Copyright (c) WithSecure Corporation
   185  
   186  These source files are distributed under the BSD-style license found in the
   187  [LICENSE](https://github.com/usbarmory/tamago/blob/master/LICENSE) file.
   188  
   189  The TamaGo logo is adapted from the Go gopher designed by Renee French and
   190  licensed under the Creative Commons 3.0 Attributions license. Go Gopher vector
   191  illustration by Hugo Arganda.