1

Building, Porting and Debugging YAMON

2
TABLE OF CONTENTS
OVERVIEW................................................................................................... 3
YAMON PROGRAM FLOW........................................................................ 3
GRAPHICAL REPRESENTATION OF THE FLOW:................................. 5
HOW TO BUILD YAMON........................................................................... 6
BUILDING YAMON TO RUN STRICTLY FROM RAM.......................... 8
ADAPTING YAMON FOR A NEW AMD ALCHEMY DESIGN............ 10
REFERENCES............................................................................................. 14










3
Overview
YAMON is the ROM monitor provided on AMD Alchemy evaluation and reference
boards. YAMON is analogous to a PCs BIOS in that it performs system initialization,
but YAMON does not contain all the features and services of a PC BIOS. YAMON is
capable of the following:

1. YAMON detects the specific board/CPU at run time.
2. YAMON contains both little- and big-endian run-time images. YAMON detects
the endianess at run time and invokes the appropriate image.
3. YAMON performs initialization of the memory controllers, caches, TLB, and
peripherals and PCI.
4. Command line history and editing, common commands such as load, go, and
dump.
5. Downloads over Ethernet (via TFTP) and serial port.

YAMON is not an operating system. It does not support switching between several
concurrent applications nor does it manage memory, caches, or the TLB. YAMON
allows a user to examine/modify memory and memory mapped devices as well as loading
and starting an application.
YAMON Program Flow
A YAMON image consists of three components, which are concatenated together into a
single image. These components are:

1. YAMON startup/initialization code that initializes memory controllers, caches,
TLB and peripherals, and then passes control to either the little- or big-endian
YAMON monitor image.
2. Little-endian YAMON monitor image
3. Big-endian YAMON monitor image.

4
The startup/initialization code is invoked upon a reset. At reset, the processor fetches
instructions starting at the reset exception vector, MIPS virtual address 0xBFC00000
which corresponds to physical address 0x1FC00000. Located at 0xBFC00000 is the
_reset_handler() function from file yamon/init/reset/reset.s. This
code performs the board-specific initialization of the memory controllers, caches, TLB
and peripherals. The actual board-specific code is partitioned into a separate file, e.g.
yamon/arch/init/reset_db1550.S, that is included at compile-time for the
board. To learn more about the board-specific reset file, refer to the separate application
note Reset Software for Alchemy Au1000 Processor[2]. When the board-specific
initialization comples, this code examines the CP0 Config0[BE] bit to determine the
appropriate big- or little-endian image to invoke.

The file yamon/bin/link/link.xn is the linker script for the startup/initialization
code. The script contains the symbols _reset_handler_be and
_reset_handler_le that correspond to the locations of the YAMON monitor big-
and little-endian images. The values for these symbols correlate to the addresses utilized
in the endian-specific linker scripts yamon/bin/link/link_eb.xn and
yamon/bin/link/link_el.xn.

The big- and little-endian YAMON monitor images start with the code located in file
yamon/init/init.S and is reached by the startup/initialization code jumping to
function _reset_handler_end(). This code copies the YAMON monitor code and
data from ROM/Flash to RAM, initializes the stack and global pointers, and then calls
c_entry(). The function c_entry() in file yamon/init/main.c. performs the
initialization of the monitor itself. Most of the initialization is done in initmodules()
function in yamon/init/initmodules.c. The YAMON command line interface is
then started with the invocation of function shell_setup().

5
Graphical Representation of the flow:



Reset Exception vector BFC00000












.




Reset.S

_reset_handler()
../arch/init/reset_xxxx.s


if (Little Endian)
jump to EL YAMON
else
jump to EB YAMON

EL YAMON
reset_handler_end()
Init.s
Init_au1000.s
Init_platform_s.s
shell_setup()

EBYAMON
reset_handler_end()
Init.s
Init_au1000.s
Init_platform_s.s
shell_setup()
6
How to Build YAMON
To build YAMON, do the following things.
1) Install the supplied GNU tool-chain [5].
2) Extract the YAMON sources. Use Winzip, and be sure to select the option Use Folder
Names so that the directory structure is preserved.
Note the ZIP archive is password-protected. The password is in the file Yamon
Software Agreement.pdf in the same directory as this document.

