Versa 8051 MCUs
Rev 1.0
TB102 – Using Versa 8051 Include Files
How to Use Include Files for Versa 8051 MCUs
1
Introduction
This technical bulletin addresses the include files
developed for each of Ramtron’s fast and flexible
Versa 8051 microcontrollers. Include files contain code
for the MCU’s special function registers (SFRs). This
code is compatible with most popular 8051 compilers
and assemblers.
2
Supported Compilers
Currently, include files exist for the following 8051
compilers and assemblers:
•
•
•
•
•
•
•
MetaLink Macro Assembler
RIDE 51 (RKit) MA51 Macro Assembler
RIDE 51 (RKit) RC51 C Compiler
Keil µVision3 A51 Macro Assembler
Keil µVision3 C51 C Compiler
SDCC (Small Device C Compiler)
ASX8051 cross assembler
3.1
AA: The initials of the compiler or assembler, such as
ML for the MetaLink Cross Assembler.
FF: The family of the target device: RS for the Versa
8051 family.
DDDD: The first digit grouping of the device name, for
example the VRS51L2070 will use 2070.
EXT: The extension for the target programming
language, such as .H for the C language, or .inc for an
assembler.
Location and Installation
All the files are placed in a zipped folder labeled with
the device name (for example, VRS51L3074.ZIP).
When downloaded, the necessary file(s) can be moved
to two possible locations:
•
•
The compiler/assembler source directory
The folder of the current project
Consult the compiler’s user guide for where it stores its
include files.
4
About the Files
Using the Files
To refer to a SFR definition, the appropriate “include”
command must be present at the top of the file.
Naming Conventions
The file name consists of the compiler/assembler used
and the device the file is intended for:
PART_COMPILER.EXT
PART: The target device’s part number, such as
VRS51L3074.
COMPILER:
The
name
of
the
target
compiler/assembler, such as Keil (short for Keil
µVision3).
EXT: The extension for the target programming
language, such as .H for the C language or .inc for an
assembler.
Ramtron International Corporation
1850 Ramtron Drive Colorado Springs
Colorado, USA, 8092
AAFFDDDD.EXT
3.2
If you are using a different compiler, apply one of the
provided files as a template or contact Ramtron for
assistance. (Any 8051 compiler or assembler that can
produce output in the Intel Hex file format can be used
with a Ramtron Versa 8051 MCU.)
3
For compilers/assemblers that do not allow long file
names, the naming convention is as follows:
♦
♦
♦
4.1
The #include Statement (C)
The C programming language uses the #include
directive to import functions and variable names.
#include will have different syntax, depending on
where the include file was placed.
If the file was placed in the same directory as other
compiler source files, i.e. STDIO.H, use angle
brackets:
#include <VRS51L2070_SDCC.h>
If the file was placed in the same directory as the other
source files, double quotes must be used:
#include “VRS51L2070_SDCC.h”
http://www.ramtron.com
MCU customer service: 1-800-943-4625, 1-514-871-2447 x 208
1-800-545-FRAM, 1-719-481-7000
Page 1 of 3
TB102 – Versa 8051 MCUs
4.2
The $INCLUDE Statement (Assemblers such
as Keil MA51)
Most assemblers use the $INCLUDE command to
access include files.
$INCLUDE (VRS51L3074_RIDE.inc)
The abbreviation $IC can be used as well. Consult the
specific assembler’s manual for more details.
4.3
The .include Statement (Assemblers such as
ASX8051)
Some assemblers use .include to access include
files. Currently, the only assembler supporting this
syntax is the ASX8051 Cross Assembler.
.include ‘VRS51L2070_ASX8051.inc’
Consult the assembler’s manual for more details.
4.4
Multiple Inclusion Prevention
The provided include files have been protected using
conditional
preprocessor
macros
to
prevent
compile/assemble errors when including the file more
than once. For instance, in C, the following might
occur:
#include <VRS51L2070_Keil.h>
#include “AnotherFile.h”
If
AnotherFile.h
contains
#include
<VRS51L2070_Keil.h>, the compiler will not
generate an error.
Some assemblers, such as the MetaLink Cross
Assembler, do not have conditional processing. In this
case, the circumstances above would generate an
error. For these assemblers, use Ramtron include files
only once per file.
4.5
Register Access
Ramtron 8051 MCUs reserve addresses 080h to 0FFh
for SFRs. Not all SFR addresses refer to a valid SFR.
Accidentally referring to an undefined SFR can cause
unexpected results. For this reason, only access SFRs
that are defined in the include file for that device.
www.ramtron.com
4.6
SFR Page
Ramtron’s VRS51L2070 and VRS51L3074 MCUs have
more registers than addresses. Therefore, a paging
system was developed: Registers that can only be
used on page 0 must have DEVMEMCFG bit 0 set to
0. Registers that can only be used on page 0 must
have DEVMEMCFG bit 0 set to 1.
Accidentally referring to an SFR on the wrong page
can cause unexpected results. For this reason, make
sure the page is set correctly before accessing SFRs
that are defined for only one page.
4.7
Inline Assembler (SDCC)
SDCC allows ASX8051 assembler code placed within
C code (inline assembler). When accessing SFRs from
inline assembler, it is not recommended to include the
ASX8051 include file. Use the SDCC include file
instead and precede every SFR to be accessed with an
underscore. For example:
#include “VRS51L2070_SDCC.h”
void function(unsigned char q)
{
_asm
nop
inc _P0
; Correct way of
accessing P0 from inline assembler
_endasm;
P0++; // Standard way of accessing
P0 from C code
}
For more information, consult the SDCC compiler user
guide.
5
Environment Settings
It is recommended to use the following setup
parameters for error-free compiling/assembling. Always
try to use the current settings before modifying compile
options. For more information, consult the
compiler/assembler user manual.
5.1
Keil µVision3 A51 Macro Assembler
From the Project menu, select “Options for Target”. On
the A51 tab, uncheck “Define 8051 SFR names”
because the name list is incomplete and will generate
errors.
Page 2 of 3
TB102 – Versa 8051 MCUs
In the include paths edit box, type the path where the
include files are placed or browse by clicking “…”. This
eliminates the need for the full path when using the
$INCLUDE statement (see Section 4.2 for more
details).
5.2
Keil µVision3 C51 C Compiler
From the Project menu, select “Options for Target” and
click on the C51 tab.
In the include paths edit box, type the path where the
include files are placed or browse by clicking “…”. This
allows for typing angle brackets when using the
#include statement (see Section 4.1 for more
details).
5.3
names.
A
path
such
as
“C:\MetaLink
Assembler\Include” will generate assemble errors. Use
a path such as “C:\MetaLink\Include”.
5.4
RIDE (RKit) MA51 Macro Assembler
Make sure the option “Define symbols for the 8051
function registers” is unchecked (this option is off by
default), because the name list is incomplete and will
generate errors.
This checkbox is located deep within the settings.
Select “Tools” from the “Options” menu. Select “MA51”
from the list box and click “Edit”. On the next dialog,
click the “Advanced” button. In the dialog that follows,
click on “Source” from the MA51 tree. The checkbox
will now appear on the right side.
MetaLink Cross Assembler
The MetaLink Cross Assembler only understands
paths in the 8.3 file format, including for directory
Disclaimers
RIGHT TO MAKE CHANGES
Ramtron International Corporation, "Ramtron", reserves the right to make changes to its products - including circuitry, software and services - without
notice at any time. Customers should obtain the most current and relevant information before placing orders.
USE IN APPLICATIONS
Ramtron assumes no responsibility or liability for the use of any of its products, and conveys no license or title under any patent, copyright or mask
work right to these products and makes no representations or warranties that these products are free from patent, copyright or mask work right
infringement unless otherwise specified. Customers are responsible for product design and applications using Ramtron parts. Ramtron assumes no
liability for applications assistance or customer product design.
LIFE SUPPORT
Ramtron products are not designed for use in life support systems or devices. Ramtron customers using or selling Ramtron’s products for use in
such applications do so at their own risk and agree to fully indemnify Ramtron for any damages resulting from such applications.
DEBUGGING
Ramtron provides its debug tools for the sole purpose of working with the customer’s own circuitry, software and services. Any attempt to copy,
disclose, disassemble, or reverse-engineer Ramtron’s circuitry, software and services, a customer’s circuitry, software and services, or a third party’s
circuitry, software and services, without prior consent is not permitted by Ramtron or by its associates. Ramtron assumes no responsibility for
damages caused by any attempt to copy, disclose, disassemble, or reverse-engineer circuitry, software or services.
Copyrights
•
•
•
•
MetaLink 8051 Cross Assembler Copyright © 1989 by MetaLink Corp
µVision3 Copyright © Keil Elektronik GmbH / Keil Software, Inc. 1995 - 2005
RKit Copyright © 2001-1995 Raisonance SA
SDCC is subject to the GNU General Public License http://www.gnu.org/copyleft/gpl.html
www.ramtron.com
Page 3 of 3