Élan™SC520 Microcontroller

MicroC/OS-II RTOS Port

CodeKit Software Embedded Processor Division
V1.0 – November 27, 2000

Readme File: Version 1.0 – November 27, 2000

1 Overview
This CodeKit software contains a flat protected mode port of the MicroC/OS-II Real Time Operating System (RTOS)
for use with the Élan™SC520 microcontroller and the Remon debugger CodeKit (CK002803). MicroC/OS-II is a simple
RTOS written by Jean J. Labrosse. It is available with a book written by Mr. Labrosse, MicroC/OS-II, The Real Time
Kernel (ISBN 0-87930-543-6). This CodeKit ports the RTOS and the three example programs in the book, for use on
either the ÉlanSC520 Microcontroller customer development platform (CDP) or the NetSC520 demonstration board.
This CodeKit requires the Remon debugger CodeKit (CK002803) for downloading to the target board.

The CodeKit includes executable files for the three examples that can be downloaded and run on the CDP or the
NetSC520. However it does not contain all of the MicroC/OS-II files required to build the executables. The software
from the book is needed to build the examples. This book is available at a reasonable price through major booksellers.

The example files are designed to be downloaded to the target board either to SDRAM or Flash memory. The
programs use UART1 to print information to a terminal program at 57600 bits/s.

MPORTANT: By loading this software or any portion thereof, you agree to all the terms of the License Agreement in
the file LICENSE.PDF. Do not use this software until you have carefully read and agreed to the terms and conditions
in the Agreement. If you do not agree to the terms of the Agreement, do not use this software or any portion thereof.

)RUVXSSRUW HPDLO HSGVXSSRUW#DPGFRP

RUFDOO 

1.1 Tool and System Requirements

The following target hardware and tools are required to build and execute this CodeKit software.

ITEM DESCRIPTION
Target Hardware ÉlanSC520 microcontroller customer development platform (CDP), revision
1.0 or newer, or the NetSC520 demonstration board revision 0.5 or newer
Monitor Remon CodeKit (CK002803), and a Macraigor Raven-AMD interface.
Workstation Operating System DOS 6.2, or Windows® 95, 98, NT, ME, or 2000
Tool Suite Microsoft® Visual C++ version 6.0 or newer
Compiler* Included with Visual C++
Assembler** Microsoft MASM compatibility driver version 6.11
Linker* Included with Visual C++
Library Embedded C Library CodeKit (CK002902)
Other Software MicroC/OS-II from the book MicroC/OS-II, The Real Time Kernel, Jean J.
Labrosse, R&D Books (Miller Freeman) 1999. ISBN 0-87930-543-6.

* Note the compiler and linker are part of the Visual C++ V6.0 tool suite.
** Note MASM6.11 is a separate product and is available with the Microsoft Developer Network on Disk 5 of the
Office Test Platform and Development Tools Pack.

Page 1 of 8
Élan™SC520 Microcontroller MicroC/OS-II RTOS Port CodeKit Software V1.0 – November 2000

1.2 Installing the CodeKit Software

This CodeKit software is delivered as a self-extracting executable file. Double click on the EXE file to create a directory
called C:\AMD\CK003800. The CK003800 directory contains the Élan™SC520 microcontroller specific files and the
Visual C++ workspace and project files. The CodeKit includes executable files for the three examples that can be
downloaded and run on the target hardware. However it does not contain all of the MicroC/OS-II files required to
build the executables.

To finish setting up the CodeKit’s build environment, open a DOS window and install MicroC/OS-II by inserting the
diskette from the book into Drive A and typing A:\install C. Next change directories to the C:\AMD\CK003800
and run the COPYRTOS batch file. This copies six files from the RTOS installation to the CodeKit directory and
completes the files needed to rebuild the CodeKit.

You should also obtain and install the Remon debugger CodeKit (CK002803), the Embedded C Library CodeKit
(CK002902) and the SDRAM Setup CodeKit (CK003102).

1.3 Files and Directories

