Merge branch 'main' of github.com:byu-cpe/ecen427

.github/workflows/github_pages.yml

@@ -4,8 +4,6 @@ on:
   push:
     branches:
       - main
-  schedule:
-    - cron: "0 0 1 * *"
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -27,12 +25,12 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.1' # Not needed with a .ruby-version file
+          ruby-version: '3.3' # Not needed with a .ruby-version file
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
           cache-version: 0 # Increment this number if you need to re-download cached gems
 
@@ -61,4 +59,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v2

.github/workflows/link_checker.yml

@@ -3,17 +3,16 @@ name: Build and check links
 on: 
   push:
   pull_request:
-  schedule:
-    - cron: "0 0 1 * *"
+
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.0' 
+          ruby-version: '3.3' 
           bundler-cache: true 
 
       - name: Build
@@ -22,10 +21,10 @@ jobs:
   link-checker:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.0'
+          ruby-version: '3.3'
           bundler-cache: true 
       - name: Check links
-        run: make check_links
+        run: make check_links

Makefile

@@ -8,4 +8,4 @@ build: install
 	bundle exec jekyll build
 
 check_links: build
-	bundle exec htmlproofer --ignore_empty_alt true --ignore_missing_alt true --enforce_https false --swap_urls "^\/ecen427:" --ignore_status_codes "0,200,301,302,403" ./_site
+	bundle exec htmlproofer --ignore-empty-alt --ignore-missing-alt --no-enforce-https --swap_urls "^\/ecen427:" --ignore-status-codes "0,200,301,302,403" ./_site

_documentation/compiling_running_code.md

@@ -12,27 +12,38 @@ Look through the files provided to you in the Git repo.  There are some helpful
 
 ## Build System
 
+For most programs you create in this class, you will compile them on your workstation, and then copy them over to the PYNQ board to run them.  This is called **cross-compiling**.  This is done because the ARM CPU on the PYNQ board is very slow, and it is much faster to compile on your workstation.  Running VS Code on your workstation will also allow you to use such benefits as intellisense and github co-pilot to help you write your code.  
+
 ### Install Compiler
-Before proceeding you should install the G++ ARM compiler on your computer.  You can do this by running the following command:
+Before proceeding you should install the G++ ARM compiler on your workstation.  You can do this by running the following command:
 
     cd <your_repo>
-    make g++-arm-8.2
+    make g++-arm-11.2
 
-This will take a few minutes and you will need about 1.5GB of free space on your computer.  If you don't want to install these, you can compile on the PYNQ board, but it will be much slower.
+This will take a few minutes and you will need about 1GB of free space in your home drive. If you don't want to install these, you can compile on the PYNQ board, but it will be much slower.
 
 ### CMake 
 
 To build your user space programs, you are required to use CMake.  CMake is a tool that will automatically create Makefiles for you, based on a configuration file called `CMakelists.txt`.  CMake is already set up in the provided repo. 
 
-You can look at the top-level [CMakeLists.txt](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/CMakeLists.txt) file provided to you.  *Note:* This file is located in your `userspace` folder.  For the first few labs of the class you will be writing code that runs in Linux user space, so all of your code will be placed within this folder.  Later, beginning in Lab 4, you will write kernel code that will be located in the `kernel` folder, but this will not be built using the CMake system.
+You can look at the top-level [CMakeLists.txt](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/CMakeLists.txt) file provided to you.  *Note:* This file is located in your `userspace` folder.  For the first few labs of the class you will be writing code that runs in Linux user space, so all of your code will be placed within this folder.  Later, beginning in Lab 5, you will write kernel code that will be located in the `kernel` folder, but this will not be built using the CMake system.
 