3) Invoke the Cygwin BASH shell for the subsequent commands (this step is not
necessary if performing on a Unix host).

4) Configure YAMON for the desired board:
% cd yamon
% cd bin
% make install
% vi makefile

and change the variable

BUILDTYPE

to reflect the proper board. Be sure to use all uppercase as the board type is translated into
a C pre-processor #define and used in the YAMON source code.

4a) If building on a Unix host, you may need to remove extraneous carriage returns (^M)
and make sure all script files (*.pl) are executable. Failure to do both of these may cause
the build to fail. Typical error messages are:

"bad interpreter: No such file or directory"
(the shell literally tries to invoke /usr/bin/perl^M )

7
"/bin/sh: line 1: ./postproc.pl: Permission denied"
(postproc.pl is not marked executable)

You must mark a file executable after using dos2unix because it marks files readable and
writable only.
% dos2unix *.pl
% chmod +x *.pl

5) Build YAMON:
% make

When the make process completes, there is an S-Record in the current directory by the
name similar to:

yamon-02.24DB15500.rec.m

This S-Record can then be used by a part programmer (or YAMON itself) to program
into the Flash. The filename has two important pieces of information in it: the version and
the board name.

When updating YAMON on the board, please read the file

UpdateYAMON.txt

for the recommended instructions for updating YAMON. These instructions are specific
to each board, so please examine the correct UpdateYAMON.txt file.

8
Building YAMON to Run Strictly from RAM
It is possible to build a version of YAMON that runs strictly from RAM; meaning that
the YAMON is not placed into ROM/Flash memory or booted from the reset vector.
Instead, the RAM-only version of YAMON is downloaded into RAM (presumably by the
YAMON already present on the platform, or perhaps by an EJ TAG probe), and run from
RAM. The following paragraphs describe how to create the RAM-only version of
YAMON.

There are two distinct differences between the RAM-only YAMON and the normal
YAMON built for ROM/Flash.
1. The board-specific reset file which is normally included as part of the
yamon/init/reset/reset.S code, is not utilized. Stated differently, the board-specific
reset file is omitted or commented out in this file.
2. The load addresses for YAMON are changed from 0xBFC00000/0x9FC00000 to
a RAM address. In the examples that follow, the address 0x80C00000 is utilized.
For the first difference cited above, this implies that the Alchemy platform has already
been initialized, and in particular the memory controllers. This is normally the case if
using the YAMON already present on the board to load the RAM-only YAMON, or if
during bring-up of a new board, an EJ TAG probe has been utilized to initialize memory
controllers. Thus, with memory and other initialization already performed, the reset code
is not needed, and in fact may create problems, for the RAM-only YAMON.

For the second difference cited above, the link addresses must be changed to be that of a
valid RAM address. The default link addresses of 0xBFC00000/0x9FC00000 are not
valid for the RAM-only version since RAM is not located at these addresses (rather
ROM/Flash is). Any RAM address can be chosen so long as it meets the following
criteria:
the address is outside the first 1MB of RAM; YAMON copies itself to the lowest
1MB of RAM upon startup and runs from this area there-after.
the address must be at least 1MB from the end of RAM; typically upwards to
1MB of space is needed to download the YAMON image.
So for example, if the Alchemy board has 64MB of RAM, physical 0x00000000 to
0x04000000, then choosing to load YAMON at physical address 0x00C00000, or
KSEG0 address 0x80C00000 (KSEG1 address 0xB0C00000), is a valid address.

With the above information in hand, the steps to create a RAM-only version of YAMON
are outlined here.
1. If applicable, build and boot the normal YAMON which resides in ROM/Flash;
this is merely a sanity check to make sure that known good YAMON sources are
in use.
2. Edit file yamon/init/reset/reset.S and ensure that the board-specific reset file is not
included in this file.
3. Edit file yamon/bin/link/link.xn and change three lines:
_r eset _handl er _l e = 0x9FC10000;
_r eset _handl er _be = 0x9FC90000;

