Add some README and cleanup

README.md

@@ -0,0 +1,18 @@
+# rp2040tools
+
+This repo contains all the tools used by Arduino to upload compiled code to the boards that use the rp2040 processor.
+The repo includes also the dependencies and the Dockerfile used to crosscompile the tools.
+
+## Tools
+
+- [**picotool**](https://github.com/raspberrypi/picotool): a tool for interacting with a RP2040 device in BOOTSEL mode, or with a RP2040 binary
+- [**elf2uf2**](https://github.com/raspberrypi/pico-sdk/tree/master/tools/elf2uf2): a tool to convert binary format
+- **rp2040load** is a go tool which orchestrates the other two
+
+## CI
+The CI is responsible for building and uploading the tools
+The [release workflow](https://github.com/arduino/rp2040tools/blob/master/.github/workflows/release.yml) is divided in:
+
+- a job which uses a docker container (called crossbuild) with all the toolchains inside required to cross-compile the two tools from raspberry pi. The binaries produced are as static and self-contained as possible.
+- a job that cross-compiles the go tool called rp2040load.
+- one last job used to move in the correct folders the binaries and to `tar.bz2` them and upload them in the [github release page](https://github.com/arduino/rp2040tools/releases) and on s3 download server.

Dockerfile → docker/Dockerfile

@@ -3,7 +3,6 @@ FROM ubuntu:latest as build
 ENV TZ=Europe/Rome
 RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone && \
     apt-get update && \
-    # TODO add --no-install-recommends
     apt-get install -y \
         build-essential \
         # Intall clang compiler used by macos
@@ -17,13 +16,11 @@ RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone &
         libxml2-dev \
         libssl-dev \
         libz-dev \
-        # liblzma5 \
         # Install Windows cross-tools
         mingw-w64 \
         p7zip-full \
         pkg-config \
         tar \
-        # xz-utils \
     && rm -rf /var/lib/apt/lists/*
 # Install toolchains in /opt
 RUN curl downloads.arduino.cc/tools/internal/toolchains.tar.gz | tar -xz "opt"

docker/README.md

@@ -0,0 +1,38 @@
+# Docker crossbuild
+
+This docker container has been created to allow us to easily crosscompile the c++ tools starting from this repo. The idea comes from [multiarch/crossbuild](https://github.com/multiarch/crossbuild), but this container unfortunately is outdated, the apt sources are no longer available.
+
+## Starting Image
+The starting image is [ubuntu:latest](https://hub.docker.com/_/ubuntu) (The ubuntu:latest tag points to the "latest LTS", since that's the version recommended for general use.) at the time of writing latest points to Ubuntu 20.04 focal.
+
+The starting image is only marginally important, since internally we use manually installed toolchains.
+
+## The Toolchains
+The toolchains are download from http://downloads.arduino.cc/tools/internal/toolchains.tar.gz .
+Inside that archive there are:
+- **gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu** toolchain to crosscompile for *linux_arm64* (downloaded from [here](https://developer.arm.com/-/media/Files/downloads/gnu-a/8.3-2019.03/binrel/gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu.tar.xz))
+- **gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf** toolchain used to crosscompile for *linux_arm* (downloaded from [here](https://developer.arm.com/-/media/Files/downloads/gnu-a/8.3-2019.03/binrel/gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf.tar.xz))
+- **i686-ubuntu16.04-linux-gnu** toolchain to crosscompile for *linux_386* (32bit)
+- **x86_64-ubuntu16.04-linux-gnu-gcc** toolchain to crosscompile for *linux_amd64*
+- [**osxcross**](https://github.com/tpoechtrager/osxcross) toolchain to crosscompile for *darwin_amd64*. Inside `osxcross/tarballs/` there is already `MacOSX10.15.sdk.tar.xz`: the SDK required by macos to crosscompile (we tried with SDK version 10.09 but it was too old)
+
+Regarding the two ubuntu toolchains: in the beginning we tried to use the ones shipped with 12.04 but they caused some build errors because they were too old, so we upgraded to 16.04 ones. They are created using [crosstool-ng](https://github.com/crosstool-ng/crosstool-ng).
+
+
+Apparently, osxcross does not have tags or version so we checkout a specific commit in order to have a pinned environment.
+
+The last toolchain required to crosscompile for windows is `mingw-w64` and it's installed through `apt` along with other useful packages.
+
+Once the toolchains are installed in `/opt` we add the binaries to the `PATH` env variable, to easily call them in the CI.
+
+## Copying and Building Libraries
+As explained in the other [`README.md`](deps/README.md) there are some libraries that needs to be compiled. This is achieved by copying `deps/` directory inside `/opt/lib/` in the container and then by using [`build_libs.sh`](deps/build_libs.sh) script [here](Dockerfile#L47-L55)
+
+## Multi-stage build
+To reduce the overall dimesion of the docker image we used the  [multi-stage build](https://learnk8s.io/blog/smaller-docker-images). 
+
+## How to build and use the container
+Usefull commands you can use:
+- `docker build -t ghcr.io/arduino/crossbuild:<version> docker/` to build the container
+- `docker push ghcr.io/arduino/crossbuild:<version>` to push the image to [github remote registry](https://docs.github.com/en/packages/guides/container-guides-for-github-packages)
+- `docker run -it --name crossbuild -v $PWD:/workdir ghcr.io/arduino/crossbuild:<version>` to get a shell inside the container and use the toolchains available inside (like the CI does).

docker/deps/README.md

@@ -0,0 +1,47 @@
+# Dependencies
+The `deps/` folder contains the dependencies used to build and link statically `picotool` and `elf2uf2`: the libraries `libusb` and `libudev`.
+The `deps/` folder contains also a bash script used by the docker container to successfully build them with different toolchains and with different targets.
+This way they are already compiled and usable by the CI during the building/linking phase!
+
+They come respectively from [here](https://github.com/arduino/OpenOCD-build-script/tree/static/libusb-1.0.20)
+and from [here](https://github.com/gentoo/eudev)
+
+## `build_libs.sh`
+`build_libs.sh` is used by the [Dockerfile](../Dockerfile#L49-L55):
+Basically during the docker build phase the libraries are compiled with every toolchain available in the Docker container. Other libraries can be added, the [`build_libs.sh`](build_libs.sh) script needs to be adapted, but the Dockerfile should be ok.
+
+## libusbudev
+libusbudev is the result of merging the two `.a` files with a command line tool called `ar`. This is done to ease the linking phase done by the [CI](.github/workflows/release.yml#L87) passing a single static library. See `LIBUSBUDEV` env variable [here](../../.github/workflows/release.yml#L67) and [here](../../.github/workflows/release.yml#L71).
+For macos is not required to merge the two libraries because libudev is not a requirement, so macos uses `libusb.a` only: thus the distinction between the two platforms. Infact libusb for mac is the last one built in the [Dockerfile](../Dockerfile#L55).
+
+`libusbudev.a` is created by the `build_libs.sh` the directory structure created is the following:
+
+```
+/opt/lib/
+|-- aarch64-linux-gnu
+|   |-- libudev
+|   |-- libusb
+|   `-- libusbudev.a
+|-- arm-linux-gnueabihf
+|   |-- libudev
+|   |-- libusb
+|   `-- libusbudev.a
+|-- build_libs.sh
+|-- eudev-3.2.10
+|-- i686-ubuntu16.04-linux-gnu
+|   |-- libudev
+|   |-- libusb
+|   `-- libusbudev.a
+|-- i686-w64-mingw32
+|   |-- libudev
+|   |-- libusb
+|   `-- libusbudev.a
+|-- libusb-1.0.20
+`-- x86_64-ubuntu16.04-linux-gnu
+    |-- libudev
+    |-- libusb
+    `-- libusbudev.a
+```
+
+The original `libusb.a` is available in `/opt/lib/libusb-1.0.20/libusb/.libs/libusb-1.0.a`
+and `libudev.a` is available in `/opt/lib/eudev-3.2.10/src/libudev/.libs/libudev.a`