Joe Davison CPSC Tech

BCEM577 Remote Access

Mon, 13 Jan 2025 15:23:24 -0700

Resources for BCEM577 are accessed remotely using Remote Desktop Connection from the lab computer. To begin, find Remote Desktop Connection in the Start Menu and open it.

In the Computer field, enter the hostname from the password slip (eg bcem15.cs.ucalgary.ca).

In the login box that follows, click on “More choices”, followed by “Use a different account”.

enter \student as the username (note the preceding backslash, this is important) and the password from the password slip.

The backslash at the start of the username is vital and must be included, or the connection will fail.

After logging in, you will see a window asking you to confirm the identity of the remote computer. On this screen, you can tick “Don’t ask me again for connections to this computer” and then click “Yes”.

Logging out

Before logging out, ensure that all of your work is saved just in case of any problems.

When logging out of the remote session, simply close the Remote Desktop window. This can be done by clicking on the X icon in the top blue bar of the remote desktop connection window.

All open applications, programs, files etc will remain on the machine while you are away. Closing the remote connection is like turning off a monitor.

Note that you can, optionally, hide the top bar by clicking the pin icon on the left hand side. If you choose to hide it, moving your cursor to the top of the screen will display it again temporarily.

Changing the password

If you would like to change your password from the random one from the password slip, you can do so inside the remote desktop connection.

Click the “More applications” button in the bottom-left part of the screen, followed by opening the “Settings” app.

In the settings app, select “Sharing” on the left-hand side.

You can then change the password. The change will apply immediately, and you can close the remote desktop window as soon as you have done so by pressing the X in the top right-hand side.

Changing other settings on this page will cause lost work.

Support

If you need technical support, such as if you lose access or the remote environment crashes, please email cpsc.uls@ucalgary.ca. In your email, please include the hostname of the machine, which can be found on the password printout (eg bcem5, bcem16).

Development Guide

Thu, 22 Aug 2024 15:28:29 -0600

These instructions will demonstrate to you how to get a simple Hello World via the UART interface, demonstrating the full functionality of the Pi Kit.

You can follow these instructions on any of the CPSC lab computers, using the Development VM, or by setting up your own toolchain (eg via WSL). Please note that CPSC ULS only supports development in the labs or using the VM.

This guide assumes the reader has some familiarity with basic Linux tools.

Hooking up the Pi

Your Raspberry Pi Kit contains all of the hardware necessary for development. The custom Pi HAT provides a number of interfaces enabling you to debug the Pi, write to the Pi’s memory, and connect devices (such as the controllers).

To get started you’ll need to plug the Pi in using the included power supply. It is important to only use the included power supply with the Pi. Take the USB type B cable and plug the B end into the top of the Pi HAT and the USB A end into your computer. Finally, plug the HDMI cable into a monitor.

Optionally - though not required at this stage - you can plug the SNES controller into the RJ45 port A.

Opening the UART interface and using OpenOCD

The Pi HAT provides several interfaces, including UART and JTAG. Using standard Linux tools we can work with these interfaces to send code and receive messages.

First of all, let’s open the UART interface to see if the program on the Pi is sending any data over UART. You can do this with a Linux tool called screen. Open a Terminal and enter the following:

screen /dev/ttyUSB0 115200,cs8,ixoff,-istrip

NOTE: You may get an error at this stage that /dev/ttyUSB0 cannot be found. Due to the way Linux assigns devices, the correct path could be /dev/ttyUSB1.

This Terminal will now display any data sent by the Pi over the UART interface.

Next we’ll open a debug interface using openocd and work with it using gdb.

Open another Terminal (hint: ctrl+shift+t will open a new tab in the same window!) and enter the following command:

openocd -f interface/rpi4.cfg

NOTE: The path to interface/rpi4.cfg is valid only in the development VM and on the CPSC lab computers. In your own environment you will need to get the rpi4.cfg file from your instructor.

You’ll see some output letting you know that a debug interface has been opened. You can think of it as a “server” that we’ll connect to using gdb.

You’ll now need to open another Terminal and enter: gdb.

gdb has its own command line where you will need to enter the following commands to finish setting up the environment:

set architecture aarch64
target extended-remote :3333

With the debug interface open you can send new code to the Pi by overwriting its memory - we’ll discuss compiling code in the next section - but assuming you have some, you can do:

load /path/to/code.elf 0x0
continue