9
. t ext 0x9FC00000 :
t o
_r eset _handl er _l e = 0x80C10000;
_r eset _handl er _be = 0x80C90000;

. t ext 0x80C00000 :

4. Edit file yamon/link/link_el.xn and change:
. t ext _i ni t 0x9FC10000 :
t o
. t ext _i ni t 0x80C10000 :
5. Edit file yamon/link/link_eb.xn and change:
. t ext _i ni t 0x9FC90000 :
t o
. t ext _i ni t 0x80C90000 :
6. Now build YAMON using the same commands as always.
7. The RAM-only YAMON is located in the yamon/yamon-02.<VERSION>.rec
file. Copy this file to the TFTP download folder.
8. Using the existing YAMON, or an EJ TAG probe, download the RAM-only
YAMON, and invoke it. Note that the entry point is going to 0x80C00000, and
not the default entry point cited in the S-Record file.
10
Adapting YAMON for a New AMD Alchemy Design

In general, when porting YAMON to a new board, only the following files need to be
modified. However, the majority of the effort required in porting YAMON to the new
board is focused on the board-specific reset file. AMD strongly encourages reading the
application notes Mapping a Boot ROM on the AMD Alchemy Au1xxx and Reset
Software for the AMD Alchemy Au1xxx as these documents describes memory map
issues and reset activities.

AMD recommends changing the following files in the order in which they appear in the
table.

File Name File Path File Status
Makefile Yamon/Bin/makefile Modified
Reset.S Yamon/Init/init/reset.S Modified
Pb1000.h Yamon/Arch/include/pb1000.h Modified
Initswitch.h Yamon/Arch/include/initswitch.h Modified
Init_platform.c Yamon/Arch/init/platform/init_platform.c Optional
Reset_xxxx.S Yamon/Arch/init/reset_xxxx.S New


1) Makefile: An entry needs to be added for the new board, specifically the
makefile variable BUILDTYPE must be declared with the name of the
new board. In the YAMON source files, the BUILDTYPE variable is
post-fixed with _CONFIG to provide compile-time C pre-processor
conditionals. For example, the Db1550 board is defined as BUILDTYPE
= DB1550 in the Makefile, and is conditionalized as #ifdef
DB1550_CONFIG in yamon/init/reset/reset.S.
2) Reset.S: This file is modified to add a conditional to obtain the board-
specific startup/initialization code. For the Db1550 example, the file
11
contains:
#ifdef DB1550_CONFIG
#include "../arch/init/reset_db1550.S"
#endif
3) Pb1000.h: This file is modified to add a conditional to describe the board-
specific ROM/Flash and DRAM arrangement. In YAMON terminology,
MONITORFLASH is the ROM/Flash space occupied by YAMON itself.
FILEFLASH is the space where YAMONs environment variables are
located. SYSTEMFLASH is the remaining ROM/Flash and is not directly
utilized by YAMON; it can be used to store operating systems, flash file
systems, data, etc. YAMON can be utilized to program Flash as long as it
is described within these three ranges.
SYSTEMRAM_SIZE informs YAMON as to how much DRAM is
available on the board.
For the Db1550 example, the file contains:
#i f defined( DB1550_CONFI G)

#def i ne PB1000_SYSTEMFLASH_BASE 0xB8000000
#def i ne PB1000_SYSTEMFLASH_SI ZE 0x07c00000 /* ~124Mbyte */
#def i ne PB1000_SYSTEMFLASH_SECTORSI ZE 0x00020000
/*128kByte*/
#def i ne PB1000_SYSTEMFLASH_BANKCOUNT 1
#def i ne PB1000_SYSTEMFLASH_BLOCKCOUNT 63

#def i ne PB1000_MONI TORFLASH_BASE 0xBFC00000
#def i ne PB1000_MONI TORFLASH_SI ZE 0x003c0000 /* ~4MByte */
#def i ne PB1000_MONI TORFLASH_SECTORSI ZE 0x00020000 /*
128kByte */

