Updated version of all labs

Updates for style and clarity; changed to misc method of specifying kernel modules; updated C coding standard to match industry.

Author: fpgacademy

lab1/design_files/DE1-SoC/README.txt

@@ -1,7 +1,8 @@
-The file part2 is an ARM executable program. It is a sample solution to Part II. This sample
-   solution exits after 12 seconds.
+The file part2 is an ARM executable program. It is a sample solution to Part II. 
+This sample solution exits after 12 seconds.
 
-The file part3.ko is a kernel module. It is a sample solution using the HEX0 display for Part III.
-
-The file part3_ASCII.ko is a kernel module. It is a sample solution using the Terminal window 
+The file part3.ko is a kernel module. It is a sample solution using the HEX0 display 
 for Part III.
+
+The file part3_ASCII.ko is a kernel module. It is a sample solution using the 
+Terminal window for Part III.

lab1/design_files/DE10-Standard/README.txt

@@ -1,7 +1,8 @@
-The file part2 is an ARM executable program. It is a sample solution to Part II. This sample
-   solution exits after 12 seconds.
+The file part2 is an ARM executable program. It is a sample solution to Part II. 
+This sample solution exits after 12 seconds.
 
-The file part3.ko is a kernel module. It is a sample solution using the HEX0 display for Part III.
-
-The file part3_ASCII.ko is a kernel module. It is a sample solution using the Terminal window 
+The file part3.ko is a kernel module. It is a sample solution using the HEX0 display 
 for Part III.
+
+The file part3_ASCII.ko is a kernel module. It is a sample solution using the 
+Terminal window for Part III.

lab1/doc/lab1.tex

@@ -18,17 +18,19 @@
 devices. This discussion assumes that the reader is using the DE1-SoC development and 
 education board, but the lab instructions apply equally well if other boards are being used,
 such as the DE10-Standard or DE10-Nano. The DE-series boards are described on the 
-FPGAcademy.org website.  Linux runs on the ARM* processor that is part 
+{\it FPGAcademy.org} website.  Linux runs on the ARM* processor that is part 
 of the Cyclone V SoC device. During the operating system boot process, Linux programs the 
 Cyclone V FPGA with the \textit{DE1-SoC Computer} system (or similar system for other
 boards). This system instantiates components inside the FPGA to make it easy to use the 
 peripherals built into the DE1-SoC board, such as the LEDs, seven-segment displays, switches, 
 and pushbuttons. For a detailed description of the computer system, please refer to 
-a document such as \textit{DE1-SoC Computer System with ARM}, available from FPGAcademy.org.
+a document such as \textit{DE1-SoC Computer System with ARM}, available as part of the
+{\it Computer Organization} materials on {\it FPGAcademy.org}.
 
 \section*{Part I}
 \noindent
 Read and complete Sections 1, 2, and 3 of the tutorial \textit{Using Linux on DE-series Boards}.
+This tutorial is available as part of the {\it Embedded Systems} material on {\it FPGAcademy.org}.
 These sections will guide you through setting up the Linux microSD card, running the 
 Linux OS on the DE-series board, and communicating with the board from a host computer. 
 
@@ -47,7 +49,8 @@ \section*{Part II}
 right-to-left, then left-to-right, and so on.  
 Use a delay so that the light moves at some reasonable speed. To implement the delay, you
 can use a Linux system function, such as \texttt{nanosleep($\ldots$)}. Documentation for 
-the \texttt{nanosleep} function can be found by searching for it on the Internet.
+the \texttt{nanosleep} function can be found by typing \texttt{man nanosleep} in a 
+Linux terminal, or by searching for it on the Internet.
 
 \section*{Part III}
 \noindent
@@ -62,7 +65,7 @@ \section*{Part III}
 augment this code to display the count of pushbutton presses as a decimal digit, either on 
 the seven-segment display {\it HEX0} or on the Linux Terminal window. You only need to 
 display the decimal value corresponding to the four 
-least-significant bits of the count, and wrap around to 0 when it reaches 9. Always
+least-significant bits of the count, and wrap around to 0 when it exceeds 9. Always
 leave the leftmost LEDR light set to 1 as a visual indicator that the device driver 
 is present in the kernel. The count values displayed on the LEDR port should cycle through 
 $\red{1}000000000, \red{1}00000000\red{1}, \red{1}00000000\red{1}0,
