%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% TITLE OF PAPER (REQUIRED)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-COMEDI and UIO drivers for PCI Multifunction Data Acquisition and Generic I/O Cards and Their QEMU Virtual Hardware Equivalents
+COMEDI and UIO drivers for PCI Multifunction\\Data Acquisition and Generic I/O Cards\\and Their QEMU Virtual Hardware Equivalents
}
\author{\large
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% STREET ADDRESS (REQUIRED)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Technick\'{a} 2, 166 27 Praha 6, Czech Republic FIXME\\
-%Karlovo náměstí 13, 121 35 Praha 2
+%Technick\'{a} 2, 166 27 Praha 6, Czech Republic FIXME\\
+Karlovo n\'{a}m\v{e}st\'{i} 13, 121 35 Praha 2, Czech Republic\\
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% E-MAIL (REQUIRED)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% STREET ADDRESS (REQUIRED)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Technick\'{a} 2, 166 27 Praha 6, Czech Republic\\
+%Technick\'{a} 2, 166 27 Praha 6, Czech Republic\\
+Karlovo n\'{a}m\v{e}st\'{i} 13, 121 35 Praha 2, Czech Republic\\
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% E-MAIL (REQUIRED)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Main reason of choosing DAQ cards for this project was ease of interfacing from programmers view and straightforward testing of proper function of the driver. This can be very helpful for beginners who are not familiar with hardware related topics.
\section{Humusoft MF614, MF624}
-Humusoft MF614 and MF624 are data acquisition (DAQ) cards. Both of this cards use PCI interface to connect to computer. The main features this cards provide are \textit{digital inputs}, \textit{digital outputs}, \textit{ADCs}, \textit{DACs}, \textit{timers}, \textit{encoder inputs}. Humusoft MF614 is predecessor of MF624 -- available functions are quite similar. There is main difference in driver programming -- MF614 has only 8-bit wide registers, whereas MF624 16- or 32-bit wide.
+Humusoft MF614 and MF624 are data acquisition (DAQ) cards. Both of this cards use PCI interface to connect to computer. The main features this cards provide are \textit{digital inputs}, \textit{digital outputs}, \textit{ADCs}, \textit{DACs}, \textit{timers}, \textit{encoder inputs}. Humusoft MF614 is predecessor of MF624 -- available functions are quite similar. There is main difference in driver programming -- MF614 has only 8-bit wide registers, whereas MF624 has 16- or 32-bit wide.
-MF624 is available for purchase on manufacturers web page. MF614 is no more sold.
+MF624 is available for purchase on manufacturers web page. MF614 is no more produced.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{UIO driver}
-Each UIO driver consists of two parts -- small kernel module (the need for it is mostly because of device-specific interrupt handling/disabling) and user-space driver logic (as shown in figure 1). This approaches main advantage is that the most of the development happens in user-space, thus during prototyping the driver (or when using bad one) it won't withdraw kernels integrity and stability.
+Each UIO driver consists of two parts -- small kernel module (the need for it is mostly because of device-specific interrupt handling/disabling) and user-space driver logic (as shown in figure 1). This approaches main advantage is that the most of the development happens in user-space, thus during prototyping of the driver (or when using bad one) the integrity and stability of the kernel won't be disrupted.
\epsin{img/uio}{80}{fig1:uio}{UIO driver structure}
\subsection*{Implementing the kernel part}
-In case of writing UIO driver for PCI device, initialization function of the module registers \texttt{struct pci\_driver} in standard way, where the probe function handles initialization of UIO-related structures. The main structure holding all data of UIO driver is \texttt{struct uio\_info}. Its simple initialization (including registration) is shown below:
+In case of writing UIO driver for PCI device, initialization function of the module registers \texttt{struct pci\_driver} in standard way\footnote{For more information about PCI driver development see \cite{book1} available online at \textit{https://lwn.net/Kernel/LDD3/}}, where the probe function handles initialization of UIO-related structures. The main structure holding all data of particular UIO driver is \texttt{struct uio\_info}. Its simple initialization (including registration) is shown below:
\begin{verbatim}
1 | /* struct pci_dev *dev */
26 | uio_register_device(&dev->dev, info);
27 | pci_set_drvdata(dev, info);
\end{verbatim}
-Structure \texttt{uio\_mem} is used for enabling memory-mapped I/O regions, whereas structure \texttt{uio\_port} is used for I/O ports.
+Structure \texttt{uio\_mem} is used for enabling memory-mapped I/O regions, whereas structure \texttt{uio\_port} is used for I/O ports (for each of this structures there is statically allocated array with size of 5 elements).
\subsection*{Driver \texttt{uio\_pci\_generic}}
When dealing with any device compliant to PCI 2.3, it is also possible to use \texttt{uio\_pci\_generic} driver in kernel instead of programming specific one. This driver makes all memory regions of the device available to user-space.
Interrupt handler uses Interrupt Disable bit in the PCI command register and Interrupt Status bit in the PCI status register. Because neither of MF614 or MF624 is PCI 2.3 compliant it is not possible to use this driver for them.
\subsection*{Interface to user-space}
-Communication with kernel part of the UIO driver is possible through \texttt{/dev/uioX} file (where X is number of instance of driver). There are several syscalls possible to use when interfacing with this file:
+Communication with kernel part of the UIO driver is possible through \texttt{/dev/uioX} file (where X is number of instance of a driver). There are several syscalls possible to be used when interfacing with this file:
\begin{description}
\item[\texttt{open()}] opens the device, returns file descriptor used for another syscalls.
\item[\texttt{read()}] blocks until an interrupt occurs (the value read is number of interrupts seen by device).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Comedi driver}
-UIO driver is versatile solution available mainly for uncommon devices. In our case of using DAQ card a special subsystem in Linux kernel designated for DAQ cards drivers can be used. It is called Comedi (\textit{Linux control and measurement device interface}). It provides library functions for user- and kernel-space making development and usage of DAQ devices easier. It is build of three different parts.
+UIO driver is versatile solution available mainly for uncommon devices. In our case of using DAQ card a special subsystem in Linux kernel designated for DAQ card drivers can be used. It is called Comedi (\textit{Linux control and measurement device interface}). It provides library functions for user- and kernel-space making development and usage of DAQ devices easier. It is build of three different parts.
\begin{description}
\item[Comedi] is part of Linux kernel. It consist of individual device drivers including Comedi driver providing basic set of functions used by device drivers.
\item[Comedilib] is user-space library providing unified interface for another user-space application to devices supported by Comedi.
-\item[Kcomedilib] is also part of Linux kernel. It provides the same API as Comedili, whereas this is used for real-time applications.
+\item[Kcomedilib] is also part of Linux kernel. It provides the same API as Comedilib, whereas this is used for real-time applications.
\end{description}
\subsection*{Implementing the driver}
\end{verbatim}
\subsection*{Interface to user-space}
-After successful compilation and loading of particular Comedi driver, there should be \texttt{/dev/comediX} (where X is number of instance of driver) file. For communication with this file Comedi library functions are used. For opening device -- \texttt{comedi\_open()}, for reading/writing ADCs/DACs -- \texttt{comedi\_data\_read()}, \texttt{comedi\_data\_write()} and for reading/writing digital inputs/outputs -- \texttt{comedi\_dio\_read()}, \texttt{comedi\_dio\_write()}.
+After successful compilation and loading of particular Comedi driver, there should be \texttt{/dev/comediX} (where X is number of instance of a driver) file. For communication with this file Comedi library functions are used. For opening device -- \texttt{comedi\_open()}, for reading/writing ADCs/DACs -- \texttt{comedi\_data\_read()}, \texttt{comedi\_data\_write()} and for reading/writing digital inputs/outputs -- \texttt{comedi\_dio\_read()}, \texttt{comedi\_dio\_write()}.
There are already applications using Comedi API\footnote{For basic list of available applications see http://www.comedi.org/applications.html} -- thus in some cases there is no need for implementing user-space application from scratch.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The PCI device specific initialization consists of:
\begin{itemize}
-\item Initializing configuration space of PCI device -- e.g. setting Vendor and Device IDs, device class, interrupt pin.
+\item Initializing configuration space of PCI device -- e.g. setting Vendor and Device IDs, device class, interrupt pin, etc.
\item Registration of I/O memory used by the device.
-\item Creating function (called when device gets allocated memory from virtual PCI controller FIXME) for mapping of physical memory to particular \textit{BARs} (Base Address Registers) of PCI device.
+\item Creating function (called when device gets allocated memory from virtual PCI controller) for mapping of physical memory to particular \textit{BARs} (Base Address Registers) of PCI device.
\end{itemize}
The very basic (non-compilable) example:
\section{Conclusion}
-The outcome of this work creates basic integrated tool for teaching PCI driver development under GNU/Linux operating system. Its main advantage is possibility to train driver development on \textit{real hardware} without the necessity of having expensive DAQ device. The other advantage is safe environment for driver prototyping -- where no mistake can damage host operating system.
+The outcome of this work creates basic integrated tool for teaching PCI driver development (mostly) for GNU/Linux operating system. Its main advantage is possibility to train driver development on \textit{real hardware} without the necessity of having expensive DAQ device. The other advantage is safe environment for driver prototyping -- where no mistake can damage host operating system.
All the information (including source code) related to topic covered in this article are publicly available on web page \texttt{rtime.felk.cvut.cz/ hw/index.php/Humusoft\_MF6xx}
projects / mf6xx.git / commitdiff