#def i ne PB1000_FI LEFLASH_BASE 0xbf f c0000
#def i ne PB1000_FI LEFLASH_SI ZE 0x00040000 /*256kByte*/
#def i ne PB1000_FI LEFLASH_SECTORSI ZE 0x00020000 /* 128kByte
*/

#def i ne PB1000_SYSTEMRAM_BASE 0x00000000
#def i ne PB1000_SYSTEMRAM_SI ZE 0x0C000000 /* 196 MEG */

NOTE: The MONI TORFLASH al ways st ar t s at 0xBFC00000, whi ch
i s t he r eset except i on vect or at whi ch YAMON i s l ocat ed.
NOTE: The FI LEFLASH t ypi cal l y i s l ocat ed at t he l ast sect or
of Fl ash, whi ch yi el ds pl ent y of space f or st or i ng YAMON s
envi r onment var i abl es.
NOTE: The SYSTEMFLASH t ypi cal l y al ways st ar t s at t he
begi nni ng of t he Fl ash t o pr ovi de a l ar ge, cont i guous
r egi on of Fl ash.
12











Note: Refer flash memory Data sheet to know more about sector size.

4) Initswitch.h: This file describes which modules are included in a given
YAMON monitor. The sequence of modules is important as many
modules are dependent on other modules. Create an entry for the new
board to declare the Flash module and/or PCI support.

5) Init_platform.c: This file is can be optionally modified to perform
miscellaneous activities upon boot. For example, many AMD Alchemy
reference boards utilize this file to display the CPU frequency.

6) reset_xxxx.S: This file is specific to the new board and is written as per
the guidelines defined in [2].Typically an existing AMD Alchemy
reference design can be utilized as a reference while authoring this file.
This file contains 99% of all the code needed to successfully boot
YAMON on a new board. It is imperative that this file be authored
according to AMD recommendations.

The following files are associated with the AMD Alchemy processor support within
YAMON:

File Flash

Monitor Flash



System Flash
13
yamon/init/reset/reset.S #modified for 16-bit boot support
yamon/arch/init/cpu/init_au1000.S #debug message support
yamon/arch/init/platform/init_platform.c
yamon/arch/init/platform/init_platform_s.S #debug message support
yamon/drivers/serial/serial_Au1000.c
yamon/drivers/rtc/rtc_au1000.c
yamon/drivers/lan/MAC_AU1000.c
yamon/drivers/flash/flash_amd.c
yamon/arch/pci/arch_pci_pb1500.c

Numerous example reset files are also available for reference when adapting YAMON
onto a new AMD Alchemy design.

yamon/arch/init/reset_pb1000.S
yamon/arch/init/reset_pb1100.S
yamon/arch/init/reset_pb1500.S
yamon/arch/init/reset_pb1550.S
yamon/arch/init/reset_db1000.S
yamon/arch/init/reset_db1500.S
yamon/arch/init/reset_db1100.S
yamon/arch/init/reset_db1550.S

This version of YAMON is created such that all AMD Alchemy boards are treated as the
same "platform" (specifically PB1000) within YAMON.

When debugging the bringup of a new board utilizing YAMON, the following tips might
prove useful:
Have disassembly of YAMONs reset.o on-hand to ensure fetches from Flash
match disassembly.
Use EJ TAG/Logic Analyzer to peek at first few instructions at 0xBFC00000
to ensure these match YAMONs reset.o. This also verifies that YAMON was
correctly programmed into Flash.
YAMON issues debug messages during its boot-up procedure, most common
failure is in the memory test. The DRAM memory controller must be
programmed correctly, and the correct size of DRAM reported to YAMON, in
order for this test to pass (assuming no board issues).

14
References

[1] YAMON Reference Manual from MIPS Technologies Inc, 2000
[2] Reset Software for Alchemy Au1000 Processor from AMD, 2002
[3] MIPS32 Architecture for Programmers, MIPS Technologies, Inc, 2001
[4] Mapping a Boot ROM on Alchemy 1000 Processor from AMD, J an 2002
[5] AMD Alchemy Au1x000 Processor Development Platform Quick Start Guide,
AMD, May 2004.