-For Lab1, you are provided a *Hello, World* application, [main.c](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/apps/lab1_helloworld/main.c).
+For Lab1, you are provided a *Hello, World* application, [main.cpp](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/apps/helloworld/main.cpp).
 
 
-Note that the top-level [CMakeLists.txt](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/CMakeLists.txt) file has a `add_subdirectory(apps)` statement, which will instruct CMake to process the apps [CMakeLists.txt](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/apps/CMakeLists.txt) file.  This in turn has a `add_subdirectory(lab1_helloworld)` statement that will process the lab1 [CMakeLists.txt](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/apps/lab1_helloworld/CMakeLists.txt) file.  The contents of these files are explained below.
+Note that the top-level [CMakeLists.txt](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/CMakeLists.txt) file has a `add_subdirectory(apps)` statement, which will instruct CMake to process the apps [CMakeLists.txt](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/apps/CMakeLists.txt) file.  This in turn has a `add_subdirectory(helloworld)` statement that will process the lab1 [CMakeLists.txt](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/apps/helloworld/CMakeLists.txt) file.  
 
-### Compiling Your Code 
+### Deploying Executables to the PYNQ Board
+
+The provided CMakeLists.txt file contains a function, [deploy_to_board()](https://github.com/byu-cpe/ecen427_student/blob/main/userspace/CMakeLists.txt#L39), that will copy your executable to the PYNQ board after it is built.  To enable this, add the following line to your CMakeLists.txt file:
+
+    deploy_to_board(exe_name)
+
+There is an example [here](https://github.com/byu-cpe/ecen427_student/blob/main/userspace/apps/helloworld/CMakeLists.txt#L2).
 
+<span style="color:red">**IMPORTANT:**</span> Before this function will work, you need to update [this line](https://github.com/byu-cpe/ecen427_student/blob/main/userspace/CMakeLists.txt#L45) and replace `pynq` with the hostname or IP address of your PYNQ board. Also update the `myrepo` directory to match the path of your code repository on your PYNQ board.
+
+### Compiling Your Code 
 
 To compile the Lab1 executable, you need to navigate to the build directory, and then run CMake and point it to the top-level CMakeLists.txt file, like so:
 
@@ -46,19 +57,23 @@ This will produce a Makefile in your build directory.  Run it to compile the *He
 
 **Tip:** After running `cmake` once, you won't need to run it ever again (unless you completely delete your build directory).  Once CMake has set up the Makefile system, you can just re-run `make` for any future changes.  Even if you change the CMake files, the system is set up so that the generated Makefile will detect these updates, and automatically call CMake to update itself.
 
-<span style="color:blue">**IMPORTANT:**</span> Never run ''cmake'' from anywhere but your *build* directory.  It creates *many* temporary files that will clutter up your source files.
+<span style="color:red">**IMPORTANT:**</span> Never run ''cmake'' from anywhere but your *build* directory.  It creates *many* temporary files that will clutter up your source files.
+
+## Running Your Code 
+Your executables will be copied to the *cross-compiled* directory you set in the earlier step.  Connect to your PYNQ board via SSH, and navigate to the directory where your executables are located.  You can then run them like so:
 
-### Running Your Code 
-From within the build directory you can run the following to execute the Lab 1 *Hello, World* program:
+    ssh <mypynq>
+    cd <myrepo>/cross-compiled
+    sudo ./helloworld
 
-    ./apps/lab1_helloworld/helloworld
+While you don't need sudo to run the helloworld program, you will need it for all later programs that access hardware devices. 
 
 
-### Understanding the CMakeLists.txt files 
+## Understanding the CMakeLists.txt files 
 
 The top-level [CMakeLists.txt](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/CMakeLists.txt) file contains the following line
 
-    cmake_minimum_required(VERSION 3.4)
+    cmake_minimum_required(VERSION 3.5)
 
 which is found at the beginning of most CMake files and indicates the minimum version of CMake that your makefile supports. The next line:
 
@@ -97,7 +112,7 @@ line instructs CMake where to look for header (*.h*) files.  In Lab 2 you will c
 These lines instruct CMake to look in these directories for additional CMakeLists.txt files and process them.
 
 
-The Lab 1 [CMakeLists.txt](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/apps/lab1_helloworld/CMakeLists.txt) file contains the following: 
+The Lab 1 [CMakeLists.txt](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/apps/helloworld/CMakeLists.txt) file contains the following: 
 
     add_executable(helloworld main.c)
 
@@ -109,3 +124,32 @@ This directs CMake to create a new executable program.  The first argument is th
 You should commit your files and push them up to Github <ins>**OFTEN!!**</ins>.  **We will not make any special accommodations for students that lose their code because they were not pushing their code up to Github frequently.**. 
 
 
+
+
+## Remote Development with VS Code
+
+Instead of cross-compiling, you can connect directly to your PYNQ board and build the code there.  This is slower, but is required for labs where you are writing kernel code.  The easiest way to do this is to use the *Remote - SSH* extension in VS Code, which allows you to run a VS code window on your workstation, but have it connect to your PYNQ board.
+
+### Install
+
+Install the *Remote - SSH* extension from *Microsoft*. 
+
+<img src="{% link media/setup/vscoderemoteextensionssh.jpg %}" width="400">
+
+### SSH Keys
+Before proceeding, make sure you set up your SSH keys (`~/.ssh/id_rsa` and `~/.ssh/id_rsa.pub`) as described on an earlier [page]({% link _documentation/setup_pynq_board.md %}#ssh-keys).  
+
+*Note:* If you are using Windows on your personal computer, VSCode will look for your SSH keys in your Windows home directory (not the WSL home directory).  You may want to copy your SSH keys there:
+
+    cp ~/.ssh/id_rsa* /mnt/c/Users/<your windows username>/.ssh/
+
+
+### Connecting 
+  - Click the blue button in the bottom left of VSCode, and select *Connect to Host..*
+  - Type in `byu@<PYNQ IP or hostname>` and press enter.
+  - A new VS Code window should pop up, and the VS Code server will be installed on your PYNQ board.  This can take a few minutes.  If an error pops up, try clicking *Retry* a few times.
+  - Once connected, the blue box in the lower left corner should display the IP/network name.
+
+### Opening a Folder
+  - You can now click *File->Open Folder* and then select your repository folder that you cloned on the PYNQ board.
+  - If you open a Terminal, it will be a remote terminal on the PYNQ board.

_documentation/hdmi.md

@@ -27,7 +27,7 @@ The device maintains an offset, meaning it will keep track of where in the virtu
     lseek(fd, 12, SEEK_SET);
 
 
-You cannot change the offset to be less than 0 or greater than the size of the buffer.  The screen resolution of the HDMI driver is by default configured to be **640x480**.  This measurement is in pixels, and each pixel is 3 bytes (one red byte, one green byte, one blue byte).  The frame buffer is byte packed, meaning there are no useless bytes.  Thus, the total size of the pixel buffer is 640x480x3 = 921,600 bytes. Care must be taken that all writes are pixel-aligned, which is not necessarily word-aligned.  Note that index ''0'' of the buffer is the top left of the screen:
+You cannot change the offset to be less than 0 or greater than the size of the buffer.  The screen resolution of the HDMI driver is by default configured to be **640x480**.  This measurement is in pixels, and each pixel is 3 bytes (one green byte, one blue byte, one red byte).  The frame buffer is byte packed, meaning there are no useless bytes.  Thus, the total size of the pixel buffer is 640x480x3 = 921,600 bytes. Care must be taken that all writes are pixel-aligned, which is not necessarily word-aligned.  Note that index ''0'' of the buffer is the top left of the screen:
 
 <img src="{% link media/hdmi_screen.png %}" width="400">
 
@@ -45,7 +45,7 @@ The [write()](http://man7.org/linux/man-pages/man2/write.2.html) function allows
 
 Each pixel is 3 bytes, so each call to `write()` should be in multiples of 3 bytes.  This example shows how to write the color pink to a single pixel in the frame buffer:
 ```
-char pink[3] = {0xFF, 0x69, 0xB4};
+char pink[3] = {0x69, 0xB4, 0xFF};
 write(fd, pink, 3);
 ```
 

_documentation/linux_drivers.md

@@ -104,7 +104,5 @@ To display the most recent entries from the kernel log run `dmesg` from the shel
 ### Serial Console 
 Sometimes your system will hang and the terminal will not respond.  *Probably* some important message was written to the kernel log, but you can't run `dmesg` to see what it was.  In this instance, using the serial console could help.
 
-[PYNQ Serial]({% link _documentation/serial.md %}) explains how to connect to the Pynq via the serial port.  This serial port has the advantage that it prints all kernel messages that would normally show up in `dmesg` as they are written.  So even if the system hangs, this console will often print out information.  
-
 ## Resources 
   * There is a book published all about Linux device drivers.  It can be found for free at <https://lwn.net/Kernel/LDD3/>. Please note that while this is a wonderful resource for understanding how the Linux Kernel is built, it is based on an older version of the kernel. As such you should not rely on the syntax or function names shown in the book.

_documentation/pynq_imaging.md

@@ -0,0 +1,46 @@
+---
+layout: page
+toc: false
+title: PYNQ Imaging
+indent: 1
+number: 2
+---
+
+## Host Computer
+> 📝 The lab computers dual-boot Windows and Linux.  You will want to use Linux for this class.  If the computer is booted into Windows, log out, then reboot (button is in bottom-right).  You should see a menu after reboot that allows you to select Ubuntu Linux.  If the menu doesn't show up, try pressing F9 repeatedly while the computer is booting.
+
+<span style="color:red">**It is recommended to use the lab computers in EB438 as these have the necessary software already set up.** </span> You can use your own computer, but you will need to install the necessary software yourself.  
+
+### Linux or Windows Subsystem for Linux (WSL)
+If you choose to use your own computer, the easiest way to get the necessary software is to use Linux.  
+
+If you are using Windows, it is recommended to use Linux via the Windows Subsystem for Linux (WSL).  Follow [Microsoft's instructions](https://learn.microsoft.com/en-us/windows/wsl/install) to install it. You may want to use the new [Windows Terminal](https://apps.microsoft.com/detail/9N0DX20HK701?hl=en-US&gl=US) application as your default terminal.
+
+### Mac
+If you are using a Mac, you can use the built-in terminal to connect to the PYNQ board; however, the it will require more substantial setup to cross-compilation working (compiling on your computer and running on the board), and some labs that require Vivado will not work.
+
+
+
+
+## Obtaining the PYNQ Board 
+
+The lab contains PYNQ-Z2 boards at each workstation.  **You do not need to buy your own board.**  
+
+If you want to purchase your own Pynq-Z2 board, you can do so online at several distributors:
+  * Board only (you will need to obtain micro SD card, micro USB cable separately): <https://www.newark.com/tul-corporation/1m1-m000127dev/tul-pynq-z2/dp/13AJ3027?st=tul-corporation>
+  * Kit: <https://www.newark.com/tul-corporation/1m1-m000127dvb/tul-pynq-z2-basic-kit-rohs-compliant/dp/69AC1754?st=tul-corporation>
+
+You may also be able to borrow a board from the Experiential Learning Center (ELC) in the Clyde Building.  You will need to pay a deposit, but it will be refunded when you return the board.  
+
+
+## Imaging the SD card 
+The PYNQ runs Linux off of an external micro SD card that you must provide. It is best to use a high-performance (V30/U3) SD card that is at least 16GB. I recommend you purchase a SD card from the ELC, where they are available for about $10-15. 
+Be wary of counterfeit SD cards, especially if you purchase them from online marketplaces that contain 3rd party sellers.  There are SD card readers in a drawer at the back of the lab.  Please return them when you are done.
+
+The SD card must have a valid system image in order for Linux to run.  We have provided a working system image [here](https://byu.box.com/s/btgto9zrhluikq58qmrubld0b3rbh7xh) (alternate download link [here](https://drive.google.com/file/d/1-6xko67BkEfBbHU2tFpgBE976g7P54vs/view?usp=sharing)).  Unzip it after you download it.  The official PYNQ documentation has a guide to [writing the SD card image](https://pynq.readthedocs.io/en/latest/appendix/sdcard.html) that you should follow. Some notes:
+* In the lab you do not need to use *sudo* to run the *dd* command, so remove this from the command when you image the SD card.
+* You probably won't have space to unzip the .img file onto your home directory, so instead extract it to the `/tmp` folder on the computers.  This is a local folder that is cleared when you log out, so you don't have to worry about filling up the hard drive. Example:
+
+      dd bs=4M if=/tmp/427_2025.img of=/dev/sda
+
+* If you are using your own Windows computer and run into issues using *Win32DiskImager*, another alternative is to use <http://etcher.io>.