Engineer-to-Engineer NoteEE-347

Technical notes on using Analog Devices DSPs, processors and development tools
Visit our Web resources http://www.analog.com/ee-notes and http://www.analog.com/processors ore-mail processor.support@analog.com or processor.tools.support@analog.com for technical support.

Formatted Print to a UART Terminal with Blackfin® Processors
Contributed by Andreas Pellkofer

Rev 3 – June 21, 2012

Introduction
This Engineer-to-Engineer Note discusses
advanced implementations of various output
functions for the Analog Devices Blackfin®
processorfamily.
TheVisualDSP++®
development tools provide C-standard I/Osupport through functions such as printf andfprintf. The achieved output performance issufficient enough for sending sporadic (debug)
information to the Output window (console) of
the VisualDSP++ IDDE. However, multiple
prints can cause an immense decrease of theapplication’s speed.

All derivatives of the Blackfin processor family
feature the UART module, a PC-style industrystandard compatible peripheral. Additionally, thesoftware overhead is very low. In principle, one
single output pin is sufficient for the purpose.
The speed is fast enough to send lots of
information to a PC terminal application withminimal impact to the performance of the actual
application.

Figure 1. UART Terminal output example
Copyright 2010-2012, Analog Devices, Inc. All rights reserved. Analog Devices assumes no responsibility for customer product design or the use or application ofcustomers’ products or for any infringements of patents or rights of others which may result from Analog Devices assistance. All trademarks and logos are property of
their respective holders. Information furnished by Analog Devices applications and development tools engineers is believed to be accurate and reliable, however noresponsibility is assumed by Analog Devices regarding technical accuracy and topicality of the content provided in Analog Devices Engineer-to-Engineer Notes.

This EE-Note provides three different ways toimplement a powerful debug system, whichkeeps the look and feel of C-standard I/Ofunctions. It includes software examples for
currently available Blackfin evaluation boards.
The three methods are described in the sections:generate a formatted
transmission.

•Accessing the UART Directly•Replacing the Standard Device

short udprintf(unsigned char UartNum,
unsigned char DmaChan, const char*format, /* args */ ...);•Extending I/O Support to New Devices

short uprintf(unsigned char UartNum,const char *format, /* args */ ...);

It is assumed that the audience of this EE-Note is
familiar with the C programming language andthe I/O features which are implemented in thestandard. For details, refer to [1].

To understand this EE-Note, it isnecessary to work with the example codeprovided in the associated .ZIP file.

stringforUART

The functions can be found in BfDebugger.cand BfDebugger.h and use the following
prototypes:

The look and feel is like printf, which takes avariable list of arguments. The argument format
contains a set of conversion specifiers, directives,and ordinary characters that are used to control
how the data is formatted.
udprintf(0,9,”Hello UART%d\n”,0);Preparations

uprintf(0,”Hello UART%d\n”,0);All the methods described later will require theBlackfin processor’s UART interface to be set up
properly. The examples provide target-specificfunctions to do this. They can be found in theADSP-BF5xx-UART.c and ADSP-BF60x-UART.cfiles, respectively. The functions are used toinitialize the Blackfin ports, the UART, and theroutines to send out buffer contents over theUART.

A carriage return and C-style NULL termination isinserted automatically. The first arguments arethe UART number and the DMA channel
number, respectively.

The associated header files, named ADSP-BF5xxUART.h, contain information about the UART
device number to be used, the DMA channel, andindicate whether autobaud detection is usedinstead of a hard-coded bitrate.

To assist the programmer with a flexible supportof the uprintf functions versus the regular
printf functions, a set of preprocessor macros
helps to switch between different modes. Use
only one at the same time:

Another set of required sources is BfDebugger.cand BfDebugger.h. Their functions aredescribed in the following sections.

•Accessing the UART Directly
Direct access, the first method illustrated in thisEE-Note, is based on a set of preprocessor
macros and uses the string library (string.h) toThe function returns the number of characterstransmitted, or a negative value if unsuccessful.
Preprocessor Definitions__DEBUG_UART_DMA__ Directs prints to the