The EXE file contains the following files in several directories.

1.3.1 Top Level Directory

FILE DESCRIPTION

CLEANIT.BAT A batch file that cleans up intermediate files after a build.

COPYRTOS.BAT A batch file to copy the missing RTOS files from the RTOS installation direc-
tory.

EXAMPLE1.EXE Executable file for Example1 from the RTOS, ported to the CDP

EXAMPLE1N.EXE Executable file for Example1 from the RTOS, ported to the NetSC520

EXAMPLE2.EXE Executable file for Example2 from the RTOS, ported to the CDP

EXAMPLE2N.EXE Executable file for Example2 from the RTOS, ported to the NetSC520

EXAMPLE3.EXE Executable file for Example3 from the RTOS, ported to the CDP

EXAMPLE3N.EXE Executable file for Example3 from the RTOS, ported to the NetSC520

INCLUDES.H Master include file from the RTOS software. Ported for this CodeKit

LDALL017.CMD A Remon command file to download all required files to the Am29LV017
Flash memory on the CDP.

LICENSE.PDF Licensing agreement for the software contained in the CodeKit.

LOADCDP.CMD A Remon command file to download all required files to the Am29F040 Flash
memory on the CDP.

LOADER.EXE A loader program required for Flash memory downloading to the CDP (from
CK002902).

LOADERN.EXE A loader program required for Flash memory downloading to the NetSC520
(from CK002902).

LOADNET.CMD A Remon command file to download all required files to Flash memory on the
NetSC520 board.

Page 2 of 8
Élan™SC520 Microcontroller MicroC/OS-II RTOS Port CodeKit Software V1.0 – November 2000

FILE DESCRIPTION

PC.C Common PC utilities from the RTOS software. Ported for this CodeKit

PC.H Include file for the common PC utilities from the RTOS software. Ported for
this CodeKit

README.PDF This document in Adobe Acrobat PDF.

SMARTFLASH.EXE The Remon SmartFlash program required for Flash memory downloading.

START16.ABS A startup program required for Flash memory downloading to the CDP (from
CK003102)

START16N.ABS A startup program required for Flash memory downloading to the NetSC520
board (from CK003102)

UC_OS2.DSP The VC++ project file for the RTOS application.

UC_OS2.DSW The VC++ workspace file for the RTOS application.

UC_OS2.NCB A settings file used by Visual Studio.

UC_OS2.OPT A settings file used by Visual Studio.

1.3.2 EXAMPLE1 Directory

FILE DESCRIPTION

DEBUG A directory containing the map file and other temporary files for building
Example 1.

EX1L.C The main Example 1 source file. From the RTOS software. Ported for this
CodeKit.

EXAMPLE1.DSP The VC++ project file for the Example 1 application

OS_CFG.H The main RTOS configuration include file for Example 1. From the RTOS
software. Ported for this CodeKit.

1.3.3 EXAMPLE2 Directory

FILE DESCRIPTION

DEBUG A directory containing the map file and other temporary files for building
Example 2.

EX2L.C The main Example 2 source file. From the RTOS software. Ported for this
CodeKit.

EXAMPLE2.DSP The VC++ project file for the Example 2 application

OS_CFG.H The main RTOS configuration include file for Example 2. From the RTOS
software. Ported for this CodeKit.

Page 3 of 8
Élan™SC520 Microcontroller MicroC/OS-II RTOS Port CodeKit Software V1.0 – November 2000

1.3.4 EXAMPLE3 Directory

FILE DESCRIPTION

DEBUG A directory containing the map file and other temporary files for building
Example 3.

EX3L.C The main Example 3 source file. From the RTOS software. Ported for this
CodeKit.

EXAMPLE3.DSP The VC++ project file for the Example 3 application

OS_CFG.H The main RTOS configuration include file for Example 3. From the RTOS
software. Ported for this CodeKit.

1.3.5 Ix86f Directory

FILE DESCRIPTION

