ePenguin-Software-Framework/README.md

# ePenguin Software Framework

## Overview
This only works for x86\_64 linux machines atm. Windows development is in progress. I have no idea how to go about testing for mac so... yeah.

As of right now, only the *new* command works. Everything else is not implemented yet. However, *new* does most of the heavy lifting so the other commands will come quickly once it is finished and polished.

## Prerequisites

You need the following things installed for igloo+eSF to work properly:
 - openocd
 - rust (nightly preferred becuase it's just better)
 - toolchains (more below)

In the future, these things will just be bundled with eSF. The problem with some toolchains is dependency matching for various distros.

**Update on Toolchains**: The toolchains were a pain to maintain, and still are. That's why for the time being, the toolchains will not be bundled with esf. It is a goal to get the toolchains bundled with esf, but development of the esf libraries are most important right now.

### Toolchains

Loose naming convention for toolchains:<br>
`<arch>-<vendor>-<target os>-<host os>-<abi>`

- arm-none-eabi:
	- Toolchain targetting the embedded ABI for arm
	- Debian/Ubuntu:<br>
		`
		sudo apt-get install gcc-arm-none-eabi binutils-arm-none-eabi gdb-arm-none-eabi
		`
	- **NOTE:** If you run into an issue when running arm-none-eabi-gdb where it needs libncurses.so.5 on Ubuntu/Debian, install this package:<br>
		`
		sudo apt-get install libncurses5
		`

	- Arch:<br>
		`
		sudo pacman -S arm-none-eabi-binutils arm-none-eabi-gcc arm-none-eabi-gdb arm-none-eabi-newlib
		`

	- Gentoo:
		- See this wiki [here](https://wiki.gentoo.org/wiki/How_to_build_a_toolchain_for_arm_cortex-m_and_cortex-r).

- avr-\*
	- Ubuntu/Debian: (To be added)
	- Arch:<br>
		`
		sudo pacman -S avr-binutils avr-gcc avr-gdb avr-libc avrdude
		`

	- Gentoo:
		- Install via [crossdev](https://wiki.gentoo.org/wiki/Crossdev):<br>
			`
			crossdev -s4 --stable --portage --verbose --target avr
			`

#### OpenOCD

It is recommended that you download the zip here:
https://github.com/xpack-dev-tools/openocd-xpack/releases

Otherwise, you can install it from your package manager:

Arch
```
sudo pacman -S openocd
```

Debian/Ubuntu
```
sudo apt install openocd
```

Gentoo
```
sudo emerge -a openocd
```


#### Rustlang

Doesn't get any easier than this: https://www.rust-lang.org/tools/install

If you're on gentoo, I recommend using rust-bin. You likely don't need these instructions, but [here](https://wiki.gentoo.org/wiki/User:Vazhnov/Knowledge_Base:replace_rust_with_rust-binhttps://wiki.gentoo.org/wiki/User:Vazhnov/Knowledge_Base:replace_rust_with_rust-bin) they are just in case.

### Instructions for testing

**WARNING**: DO NOT COPY AND PASTE THESE INSTRUCTIONS. READ THROUGH THEM.

```
cd ~

# get igloo + esf
git clone https://git.epenguin.net/ePenguin/ePenguin-Software-Framework.git
git clone https://git.epenguin.net/ePenguin/ePenguin-Igloo.git

chmod -R u+x ~/ePenguin-Software-Framework/
chmod -R u+x ~/ePenguin-Igloo/
export ESF_DIR=~/ePenguin-Software-Framework

alias igloo_rls=~/ePenguin-Igloo/target/release/igloo
alias igloo_dbg=~/ePenguin-Igloo/target/debug/igloo
alias igloo=igloo_dbg

# Building
cd ~/ePenguin-Igloo

# Debug build is default
cargo build

# For release build
# cargo build --release

igloo
```

You should see a help menu thrown at you for more instruction.

I've aliased igloo_dbg for igloo, but you can use the release version if you want better performance and faster compile times. It is highly recommended to use the debug version right now, though.

### Generating a new project
```
igloo new <project_name> --target=<mcu>
# Example
igloo new testproject --target=samd21j18a
```

### Instructions for building
The framework comes with compilers so no external dependencies are needed. There are unfortunately no libraries yet because I want to nail igloo, the project manager, with certainty first.

```
cd <project_name>/.igloo/target/
make
```

### Instructions for running
I'm not including these steps because openocd releases vary with target configs. I recommend you download a release from https://openocd.org and unzip it there. Downloading via a package manager almost guarantees you're going to be missing target scripts.

At some point in the future, I'm going to fork openocd just so I can make sure default board config scripts are 100% available because right now it's really hit or miss on various distros.

for the e54 xplained
```
openocd -f board/atmel_same54_xplained_pro.cfg
```

for the d21 xplained
```
openocd -f board/atmel_samd21_xplained_pro.cfg
```

If the E54 xplained cfg isn't found for some reason, try this:
```
echo "
#
# Atmel SAME54 Xplained Pro evaluation kit.
#

source [find interface/cmsis-dap.cfg]
transport select swd
# chip name
set CHIPNAME same54p20a
source [find target/atsame5x.cfg]
" > same54.cfg

openocd -f same54.cfg
```
Now in another terminal:
```
cd <project_dir>/igloo/targets/same54p20a/
make
arm-none-eabi-gdb -iex "target extended-remote localhost:3333" testdir.elf
load
monitor reset
```

If you're using gdb with python extensions then use this instead
```
arm-none-eabi-gdb -iex "target extended-remote localhost:3333" testdir.elf
```

### Supported Targets

The framework allows me to add support for mcus pretty rapidly. I can add entire families of mcus with a few lines in the manifests. For now I've added support for mcus I use, but I'll be adding support for every Microchip SAM mcu shortly, as well as SiFive MCUs and STM32 MCUs.
### Status Guide
| Icon               | Description         |
| ---                | ---                 |
| :exclamation:      | In Development      |
| :grey_question:    | Unstable            |
| :question:         | Experimental        |
| :white_check_mark: | Stable              |

#### ARM32

| MCU Series         |        Status |
|:------------|--------------:|
| SAMD21A | :question: |
| SAME54A | :question: |
| SAME70A | :exclamation: |

#### AVR

| MCU Series | Status |
|:------------|--------------:|
| XMEGAA | :exclamation: |
| MEGA | :exclamation: |