Watch your UART interface as you do this - if you send text to UART in your program, you should see it immediately! When you want to send new code to the Pi, you can press ctrl+c in the gdb window and repeat the load command.

With this in mind you will be able to iterate your code more conveniently, sending new variations of your code to the Pi as you compile it.

Writing some code

Your TA / instructor should have provided you some code to bootstrap the Pi. This will be files named similar to start.S, uart.c etc. If you don’t have these, speak to your instructor.

The boilerplate bootstrap contains code to initiate the UART interface so text can be sent. The function as defined in uart.c for this is uart_init(). So with that in mind, let’s see a simple boilerplate Hello World:

#include "types.h"
#include "uart.h"
#include "mbox.h"
#include "ssp.h"

void main() {
    uart_init();

    uart_puts("Hello world!\n");
}

There should be a Makefile with the boilerplate, using that, simply make your code. Two files will be generated: kernel8.elf and kernel8.img. We are interested in the elf file at this stage.

In the gdb window you opened in the previous step, enter the following, while watching your Terminal window with the UART interface:

load /path/to/kernel8.elf 0x0
continue

As soon as you type in continue (or c! gdb has lots of abbreviations), you should see Hello World! output in the the UART interface window.

Now try adding an extra uart_puts into your code and compile it. Press ctrl+c in gdb and then run the load command again (hint: use the UP arrow on your keyboard as a neat shortcut). Your new text should appear in the UART interface!

Development on Windows using WSL

Thu, 07 Mar 2024 11:02:21 -0600

The CPSC359 VM is an option for most Windows devices, but modern Windows includes an awesome tool (that you should get familiar with anyway!) called Windows Subsystem for Linux - WSL.

WSL is a slim virtual machine that runs Linux and tightly integrates it with Windows. It is essential for any modern developer as it lets you have a neat combination of Windows and Linux development environments.

I won’t go into how to install and set up WSL here as this is covered quite nicely elsewhere, but I will provide the specific steps for hooking up your Pi and using WSL to do everything you need it to.

This guide is here as a reference to get you started if you are feeling adventurous enough to try this out. Support for development and compiling on WSL cannot be provided; you’re on your own if you go this route!

Requirements

You must have local admin access on your Windows machine and WSL2 installed. You won’t be able to do any of this on a campus computer.
This guide assumes you are using Ubuntu (the default distro for WSL) - other distros may differ

Software setup

You only need a few packages to get going, install them with the following command:

sudo apt install openocd screen build-essential gdb-multiarch

To build software you will also need the aarch64-elf toolchain. The easiest way to install this in WSL is to use Homebrew. Run the Homebrew installation command given on the Homebrew website, and then follow the steps in the Homebrew-on-Linux documentation to add it to your $PATH.

With Homebrew installed, simply run brew install aarch64-elf-gcc. This will install the correct compiler toolchain for you to build baremetal code inside of WSL!

Now looking outside of the VM, you need to install a driver called usbipd to attach USB devices to the WSL VM. Some more information on this is given on the Microsoft documentation site, but the gist is to just do the following:

In Windows Terminal, run: winget.exe install --interactive --exact dorssel.usbipd-win (you can run Windows executables from inside of WSL!). If you don’t have winget (it should be included in all installations of Windows 11 now), go to the Github page for usbipd and download the installer.

Once you have installed usbipd, restart your computer.

Hardware setup

With WSL and the usbipd driver set up, hook up your Pi to your computer via USB-B and turn it on. In an elevated Powershell window (right click Powershell and select “Run as Administrator”), do the following:

usbipd list - This will show the USB devices that can be attached to WSL. Note the BUSID and DEVICE columns
Look for a device named something like “USB Serial Converter A, USB Serial Converter B” and note its BUSID - let’s assume the BUSID is 2-3
Run usbipd bind -b 2-3, which opens the device up for use in WSL
Finally, run usbipd attach -b 2-3, which attaches the Pi to WSL

That’s it! The Pi is hooked up to WSL and you can use all the tools as you’d expect EXCEPT in the case that gdb must be invoked as gdb-multiarch so;

openocd -f /path/to/rpi4.cfg
-- new terminal --
gdb-multiarch
set architecture aarch64
target extended-remote :3333
-- new terminal --
screen /dev/ttyUSB1 115200

Support

Please note that I cannot provide support for a WSL development environment. This is simply because I don’t have access to one readily available.

The official means that you have at your disposal to develop for CPSC359 is to use the CPSC359 VM or any of the computer science lab spaces.