OS_CPU.H CPU specific OS include file. From the RTOS software. Ported for this Code-
Kit.

OS_CPU_A.ASM CPU specific assembly code. From the RTOS software. Ported for this Code-
Kit.

OS_CPU_C.C CPU specific C RTOS task. From the RTOS software. Ported for this Code-
Kit.

1.3.6 OS_CODE Directory

FILE DESCRIPTION

DEBUG The destination directory for os_code objects during compilation.

OS_CODE.DSP The VC++ project file for the RTOS code.

OS_CORE.C RTOS C file. From the RTOS software. Ported for this CodeKit.

SCREEN.C VT100 output utilities to support the RTOS output statements.

UCOS_II.C The master file for the RTOS. Defines the RTOS globals. From the RTOS
software. Ported for this CodeKit.

UCOS_II.H The master RTOS data structure definition file. From the RTOS software.
Ported for this CodeKit.

1.4 Setting Up the Build Environment

This CodeKit is built from the Microsoft Visual C++ workspace file UC_OS2.DSW in the libtest directory. Double click
on this file and the build environment will be loaded. The build environment assumes that Microsoft MASM 6.11 is
installed and its path is in the system PATH variable.

Page 4 of 8
Élan™SC520 Microcontroller MicroC/OS-II RTOS Port CodeKit Software V1.0 – November 2000

1.5 Setting Up the Target Hardware

This CodeKit requires the Remon CodeKit (CK002803) to be run on a target ÉlanSC520 microcontroller CDP or
NetSC520 demonstration board. Follow the hardware setup directions in that CodeKit.

The Remon CodeKit is designed to run on a Windows PC, and requires a Macraigor Raven-AMD device and an
ÉlanSC520 microcontroller CDP or NetSC520 demonstration board. The Raven device is connected to the PC via
a parallel cable, and to the CDP via a short ribbon cable. The CDP also requires an ATX power supply. The NetSC520
board requires an included 12-V power supply.

The MicroC/OS-II example programs require a terminal program to display and enter standard I/O. To set this up,
connect UART port 1 (the rightmost DB9 connector, when looking at the back of the CDP or the edge of the NetSC520
board) to a terminal program. You must use a null modem (reversing) cable because both devices are DTE's. Set
the terminal program to 57.6 Kbit/s, 8 bits, 1 stop, no parity.

1.6 Building the CodeKit Software

To build the MicroC/OS-II example files, double click on UC_OS2.DSW in the CK003800 directory. Settings have to
be changed for each example. To build Example1, first set Example1 as the active project by selecting the Project
Menu, Set Active Project..., Example1. Next select Settings... from the Project Menu. On the left, choose the
OS_CODE project. On the right, choose the C/C++ tab. Select Preprocessor in the Category list box. Ensure that
the first entry under Additional Include Directories is ..\Example1. Then select Rebuild all from the build menu. Repeat
for Example2 and Example3.

NOTE: Other settings will also need changing. The include paths to the C library files for both the compiler and the
linker will need to be changed to get these files from the correct place on your build system. For instance, after the
previous step, you will notice that ../../clib/h is an include file path in the os_code compiler options. This should be
changed to something like ../../ck002902/h, or the correct relative path for your system. A similar change must be
made in the compiler and linker options for all three example projects. When these settings are right, the projects
will build with no errors. If they are not set properly, you will get file not found errors from the compile and/or link steps.

Press F7 to rebuild all. The os_code library is built and linked with the example code to build the EXAMPLEx.EXE
file. This file will be placed in the top level directory. You can then download this EXE file to the target ÉlanSC520
microcontroller CDP or NetSC520 board using Remon.

NOTE: The linker will generate the following warning - “LINK: warning LNK4096: /BASE value “0” is invalid for
Windows 95; image may not run”. This is because we have asked the linker to locate the program at 0, which is not
valid for a Windows environment. However, it is valid for the embedded environment used on the ÉlanSC520
microcontroller CDP. You can ignore the warning.

1.7 Downloading to SDRAM