@@ -95,7 +98,8 @@ \section*{Part III}
 \end{lstlisting}
 
 ~\\
-\noindent More Terminal window commands can be found by searching on the Internet for
+\noindent Documentation for the {\it printk} library function can be found by searching on
+the Interet. Also, more Terminal window commands can be found by searching on the Internet for
 \texttt{VT100 escape codes}.
 
 ~\\

lab10/doc/figures/gaussian.pdf

@@ -3,6 +3,7 @@
 \newcommand{\LabNum}{10}
 \newcommand{\CommonDocsPath}{../../common/docs}
 \input{\CommonDocsPath/preamble.tex}
+\usepackage{amsmath}
 
 \begin{document}
 
@@ -24,10 +25,10 @@
 \noindent
 ~\\
 In this laboratory exercise, we will implement two versions of an image processing application
-that detects the edges of an image. The first version will run entirely on the CPU. We
-will assume that the reader is using the DE1-SoC board to run their programs. If a 
-different board is being used, the same instructions will mostly apply, but we will point
-out any differences as needed. The second version of the application will
+that detects the edges of an image. The first version will run entirely on the CPU. This
+discussion assumes that you are using the ARM processor in the DE1-SoC Computer to run your 
+programs. If a different board is being used, the same instructions will mostly apply, but we 
+will point out any differences as needed. The second version of the application will
 make use of hardware acceleration, by offloading most of the image processing operations to 
 a hardware accelerator implemented inside an FPGA. We will assume that image files are 
 represented in the {\it bitmap} (BMP) file format, using {\it 24-bit true color}.
@@ -40,11 +41,8 @@ \section*{The Canny Edge-Detection Technique}
 a widely-used edge-detection scheme. Figures~\ref{fig:tracks} and \ref{fig:tracks_edges} 
 show a sample image that is provided as the input to a Canny edge detector, as well as the 
 resulting edge-detected output image. 
-
-~\\
-\noindent
-As illustrated in Figure~\ref{fig:canny} the Canny edge-detection algorithm involves five
-stages, which are applied to the input image in succession. The following 
+As illustrated in Figure~\ref{fig:canny}, the Canny edge-detection algorithm involves five
+stages that are applied to the input image in succession. The following 
 sections describe each stage of the algorithm and show how the sample image from 
 Figure~\ref{fig:tracks} is transformed as it passes through each stage.
 
@@ -109,9 +107,10 @@ \section*{Stage 2: Gaussian Smoothing}
 \noindent
 Smoothing, or blurring, of the image is accomplished by using a {\it Gaussian filter}, which 
 modifies noisy pixels (pixels that are unlike their neighbouring pixels) to be more like 
-their neighbours. An example of a Gaussian function is illustrated in Figure~\ref{fig:gaussian}$a$.
-By choosing different values for the parameters $\sigma$ and $\mu$, the amplitude and shape of the 
-function can be selected. For this exercise we are using a digital version of the Gaussian, 
+their neighbours. An example of a 2-D Gaussian function is illustrated in 
+Figure~\ref{fig:gaussian}$a$. The shape of this function can be selected by choosing different 
+values for the standard deviation $\sigma$. For this exercise we are using a 
+digital version of the Gaussian, 
 specified as a $5 \times 5$ filter, or {\it kernel}. This kernel corresponds to a Gaussian function
 with standard deviation $\sigma = 1$ and mean $\mu = 0$. Part~($b$) of Figure~\ref{fig:gaussian}
 shows how the kernel is applied to the image. The * operator denotes {\it convolution}, $A$ is 
@@ -410,7 +409,11 @@ \section*{Part I}
 hardware-accelerated version developed later in this exercise. The code in 
 Figure~\ref{fig:skeleton} is provided along with this exercise. Some additional functionality not
 shown in the figure is also included, such as code that can draw the images on an
-output video display.
+output video display.  To view the images generated by your program, you can connect
+a video monitor to your DE1-SoC board. Alternatively, you can view the images by using the
+VGA emulator that is provided along with Lab Exercise 6. This emulator allows video output
+to be displayed in a window within a VNC Viewer tool.
+
 
 \lstset{language=C,numbers=none,escapechar=|,basicstyle=\small\ttfamily,}
 \begin{figure}[h]
