4 Example host applications
4.1 General
There are six C programs that demonstrate how to access Xillybus’ device files. These programs can be found in the Xillybus package for Windows, which is a zip file that is available for download on the same web page that offers the driver.
Inside this file, there are precompiled executables in the “precompiled-demoapps” subdirectory.
The source code can be found in the “demoapps” subdirectory. These C programs are intended for Microsoft’s Visual C++ compiler which can be downloaded free as part of Microsoft’s SDK. These programs can also be used with Visual Studio.
It’s also possible to run the sample programs inside Cygwin (refer to section 4.3). MinGW can also be used for this purpose. If one of these two tools is chosen, the source code for Linux should be used, and the instructions in Getting started with Xillybus on a Linux host should be followed. Also refer to section 4.4 regarding the substitution of /dev/ prefixes with \\\\.\\.
The “demoapps” subdirectory consists of the following files:
-
Makefile – This file contains the rules that are used by the “nmake” utility for the purpose of the programs’ compilation.
-
streamread.c – Reads from a file, sends data to standard output.
-
streamwrite.c – Reads data from standard input, sends to file.
-
memread.c – Reads data after performing seek. Demonstrates how to access a memory interface in the FPGA.
-
memwrite.c – Writes data after performing seek. Demonstrates how to access a memory interface in the FPGA.
-
fifo.c – Demonstrates the implementation of a userspace RAM FIFO. This program is rarely useful, because the device file’s RAM buffers can be configured to be sufficient for almost all scenarios. fifo.c is hence useful only for very high data rates, and when the RAM buffer needs to very large (i.e. several gigabytes).
-
winstreamread.c – Reads from a file, sends data to standard output. This program does the same as streamread.c, but winstreamread.c uses and demonstrates Microsoft’s file I/O API instead of the standard API.
All programs (except for winstreamread.c) are written in classic Linux style, even though they are intended for compilation with Microsoft’s compiler.
The purpose of these programs is to show correct coding style. They can also be used as a basis for writing your own programs. However, neither of these programs is intended for use in a real-life application, in particular because these programs don’t perform well with high data rates. See chapter 5 for guidelines on achieving high bandwidth performance.
These programs are very simple, and merely demonstrate the standard methods for accessing files. These methods are discussed in detail in the Xillybus host application programming guide for Windows. For these reasons, there are no detailed explanations about these programs here.
Note that these programs use the low-level API, e.g. _open(), _read(), and _write(). The more well-known API (fopen(), fread(), fwrite() etc.) is avoided, because it relies on data buffers that are maintained by the C runtime library. These data buffers may cause confusion, in particular because the communication with the FPGA is often delayed by the runtime library.
4.2 Compilation
As already mentioned, there is no need for a compilation for the purpose of trying out the example programs: The Xillybus package for Windows contains files that are ready to run on a Windows computer. But obviously, the compilation of these programs is necessary to make changes.
Those who are used to working with Microsoft Visual Studio will probably prefer using this compiler, and know how to use this tool. The example programs are simple Command Prompt applications.
However, the guidelines below are based upon Microsoft’s software development kit (SDK) 7.1. This is an old and simple development kit, which is available for download at no cost. The instructions below are based on this software, mainly because a small number of steps are required to accomplish the task.
Download and install Windows SDK 7.1. Open Program Files in the “Start menu” and select Microsoft Windows SDK v7.1 > Windows SDK 7.1 Command Prompt. This opens a Command Prompt window, which has several environment variables configured for the purpose of compilation. The text in this window is displayed with a yellow font.
Change directory to where the C files are:
> cd \path\to\demoapps
To run compilation on all programs, type “nmake”. The following transcript is expected:
> nmake Microsoft (R) Program Maintenance Utility Version 10.00.30319.01 Copyright (C) Microsoft Corporation. All rights reserved. if not exist "XP32_DEBUG/" mkdir XP32_DEBUG cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ] link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ] cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ] link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ] cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ] link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ] cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ] link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ] cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ] link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ] cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ] link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ]
The six rows that start with “cl” are the commands that are requested by “nmake” in order to use the compiler. These commands can be used for compilation of the programs separately. However, there is no reason to do so. Just use “nmake”. The same goes for the “link” commands, which perform linking on the object files and the libraries, and hence create executables.
The executables (and the object files) can be found in the XP32_DEBUG subdirectory. This subdirectory is created during the compilation process if necessary. As the directory’s name implies, these files are intended for 32-bit Windows XP. However, the executables run on later versions of Windows, including 64 bit versions.
The “nmake” utility runs compilation only on what is necessary. If only one file is changed, “nmake” will request the compilation of only that file. So the normal way to work is to edit the file you want to edit, and then use “nmake” for a recompilation. No unnecessary compilation will take place.
Use “nmake clean” in order to remove the executables that were generated by a previous compilation.
As mentioned above, the Makefile contains the rules for the compilation. The syntax of this file is not simple, but fortunately it is often possible to make changes to this file by using just common sense.
A Makefile relates to the files that are in the same directory as the Makefile itself. It is therefore possible to make a copy of the entire directory, and work on the files that are inside this replica. The two copies of the directory will not interfere with each other.
It is also possible to add a C file and easily change the Makefile, so that “nmake” also runs a compilation of this new file.
4.3 Using tools from Linux with Windows
People who work with Linux tend to use standard command line tools for carrying out simple tasks. These tools are less known among people who primarily use Windows. The main reason is that the command-line tools for Windows are unfortunately not as useful as the tools that exist on every Linux computer.
As already mentioned, it is possible to carry out the “Hello world” test as detailed in Getting started with Xillybus on a Linux host instead of the instructions in this guide. In order to do that in Windows, it is necessary to make a few tools available on the computer. There are a few alternatives for accomplishing that:
-
Download and install two packages from the Gnuwin32 project: Coreutils and Util-Linux-NG. These two packages cover the needs of the “Hello world” test (and also supply programs that aren’t required for this task). Note that even if these packages are installed with Gnuwin32’s setup tool, there will not be change in the Command Prompt’s execution path.
-
Use the tools for Windows that are supplied by Xillybus: These can be found in in the “unixutils” subdirectory of the Xillybus package for Windows. The tools that are obtained this way were selected from the Gnuwin32 packages in order to suffice for the “Hello world” test.
-
Install Cygwin. Choosing this method means installing a whole system that offers a command-line interface that resembles Linux. An installation of this sort may include the GNU C compiler and other tools for software development. This is the recommended choice for those who are used to working with Linux’ command-line.
4.4 Differences from Linux
When carrying out the “Hello world” test as described in Getting started with Xillybus on a Linux host on a Windows computer, there are a few differences to be aware of.
The most important difference is that the path to the device files is \\.\, and not /dev/. So for example, when the guide for Linux mentions /dev/xillybus_read_8, the correct file name for Windows is \\.\xillybus_read_8.
Because the name of the device file contains backslashes, there is a need for escape characters in some situations: The backslash itself is often treated as an escape character. Hence there’s a need for two backslashes for each backslash in the file name. In other words, \\.\ needs to be written as \\\\.\\. For example, when the guide for Linux mentions /dev/xillybus_read_8, the file name \\\\.\\xillybus_read_8 should be used in some situations.
But it is not always so: When a program is executed from the Command Prompt, there is no need for an escape characters. The Command Prompt treats a backslash like any other character.
In most programming languages, there is a need for extra backslashes. Inside scripts there may be a need for extra backslashes. This depends on how the arguments are handled inside the script.
4.5 Cygwin’ warning message
Extra backslashes are required with Cygwin’s command-line interface. However, when the \\\\.\\ prefix is used for the first time, Cygwin will probably display a warning as follows:
$ cat \\\\.\\xillybus_read_8
cygwin warning:
MS-DOS style path detected: \\.\xillybus_read_8
Preferred POSIX equivalent is: //./xillybus_read_8
CYGWIN environment variable option "nodosfilewarning" turns off this warning.
Consult the user's guide for more details about POSIX paths:
\url{http://cygwin.com/cygwin-ug-net/using.html#using-pathnames}
This warning should be ignored.
Xillybus has been extensively tested with Cygwin, and the method that is shown above for accessing device files is correct. For normal file names, it’s indeed a better idea to use forward slashes. But Cygwin does not translate //./ into \\.\. Hence the use of backslashes is mandatory.
In order to avoid this warning, possibly follow the suggestion in the warning message regarding the environment variable.