Using your MCU's time processing unit as an on-chip logic analyzer: Part 2

The following sections describe the steps taken to make the uClinux Operating System work on the MCF5235 evaluation board. All the source code and the uClinux system files that needed to be modified for the Logic Analyzer application are available for download as a Zip file at Embedded Logan Code..

There is also a complete S-record image of the application suitable for the M5235BCC evaluation board. In addition to the configured uClinux kernel and all the binary applications developed for the Logic Analyzer device, the image also contains the web-server-side HTML pages and a prototype of the visualization component self-installing cabinet file.

Configuring the uClinux
After you extract the uClinux distribution somewhere to your home folder, you should see the directory structure as shown below:

+ bin helper build utilities and tools
+ config scripts used to configure the uClinux system
+ Documentation various how-to documents
+ glibc standard C library source code
+ images destination directory for generating uClinux images
+ include kernel include files
+ lib other libraries source code + linux-2.0.x Linux 2.0 source tree
+ linux-2.4.x Linux 2.4 source tree
+ linux-2.6.x Linux 2.6 source tree
+ Makefile the master makefile
+ romfs device file system generated as uClinux apps are built
+ tools various scripts and utilities used during build process
+ uClibc standard C library optimized for uClinux
+ user user application source tree
+ busybox standard Unix command line toolset
+ samba SMB/NetBios services
+ portmap remote procedure call portmapper (used by NFS)
+ boa the web server source
+ .. a lot of other Linux applications ported to uClinux
+ vendors support and configuration files
+ Motorola Freescale processor platforms
+ M5235EVB ColdFire 5235-specific makefiles and configurations

With such a clean installation, and before any changes are made to the source tree, it is worth testing that you are able to configure and build up the uClinux image. There are several ways to configure the uClinux before building " one of the most user-friendly is to use the text-based menu-driven application invoked by the "make menuconfig" command from the base "uClinux-dist" directory.

In the first menu system, shown below, you can select the vendor and target board (Motorola, M5235EVB), Linux kernel version (2.4.x), and the uClibc as the standard C library. Options to further customize the kernel and vendor/user settings should also be selected, so the next menu system is automatically invoked upon exiting the first menu system. The following list below summarizes the options we enabled in order to make the uClinux successfully work on the development board.

[uClinux-dist]$> make menuconfig

Linux Kernel 2.4.27 Configuration:
* Code maturity level options
    o Prompt for development and/or incomplete code/drivers
* Loadable module support
    o Enable loadable module support
* Processor type and features
    o MCF5235 CPU
    o 150MHz CPU Clock Frequency
    o Motorola M523xEVB board support
    o 16MB RAM size
    o AUTO RAM bit width
    o Kernel executes from RAM
* General setup
    o Networking support
    o Kernel core format ELF
    o Kernel support for flat binaries
* Block Devices
    o RAM disk support
    o 4096 Default RAM disk size
    o ROM disk memory block device (blkmem)
* Networking options
    o Packet socket
    o TCP/IP networking
* Network device support
    o Network device support enabled o Ethernet 10 or 100Mbit
* FEC Ethernet controller of ColdFire 52xx
* Character devices
    o ColdFire serial support
* File systems
    o /proc file system support
    o ROM file system support
    o Second extended fs support
    o Network File Systems
* NFS file system support
* Provide NFSv3 client support

uClinux Configuration
* Core Applications
    o shell program: other
    o expand
* Filesystem Applications
    o SAMBA
* nmbd
* Network Applications
    o boa
    o portmap
* BusyBox
    o BusyBox: enabled with the following applets: cat, chmod, cp, echo, expr, ifconfig (with status reporting), init (using inittab), insmod (with lsmod and rmmod), kill, ln, ls, mkdir, mknod, more, mount (with loop devices and NFS support), mv, ping, ps, rm, rmdir, route, shell (with msh as /bin/sh), sleep, test, true_false, udhcpc, umount, uname, yes

After the configuration is saved, you have to run the "make dep" command and then the final "make":

[uClinux-dist]$> make dep
[uClinux-dist]$> make

