diff --git a/README.md b/README.md index 89c1686..bf5cf01 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,8 @@ # upsilon -Upsilon is a 100% free and open source STM/AFM controller for FPGAs. - -## Organization - -The project is split into hardware (`firmware`), kernel (`software`), -and client software (`client`). - -Hardware uses Verilog, LiteX and F4PGA to implement the Soft CPU (Risc-V), -hardware communication, PI control loop, image scanning, and tip autoapproach. - -Kernel implements the network communication between the hardware and the -client software. - -The client software receives and interprets data from the hardware. +Upsilon is a 100% free and open source STM/AFM controller for FPGAs running +Linux. ## License -GNU GPL v3.0 or later. Other portions are dual licensed under the CERN -OHL-v2-S, or permissive licenses: please view all `COPYING` files for more -legal information. - -## See also - -* SPI nodes -- +See `copying` folder for more information. diff --git a/build/Dockerfile.buildroot b/build/Dockerfile.buildroot new file mode 100644 index 0000000..7f98825 --- /dev/null +++ b/build/Dockerfile.buildroot @@ -0,0 +1,30 @@ +# Copyright 2023 Peter McGoron +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +FROM debian:bookworm + +RUN apt-get update \ + && apt-get -y upgrade \ + && apt-get install -y git wget xz-utils build-essential gcc g++ sed \ + make binutils diffutils bash patch gzip bzip2 perl tar cpio unzip \ + rsync bc findutils wget python3 libncurses5-dev libncurses-dev file \ + which \ + && adduser --quiet --disabled-password user + +USER user:user +WORKDIR /home/user +COPY --chown=user:user buildroot.tar.gz /home/user +RUN tar -xvf buildroot.tar.gz && rm buildroot.tar.gz diff --git a/build/Dockerfile.litex_f4pga b/build/Dockerfile.litex_f4pga new file mode 100644 index 0000000..3688e2d --- /dev/null +++ b/build/Dockerfile.litex_f4pga @@ -0,0 +1,52 @@ +# Copyright 2023 Peter McGoron +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +FROM debian:bookworm + +ENV FPGA_FAM=xc7 +ENV F4PGA_INSTALL_DIR=/home/user/conda + +RUN apt-get update \ + && apt-get -y upgrade \ + && apt-get install -y git wget python3 xz-utils bash verilator \ + m4 device-tree-compiler make gcc-riscv64-unknown-elf \ + && adduser --quiet --disabled-password user + +USER user:user +WORKDIR /home/user + +# F4PGA +COPY --chown=user:user scripts/install_f4pga_defs.sh /home/user +RUN chmod +x install_f4pga_defs.sh \ + && ./install_f4pga_defs.sh \ + && echo 'source ~/conda/xc7/conda/etc/profile.d/conda.sh' >> /home/user/.bashrc \ + && echo 'conda activate xc7' >> /home/user/.bashrc \ + && rm install_f4pga_defs.sh + +COPY --chown=user:user f4pga.tar.gz /home/user +RUN tar -xvf f4pga.tar.gz \ + && rm f4pga.tar.gz \ + && cd f4pga/f4pga \ + && bash -c 'source ~/conda/xc7/conda/etc/profile.d/conda.sh; conda activate xc7; pip install . ninja meson' + +#LITEX +COPY --chown=user:user litex/litex_setup.py /home/user +RUN mkdir /home/user/litex \ + && chmod +x litex_setup.py \ + && cd litex/ \ + && bash -c 'source ~/conda/xc7/conda/etc/profile.d/conda.sh; conda activate xc7; ../litex_setup.py --init --install --user --tag=2023.04' \ + && rm ../litex_setup.py + diff --git a/build/Dockerfile.opensbi b/build/Dockerfile.opensbi new file mode 100644 index 0000000..f67e962 --- /dev/null +++ b/build/Dockerfile.opensbi @@ -0,0 +1,35 @@ +# Copyright 2023 Peter McGoron +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +FROM debian:bookworm + +RUN apt-get update \ + && apt-get -y upgrade \ + && apt-get install -y make device-tree-compiler python3 \ + adduser gcc-riscv64-linux-gnu \ + && adduser --quiet --disabled-password user +#RUN apt-get update \ +# && apt-get -y upgrade \ +# && apt-get install -y git wget python3 xz-utils bash verilator \ +# m4 device-tree-compiler make gcc-riscv64-unknown-elf \ +# && adduser --quiet --disabled-password user + +USER user:user +WORKDIR /home/user + +COPY --chown=user:user opensbi.tar.gz /home/user +RUN tar -xvf opensbi.tar.gz \ + && rm ~/opensbi.tar.gz diff --git a/build/Dockerfile.verilator b/build/Dockerfile.verilator new file mode 100644 index 0000000..3d0fe97 --- /dev/null +++ b/build/Dockerfile.verilator @@ -0,0 +1,37 @@ +# Copyright 2023 Peter McGoron +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +FROM debian:bookworm + +RUN apt-get update \ + && apt-get -y upgrade \ + && apt-get install -y git perl python3 make autoconf g++ flex bison ccache \ + libgoogle-perftools-dev numactl perl-doc \ + libfl2 libfl-dev zlib1g zlib1g-dev help2man \ + && adduser --quiet --disabled-password user + +USER user:user +WORKDIR /home/user + +RUN git clone https://github.com/verilator/verilator \ + && cd verilator \ + && git checkout v5.010 \ + && autoconf \ + && ./configure \ + && make -j 6 +USER root:root +RUN cd /home/user/verilator && make install +USER user:user diff --git a/build/Makefile b/build/Makefile new file mode 100644 index 0000000..8259634 --- /dev/null +++ b/build/Makefile @@ -0,0 +1,160 @@ +# Copyright 2023 Peter McGoron +# +# SPDX-License-Identifier: Apache-2.0 + +.PHONY: images f4pga buildroot litex clone help attach hardware-image \ + buildroot-image litex-f4pga-image \ + upsilon-hardware.tar.gz upsilon-opensbi.tar.gz upsilon-buildroot.tar.gz + +###### Images + +images: hardware-image buildroot-image opensbi-image + + + +###### Containers + +### Hardware container + +hardware-image: + docker build -f Dockerfile.litex_f4pga -t "upsilon-litex-f4pga-env" . +hardware-container: + docker run -d --name upsilon-hardware upsilon-litex-f4pga-env /bin/sh -c 'while true; do sleep 2; done' +hardware-copy: upsilon-hardware.tar.gz + # XXX: this always fails if there are very high UIDs, but the + # file is copied successfully. + -docker cp upsilon-hardware.tar.gz upsilon-hardware:/home/user/upsilon-hardware.tar.gz +hardware-execute: + docker exec -ti upsilon-hardware /bin/bash -lc ' \ + tar -xvf upsilon-hardware.tar.gz && \ + cd upsilon/firmware && \ + source ~/conda/xc7/conda/etc/profile.d/conda.sh && \ + conda activate xc7 && \ + make clean && make' +hardware-shell: + docker exec -ti upsilon-hardware /bin/bash -l +hardware-get: + docker cp upsilon-hardware:/home/user/upsilon/firmware/build/digilent_arty/gateware/digilent_arty.bit ../boot/ + docker cp upsilon-hardware:/home/user/upsilon/firmware/arty.dtb ../boot/ + docker cp upsilon-hardware:/home/user/upsilon/firmware/csr.json ../boot/ +hardware-clean: + -docker container stop upsilon-hardware + -docker container rm upsilon-hardware + +### OpenSBI Container + +opensbi-image: opensbi.tar.gz + docker build -f Dockerfile.opensbi -t "upsilon-opensbi-env" . +opensbi-container: + docker run -d --name upsilon-opensbi upsilon-opensbi-env /bin/sh -c 'while true; do sleep 2; done' +opensbi-copy: upsilon-opensbi.tar.gz + -docker cp upsilon-opensbi.tar.gz upsilon-opensbi:/home/user/upsilon-opensbi.tar.gz +opensbi-get: + docker cp upsilon-opensbi:/home/user/opensbi/build/platform/litex/vexriscv/firmware/fw_jump.bin ../boot/ +opensbi-shell: + docker exec -ti upsilon-opensbi /bin/bash -l +opensbi-execute: + docker exec -ti upsilon-opensbi /bin/bash -c ' \ + tar -xvf upsilon-opensbi.tar.gz && \ + cd opensbi && \ + make clean && \ + make CROSS_COMPILE=riscv64-linux-gnu- PLATFORM=litex/vexriscv \ + ' +opensbi-clean: + -docker container stop upsilon-opensbi + -docker container rm upsilon-opensbi + +### Verilator Container + +verilator-image: + docker build -f Dockerfile.verilator -t "upsilon-verilator-env" . +verilator-container: + docker run -d --name upsilon-verilator upsilon-verilator-env /bin/sh -c 'while true; do sleep 2; done' +verilator-copy: upsilon-hardware.tar.gz + -docker cp upsilon-hardware.tar.gz upsilon-verilator:/home/user/upsilon-hardware.tar.gz +verilator-shell: + docker exec -ti upsilon-verilator /bin/bash -l +verilator-execute: + docker exec -ti upsilon-verilator /bin/bash -c ' \ + tar -xvf upsilon-hardware.tar.gz && \ + cd upsilon/firmware && \ + make clean && \ + make test \ + ' +verilator-clean: + -docker container stop upsilon-verilator + -docker container rm upsilon-verilator + +### Buildroot Container + +buildroot-image: buildroot.tar.gz + docker build -f Dockerfile.buildroot -t "upsilon-buildroot-env" . +buildroot-container: + docker run -d --name upsilon-buildroot upsilon-buildroot-env /bin/sh -c 'while true; do sleep 2; done' +buildroot-copy: upsilon-buildroot.tar.gz + -docker cp upsilon-buildroot.tar.gz upsilon-buildroot:/home/user/upsilon-buildroot.tar.gz +buildroot-shell: + docker exec -ti upsilon-buildroot /bin/bash -l +buildroot-get: + docker cp upsilon-buildroot:/home/user/buildroot/output/images/Image ../boot/ + docker cp upsilon-buildroot:/home/user/buildroot/output/images/rootfs.cpio ../boot/ +buildroot-execute: + docker exec -ti upsilon-buildroot /bin/bash -c ' \ + tar -xvf upsilon-buildroot.tar.gz && \ + cd buildroot && \ + make clean && \ + make BR2_EXTERNAL=../upsilon/buildroot litex_vexriscv_defconfig && \ + make ' +buildroot-clean: + -docker container stop upsilon-buildroot + -docker container rm upsilon-buildroot + +###### TFTP + +tftp: + cd upsilon/boot && py3tftp --host 192.168.1.100 -p 6969 -v + +###### External projects + +clone: f4pga buildroot litex opensbi + +f4pga: + if [ ! -d 'f4pga' ]; then \ + git clone https://github.com/chipsalliance/f4pga; \ + fi + cd f4pga && git checkout main && git pull && \ + git checkout -B upsilon_stable 835a40534f9efd70770d74f56f25fef6cfc6ebc6 \ + tar -czvf f4pga.tar.gz f4pga + +buildroot: + if [ ! -d 'buildroot' ]; then \ + git clone https://git.buildroot.org/buildroot; \ + fi + cd buildroot && git checkout master && git pull && \ + git checkout -B upsilon_stable 2023.02.1 + tar -czvf buildroot.tar.gz buildroot/ + +litex: + if [ ! -d 'litex' ]; then \ + git clone https://github.com/enjoy-digital/litex; \ + fi + cd litex && git checkout master && git pull && \ + git checkout -B upsilon_stable c6ccb626e88168045edacced3743f6bd98746742 + +upsilon-hardware.tar.gz: + tar -czvf upsilon-hardware.tar.gz ../firmware/ +upsilon-buildroot.tar.gz: + tar -czvf upsilon-buildroot.tar.gz ../buildroot/ +# This script only works for GNU tar. It renames the extraction directory. +upsilon-opensbi.tar.gz: + tar -czvf upsilon-opensbi.tar.gz ../opensbi/ --transform 's|opensbi|opensbi/platform|' + +opensbi: + if [ ! -d 'opensbi' ]; then \ + git clone https://github.com/riscv-software-src/opensbi; \ + fi + cd opensbi && git checkout master && git pull && \ + git checkout -B upsilon_stable v1.2 + +opensbi.tar.gz: + tar -czvf opensbi.tar.gz opensbi/ diff --git a/build/install_f4pga_defs.sh b/build/install_f4pga_defs.sh new file mode 100755 index 0000000..282de6a --- /dev/null +++ b/build/install_f4pga_defs.sh @@ -0,0 +1,47 @@ +#!/usr/bin/env bash + +# Copyright (C) 2020-2022 F4PGA Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +FPGA_FAM="${FPGA_FAM:=xc7}" +F4PGA_INSTALL_DIR="${F4PGA_INSTALL_DIR:=/opt/f4pga}" +F4PGA_INSTALL_DIR_FAM="${F4PGA_INSTALL_DIR}/${FPGA_FAM}" + +wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh + +bash conda_installer.sh -u -b -p "${F4PGA_INSTALL_DIR_FAM}"/conda +rm conda_installer.sh +source "${F4PGA_INSTALL_DIR_FAM}"/conda/etc/profile.d/conda.sh +mkdir -p "$F4PGA_INSTALL_DIR_FAM" + +F4PGA_TIMESTAMP='20220907-210059' +F4PGA_HASH='66a976d' + +# Only Arty supported +case "$FPGA_FAM" in + xc7) PACKAGES='install-xc7 xc7a50t_test xc7a100t_test';; + *) + echo "Unknowd FPGA_FAM <${FPGA_FAM}>!" + exit 1 +esac + +for PKG in $PACKAGES; do + wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/${F4PGA_TIMESTAMP}/symbiflow-arch-defs-${PKG}-${F4PGA_HASH}.tar.xz \ + | tar -xJC $F4PGA_INSTALL_DIR_FAM +done + +rm -vrf $F4PGA_INSTALL_DIR_FAM/share/f4pga/scripts +conda env create -f $F4PGA_INSTALL_DIR_FAM/"$FPGA_FAM"_env/"$FPGA_FAM"_environment.yml diff --git a/buildroot/board/litex_vexriscv/rootfs_overlay/etc/network/interfaces b/buildroot/board/litex_vexriscv/rootfs_overlay/etc/network/interfaces index e6170a0..869576c 100644 --- a/buildroot/board/litex_vexriscv/rootfs_overlay/etc/network/interfaces +++ b/buildroot/board/litex_vexriscv/rootfs_overlay/etc/network/interfaces @@ -3,7 +3,7 @@ iface lo inet loopback auto eth0 iface eth0 inet static -address 192.168.1.100 +address 192.168.1.50 netmask 255.255.255.0 network 192.168.1.0 gateway 192.168.1.1 diff --git a/copying/Apache-2.0 b/copying/Apache-2.0 new file mode 100644 index 0000000..7a4a3ea --- /dev/null +++ b/copying/Apache-2.0 @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/copying/index.md b/copying/README.md similarity index 93% rename from copying/index.md rename to copying/README.md index 1aa096d..4d7e9f2 100644 --- a/copying/index.md +++ b/copying/README.md @@ -14,6 +14,8 @@ The files under `software/` are disjunctively dual-licensed under the CERN-OHL-S v2.0 (or any later version), or the GNU GPL v3.0 (or any later version). +All files under `build/` are licensed under the Apache 2.0 license. + All license files under `copying/` (except this one) are licensed according to the text of the license. diff --git a/doc/docker.md b/doc/docker.md new file mode 100644 index 0000000..11b0b6c --- /dev/null +++ b/doc/docker.md @@ -0,0 +1,85 @@ +Upsilon docker development environment setup. + +# Setup steps + +## Installing OpenFPGALoader + +Then install [openFPGALoader][1]. This utility entered the Ubuntu repositories +in 23.04. Install and compile it if you do not have it. Install the udev rule +so that admin access is not required to load FPGA bitstreams. + +[1]: https://trabucayre.github.io/openFPGALoader/index.html + +## Setup Rootless Docker + +Docker allows you to run programs in containers, which are isolated +environments. Upsilon development (at the Maglab) uses Docker for +reproducibility: the environment can be set up automatically, and re-setup +whenever needed. + +If you have issues with docker, try adding to `~/.config/docker/daemon.json` + + { + "storage-driver": "fuse-overlayfs" + } + + +## Download and Install Python3 + +Install `python3-venv` (or `python3-virtualenv`) and `python3-pip`. + +## Clone External Repositories + +Run `make clone`. You may need to download the upsilon repositories +and put them in the same folder as the Makefile. + +## Setup Network + +Plug in your router/switch to an ethernet port on your computer. If your +computer is usually wired to the network, you will need another ethernet +port (a PCI card is ideal, but a USB-Ethernet port works). + +Set the ethernet port to static ip `192.168.1.100/24`, netmask 255.255.255.0, +gateway `192.168.1.1`. Make sure this is not the default route. Make sure +to adjust your firewall to allow traffic on the 192.168.1.0/24 range. + +If your local network already uses the 192.168.1.0/24 range, then you must +modify `upsilon/firmware/soc.py` to use different IPs. You must rebuild the +SoC after doing this. + +## Setup Images + +Run `make images` to create all docker images. + +## Setup and Run Containers + +For `NAME` in `hardware`, `opensbi`, `buildroot`: + +1. Run `make $NAME-container` to build the container. +2. Run `make $NAME-copy` to copy Upsilon's code into the container. +3. Run `make $NAME-execute` to build the data. +4. Run `make $NAME-get` to retrieve the build artefacts. +5. (Optionally) run `make $NAME-clean` to delete the container. + +If you do not delete the container you can run + + make $NAME-copy $NAME-execute $NAME-get + +when you need to rebuild. If you need shell access, run `make $NAME-shell`. + +## Flash FPGA + +Plug in your FPGA into the USB slot. Then run + + openFPGALoader -c digilent upsilon/boot/digilent_arty.bit + +## Launch TFTP Server + +Install py3tftp (`pip3 install --user py3tftp`). Then run `make tftp` to +launch the TFTP server. Keep this terminal open. + +## Launch FPGA Shell + +Run `litex_term /dev/ttyUSB1`. You should get messages in the window with +the TFTP server that the FPGA has connected to the server. Eventually you +will get a login prompt: you have sucessfully loaded Upsilon onto your FPGA.