If you are having a hard time finding a space to work on campus, please contact cpsc.uls@ucalgary.ca and we can help.

Thanks to Ivan Agalakov for the tip on using WSL for development!

CPSC359 Pi Kits

Thu, 29 Jun 2023 10:53:06 -0600

The Pi kits are loaned to you for the duration of your enrolment in CPSC359. They must be returned in full and in an undamaged state at the end of the course, subject to the damage/late fee on your signed agreement.

The full contents of the kit are as follows. Everything on this list must be returned! If any of these components are missing from your kit, email cpsc.uls@ucalgary.ca.

Item No.	Description	Image
1	Raspberry Pi w/ HAT, SD Card, case
2	SNES Controller
3	Traffic Light Board
4	Mini-HDMI to HDMI cable
5	RJ45/Cat6 cables (x2)
6	USB Type B cable in Ziploc bag
7	USB C Power Supply

FAQ

Below are some common issues and steps on how to address them.

Do I get to keep the kit?

No. The kit is loaned to you for the duration of your enrolment in CPSC359. You will be charged a damage fee if the kit is not returned on time. This is explained in the agreement you have signed. Questions regarding this should be directed to your professor.

Can I save data to the SD card?

Please do not. The cards are loaded with the configuration necessary to use the UART interface and run the Pis at a safe clock speed. Further, the SD cards are reused for future classes, so anything you write to the card may be found by a student later on. If you do write any data to the card, please do future students the courtesy of restoring the card to its original state by downloading the test program and writing it to the card.

Something in my kit is broken

First of all, check and indeed triple check if it really is broken. If your SNES controller isn’t working how you expect it to, run it through the test program which is included in your kit. If the test program shows abnormal behaviour, send an email to cpsc.uls@ucalgary.ca.

Something is missing from my kit

Send an email to cpsc.uls@ucalgary.ca to let us know what is missing. You should also check to make sure it didn’t fall out in your bag!

I cannot return the kit on time

You are obligated to return the kit in an undamaged state by the return date stated on your agreement. If you cannot, send an email to cpsc.uls@ucalgary.ca as soon as possible. We may be able to help.

Can I use my own Raspberry Pi?

It’s best if you do not. The kits we provide are in the best known good state for bare metal development. If you use your own Pi you may get unexpected results which could impact your grade. You should use the skills you learn in 359 to make yourself something cool with your Pi though!

aarch64 Toolchain

Thu, 01 Jun 2023 11:02:21 -0600

To support CPSC359, I needed to get access to an aarch64 cross-compiler, specifically for baremetal targets. Turns out this is…harder than it needs to be. This is a brain dump of some of the work I did to get the toolchain up and running.

Generally speaking, I don’t recommend trying to build your own toolchain. But hey, go nuts if you want to. In my role as a CPSC tech I cannot support you if you try to do this, but it could be helpful if you need to waste a few hours :)

Locating a toolchain

Many distributions - Fedora and Arch to name a few - provide cross-compilers in their repos, but these are usually for linux and mingw32 targets. That’s….not super useful for baremetal! We don’t have an ABI to build against in baremetal.

Linario do provide fully built binary toolchains, but the latest version they have for aarch64-elf is 7.5.0!. To be honest, I don’t really remember how I even stumbled upon this.

A more up to date toolchain is found at ARM’s developer site, but it targets the none-elf ABI which I found didn’t always build correctly. In the early days of supporting 359 I simply packaged both of these up in my development VM and as Fedora packages for use in MS-252. But now things are weird - I’m proving two different toolchains for two different ABIs and the GCC versions are very different. And at this stage of the project, I don’t even really understand the differences between the two toolchains.

At any rate, the Winter 2023 semester went off without much of a problem, and students completed their assignments. Some code some students shared with me built nicely with aarch64-elf, thankfully!

Building a toolchain

Two GCC versions for two ABIs. That’s… not ideal. A professor and TA can adapt just fine, but we can streamline this some more. I set about working to update the toolchain and provide a consistent ABI.

I found very little use for the none-elf target, so I decided to get rid of that. But I still needed to get the VM and 252 away from such an old version of GCC - we should not expect students to use such old versions! So let’s build a toolchain.

Turns out - building a toolchain is so ridiculously hard that no one recommends doing it, but thankfully a project known as crosstool-ng exists. Thank goodness! crosstool-ng vastly simplifies the process of building a toolchain by grouping together known-good versions and baselines and produces, at the end of a download, extract, and compile process, a nice tarball of a toolchain. And there is plenty of flexibility!