@@ -658,7 +661,7 @@ \section*{Part II}
 (for the DE10-Nano board you would need to use the Onchip memory instead of SDRAM).
 The functions {\it open\_physical} and {\it map\_physical} use the {\it /dev/mem} mechanism 
 and the Linux system function {\it mmap} to provide virtual memory mappings of physical 
-addresses. More details are provided in the tutorial {\it Using Linux on DE-series Boards}. 
+addresses. More details are provided in the tutorial {\it Using Linux on DE-series Boards}.
 
 \item
 You are to write the function {\it memcpy\_consecutive\_to\_padded} to complete the code in 
@@ -668,8 +671,10 @@ \section*{Part II}
 \item
 Compile and test your code. Some sample images that have the correct dimensions are provided with
 this lab exercise ($640 \times 480$ pixels for the DE1-SoC and DE10-Standard boards, and $320
-\times 240$ for the DE10-Nano). You should see the bitmap image, upside down, on the video
-display.
+\times 240$ for the DE10-Nano). With a video monitor connected to your DE-series board, you 
+should see the bitmap image, upside down, on the video display. (Note that you cannot
+view your images using the video emulator (provided with Lab Exercise 6) that was mentioned in 
+Part I, as this emulator does not work with the system in Figure~\ref{fig:edge_detect_system}.)
 
 \item
 Write a function called {\it flip} that flips the image vertically before writing it into

lab10/doc/figures/gaussian.svg

@@ -1,15 +1,16 @@
-The file part1 is an ARM executable program that provides a sample solution for Part I. The
-program automatically exits after 12 seconds.
+The file part1 is an ARM executable program that provides a sample solution for
+Part I.  The program automatically exits after 12 seconds.
 
-The files physical.c and physical.h provide sample source code for handling virtual-to-physical
-memory mapping. These files are useful for Part I
+The files physical.c and physical.h provide sample source code for handling 
+virtual-to-physical memory mapping. These files are useful for Part I
 
-The file timer.ko is a kernel module that provides a sample solution for Part II
+The file timer.ko is a kernel module providing a sample solution for Part II.
 
-The file stopwatch.ko is a kernel module that provides a sample solution for Part III. It can 
-be controlled by the KEY pushbuttons and SW switches. The stopwatch can be stopped/started by
-pressing pushbutton KEY0. When the stopwatch is stopped, it can be set to a starting time by 
-using KEY1, KEY2, and KEY3. Pressing KEY1 causes the hundredth to be set using the SW switches,
-pressing KEY2 sets the seconds, and pressing KEY3 sets the minutes. The maximum values possible 
-are 59 for minutes, 59 for seconds, and 99 for hundredths. The SW values are interpreted as a 
-10-bit binary number.
+The file stopwatch.ko is a kernel module that provides a sample solution for 
+Part III.  It can be controlled by the KEY pushbuttons and SW switches. The 
+stopwatch can be stopped/started by pressing pushbutton KEY0. When the 
+stopwatch is stopped, it can be set to a starting time by using KEY1, KEY2, 
+and KEY3. Pressing KEY1 causes the hundredth to be set using the SW switches, 
+pressing KEY2 sets the seconds, and pressing KEY3 sets the minutes. The 
+maximum values possible are 59 for minutes, 59 for seconds, and 99 for
+hundredths. The SW values are interpreted as a 10-bit binary number.

lab10/doc/lab10.tex

@@ -4,51 +4,44 @@
 #include <sys/mman.h>
 
 // Open /dev/mem, if not already done, to give access to physical addresses
