From 66aec6112c495f83ee5c0e24e71010792c0e9971 Mon Sep 17 00:00:00 2001 From: Jeff Goeders Date: Mon, 16 Dec 2024 23:31:34 -0700 Subject: [PATCH 1/7] 2025w changes --- _documentation/compiling_running_code.md | 39 ++++- _documentation/linux_drivers.md | 2 - _documentation/pynq_imaging.md | 43 +++++ _documentation/serial.md | 38 ----- ...config_pynq_and_github.md => setup_git.md} | 28 +--- _documentation/setup_home_computer.md | 30 ---- _documentation/setup_pynq_board.md | 155 +++++++----------- _documentation/vscode.md | 74 --------- _labs/audio_driver.md | 2 +- _labs/hello_world.md | 7 +- _labs/space_invaders.md | 13 ++ 11 files changed, 157 insertions(+), 274 deletions(-) create mode 100644 _documentation/pynq_imaging.md delete mode 100644 _documentation/serial.md rename _documentation/{config_pynq_and_github.md => setup_git.md} (78%) delete mode 100644 _documentation/setup_home_computer.md delete mode 100644 _documentation/vscode.md diff --git a/_documentation/compiling_running_code.md b/_documentation/compiling_running_code.md index 4c70fd6..90abe84 100644 --- a/_documentation/compiling_running_code.md +++ b/_documentation/compiling_running_code.md @@ -12,21 +12,23 @@ 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 - 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/lab1_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. @@ -109,3 +111,30 @@ 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 **OFTEN!!**. **We will not make any special accommodations for students that lose their code because they were not pushing their code up to Github frequently.**. + + +## Method 2: Remote VS Code + +### Install + +Install the *Remote - SSH* extension from *Microsoft*. + + + +### 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//.ssh/ + + +### Connecting + - Click the blue button in the bottom left of VSCode, and select *Connect to Host..* + - Type in `byu@` 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. \ No newline at end of file diff --git a/_documentation/linux_drivers.md b/_documentation/linux_drivers.md index 0cdad99..ddb8b16 100644 --- a/_documentation/linux_drivers.md +++ b/_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 . 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. \ No newline at end of file diff --git a/_documentation/pynq_imaging.md b/_documentation/pynq_imaging.md new file mode 100644 index 0000000..0f5ae4b --- /dev/null +++ b/_documentation/pynq_imaging.md @@ -0,0 +1,43 @@ +--- +layout: page +toc: false +title: PYNQ Imaging +indent: 1 +number: 2 +--- + +## Host Setup Choice +> 📝 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. + +**It is recommended to use the lab computers in EB438 as these have the necessary software already set up.** 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): + * Kit: + +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. + +The SD card must have a valid system image in order for Linux to run. We have provided a working system image [here](). 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. +* If you are using your own Windows computer and run into issues using *Win32DiskImager*, another alternative is to use . \ No newline at end of file diff --git a/_documentation/serial.md b/_documentation/serial.md deleted file mode 100644 index dae834b..0000000 --- a/_documentation/serial.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: page -toc: false -title: Serial Communications -short_title: PYNQ Serial -indent: 2 -number: 4 ---- - -In the case that an `ssh` connection fails, or you don't know the board's IP address yet, you can also get command-line access to the PYNQ via UART connection over USB. The board must be powered via a USB cable connected the host computer for this to work. - -## Windows -Find the serial port: - * Open *Device Manager* - * In the *Ports* section, find the *USB Serial Port* device, and make note of the COM port number. For example, it may be *COM6*. - -Connect using [putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/) - * Run putty - * Switch to *Serial* - * In the *Serial Line* box, enter the appropriate COM port number, eg. *COM6* - * In the *Speed* box, enter 115200. - * Click *Open* - * You may need to hit *Enter* on your keyboard a few times for the PYNQ command prompt to appear. - -## Linux or Mac - -Find the serial port: - * Run `ls /dev/ttyUSB*` (Linux) or `ls /dev/tty.*` (Mac) - * Plug in the Pynq board via USB - * Run the command again and see what is new. It will probably be named /dev/ttyUSB0 or /dev/ttyUSB1 (different on Mac). There may be more than one new serial port connected, and you may need to try connecting to both. (Usually it is USB1) - -Connect with `screen`: - * Run `sudo screen /dev/[port_name] 115200` - * If it hangs, type ''Ctrl-a, k'' to kill the Screen session - * Try the other port - * You may need to hit *Enter* on your keyboard a few times for the PYNQ command prompt to appear. - -While you may be tempted to use this UART connection for all of your work, we strongly advise against it. It is slow and sometimes unreliable. Use this to determine the IP address, and then connect via SSH. diff --git a/_documentation/config_pynq_and_github.md b/_documentation/setup_git.md similarity index 78% rename from _documentation/config_pynq_and_github.md rename to _documentation/setup_git.md index 62786b7..36531df 100644 --- a/_documentation/config_pynq_and_github.md +++ b/_documentation/setup_git.md @@ -9,28 +9,6 @@ number: 7 In the labs for this class, you will be completing some tasks on your computer, and some tasks on the PYNQ board. In this setup step, you will set up your Git repository and SSH keys on both your computer and the PYNQ board. -## Extend your Partition - -You should extend the PYNQ filesystem to fill your entire SD card (by default the filesystem only provides a small amount of free space, and doesn't fill your SD card) - -Run these commands. Please copy and paste them one at a time, and be careful in the process. It's easy to mess up your entire SD card image: - -``` -sudo growpart /dev/mmcblk0 2 -sudo resize2fs /dev/mmcblk0p2 -``` - -## Set PYNQ time - -Run the following to update the time on your PYNQ - - sudo apt install chrony - sudo chronyc -a 'burst 4/4' - sudo chronyc -a makestep - sudo timedatectl set-timezone America/Boise - - -This will fix the current time of the PYNQ, but if you have your PYNQ off for some extended period, and then turn it back on, you will may notice the time is wrong. ## Computer Setup > 📝 Run this on your computer. @@ -51,7 +29,7 @@ This will fix the current time of the PYNQ, but if you have your PYNQ off for so ### Github Repository Creation -1. Sign up for your Github classroom repo using this link: This will create an empty private repository on Github for you to use throughout the entire semester. **You must create your repository using this link, or the TAs will not be able to grade your code.** +1. Sign up for your Github classroom repo using this link: <> This will create an empty private repository on Github for you to use throughout the entire semester. **You must create your repository using this link, or the TAs will not be able to grade your code.** 1. You should now see the message below. Click the link to navigate to your repository. @@ -118,7 +96,3 @@ Since this is the first time using Git on the PYNQ system, you need to configure git config --global user.name "Your Name" git config --global user.email your_email@example.com ``` - -### Add Starter Code Remote - -Repeat the steps above to add the *startercode* remote. \ No newline at end of file diff --git a/_documentation/setup_home_computer.md b/_documentation/setup_home_computer.md deleted file mode 100644 index 67b6283..0000000 --- a/_documentation/setup_home_computer.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: page -toc: false -title: Setting up your Home Computer -short_title: Home Computer -indent: 1 -number: 2 ---- - -> 📝 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. - -**You can skip this setup page if you only plan to work in the lab using the lab computers, and not work from your personal computer.**. - - - -Much of the work done in this class will be done using the command-line. At minimum, you need a computer with a Unix-based command-line terminal. - -## Mac or Linux -If you are using Mac or Linux, you can use the built in terminal. - -## Windows -Follow [Microsoft's instructions](https://learn.microsoft.com/en-us/windows/wsl/install) to install the Windows Subsystem for Linux (WSL). - -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. - -## Testing SSH Capabilities - -Make sure you can run SSH by connecting to the CAEDM ssh server: - - ssh your_caedm_username@ssh.et.byu.edu \ No newline at end of file diff --git a/_documentation/setup_pynq_board.md b/_documentation/setup_pynq_board.md index 84ec400..7d34a85 100644 --- a/_documentation/setup_pynq_board.md +++ b/_documentation/setup_pynq_board.md @@ -7,42 +7,21 @@ indent: 1 number: 3 --- +## Booting the PYNQ Board +The first time you boot the PYNQ board, we will observe the boot process over the serial port. This can be useful for debugging, and interacting with the system before the network is set up. +1. Make sure the PYNQ board is powered off. +1. Connect the PYNQ board to your computer using the micro USB cable. +1. Open the serial port on the host computer: + * Run `ls /dev/ttyUSB*` to see the serial devices connected to your computer. Typically the UART from the PYNQ board will be named `/dev/ttyUSB1`. + * Run `screen /dev/ttyUSB1 115200` to open the serial port. + * You can always close the serial port by typing `Ctrl-a, k` and then `y` to confirm. +1. Power on the PYNQ board. You should see the boot process in the terminal window. +1. After the boot process is complete, you should automatically be logged in as the `byu` user. The default password is `byu`. -## 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): - * Kit: - - - - - - -## Imaging the SD card -The PYNQ runs Linux off of an external micro SD card that you must provide. 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/5o669wg1lh4dlh0asb07ucl32ppesdvp) (unzip it after you download it), but you must image this to your own SD card. The micro SD card must be at least 16GB and class 10 or better. 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. -* If you are using your own Windows computer and run into issues using *Win32DiskImager*, another alternative is to use . - -## Powering Up the PYNQ Board -To power the PYNQ board, you will need to connect the micro USB cable, insert the micro USB cable, and turn on the power switch. - -### Powering Down the PYNQ Board +## Powering Down the PYNQ Board **Important:** Once you have powered up your board, it should begin to boot Linux. Keep in mind that once you have it powered, treat it like a regular computer running Linux, and don't unplug it or turn off the power switch until you have shut it down properly. If you unplug it or turn off the power switch while it is running, you risk corrupting the SD card and you may have to re-image it. Once you have connected to the board using the methods described below, you can shut down the board by typing @@ -51,93 +30,71 @@ Once you have connected to the board using the methods described below, you can in the terminal. Wait 10 seconds before shutting of the power switch. -### Verifying BOOT using HDMI -The PYNQ video signal comes from the HDMI port labeled *HDMI Out* located on the topside of the board. This should already be connected to a dedicated monitor in the lab. If you work remotely, you will need to find an HDMI-compatible display to use. - - - -You can verify that your PYNQ board is imaged correctly, and connected to the display correctly by powering it on, and after it has booted (about 1 min), you should see something like this on your display: - - ## Connect the PYNQ to Your Network -**You can skip the rest of this page if only plan to work in the lab and not work remotely**. - - -You will need to connect your PYNQ to a network with internet access. The PYNQ board does not have WiFi, so you will need a physical Ethernet connection. This can be done three ways: - - Connect the PYNQ directly to your home router or switch (this is how it is setup in the lab). - - Connect the PYNQ directly to the Ethernet port on your computer. This can be done if you aren't using the Ethernet port for your computer's internet connection, ie. you are using WiFi or have an extra ethernet port. - - If you don't have an extra Ethernet port on your computer, you can buy a USB-to-Ethernet adapter such as the one [here](https://www.amazon.com/Cable-Matters-Ethernet-Adapter-Supporting/dp/B00BBD7NFU/ref=sr_1_5?crid=2VLSDOH1QTN7Q&dchild=1&keywords=usb+to+ethernet+adapter&qid=1594321211&sprefix=usb+to+eth%2Caps%2C188&sr=8-5). Make sure to buy one that is compatible with your computer. - -### Internet Sharing - -If you used Option #1 above and connected the PYNQ directly to your home network, you can skip this section. Otherwise, if you connected the PYNQ to your computer, follow the steps in this section to share your internet connection with the PYNQ board. - -#### Windows - - * Open Windows Settings (Windows Key + I) and go to *Network & Internet*. - * Expand the connection you want to share (Ethernet or WiFi), locate the *More adapter options* item and click *Edit*. - * In the adapter pop-up window, click the *Sharing* tab. Check the box for *Allow other network users to connect through this computer's Internet connection*. - -#### Mac +Use a command line editor (vim, nano, etc.) to edit the `/etc/netplan/01-netcfg.yaml` file: - + sudo nano /etc/netplan/01-netcfg.yaml -#### Ubuntu Linux - * For those with the Unity launcher, should work - * For those with the Gnome desktop, should work +The version of the PYNQ image we are using has a corrupted MAC address, so we will use netplan to override the MAC address. Each student is assigned a unique MAC address. **It is important that you carefully update the MAC address to the one assigned to you. Do not skip this step, or update the value incorrectly, or you will have connectivity issues with your board, and may impact other students in the lab as well.** -### Find the PYNQ IP Address +1. Find the line that starts with `macaddress:` and update the value to the MAC address assigned to you. The line should look like this: -Next you will need to determine what IP address your PYNQ board was given. Make sure you insert the imaged SD card into your PYNQ board and power it on before proceeding. + ```yaml + macaddress: 42:59:55:01:23:45 + ``` -If you use option 1 or 2 below, keep in mind that as you look for the PYNQ IP address, **the PYNQ boards tend to have MAC addresses that start with 00:05:6b:**. +1. Enable dhcp by changing the `dhcp4` line to `true`: -**Option 1: Retrieve from router.** *You can only use this technique if you used option #1 above, and your PYNQ is connected directly to your home router or switch* + ```yaml + dhcp4: true + ``` -Your PYNQ should be given an IP address on your home network. This is likely something like 192.168.x.x and you may be able to find it using the DHCP list on your router's configuration webpage or app. +1. Run the following command to apply the changes: + ```bash + sudo netplan apply + ``` -**Option 2: Use ARP.** - -ARP (Address Resolution Protocol) allows you to view IP addresses and MAC addresses of computers on your network. - -In Windows, Linux, or Mac, you should be able to run `arp -a` in the terminal to view a list of IP/MAC pairs. They are usually grouped by network device, so if you have the PYNQ connected to your computer via USB-to-Ethernet adapter, the PYNQ should be in it's own category. - -**Option 3: Connect to the PYNQ board using UART** - -The [PYNQ Serial]({% link _documentation/serial.md %}) page describes how to get a command prompt on the PYNQ board using the USB connection. From there you can run `ip a` to view the network adapters on the PYNQ board and their IP addresses. The Ethernet adapter on the PYNQ is named `eth0`. - +1. Reboot the PYNQ board: + ```bash + sudo reboot + ``` +1. After reboot, make sure you board receives the correct IP address by running: + ```bash + ip a + ``` ## SSH Communication -Once you have the PYNQ set up you can connect to it using SSH. +Once you have the PYNQ set up you can connect to it using SSH, which will be much faster and more full-featured than the serial connection. -If you are working in the lab, you can access the PYNQ board in the lab using: - - ssh byu@pynq03.ee.byu.edu +```bash +ssh byu@.ee.byu.edu +``` -where the "03" is replaced with the number of the PYNQ board you are using. **The default password is `byu`.** - -If working remotely, you will need to replace *pynq03.ee.byu.edu* with your PYNQ's IP address. - +## SSH Keys +> 📝 *Run this on your computer. If you are still SSh'd into the PYNQ board, type `exit` to get back to your computer.* +Instead of having to authenticate with a password each time connecting to the PYNQ, you should set up an SSH key to do automatic authentication: +1. Generate an SSH key on your computer: -## SSH Keys + ```bash + ssh-keygen + ``` -> 📝 *Run this on your computer. If you are still SSh'd into the PYNQ board, type `exit` to get back to your computer.* + Just press enter for the default location and no passphrase. -Instead of having to authenticate with a password each time connecting to the PYNQ, you can set up an SSH key to do automatic authentication. [This tutorial](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-on-ubuntu-1804) explains how to set this up in a variety of ways. +1. Enable passwordless SSH login to the PYNQ board: -A few of notes __before__ following the tutorial: - * If your computer doesn't have `ssh-copy-id` installed, you will need to follow the instructions below that (the lab computers have it installed). - * Although it is less secure, it is nicer if you do not specify a passphrase for the key; this will give you secure, passwordless access to the PYNQ. Presumably the host computer is protected by password, which makes not having a passphrase less of an issue - * You probably don't want to follow Step 4 of the tutorial + ```bash + ssh-copy-id byu@.ee.byu.edu + ``` **Before proceeding, make sure you can ssh into your PYNQ board without being prompted for a password.** @@ -148,3 +105,15 @@ A few of notes __before__ following the tutorial: You should change the password for the *byu* account in your PYNQ Linux system. This is not just to prevent people from looking at your work, it also prevents another student from accidentally SSH'ing in your PYNQ board and modifying your files. To change the *byu* user password, SSH into your PYNQ board and run the `passwd` command. + + +## Extend your Partition + +You should extend the PYNQ filesystem to fill your entire SD card (by default the filesystem only provides a small amount of free space, and doesn't fill your SD card) + +Run these commands. Please copy and paste them one at a time, and be careful in the process. It's easy to mess up your entire SD card image: + +``` +sudo growpart /dev/mmcblk0 2 +sudo resize2fs /dev/mmcblk0p2 +``` \ No newline at end of file diff --git a/_documentation/vscode.md b/_documentation/vscode.md deleted file mode 100644 index b0b5c32..0000000 --- a/_documentation/vscode.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -layout: page -toc: false -title: Setup VSCode -indent: 1 -number: 8 ---- - -There are two ways for us to work on our PYNQ filesystem remotely: - -1. Mounting the remote PYNQ filesystem on our local computer. This will make it appear as if the PYNQ filesystem is a folder on your computer. This allows us to use our computer's processor to analyze and compile code, so it is much faster than working directly on the PYNQ board. This is what I would advise to use most of the time. - -1. Connecting to the PYNQ board via VS Code Remote Extension, and editing and compiling on the PYNQ board. This will run much slower. - -## Method 1: Mounting the PYNQ Filesystem - -> 📝 Run this on your computer. - -1. Create a directory where you will mount the PYNQ remote filesystem. For example: - - mkdir ~/pynq_remote - -1. Run the sshfs command to mount the remote filesystem: - - sshfs -o idmap=user byu@PYNQ_IP:/home/byu/repo_path ~/pynq_remote - - Replacing `PYNQ_IP` with the IP address or network name of your PYNQ board, `~/repo` with the path of your repository on the PYNQ board. - -1. Verify that you can view and edit the files on the PYNQ board, and open the files in VSCode. For example: - - cd ~/pynq_remote - ls - touch test.txt - - code ~/pynq_remote - - -1. You can unmount the filesystem by running: - - fusermount -u ~/pynq_remote - - You will need to close any windows or terminals using this directory before the command will work. - -I like to set up my VS code like this: - - - -### Cross-Compiling - -## Method 2: Remote VS Code - -### Install - -Install the *Remote - SSH* extension from *Microsoft*. - - - -### 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//.ssh/ - - -### Connecting - - Click the blue button in the bottom left of VSCode, and select *Connect to Host..* - - Type in `byu@` 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. \ No newline at end of file diff --git a/_labs/audio_driver.md b/_labs/audio_driver.md index b84d99c..6d36c73 100644 --- a/_labs/audio_driver.md +++ b/_labs/audio_driver.md @@ -96,7 +96,7 @@ Create a new user space program in *userspace/apps/lab5_m1*, with appropriate CM ### Pass Off To grade your submission we will: -1. Load and unload your driver (`insmod` and `rmmod`) **TWICE**. Make sure it works without error and has appropriate logging messages as described above. A simple [script](https://github.com/byu-cpe/ecen427_student/blob/master/kernel/audio_codec/test_insmod.sh) is provided that loads and unloads the module twice, prints recent kernel log entries, and prints details of your device file. **Recent changes have been made to this script, so make sure you have the latest version. Go back to [this page]({% link _documentation/config_pynq_and_github.md %}) for instructions on merging in the latest changes to the starter code repository.** +1. Load and unload your driver (`insmod` and `rmmod`) **TWICE**. Make sure it works without error and has appropriate logging messages as described above. A simple [script](https://github.com/byu-cpe/ecen427_student/blob/master/kernel/audio_codec/test_insmod.sh) is provided that loads and unloads the module twice, prints recent kernel log entries, and prints details of your device file. **Recent changes have been made to this script, so make sure you have the latest version. Go back to [this page]({% link _documentation/setup_git.md %}) for instructions on merging in the latest changes to the starter code repository.** 1. Compile and run your *lab5_m1* program. Make sure your cmake files are set up to correctly build the executable. We will run it after loading your driver and inspect the kernel logs to see that the `read()` and `write()` functions in your driver were executed. ## Milestone 2 diff --git a/_labs/hello_world.md b/_labs/hello_world.md index 19edb6a..a2e0e78 100644 --- a/_labs/hello_world.md +++ b/_labs/hello_world.md @@ -24,11 +24,10 @@ This page describes how to set up your computer and PYNQ board for the labs in t If you run into issues, post on Teams. **Do not skip any setup steps**. For convenience, these setup steps are also shown in the sidebar. - * [Setup your home computer]({% link _documentation/setup_home_computer.md %}). You can use a Windows, Linux or Mac computer. - * [Setup the PYNQ board]({% link _documentation/setup_pynq_board.md %}) + * [Image the PYNQ SD card]({% link _documentation/pynq_imaging.md %}) + * [Setup the PYNQ board]({% link _documentation/setup_pynq_board.md %}) - [Complete the Tutorials]({% link _documentation/tutorials.md %}) - - [Configure your PYNQ system]({% link _documentation/config_pynq_and_github.md %}) - - [Setup VSCode]({% link _documentation/vscode.md %}) + - [Setup Git/Github]({% link _documentation/setup_git.md %}) - [Compiling and Running Programs]({% link _documentation/compiling_running_code.md %}) diff --git a/_labs/space_invaders.md b/_labs/space_invaders.md index e9aa179..830edb6 100644 --- a/_labs/space_invaders.md +++ b/_labs/space_invaders.md @@ -8,6 +8,19 @@ under_construction: true --- +## Graphics + +### Verifying BOOT using HDMI +The PYNQ video signal comes from the HDMI port labeled *HDMI Out* located on the topside of the board. This should already be connected to a dedicated monitor in the lab. If you work remotely, you will need to find an HDMI-compatible display to use. + + + +You can verify that your PYNQ board is imaged correctly, and connected to the display correctly by powering it on, and after it has booted (about 1 min), you should see something like this on your display: + + + + + ## Objective Write the software that implements all video functionality for Space Invaders. Your game should closely mirror the game shown in the video below. From 9f55b1e5ed699e7ba8b6df879cdfff1ed59ee16b Mon Sep 17 00:00:00 2001 From: Jeff Goeders Date: Tue, 17 Dec 2024 11:20:55 -0700 Subject: [PATCH 2/7] Lab 1 updates --- _documentation/compiling_running_code.md | 33 +++++++++++++++++------- _documentation/pynq_imaging.md | 2 +- _labs/hello_world.md | 4 +-- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/_documentation/compiling_running_code.md b/_documentation/compiling_running_code.md index 90abe84..dba54fe 100644 --- a/_documentation/compiling_running_code.md +++ b/_documentation/compiling_running_code.md @@ -31,10 +31,19 @@ You can look at the top-level [CMakeLists.txt](https://github.com/byu-cpe/ecen42 For Lab1, you are provided a *Hello, World* application, [main.cpp](https://github.com/byu-cpe/ecen427_student/blob/master/userspace/apps/lab1_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/lab1_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). +**IMPORTANT:** 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: @@ -48,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. -**IMPORTANT:** Never run ''cmake'' from anywhere but your *build* directory. It creates *many* temporary files that will clutter up your source files. +**IMPORTANT:** Never run ''cmake'' from anywhere but your *build* directory. It creates *many* temporary files that will clutter up your source files. -### Running Your Code -From within the build directory you can run the following to execute the Lab 1 *Hello, World* program: +## 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: - ./apps/lab1_helloworld/helloworld + ssh + cd /cross-compiled + sudo ./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: @@ -113,7 +126,9 @@ You should commit your files and push them up to Github **OFTEN!!**. -## Method 2: Remote VS Code +## 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 diff --git a/_documentation/pynq_imaging.md b/_documentation/pynq_imaging.md index 0f5ae4b..572aa6f 100644 --- a/_documentation/pynq_imaging.md +++ b/_documentation/pynq_imaging.md @@ -6,7 +6,7 @@ indent: 1 number: 2 --- -## Host Setup Choice +## 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. **It is recommended to use the lab computers in EB438 as these have the necessary software already set up.** You can use your own computer, but you will need to install the necessary software yourself. diff --git a/_labs/hello_world.md b/_labs/hello_world.md index a2e0e78..96d1418 100644 --- a/_labs/hello_world.md +++ b/_labs/hello_world.md @@ -42,8 +42,8 @@ After you have completed these steps, do the following: Follow the instructions on the [Submission]({% link _other/submission.md %}) page. -## Resources - * [Official PYNQ documentation](http://pynq.readthedocs.io/en/latest/getting_started.html) + From d8c1fcc119b81619ae338d5973f2132699db0da4 Mon Sep 17 00:00:00 2001 From: Jeff Goeders Date: Tue, 17 Dec 2024 15:35:43 -0700 Subject: [PATCH 7/7] Update checkout version --- .github/workflows/github_pages.yml | 2 +- .github/workflows/link_checker.yml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml index fb148b9..f297ff8 100644 --- a/.github/workflows/github_pages.yml +++ b/.github/workflows/github_pages.yml @@ -25,7 +25,7 @@ jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Setup Ruby uses: ruby/setup-ruby@v1 diff --git a/.github/workflows/link_checker.yml b/.github/workflows/link_checker.yml index 400e3ad..610eade 100644 --- a/.github/workflows/link_checker.yml +++ b/.github/workflows/link_checker.yml @@ -9,7 +9,7 @@ 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' @@ -21,7 +21,7 @@ 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'