Add zero-install openocd binaries and support files, add documentation (#145)

Author: Robert Muchsel

.python-version

@@ -1 +1 @@
-3.8.9
+3.8.10

README.md

@@ -1,6 +1,6 @@
 # MAX78000 Model Training and Synthesis
 
-_June 30, 2021_
+_July 1, 2021_
 
 The Maxim Integrated AI project is comprised of five repositories:
 
@@ -412,7 +412,7 @@ if [ $? -eq 1 ] ; then
 fi
 ```
 
-The debugger requires OpenOCD. On Windows, an OpenOCD executable is installed with the SDK. On macOS and Linux, the OpenOCD fork from [https://github.com/MaximIntegratedMicros/openocd.git](https://github.com/MaximIntegratedMicros/openocd.git) must be used. An x86_64 Ubuntu Linux binary is available at https://github.com/MaximIntegratedAI/MAX78000_SDK/blob/master/Tools/OpenOCD/openocd. *Note: A copy of the configuration files and a `run-openocd-maxdap` script are contained in the `hardware` folder of the `ai8x-synthesis` project.*
+The debugger requires OpenOCD. On Windows, an OpenOCD executable is installed with the SDK. On macOS and Linux, scripts and binaries are provided in the `openocd` folder of the `ai8x-synthesis` project, see [openocd/Readme.md](openocd/Readme.md).
 
 `gen-demos-max78000.sh` will create code that is compatible with the SDK and copy it into the SDK’s Example directories.
 

README.pdf

@@ -0,0 +1,46 @@
+# Development on Raspberry Pi 4 and 400
+
+*July 1, 2021*
+
+### Requirements and Performance
+
+Software development for MAX78000 is possible on a 64-bit Raspberry Pi OS with the following restrictions:
+
+* A 64-bit OS is required, since the embedded C compiler and PyTorch are only available for 64-bit systems. While the Raspberry Pi 3 does have a 64-bit CPU, the Raspberry Pi 4 and 400 with fan are strongly recommended for performance reasons.
+  As operating system, use either https://downloads.raspberrypi.org/raspios_lite_arm64/images/
+  or https://downloads.raspberrypi.org/raspios_arm64/images/.
+* Performance for running the synthesis tools is bounded by disk I/O. Consider using a USB 3-connected SSD as mass storage, since I/O performance on SD cards and USB Flash drives will suffer from long latencies.
+* The installation will take more time than on an x86_64 system, since more Python “wheels” have to be built from source during installation compared to x86_64.
+* Since there is no CUDA on Raspberry Pi, model training will be very slow and a CPU fan is required.
+
+### Installation
+
+First, install the following additional packages on the Raspberry Pi:
+
+```shell
+$ sudo apt-get install screen libtool git libusb-1.0-0-dev libgpiod-dev libhidapi-dev \
+libftdi-dev zip libbz2-dev libssl-dev libreadline-dev libsqlite3-dev libatlas-base-dev \
+libopenblas-dev libopenmpi-dev libomp-dev libncurses5 ninja-build cmake ccache \
+libblas-dev libeigen3-dev libprotobuf-dev protobuf-compiler llvm-dev
+```
+
+Then follow the instructions for Ubuntu Linux.
+
+#### OpenOCD
+
+The pre-built binary in the `openocd` folder of the `ai8x-synthesis` project works with MAX78000.
+
+To avoid having to use superuser privileges to run OpenOCD, follow the instructions on https://forgge.github.io/theCore/guides/running-openocd-without-sudo.html.
+
+#### Embedded Arm Compiler
+
+The embedded C compiler version 10-2020-q4-major for “aarch64” works on Raspberry Pi OS 64-bit (`gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2`).
+
+#### Embedded RISC-V Compiler
+
+The embedded C compiler version v10.1.0-1.1 for “arm64” works on Raspberry Pi OS 64-bit (`xpack-riscv-none-embed-gcc-10.1.0-1.1-linux-arm64.tar.gz`).
+
+#### Training and Synthesis Projects
+
+Both model training and C code generation will work on a Raspberry Pi 64-bit. Note that model training will be very slow without CUDA.
+

docs/RaspberryPi.md

@@ -0,0 +1,67 @@
+# Pre-built OpenOCD
+
+For your convenience, this folder contains the files and binaries needed to run OpenOCD for MAX78000 on macOS Catalina/Big Sur and on Ubuntu Linux 20.04 LTS, as well as 32-bit and 64-bit Raspberry Pi OS 10 “Buster”.
+
+
+
+#### Using the Pre-built OpenOCD Binaries
+
+The `run-openocd-maxdap` and `run-openocd-olimex` scripts automatically select an appropriate binary and run OpenOCD with all arguments required for MAX78000.
+
+##### Linux
+
+On Linux, several packages are required:
+
+```shell
+$ sudo apt-get install libusb-1.0 libusb-0.1 libhidapi-libusb0 libhidapi-hidraw0
+```
+
+##### macOS
+
+On macOS, both the command line developer tools and Homebrew must be installed. Follow the instructions to set up your shell.
+
+```shell
+% xcode-select --install
+% bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+The following additional packages are also required:
+
+```shell
+% brew install libusb-compat libftdi hidapi libusb
+```
+
+
+
+#### Building from Scratch
+
+To obtain the full OpenOCD source code, and to re-build the binaries, please use `git clone https://github.com/MaximIntegratedMicros/openocd.git`. 
+
+##### Linux
+
+```shell
+$ ./bootstrap
+$ ./configure  # Linux only, see below for macOS
+$ make
+$ sudo make install  # or use binary from src/
+```
+
+##### macOS
+
+On macOS, the following packages are needed to build the binary:
+
+```shell
+% brew install autoconf autoconf-archive automake libtool pkg-config
+```
+
+You may need to add arguments to `./configure`. The exact paths may vary depending on the MacOSX.sdk release.
+
+```shell
+% autoreconf -i -I /opt/homebrew/share/aclocal  # on M1 only, and ignore errors
+% ./bootstrap
+% CFLAGS=-D_FTDI_DISABLE_DEPRECATED ./configure --prefix=/Library/Developer/CommandLineTools/usr \
+--with-gxx-include-dir=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/c++/v1
+% make
+% sudo make install  # or use binary from src/
+```
+