In a few minutes, you should get the resulting uClinux binary image in the "image" output directory.

Customizing uClinux for the Logic Analyzer
Having a clean uClinux source tree, let's now add the "Logic Analyzer" application.

A good starting point is to read the Adding-User-Apps-HOWTO document we have created, which will guide you step by step in modifying the "user/Makefile" and "config/config.in" files. Our code will be placed in the "user/logan" directory and the build will be controlled by two configuration options: CONFIG_USER_LOGAN_LOGAN and CONFIG_USER_LOGAN_KMODS.

"logan_drv" - the Kernel Driver
The Logic Analyzer kernel driver is heavily based on the examples given in the O'Reilly "Horse Book", the Linux Device Drivers 2nd Edition. The driver code begins in the logan_mod.c file and completely reuses the C API code developed for the eTPU "LA" function.

The driver compiles to logan_drv.o, a so-called "loadable module" of the uClinux kernel. In fact, the code is compiled as if it were a part of the kernel, with access to all kernel and device resources. The only difference from the "static" device drivers compiled into the monolithic kernel image, is that the loadable module is available as a separate object and can be "inserted" into the running kernel using the "insmod" utility.

After the logan_drv.o module is inserted into the kernel, it initializes the eTPU, installs the eTPU interrupt service routines and registers itself as a "character device 42". Being a character device means that the driver mimics the standard file behavior of a special file object, often called a "device file". Any time this special file is opened or closed, or any time it is read or written to by the application, the driver gets a special call to handle the operation. The device file can be created anywhere in the user file system using the mknod utility. Typically, the /dev directory is the place where device files are stored:

[uClinux-dist]$> mknod /dev/logan c 42 0
The "/dev/logan" here is an arbitrary name under which the driver is known in the user file system. The 42 and 0 are so-called "major" and "minor" device numbers. The major number identifies the particular device driver, while the minor number is passed to the device driver as an argument and typically identifies different device instances.

There can be up to 255 different character device drivers registered in the system. The major number 42 is reserved for experimental purposes or custom applications, so we use it for our application. The minor number is currently ignored by the logan_drv, but in future it might be used to identify a particular eTPU unit on devices with multiple eTPUs.

The logan_drv operation is quite straightforward: any time the device file is written to, the input data is parsed as a set of newline-delimited commands and processed one by one. In case there is any output text to be generated by the driver, it is buffered until the device file is read. The following list gives a summary of "commands" handled by the driver:

* set param value - configure the Logic Analyzer parameter
* get param - obtain a parameter value
* start - start measuring
* stop - abort measuring
* trig force - a trigger event to occur
* get_status - get the state machine status (running, triggered, ...)
* get_data - get the measured data

The set and get commands are used to configure the parameters of the eTPU Logic Analyzer engine. The following "param" values can be used:

* set channel_mask - configure channels to be used
* set buffer_size - allocate CPU buffer memory
* set trigger_mask_hl - specify High-to-Low trigger channels
* set trigger_mask_lh - specify Low-to-High trigger channels
* set pre_trigger_time - specify pre-trigger time (in clocks count)
* set total_time - specify maximum measure time (in clocks count)

The advantage of text-based communication between kernel driver and the user space application is that simple "echo" and "cat" utilities can be used to exercise or to monitor the Logic Analyzer operation.

"logan_srv" - the Network Interface
The Logic Analyzer network application is a very simple TCP server used only to forward and replicate text messages between the network client and the /dev/logan device file. The application runs in an endless loop, permanently waiting for an activity on any of the client-connected sockets.

Each time a text-based message is received from any client, it is written to the /dev/logan file. Then, the file is immediately read and its whole content, i.e. the command response, is replicated back to all listening clients.

The output generated by the kernel driver is fully "self-descriptive", so even if there are multiple network connected clients and one of them issues a command to the Logic Analyzer device, the response describes to all the clients what really happened. In theory, this mechanism enables the Logic Analyzer device to be accessed simultaneously from multiple clients.

For example, the command:
set channel_mask 0x0f

generates the response:
value channel_mask=0x0f