There are now two methods for running the RTOS example applications. The first method is by downloading to
SDRAM with Remon, and the second is by downloading to Flash memory using Remon.

To run the software by downloading to SDRAM on the CDP, download the resulting EXAMPLE1.EXE to the
ÉlanSC520 microcontroller CDP using the Remon command L EXAMPLE1.EXE 0:1000 (first type a Z and a YI).
Use the Remon G command to execute the application. The example will print a table of RTOS information. Pressing
the Esc key will terminate the application. A similar procedure applies for Example2 and Example3.

To run the software by downloading to SDRAM on the NetSC520 board, download the resulting EXAMPLE1N.EXE
to the NetSC520 board using the Remon command L EXAMPLE1.EXE 0:1000 (first type a Z and a YN). Use the
Remon G command to execute the application. The example will print a table of RTOS information. Pressing the Esc
key will terminate the application. A similar procedure applies for Example2n and Example3n.

Page 5 of 8
Élan™SC520 Microcontroller MicroC/OS-II RTOS Port CodeKit Software V1.0 – November 2000

1.8 Downloading to Flash on the CDP

To run the software by downloading to the 29040 Flash memory on the CDP, invoke Remon using the command
remon @loadcdp.cmd. Use the command remon@loadnet.cmd to download to the NetSC520 board. You should
optionally obtain the SDRAM setup codekit, (CK003102); this CodeKit contains a system startup program that runs
from reset.

NOTE: Loading the SDRAM Setup CodeKit into the Am29F040 Flash memory erases any prior contents of this Flash
device. This Flash device contains the General Software Embedded BIOS used to provide DOS/Windows capability
on the CDP. The BIOS for the NetSC520 board can be restored by using the instructions in CK003902.

To load into the Am29F017 device, first install the Remon CodeKit and SDRAM Setup CodeKit. Next, change the
jumpers to make the first Am29LV017 array the boot Flash device. To do this, perform the following:

• Move the jumper on JP3 from the DIPCS pins to the 8MLCS pins.
• Remove the 8MLCS jumper on JP4 or JP5.
• Set all switches on S3 to ON.
• Load the application files into the device by entering the command remon @ldall017.cmd. This command
starts Remon, erases the Flash memory, and places the loader at offset F0000 in the Flash memory.
• When the commands are finished executing, enter z followed by g, or press reset. The Start16 SDRAM Setup
Codekit executes and calls the loader, which copies the C Library executable to SDRAM and executes it. After
the process is complete, the seven segment LEDs will begin counting upward in hex, and the RTOS output will
appear on the terminal program.

1.9 Downloading to Flash on the NetSC520 Board

The procedures for the NetSC520 board are very similar to the above discussion. Before issuing the Rebuild-All,
make sure that the NETSC520 definition line in LIBRARY.H is uncommented. You should also uncomment the
NetSC520 definition in astart.asm in the Loader subdirectory. For a SDRAM download, simply follow the above
SDRAM downloading instructions. For Flash memory, the procedure is slightly different. Download the newest Remon
and SDRAM Setup CodeKits. Execute the remon @loadnet.cmd instructions as found in the SDRAM Setup
CodeKit. This command file is designed specifically for downloading the libtest application to the NetSC520 board’s
Flash memory.

2 About the Software

This CodeKit contains a simple embedded C library and example application that you can build using the Microsoft
32-bit Visual C compilers. The software consists of three parts: The C library, the libtest application, and assembly
language startup and library functions. The Visual C project files for this CodeKit are designed to ignore the standard
libraries and startup code provided by Microsoft. The output of the libtest build is an .EXE file in portable executable
(PE) format that can be downloaded to the ÉlanSC520 microcontroller CDP using Remon.

2.1 HELLO.C
This file contains the main() function for the libtest application. It calls the libtest function. Main is called from the
assembly language startup routine in START32.ASM. If the call to libtest is removed or commented out, this file can
serve as the classic “Hello World” C program.

