README: add the initial README.md

Add the initial description and instructions for this repo.

Signed-off-by: Bill Mills <[email protected]>

README.md

@@ -0,0 +1,175 @@
+# OpenAMP Demo Support
+
+This repo contains:
+* Integrations for various demos (demos/)
+  + TFTP dir creation for reference boards
+  + SD card creation for reference boards
+  + scripts to run the demos
+  + boot support and user guidance messages
+  + pre-built images built from
+    * openamp-ci-builds (Linux side)
+    * openamp-system-reference (RTOS side)
+* Tools and scripts for use by demos (qemu-zcu102/)
+  + qemu-zcu102 script and support for running a Zynqmp QEMU model
+  + make-image-targets script for manipulating cpio and sdcard images
+* Docker container build support (docker/)
+  + Makefile is the main starting point for local builds
+  + build-containers.sh is automation for building multi architecture containers
+
+**NOTE**: This repo uses git-lfs for storage of the large software images.  You
+will need git-lfs installed to use this repo.
+
+A basic setup can be done on Ubuntu via:
+
+```
+$ sudo apt install git git-lfs fakeroot u-boot-tools mtools make
+$ mkdir -p XXXX; cd XXXX
+$ git clone https://github.com/OpenAMP/openamp-demo.git
+$ cd openamp-demo
+```
+
+## Create SD card images
+
+The following will create the demo sdcard images when starting for the cloned
+directory:
+
+```
+$ cd demos/demo-r5-combo
+$ ../../qemu-zcu102/bin/make-image-targets . sdcard
+$ cd ../demo-kv260
+$ ../../qemu-zcu102/bin/make-image-targets . sdcard
+$ cd ../demo-stm32mp157c-dk2
+$ ../../qemu-zcu102/bin/make-image-targets . sdcard
+```
+
+## Create docker images locally
+
+You will need to setup for docker usage.  An example for Ubuntu is as follows:
+
+```
+$ sudo apt install docker.io
+$ sudo adduser $USER docker
+```
+
+**NOTE**: log out and back in to get the docker group
+
+The following will create the demo container images when starting for the cloned
+directory:
+
+```
+$ cd docker
+$ make
+```
+
+The openamp/demo-lite:latest and openamp/demo:latest images will be created on
+your machine.  They can be run as documented as:
+
+```
+$ docker run -it --rm openamp/demo-lite
+```
+
+## Setup to run qemu-zcu102 locally
+
+In the future we will add an "install" command to qemu-zcu102 to make this easy.
+For now this procedure can be followed.
+
+Install our build of Xilinx QEMU locally:
+
+```
+$ cd
+$ sudo apt install tmux socat cpio libpixman-1-0 libslirp0 file
+$ wget https://github.com/wmamills/xen-rt-exp-images/raw/main/host/x86_64/qemu-xilinx-v2024.1.tar.gz
+$ mkdir -p ~/opt/qemu/
+$ tar xzf qemu-xilinx-v2024.1.tar.gz -C ~/opt/qemu
+```
+
+Make qemu-zcu102 and make-image-targets available from anywhere:
+
+```
+$ mkdir -p ~/.local/bin
+$ ln -s ~/XXXX/openamp-demo/qemu-zcu102/bin/{qemu-zcu102,make-image-targets} ~/.local/bin/.
+```
+
+**NOTE**: $ Alternatively you can use ~/bin instead of ~/.local/bin.  In either
+case ensure the directory is in PATH.  On Ubuntu with stock .bashrc, just log
+out and the directory will have been added to the PATH.
+
+Setup to use our QEMU for qemu-zcu102:
+
+```
+$ ln -s ~/opt/qemu/qemu-xilinx-v2024.1/bin/qemu-system-{aarch64,microblazeel} \
+    ~/XXXX/openamp-demo/qemu-zcu102/sysroot/usr/bin/.
+```
+
+Test as follows:
+```
+$ qemu-zcu102 ~/XXXX/openamp-demo/demos/demo1
+```
+
+## Create multi architecture container images
+
+**NOTE**: I will investigate buildx to do this step in the future.  It will be
+easier to setup as it uses QEMU user mode to run the arm64 container build.
+For now we use a real arm64 machine to build and test the container.
+
+Requirements:
+* AWS account with
+  + local access configuration
+  + a ssh key registered with the EC2 region used
+  + at least one EC2 security group in the EC2 region that allows ssh access
+* aws cli v1
+* Bill's ec2 script
+* docker push access to the openamp account
+
+Machine setup:
+
+**NOTE**: the instructions below will be improved to avoid the use
+of --break-system-packages.
+
+```
+$ sudo apt install python3-venv python3-pip
+$ pip3 install --user --break-system-packages awscli
+$ mkdir -p ~/opt/; cd ~/opt
+$ git clone https://github.com/wmamills/cloudbuild.git
+$ mkdir -p ~/.local/bin
+$ ln -s ~/opt/cloudbuild/ec2 ~/.local/bin/.
+$
+$ cat ~/.aws/config
+[default]
+region=us-east-2
+
+$ cat ~/.aws/credentials
+[default]
+aws_secret_access_key = AAaA1Aa11AAA1aaa11aaaaaaaaAAA11/1aaAAaaA
+aws_access_key_id = AAAAAAAAAAAAAAAAAA1A
+
+$ cat ~/.prjinfo/setenv
+# The key and security groups must be setup in the EC2 region
+
+: ${EC2_KEYPAIR_NAME:=my_ec2_key_name}
+: ${EC2_SEC_GROUPS:=ssh}
+
+$ mkdir -p ~/.ssh/config.d
+$ mv ~/.ssh/config ~/.ssh/config.orig
+$ echo "Include config.d/*" >~/.ssh/config.head
+$ cat ~/.ssh/config.head ~/.ssh/config.orig >~/.ssh/config
+$
+$ cat ~/.docker/config.json
+{
+    "auths": {
+        "https://index.docker.io/v1/": {
+            "auth": "a1AaaaAaaAaaaAa1aAAaaA1a1aA1AAaaaaAaaAAaaaa="
+        }
+    }
+}
+
+$ # test as follows
+$ ec2 status
+```
+
+Run the build with today's date as a tag:
+
+```
+$ cd ~/XXXX/openamp-demo/docker
+$ ./build-containers.sh ec2-all
+```