-int open_physical (int fd)
-{
-	if (fd == -1)
-		if ((fd = open( "/dev/mem", (O_RDWR | O_SYNC))) == -1)
-		{
-			printf ("ERROR: could not open \"/dev/mem\"...\n");
-			return (-1);
-		}
-	return fd;
+int open_physical (int fd) {
+    if (fd == -1)
+        if ((fd = open( "/dev/mem", (O_RDWR | O_SYNC))) == -1) {
+            printf ("ERROR: could not open \"/dev/mem\"...\n");
+            return (-1);
+        }
+    return fd;
 }
 
 // Close /dev/mem to give access to physical addresses
-void close_physical (int fd)
-{
-	close (fd);
+void close_physical (int fd) {
+    close (fd);
 }
 
 /*
  * Establish a virtual address mapping for the physical addresses starting at base, and
  * extending by span bytes.
  */
-void* map_physical(int fd, unsigned int base, unsigned int span)
-{
-	void *virtual_base;
+void* map_physical(int fd, unsigned int base, unsigned int span) {
+    void *virtual_base;
 
-	// Get a mapping from physical addresses to virtual addresses
-	virtual_base = mmap (NULL, span, (PROT_READ | PROT_WRITE), MAP_SHARED, fd, base);
-	if (virtual_base == MAP_FAILED)
-	{
-		printf ("ERROR: mmap() failed...\n");
-		close (fd);
-		return (NULL);
-	}
-	return virtual_base;
+    // Get a mapping from physical addresses to virtual addresses
+    virtual_base = mmap (NULL, span, (PROT_READ | PROT_WRITE), MAP_SHARED, fd, base);
+    if (virtual_base == MAP_FAILED) {
+        printf ("ERROR: mmap() failed...\n");
+        close (fd);
+        return (NULL);
+    }
+    return virtual_base;
 }
 
 /*
  * Close the previously-opened virtual address mapping
  */
-int unmap_physical(void * virtual_base, unsigned int span)
-{
-	if (munmap (virtual_base, span) != 0)
-	{
-		printf ("ERROR: munmap() failed...\n");
-		return (-1);
-	}
-	return 0;
+int unmap_physical(void * virtual_base, unsigned int span) {
+    if (munmap (virtual_base, span) != 0) {
+        printf ("ERROR: munmap() failed...\n");
+        return (-1);
+    }
+    return 0;
 }

lab2/design_files/DE1-SoC/README.txt

@@ -4,51 +4,44 @@
 #include <sys/mman.h>
 
 // Open /dev/mem, if not already done, to give access to physical addresses
-int open_physical (int fd)
-{
-	if (fd == -1)
-		if ((fd = open( "/dev/mem", (O_RDWR | O_SYNC))) == -1)
-		{
-			printf ("ERROR: could not open \"/dev/mem\"...\n");
-			return (-1);
-		}
-	return fd;
+int open_physical (int fd) {
+    if (fd == -1)
+        if ((fd = open( "/dev/mem", (O_RDWR | O_SYNC))) == -1) {
+            printf ("ERROR: could not open \"/dev/mem\"...\n");
+            return (-1);
+        }
+    return fd;
 }
 
 // Close /dev/mem to give access to physical addresses
-void close_physical (int fd)
-{
-	close (fd);
+void close_physical (int fd) {
+    close (fd);
 }
 
 /*
  * Establish a virtual address mapping for the physical addresses starting at base, and
  * extending by span bytes.
  */
-void* map_physical(int fd, unsigned int base, unsigned int span)
-{
-	void *virtual_base;
+void* map_physical(int fd, unsigned int base, unsigned int span) {
+    void *virtual_base;
 
-	// Get a mapping from physical addresses to virtual addresses
-	virtual_base = mmap (NULL, span, (PROT_READ | PROT_WRITE), MAP_SHARED, fd, base);
-	if (virtual_base == MAP_FAILED)
-	{
-		printf ("ERROR: mmap() failed...\n");
-		close (fd);
-		return (NULL);
-	}
-	return virtual_base;
+    // Get a mapping from physical addresses to virtual addresses
+    virtual_base = mmap (NULL, span, (PROT_READ | PROT_WRITE), MAP_SHARED, fd, base);
+    if (virtual_base == MAP_FAILED) {
+        printf ("ERROR: mmap() failed...\n");
+        close (fd);
+        return (NULL);
+    }
+    return virtual_base;
 }
 
 /*
  * Close the previously-opened virtual address mapping
  */
-int unmap_physical(void * virtual_base, unsigned int span)
-{
-	if (munmap (virtual_base, span) != 0)
-	{
-		printf ("ERROR: munmap() failed...\n");
-		return (-1);
-	}
-	return 0;
+int unmap_physical(void * virtual_base, unsigned int span) {
+    if (munmap (virtual_base, span) != 0) {
+        printf ("ERROR: munmap() failed...\n");
+        return (-1);
+    }
+    return 0;
 }