UART, DMA mode•••

Directs prints to the
UART, Core mode__DEBUG_FILE__ Directs prints to a file__DEBUG_VDSP__ Directs prints to the
VisualDSP++ Output window (console)__DEBUG_UART__

Formatted Print to a UART Terminal with Blackfin® Processors (EE-347)

Page 2 of 2

The last two definitions are just an additionalfeature for completeness and use the standard
fprintf() function.
•__VERBOSITY__ [int] Level of verbosity(LoV)This definition allows masking or unmaskingcertain messages using a level hierarchy. So for
example, __VERBOSITY__ is defined as 2, so any
messages using the preprocessor macros in thenext section and have n set to 1 or 2 (DEBUG(1,args) or DEBUG(2, args)) are printed while 3(DEBUG(3, args)) or higher are masked by thepreprocessor.
Preprocessor Macros
A set of preprocessor macros adds additional
functionality such as evaluation of a desiredverbosity level and automatic color output. They
insert, according to ADSP-BF5xx-UART.h., thecorrect UART number and DMA channel,respectively.
•DEBUG(n,*format,/*args*/...)*format,/*args*/...)/*args*/...)

args*/...)

No color•

INFO(n,Yellow text•

ERROR(n,*format,Red text•

MSG(n,*format,/*Green text
ANSI escape sequences are used to color theoutput. A list of available ESC codes can befound in [4].
Finally,

themacros
DEBUG_OPEN()andDEBUG_CLOSE(), both of which are required only
once in the application, are used to prepare andclose all required resources, including the UARTsetup.
DEBUG_OPEN();DEBUG(1,”Hello UART%d\n”,0);
ERROR(1,"This is an error message\n");
DEBUG_CLOSE();

C/C++ Run-Time I/O LibraryThis section discusses C/C++ run-time (CRT)
I/O library features, which can be used to senddebug information from within an application.
Additional examples showing how to work withthe I/O library can be found in [2] and [3].
Stdio.h Basics
The stdio.h header file defines a set offunctions, macros, and data types for performing
input and output. The standard functions forgenerating formatted output are the printf
family. The printf function sends its arguments
to stdout, which by default, is the VisualDSP++
console output window. The programmer canchange the device or file to which stdout refers.
The fprintf function writes to a file-pointer.
The associated file is opened / closed on the PC
by the fopen / fclose function.
File I/O Support
File I/O support is described in detail in [1]. By
default, the standard C functionality is achieved
through a device called PrimIO. It is set up andregistered on startup by the CRT and handles thethree standard files (stdin, stdout, and stderr)
and any other stream to be opened by the user,
unless the default device is changed.

Replacing the Standard Device
This method is radical. Any printf call will beformatted as usual by the I/O subsystem but
directed to the _write function (see DevEntry
structure, defined in the device.h header file),
which is associated with your new device. The
downside is that you lose the print-to-console
functionality. The advantage is that existingsource files may remain virtually unchanged.
Only a few additions to the project are required.
The documentation describes what changes arerequired to devtab.c and primiolib.c. Thesefiles are prepared and included in the example
projects already.

Formatted Print to a UART Terminal with Blackfin® Processors (EE-347)

Page 3 of 3

A modification to devtab.c is required if adevice should be pre-registered when the CRT issetting up.
If a new device claims the standard streams
instead of the PrimIO device, primiolib.c must
be modified.
The BfDebugger.c file defines the device withthe required function pointers:
struct DevEntry UartIODevice

The BfDebugger.h file provides thepreprocessor definitions used to activate thereplacing method:••__UART_IO_DEVICE____PRE_REGISTERING_DEVICE__

The following definitions determine whether theUART transfer is done by Core or DMA. Use
only one at a time:••__DEBUG_UART_DMA____DEBUG_UART__

Now any printf output is redirected.

set_default_io_device(PrimDevId);
fprintf(pUartIOFile,"Test\n");printf("Test\n");fclose(pUartIOFile);

The above example saves the current device ID(PrimDevId).
Thenanewdevice(UartIODevice) is added and marked as default.
A fopen operation opens a dummy file on thedefault device. Immediately afterwards, a new
buffer is required to be associated with the newdevice. Line buffering is preferred for consoleoutput. The previous default device can berestored, and writes can be performed to the newdevice. A printf output will still be seen to the
VisualDSP++ Output window.
SDTIO System Service
The System Services, starting with VisualDSP++
Update 8, provide a similar approach for redirecting a printf to UART. The examples canbe found in the specific Evaluation Board
examples folder:\Services\stdio\char_echo\Extending I/O Support to NewDevices
The last method is a bit more elegant than theprevious one. It uses the possibility to extend I/O
support to new devices, too. But now standard
functionality is preserved.
The same sources as the previous example areused. Pre-registering of the device is not done.
int PrimDevId =get_default_io_device();int SecDevId =add_devtab_entry(&UartIODevice);
set_default_io_device(SecDevId);
pUartIOFile = fopen("uart","w");if(setvbuf(pUartIOFile,buf,_IOLBF,size

UART Direct Access vs. I/ODevice
The downside of using an I/O device rather thanaccessing the UART directly is the DMA mode.
Before updating the buffer, any ongoing DMA
transfer must be finished first. This is ensured bya function named
UartDmaWaitForDmaDone.

Since the I/O system that prepares the buffer iscalled in the very first stage, polling of theDMA_DONE status bit must be performed
immediately after starting the transfer. Accessing
the UART directly allows moving the waitroutine right before preparing the buffer to betransmitted.

of(buf)) == -1) { return -1; }Formatted Print to a UART Terminal with Blackfin® Processors (EE-347)

Page 4 of 4

Console Application
Figure 1 shows the console output with theWindows program PuTTY. See [5] for download
details. This program can be used as analternative terminal window as HyperTerminal®
has been removed from Windows Vista®. The
window must be set to at least 91 columns toshow the “welcome screen” displayed in thepicture.
The Blackfin application features a UART talkthrough mode based on interrupts. This means
you can type characters in you console
application window and get them bounced backand displayed on the screen.

CrossCore Embedded Studio®
SupportThe document and especially the attached ZIP
file have been updated to support the newmembers of the Blackfin family, ADSP-BF60xprocessors. This processor family is only
supported by the new IDE, CrossCore Embedded
Studio® software. A dual core project running on
the ADSP-BF609 ET-KIT Lite® Evaluation
Board is included.

Conclusion
This EE-Note has shown some methods to create
debug information and print them without thelow-speed Output window (console) output of
the VisualDSP++ debugger. The providedexamples can be used as is on any Blackfin EZKIT Lite evaluation board and easily included inexisting projects with similar targets.

References[1] VisualDSP++ 5.0 C/C++ Compiler and Library Manual for Blackfin Processors. Rev. 5.2, September 2009.
Analog Devices, Inc.
[2] VisualDSP++ 5.0 Blackfin examples: Services\File System\VDK\shell_browser\. Analog Devices, Inc.
[3] VisualDSP++ 5.0 Blackfin examples: LAN\FileServerStdio\. Analog Devices, Inc.
[4] ASCII-Table.com: http://ascii-table.com/ansi-escape-sequences.php[5] PuTTY.org: http://www.putty.org[6] CrossCore® Embedded Studio 1.0.0 C/C++ Compiler and Library Manual for Blackfin Processor. Rev. 1.0, March 2012.
Analog Devices, Inc.

Document History
Revision

Description

Rev 1 – January 26, 2010
by Andreas Pellkofer

Initial release.

Rev 2 – December 10, 2010
by Andreas Pellkofer

Chapter Console Application updated. Example Code enhanced and extended tonew Blackfin Evaluation Boards.

Rev 3 – June 21, 2012by Andreas Pellkofer

Example Code enhanced and extended to new Blackfin Evaluation Boards.
Support for ADSP-BF60x Blackfin Processor family added.

Formatted Print to a UART Terminal with Blackfin® Processors (EE-347)

Page 5 of 5