Thankfully, a template for the Pi 4 existed and using crosstool’s excellent menuconfig utility I could change the ABI from Linux to none! Now I had a working toolchain I could build my test code on and deploy to MS-252 and the VM! Almost.

Packaging the toolchain

crosstool-ng makes the whole process of building a toolchain super simple, but it also makes a ton of assumptions. Primarily, it makes the assumption that if you are building a toolchain, you’re most likely not distributing it. Distros have standard ways of building toolchains (we use Fedora here at the University, and I just don’t understand Fedora packaging enough to crib from upstream there), so crosstool doesn’t want to advertise itself as a way of creating a new standard (insert relevant XKCD here). That’s fair, and I’m happy with that. Buuut I kinda need to get this packaged up for deployment to 252 - our sysadmins aren’t going to happy with a bash script that copies everything into /usr/bin.

So I cobbled together enough knowledge on how Fedora’s rpmbuild works to make a disgustingly hacky .spec file for building a package - I have it published on GitLab here for reference. The spec is not good - it would make a real Fedora packager weep. But we need something that will work!

Like crosstool itself, the spec assumes you have already built a crosstool binary and can provide it to rpmbuild. It then uses the .config file from crosstool to build the toolchain and stick it in an rpm.

Don’t use this spec. Don’t even look at it. It’s embarasing!

Final thoughts

So as I write this we are between semesters and the Fall semester will rely on this new toolchain. Early testing and feedback is good, but once the floodgates are opened, who knows what will happen? Updates here once we know more.

CPSC359 VM

Tue, 23 May 2023 11:16:05 -0600

The CPSC359 VM contains the tools required to connect to the FT2232 device connected to the Raspberry Pi in order to load and debug baremetal code. All of the tools in this VM should be available on all computers in MS-252.

You can use it as a means to quickly get a development environment for your Pi kit if you are not sure how to install the toolchain yourself (which is fair - don’t build toolchains!) or work in MS-252.

Specs

The VM is configured with the following specs:

Fedora 42
4GB RAM
2 CPUs
15GB disk.

The specs can be adjusted in the VM settings if desired.

The VM runs Fedora 42 and includes a mostly-default Cinnamon desktop, Visual Studio Code, openocd, screen, gdb, and the toolchain required to build code for the Pi - aarch64-elf-gcc.

A basic bare metal code example is included in ~/Examples/rpi4-baremetal-uart, sourced from ethanfaust/rpi4-baremetal-uart.

System Requirements

You will require the latest version of VirtualBox available for your OS. The VM has been tested in VirtualBox 7.1.12 running on Linux and Windows. macOS is currently not supported and your mileage may vary if you intend to run the VM on a macOS host.

You will need a minimum of 20GB free disk space and at least 8GB RAM. You should also ensure that virtualisation acceleration enabled in your BIOS. Check your motherboard’s documentation for more information on this.

Downloading the VM

The VM image is approx. 4GB in size and can be downloaded here.

CPSC359.ova 4.3GB, sha256:
245e0113a1238875ba2f7f3a96261f4f98926e2f5ba1f95a245bd9fb2886412b

Installing the VM

The following steps assume you already have VirtualBox installed on your system.

VirtualBox has an import feature accessed from its main menu. Select Import and then browse to where you have saved the CPSC359.ova file.

Once you have selected the .ova file, you will be presented with a screen that will allow you to customise the VM configuration. By default, we have allocated 2GB of memory and 2 CPU cores. If your hardware is up to it, feel free to increase these before continuing.

Once you are happy with your settings, click Import. Do note that it will take some time to import the image.

Accessing the FT2232 (Debug/UART/Serial interface)

Plug the FT2232 device into your computer via USB. With the VM running, navigate to Devices -> Usb and select the FT2232 device. The name may differ from what is shown here, but it will probably be something like FTDI <-> Serial

With it selected, the device will be passed through to the VM and you will be able to interface with it as though it were “plugged in” to the VM itself.

See the Development Guide for information on working with sending code to the Pi.

Known issues

When running VirtualBox on some Linux distributions, you may need to add your user to the vboxusers group.
Under Windows, USB passthrough can fail if the FTDI device is “busy” in the host. Windows tends to take control of it to install the driver - rebooting your PC may help.