which is sent to all network-connected clients. Each client then knows that the channel mask was changed and what the new value is. In general, any changes to the configuration or to any data measured by the Logic Analyzer device are immediately made available to all clients.

Making it all Work Together
What I still find wonderful on the Linux source tree, and even more so on the uClinux distribution, is the really well thought out set of make-files, spread over the source directories and co-operating together.

Using a single "make" command issued in the base directory, the whole system builds up into a binary image which is ready to be burned onto a device Flash memory and used as it is. The image consists of the kernel runtime as well as the read-only file system (romfs) mounted automatically as a root directory "/".

The romfs contains all the files needed by the running system: configuration files, device file, utilities and user applications. For the Logic Analyzer device, some system files need to be changed in the file system, so first let's take a look on how it all works.

During the make process, the complete file system is temporarily built in the "romfs" subdirectory of the uClinux tree, from where it is later packaged into the binary image suitable for the embedded target.

You can examine the files in the romfs directory to see what you really get after the build process, but it makes no sense to make any modifications here. All romfs files are re-generated any time the make builds the binary image. The question of how the romfs gets built can be answered after a closer look at the individual Makefiles, and especially the central Makefile of the selected platform, which is "vendors/Motorola/M5235EVB" in our case.

This Makefile builds the romfs directory structure, prepares device files in the directory, and installs the configuration and other "static" files into the romfs/etc or romfs/devromfs/home directories. The executables such as the BusyBox, "boa" web server, or our logan_srv, logan_drv.o are installed by individual Makefiles as part of their build processes.

By default, the M5235EVB Makefile takes the files to be installed from the "vendors/Generic" directory. To build up the Logic Analyzer system we made a slight modification to the Makefile in order to take the original files from a separate "M5235EVB/LogAn" directory. All the files can be found in the download section.

The resultant "image.bin" is finally built with the "make" command and can now be tested on a real board.

On an embedded platform, the uClinux system is typically invoked by a so-called "bootloader" program " a small application which initializes the CPU, memory and other board resources and jumps to the operating system entry point. The factory-default bootloader program for the MCF5235BCC board is the "dBug", also available for other Freescale platforms.

dBug is quite a powerful application in itself, enabling the downloading of other applications or operating system images over the Ethernet (TFTP) network, and also the programming of the system Flash memory. The user communicates with dBug using a serial command-line interface which is then reused by the uClinux as a system console.

Please see the dBug documentation available on the board support CD, or visit www.freescale.com for more details on how to use and configure the dBug environment. Look for the MCF_DBUG product in the Design Tools section of a particular product summary page.

To view the uClinux startup process after it is invoked from dBug by a "go" command, go to iClinux Startup. 

When the device is running, you may try connecting to it from a regular Internet Explorer browser. The default device address assigned by the startup script "/etc/rc" is 169.254.100.100. This address remains valid until the "udhcpc" application discovers a DHCP server and requests an address more suitable for the local network.

At any time on the device console, you may issue the "ifconfig" command which gives you information on what address is currently assigned to the TCP/IP networking layer.

Conclusion
The choice of using the uClinux operating system just to implement the network interface seems, even to us, as an overkill today. Using one of the commercially available TCP/IP drivers, or the freely available Open-TCP stack would perhaps better suit this kind of application.

On the other side, we began this project to demonstrate the eTPU capabilities and to show how it helps off-load the main CPU from extensive and time-consuming work. And what might be a better demonstration than the Logic Analyzer working simultaneously with the operating system core, networking services, and the web server?

More information on this application and access to all of the source code and the uClinux system files that need to be modified for the Logic Analyzer application is available for download at Embedded_logan_code as a 1.81 MB zip file. 

Included in the download is a complete S-record image of the application suitable for the M5235BCC evaluation board. In addition to the configured uClinux kernel and all the binary applications developed for the Logic Analyzer device, the image also contains the web-server-side HTML pages and a prototype of the visualization component self-installing cabinet file.

Michal Hanak is systems engineer and Milan Brejl, Ph.D., is System Application Engineer is Freescale Semiconductor's Roznov Czeck Systems Center. 

To read Part 1 in this series, go to The basics of using an enhanced TPU.