2.2 LIB.C
This file contains standard C library functions. It also contains some ÉlanSC520 microcontroller embedded functions
such as SetVector() and InitPic().

Page 6 of 8
Élan™SC520 Microcontroller MicroC/OS-II RTOS Port CodeKit Software V1.0 – November 2000

2.3 LIBTEST.C
This file is a test application for the C library. This test performs several print and input functions and tests the utility
routines in TIMER.C. This file expects user input from the Remon console. You should read the prompts the application
prints out and respond by typing on the Remon keyboard.

2.4 BUFPOOL.C
These routines will allocate a pool of memory buffers from the available SDRAM. Each pool is an array of fixed-sized
buffers. The number of pools specified by the constant MAX_POOLS. It is currently set to 4. The maximum number
of pools is specified by MAX_BUFS_PER_POOL. It is currently 1024.

The buffer pool routines reserve memory at a specific location, outside of the application memory map. This is
specified by the macros MEM_START and MEM_STOP. These are currently set to 0x2F00000h and 0x4000000h,
reserving SDRAM from 47Mbytes to 64 Mbytes for buffer pools. You must ensure that there are no conflicts with
other uses of this memory. For the NetSC520 board, these are set to 0x0A00000h and 0x1000000h, reserving
6 Mbytes for buffer pools.

A buffer pool is created by calling the function create_pool() with the number of buffers needed and the size of the
buffers.

2.5 PRINTF.C
This file implements the standard C printf() function. This file also supports segmented address formatted printing.

2.6 SERIALIO.C
This file contains stdio functions for getch(), kbhit(), putch(), etc. It uses the AMDebug™ utility serial port so that
standard I/O is routed to a PC monitor/debugger such as Remon.

2.7 SSCANF.C
This file implements the standard C scanf() function.

2.8 TIMER.C
This file contains utility routines that use the ÉlanSC520 microcontroller timer peripherals. Routines are implemented
for the programmable interval timers, the general purpose timers, the software microsecond timer, and the real time
clock.

2.9 ALIB.ASM
This file implements low-level assembly functions such as input/output, memory mapped I/O, and AMDebug utility
special instructions. This file also contains the template for the interrupt service routine wrapper used by SetVector().

2.10 CSTART.ASM
This file replaces CRT0.ASM, which is usually used by the Microsoft compiler. This file contains the _mainCRTStartup
label, which the linker uses to find the first instruction in an application. It sets up the GP Bus and switches to 32-bit
real mode. This file then calls several library initialization routines before calling the main() function.

2.11 ASTART.ASM
This file replaces CRT0.ASM for the Loader application. This file sets up a start record used to call the Loader main
function. After the loader copies the PE file application to SDRAM, it fills in the start record with the application starting
point and stack size. It then sets the stack pointer and jumps to the Libtest application.

Page 7 of 8
Élan™SC520 Microcontroller MicroC/OS-II RTOS Port CodeKit Software V1.0 – November 2000

2.12 LOADER.C
This file is a simple PE (Portable Executable) file loader. The LIBTEST.EXE file is a PE file. Loader() looks for a PE
file signature at the beginning of Flash memory. If found, the PE file is copied to SDRAM. Starting point and stack
size requirements are returned to ASTART.ASM, which calls LOADER.C. Because LOADER assumes the PE file is
loaded at the beginning of Flash memory, this limits PE files to 56 Kbytes in size. By modifying loader() to look starting
at an offset of 64 Kbytes in the Flash device, files of more than 7 Mbytes (14 Mbytes for the NetSC520 board) can
be accommodated.

Note that more information about the code is supplied in the inline documentation.

Trademarks
© 2000 Advanced Micro Devices, Inc. All rights reserved.
AMD, the AMD logo, combinations thereof, AMDebug, and Élan are trademarks of Advanced Micro Devices, Inc.
Microsoft and Windows are registered trademarks of Microsoft Corporation.
Other product names used in this publication are for identification purposes only and may be trademarks of their respective
companies.

Page 8 of 8