IBM Full-System Simulator Command...
Transcript of IBM Full-System Simulator Command...
IBM Full-System Simulator Command Reference
Understanding and Applying Commands in the IBM Full-System Simulator Environment
Version 0.01
© International Business Machines Corporation
IBM Full-System Simulator Command Reference
© International Business Machines Corporation (2005). All Rights Reserved.
Printed in the United States of America October 2005.
Please be advised that this document, marked IBM Confidential, contains trade secrets and commercial
information about IBM and its business that is privileged and confidential and which is, therefore,
exempt from the public access provisions of the Freedom of Information Act, 5 U.S.C. Part 552. Such
information if disclosed, could adversely affect the financial and competitive position of IBM and the
normal conduct of its business operation. Accordingly, IBM requests that this document be withheld in
the event of a demand for disclosure. IBM understands that in the event of such a demand the U.S.
Government will give IBM prompt notice and opportunity to be heard prior to taking any action to
disclose.
No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any
computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise,
without prior written permission of IBM Corporation. No other rights under copyright are granted without prior written
permission of IBM Corporation.
While the information contained herein is believed to be accurate, such information is preliminary, and should not be relied
upon for accuracy or completeness, and no representations or warranties of accuracy or completeness are made. All
information contained in this document is subject to change without notice. This document contains information on products
in the design, sampling and/or initial production phases of development. This information is subject to change without
notice, and is provided without warranty of any kind. The information contained in this document does not affect or change
IBM product specifications or warranties. Nothing in this document shall operate as an express or implied license or
indemnity under the intellectual property rights of IBM or third parties. All information contained in this document was
obtained in specific environments, and is presented as an illustration. The results obtained in other operating environments
may vary. The document is not intended for production.
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN “AS IS” BASIS. In no event will IBM be liable
for damages arising directly or indirectly from any use of the information contained in this document.
U.S. Government Users Restricted Rights—Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM
Corporation.
IBM is a registered trademark of International Business Machines Corporation in the United States, other countries, or both.
The IBM logo, PowerPC, PowerPC logo, and PowerPC architecture are trademarks of International Business Machines
Corporation in the United States, or other countries, or both.
Linux is a registered trademark of Linus Torvalds. Linux is written and distributed under the GNU General Public License in
the United States and other countries.
Other company, product, and service names may be trademarks or service marks of others.
The IBM home page can be found at www.ibm.com.
SystemSimCmdRef, Version 0.01
DRAFT - New versions will be updated as available.
CONTENTS
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
CHAPTER 1 Introduction to the IBM Full-System Simulator Command Syntax and Usage . . . . . . . . . . . .1
Understanding and Using Simulator Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Defining and Managing a Simulated Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Overview of Command Structure and Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Summary of Top-Level Simulator Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Using Command Pages in This Reference Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Accessing Help for Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
CHAPTER 2 Performing 64-Bit Arithmetic Operations in the Simulation Environment . . . . . . . . . . . . . .9
add64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
and64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
compare64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
div64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
format64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
incr64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
lessthan_u64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
CHAPTER 3 Defining, Configuring, and Instantiating a Machine from a Configuration Object . . . . . . . 19
define config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
define dup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
define list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
define machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
{configuration_object} config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
{configuration_object} delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
{configuration_object} display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
{configuration_object} exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
iii© International Business Machines Corporation. All rights reserved.
IBM Confidential & Proprietary
{configuration_object} query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
{configuration_object} quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
CHAPTER 4 Configuring and Modifying Machine Properties in the Simulation Environment . . . . . . . . 31
{machine} config_on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
{machine} cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
{machine} dtranslate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
{machine} dtranslate_wimg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
{machine} exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
{machine} go . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
{machine} itranslate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
{machine} itranslate_wimg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
{machine} quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
{machine} setargs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
{machine} stall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
{machine} step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
{machine} tick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
{machine} to_cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
{machine} allow tlbia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
{machine} bogus disk cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
{machine} bogus disk init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
{machine} bogus disk sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
{machine} bogus net init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
{machine} bogushalt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
{machine} caches stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
{machine} caches display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
{machine} caches modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
{machine} console destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
{machine} console disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
{machine} console enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
{machine} console list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
{machine} console create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
{machine} console display buffered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
{machine} console modify buffered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
{machine} cpu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
iv IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
IBM Confidential & Proprietary
{machine} display config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
{machine} display console_format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
{machine} display cpi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
{machine} display number_of_cpus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
{machine} display cycle_mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
{machine} display cycles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
{machine} display die_on_illegal_inst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
{machine} display emulate_floating_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
{machine} display fast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
{machine} display features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
{machine} display frequency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
{machine} display gdb_port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
{machine} display hexdump_file_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
{machine} display inst_profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
{machine} display instruction_count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
{machine} display kdebug_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
{machine} display kdebug_real . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
{machine} display kdebug_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
{machine} display kdebug_virtual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
{machine} display kips_format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
{machine} display latency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
{machine} display loose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
{machine} display mcm_attachment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
{machine} display memorymap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
{machine} display number_of_MCMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
{machine} display sim_support_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
{machine} display strict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
{machine} display thinwire_port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
{machine} display ticks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
{machine} display time_domain_for_display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
{machine} display time_domain_for_step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
{machine} display timer_slowdown_ratio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
{machine} display uart_interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
{machine} dynlib open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
vTable of Contents
IBM Confidential & Proprietary
{machine} dynlib close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
{machine} interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
{machine} job display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
{machine} job freeze . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
{machine} job readyq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
{machine} job showdebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
{machine} job thaw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
{machine} load elf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
{machine} load linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
{machine} load qtrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
{machine} load vmlinux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
{machine} load xcoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
{machine} mcm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
{machine} memory display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
{machine} memory fread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
{machine} memory fwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
{machine} memory set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
{machine} modify console_format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
{machine} modify cpi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
{machine} modify cycle_mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
{machine} modify die_on_illegal_inst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
{machine} modify emulate_floating_point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
{machine} modify fast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
{machine} modify frequency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
{machine} modify gdb_port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
{machine} modify heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
{machine} modify hexdump_file_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
{machine} modify inst_profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
{machine} modify kdebug_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
{machine} modify kdebug_real . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
{machine} modify kdebug_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
{machine} modify kdebug_virtual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
{machine} modify kips_format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
{machine} modify latency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
vi IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
IBM Confidential & Proprietary
{machine} modify loose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
{machine} modify sim_support_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
{machine} modify strict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
{machine} modify thinwire_port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
{machine} modify time_domain_for_display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
{machine} modify time_domain_for_step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
{machine} modify timer_slowdown_ratio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
{machine} modify uart_interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
{machine} ram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
{machine} save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
{machine} set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
{machine} tdomains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
{machine} thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
{machine} trigger clear assoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
{machine} trigger clear console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
{machine} trigger clear pc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
{machine} trigger clear real_pc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
{machine} trigger clear memory system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
{machine} trigger display assoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
{machine} trigger display console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
{machine} trigger display pc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
{machine} trigger display real_pc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
{machine} trigger display memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
{machine} trigger set assoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
{machine} trigger set console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
{machine} trigger set cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
{machine} trigger set pc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
{machine} trigger set real_pc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
{machine} trigger set memory system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
{machine} util dtranslate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181
{machine} util itranslate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182
{machine} util ppc_disasm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
{machine} util ppc_disasm2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
viiTable of Contents
IBM Confidential & Proprietary
viii IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
PREFACE
The IBM Full-System Simulator, internally referred to as “Mambo,” harnesses the power of the Tcl/Tk command
scripting language to enable users to easily control the simulation framework and extend simulation functionality.
The IBM Full-System Simulator Command Reference provides information about simulator commands that are
available to configure and manage components in the simulation environment. These commands pertain to the
command line interface that is available once the simulator is installed and started.
To illustrate command syntax and usage, this guide uses the IBM Full-System Simulator PowerPC 970 and the IBM
Full-System Simulator for PowerPC 750 to generate and test command output. The IBM Full-System Simulator for
PowerPC 970 is available from the IBM alphaWorks Emerging Technologies web site.
Intended Audience
This document is intended for designers and programmers who are modeling, configuring, and correlating
performance of supported system architectures. Potential users include:
System and software designers
Application and product engineers
Validation engineers
Using This Version of the Guide
This version of the IBM Full-System Simulator Command Reference is organized into preliminary topics that cover
concepts for understanding and specifying command syntax and usage, and then provides a command page for
available commands. The following “Typographical Conventions” and “Related Information and Recommended
Reference” sections outline command notation and documentation standards.
Command Page Organization
Commands in this manual are arranged alphabetically, and typically contain the following information:
Command Name. Provides a brief introduction to command functionality.
Tcl Syntax. Specifies the full Tcl syntactic structure and grammer of the command statement. The syntax
statements in this guide adhere to standard Tcl command notation, as described in Table 3-1, “Typographic
Conventions,” on page x. Some commands require one or more input parameters that must be passed to the
ix© International Business Machines Corporation. All rights reserved.
command in order for it to execute successfully. In cases where multiple optional parameters are supported,
the default is stated if applicable. For an exaplanation of how to read a synopsis statement, see Chapter 1.
Description and Arguments. Describes the type of operation that is performed in the simulation by this
command, and lists a description of each required or optional input argument.
Example Code and Output. Provides sample code to demonstrate how the command is called, and displays
corresponding output that is generated by the executed sample command sequence.
Typographical Conventions
The following typographical components are used for defining special terms and command syntax:
Table 3-1. Typographic Conventions
Convention Description
Bold typeface Represents literal information, such as:
Information and controls displayed on screen, including
menu options, application pages, windows, dialogs, and
field names.
Commands, file names, and directories as used in general
descriptions.
In-line programming elements, such as function names and
XML elements when referenced in the main text.
Italics typeface Italics font is used to emphasize new concepts and terms, and to
stress important ideas. Additionally, book and chapter titles are
displayed in italics. In the case of command names, this font is
used to denote user-specified components when describing
command usage and functionality.
Bold sans serif typeface Used in Tcl command format and syntax statements to denote the
command name (as provided in each command page), for
example define config.
Bold italics sans serif typeface Used in Tcl command format and syntax statements to denote the
user-specified component in a command name (if applicable.)
For example, in the configuration_object config command, the configuration_object represents the
name of a configuration object on which the command action is
performed.
Italic sans serif typeface Delimits required parameters in Tcl command format and syntax
statements or in sample code for which a value must be
specified, such as in cd /users/your_name, where
your_name denotes a user-specified input.
?argument? (Question-mark delimited) Encloses optional parameters in format and syntax descriptions.
For example, in the statement mysim config bus frequency absolute_value ?relative_value?,
the ?relative_value? parameter is an optional input.
x IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
Related Information and Recommended Reference
The IBM Full-System Simulator Command Reference is available on-line via the Mambo intranet site at
http://mambo.austin.ibm.com. In addition to this command reference, the IBM Full-System Simulator: Overview
and Installation guide (available from the IBM alphaWorks Emerging Technologies web site) introduces the
IBM Full-System Simulator for PowerPC 970 installation environment, describes procedures to install and run a
default simulator, and provides troubleshooting information to isolate and fix a potential installation problems.
The IBM Austin Research Lab also recommends the following documentation sources that may provide helpful
guidelines and background information about technologies used in the IBM Full-System Simulator environment:
Practical Programming in Tcl and Tk by Brent B. Welch. Prentice Hall, Inc.
Tcl/Tk in a Nutshell by Paul Raines & Jeff Tranter, O’Reilly and Associates.
The SourceForge.net Tcl Foundry located at http://sourceforge.net/projects/tcl/.
Sans serif typeface Plain sans serif font is used for example code, such as to
represent TCL or C/C++ code examples.
{ } (Braces) Used in general descriptions to delimit a set of mutually exclusive
user-specified parameter. (Note that braces are not used in Tcl
command format and syntax statements, which follow the
conventions defined above).
| (Vertical rule) Separates items in a list of choices enclosed in { } (braces) in
format and syntax descriptions.
UPPERCASE Indicates keys or key combinations that you can use. For
example, press CTRL + ALT + DEL.
... (Horizontal or Vertical ellipsis)
.
.
.
In format and syntax descriptions, as well as in code example, an
ellipsis indicates that some material has been omitted to simplify
a discussion.
Hyperlink Web-based URIs are displayed in blue text to denote a virtual link
to an external document. For example: http://www.ibm.com
The note block denotes information that emphasizes a concept or
provides critical information.
This is an inline footnote reference.1
_______________________
1. Descriptive footnote text.
A footnote annotates an explanatory note or reference inserted at
the foot of the page that explains or expands upon a point within
the text or indicates the source of a citation or peripheral
information.
Table 3-1. Typographic Conventions
Convention Description
NOTE This is note text.
xiPreface
Contacting the Austin Research Lab Team
The Austin Research Laboratory is very interested in hearing from you about your experience with the IBM Full-
System Simulator and its supporting tools and information set. Should you have questions or encounter any issues
with the simulator, contact us via email at [email protected]. This mailing list is used by
the ARL development team to discuss simulator features and known issues, and is a good way to get answers to
general simulation-related questions.
We also welcome your suggestions for improvements with any information products. If you have comments or
suggestions about the IBM Full-System Simulator Command Reference or other supporting documentation, send
email to the [email protected] mailing list. Additional project-specific mailing lists are
available on the IBM Internal Open Source Bazaar (IIOSB). To subscribe to a mailing list, you must first
register as a user on the Sourceforge site using your IBM intranet password. After registering with Sourceforge, visit
the Mambo Full Systems Simulator project page to access the project.
xii IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
CHAPTER 1
Introduction to the IBM Full-System Simulator
Command Syntax and Usage
This chapter describes the IBM Full-System Simulator command framework, and introduces the
structure, format, and usage of simulator commands. Topics in this chapter include:
Understanding and Using Simulator Commands
Defining and Managing a Simulated Machine
Summary of Top-Level Simulator Commands
Using Command Pages in This Reference Guide
Accessing Help for Commands
1© International Business Machines Corporation. All rights reserved.
IBM Confidential & Proprietary
Understanding and Using Simulator Commands
In designing and developing the IBM Full-System Simulator framework, internally referred to as “Mambo,” the
Austin Research Laboratory (ARL) recognized the need for a unified, cross-platform application programming
interface that would enable users to easily set up the simulation environment, manage simulated architecture
components, and write debugging and performance analysis routines. The IBM Full-System Simulator has harnessed
the power of Tcl/Tk to develop a simple and programmable text-oriented syntax that is easily extended and
minimizes the need for proprietary and difficult programming grammar and usage. By extending Tcl with exported
functions, data types, and numerous predefined interfaces that are used for all interobject communication, the
simulator provides a rapid, cross-platform development environment that enables users to quickly start working in
the simulation environment.
The IBM Full-System Simulator command framework provides an extensive set of commands for modeling,
simulating, and tuning microprocessor components in a system. Each component in a microprocessor system is
configured via commands that not only define the component’s run-time behavior and characteristics, but govern its
relationships and interactions with surrounding components in the system.
In addition to configuring system components, the simulator commands can be combined with programming logic
and Tcl programming constructs to gather, analyze, and visualize simulation events, run workloads on the modeled
microarchitecture, and generate performance metrics with new or revised configurations to forecast performance at
future workloads. The command line interface also can be used to perform a number of operations on the simulator
itself, such as to control a simulation, start data collection and visualization tools, and define and load virtual
devices and disk images.
Figure 1-1 illustrates how commands are processed in the simulation environment and describes the different
categories of commands that are available:
Figure 1-1. Categories of Simulator Commands
Command Line Input
Tcl Interpreter
Component Configuration Commands:
commands to display or modify configurations of a
machine or configuration object in the simulation
Simulator tools
IBM Full-System Simulator
Simulator Tools Commands:
commands to set up and use the
simulator’s data collection and
analysis utilities
Simulator Commands: commands to manage the simulation
environment, or to define and modify simulator elements
sysrtemsim %
Interpreter reads command line input and confirms if command is pure
Tcl or simulator Tcl syntax; the interpreter executes Tcl operations and
passes simulator-specific commands to the simulation framework
Arithmetic utilities
64-bit Arithmetic Commands: commands to perform
64-bit arithmetic (not supported by default in Tcl)
Simulated Machine
2 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
IBM Confidential & Proprietary
Once the simulator is started, commands may be entered at the simulator command line or via simulation Tcl
scripts. Figure 1-2 illustrates the simulator command line at start-up and the simulated Linux console that is
launched from the simulator command line with the mysim go command:
Figure 1-2. IBM Full-System Simulator Command Line
The IBM Full-System Simulator: Overview and Installation (available from the IBM alphaWorks Emerging
Technologies web site) document describes how to start and stop a simulation from the simulator command line.
Defining and Managing a Simulated Machine
Each version of the IBM Full-System Simulator delivers a set of default configurations for the type of PowerPC
processor it is modeling. Using these configurations, users can instantiate a simulated machine based on a default
configuration object to examine functionality and performance of a baseline system. Alternatively, users can create
a configuration object of the pre-defined machine, replace one or more default settings, and instantiate a custom
machine to evaluate how an individual component or the entire processor architecture performs under customized
conditions.
simulator command
line prompt
Linux command line in
simulated system
3Introduction to the IBM Full-System Simulator Command Syntax and Usage
IBM Confidential & Proprietary
Figure 1-3 describes the general sequence of commands that are used to define a machine in the simulation
environment:
Figure 1-3. Defining, Creating, and Starting a Simulated Machine
Commands to set up and start a simulated machine can be entered at the simulator command line or via a Tcl
configuration and start-up file that is loaded when the simulator starts. Each IBM Full-System Simulator installation
provides a default .systemsim.tcl file that specifies a general set of commands to initialize the base simulation
configurations and environment settings, create a local version of the simulator, and load and initialize one or more
disk images. At startup, the IBM Full-System Simulator interprets instructions in .systemsim.tcl to set up default
simulation behavior. Alternatively, a custom Tcl file is commonly used to start up and configure the simulation
environment.
Overview of Command Structure and Syntax
Commands in the IBM Full-System Simulator are organized into a hierarchy of operations based on the command
function. At the top level, commands perform general sets of operations in the simulation environment, such as
defining and displaying machine properties and system configurations, modifying configurable parameters,
Simulator tools
IBM Full-System Simulator
Arithmetic utilities
Simulated Machine
1. Create a configuration object for a machine type: the define config command is used to define a new machine type for which an empty
configuration template is created, or the define dup is used to duplicate an existing configuration based on pre-defined settings.
2. Modify configurable settings for the configuration object: the [configuration_name} config command is used to customize the default
machine configuration by modifying mutable configuration properties.
3. Instantiate a machine based on the configuration object: the define machine [machine_name} command is used to create an instance of
the machine type. At this point, most machine properties are fixed— although a subset of properties can be changed for the simulated machine (see
Step 6 below).
4. Load the Linux kernel and rootdisk image used by the simulated machine: the [machine_name] load and [machine_name} bogus
commands are used to load disk images. Booting an operating system enables the execution of typical application programs that utilize standard
operating system functionality. The Linux operating system (running in the simulated environment) loads the application and is responsible for all
operating system calls.
5. Start the simulation: the [machine_name] go command launches the simulator console window, which displays output of the simulated machine
and allows users to configure and interact with the simulation.
6. Reconfigure a modifiable machine parameter: the [machine_name] modify command is used to change values of machine properties that can
be modified. When the simulation is started, the revised value is used in the simulation.
Configuration object Modified parameters in configuration object
Instantiated machine
memory=256M
Disk images loaded in simulation environment
Simulated machine in simulation environment
cpi=2
cpi=1
Reconfigured parameter of a modifiable property
4 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
IBM Confidential & Proprietary
performing 64-bit arithmetic operations that are not provided by default in Tcl, or managing the simulation
environment and its data collection and analysis tools. The following command notation illustrates the general
syntax structure of the simulator commands:
where:
object is the entity on which the command action is performed. There are three types of objects to consider
when specifying a command:
Simulator. Most commands are available to perform an action on the simulator itself—in this case, the
simulator is the implied object of a command and is not, therefore, explicitly stated in the command
syntax. For example, the quit command simply exits the simulation environment and returns to the host
command line. Likewise, the version list command determines and displays version and build
information for the IBM Full-System Simulator.
Machine or configuration objects. Once a machine configuration is created or a machine is instantiated,
simulator commands can be used to manage these objects. For instance, a system parameter can be
reconfigured only after a configuration object, for example myconf, is created. Once the object is
created, the config command is used to modify a setting in this configuration object.
To further illustrate, the object of an action can be a component of the simulated machine, such as a cache
or bus. For example, the mysim caches command specifies an operation on the system cache; as such,
mysim caches stats print displays simulation statistics for the memory hierarchy.
Utility objects. The IBM Full-System Simulator includes utilities for data collection and performance
analysis that are called via commands, in which the utility is the object of the command. For example, the
ereader command specifies actions for the emitter framework.
action defines the type of operation that the command is performing on an object. Extending the quit
command described earlier, quit stops the simulator and returns to the main shell. Likewise, the display
command lists information about the simulation.
parameter1 . . parametern specifies required input parameters. For example, the ereader start command
must pass the file path to the emitter reader executable that is launched in a simulation.
options lists arguments that modify the action that is performed on the object. Extending the previous
ereader start example, the process identifier of an emitter reader executable can be passed with the
required file path to the ereader.
object [action] [{parameter1 . . parametern} [options]]
5Introduction to the IBM Full-System Simulator Command Syntax and Usage
IBM Confidential & Proprietary
Summary of Top-Level Simulator Commands
Table 1-1 summarizes functionality of selected top-level commands that are used to define, modify, and use the
simulator. Command pages provided in this guide provide the complete command line syntax and usage of each
command or class of commands.
Table 1-1. IBM Full-System Simulator Top-Level Commands
Command Command Summary
alias Assigns a user-specified personal shorthand for a command string. The alias
command allows users to call a small, more familiar command or name to
execute long or complex command strings.
define Defines settings for a configuration object. The define command also provides
that ability to duplicate configurations from a pre-defined machine type,
instantiate a machine based on a configuration object, and enumerate a list of
machines that are active in the simulation.
display Displays system-wide information about configurations, machines, instruction
settings, and warning levels. The display command is especially useful to
determine properties that are configured for machines that are currently available
in a simulation.
ereader Controls emitter readers that are used in a simulation for performance data
collection and measurement.
help or helprecursive Displays a listing the IBM Full-System Simulator commands. The helprecursive
command displays a comprehensive command tree that hierarchically lists syntax
and input parameters for all available commands.
modify Modifies configurable simulation settings or parameters. The modify command
is useful for changing various run-time paramters, such as the interval at which
instructions are executed, the checkpoint type, latency cycles, or the warning
level that is set for the simulation environment.
object Provides the ability to interrogate information from one or more executable files
to examine low-level execution details.
quit Ends the current simulation and exits to the operating system command line.
simdebug Provides low-level tracing capabilities that are useful for debugging functionality
or performance issues in the simulated system.
simemit Specifies event types to be written to the shared memory buffer that is recording
emitted data.
simstop Stops the simulation and waits for instruction at the simulator command line. The
simstop command performs the same operation as typing CTRL+C to interrupt
the simulation.
version Displays the version number of simulation system components, the date and
timestamp of the installed IBM Full-System Simulator build, and compile-time
flags that are enabled in the build.
6 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
IBM Confidential & Proprietary
Using Command Pages in This Reference Guide
Commands in this guide are arranged alphabetically and typically contain the following command information: The
following sample syntax page illustrates the format and general contents of command pages provided in this
reference guide:
Figure 1-4. Sample Command Page Content and Format
64-bit arithmetic
operations
By default, arithmetic operations in the Tcl scripting language do not support 64-
bit arithmetic. The IBM Full-System Simulator provides the following operations
to perform general calculations on 64-bit numbers:
add64
and64
compare64
div64
format64
incr64
invert64
lessthan_u64
lshift64
mul64
or64
percent64
rshift64
sub64
uint32_to_float
Table 1-1. IBM Full-System Simulator Top-Level Commands
Command Command Summary
Name highlights the command function and summarizes the type of operation that is performed.
Description provides more detailed information about
how a command or command class is used in the
simulation environment.
Synopsis specifies the full grammar of a command or a
class of commands. The syntactic structure includes any
input parameters that must be passed with the command
in order for it to execute successfully.
Example provides sample code to demonstrate how the
command is called, and displays corresponding output
(if applicable) that is generated by the executed sample
command sequence.
Arguments describes the parameters that are passed
with the command.
7Introduction to the IBM Full-System Simulator Command Syntax and Usage
IBM Confidential & Proprietary
Accessing Help for Commands
At any time, users can type the help command at the command line to retrieve a list of command choices that are
available from that point in the syntax statement. In most cases, you can also just type a partial command sequence
and hit return. For example, at the top level, help displays a of top-level commands. An arrow indicates that a
subsequent level of command functionality is available for this command.
8 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
CHAPTER 2
Performing 64-Bit Arithmetic Operations in the
Simulation Environment
This chapter provides command notation and syntax for the IBM Full-System Simulator TCL
commands for 64-bit arithmetic functions. By default, arithmetic operations in the Tcl scripting
language do not support 64-bit arithmetic.
9© International Business Machines Corporation. All rights reserved.
NAME
add64 -- adds two 64-bit integers.
TCL SYNTAX
add64 integer1 integer2
DESCRIPTION
The add64 command calculates the sum of two 64-bit integers and displays the 64 bit result.
ARGUMENTS
integer1 Specifies the first operand in the addition operation.
integer2 Specifies the operand that is added to integer1.
EXAMPLE
1. Calculate the sum of integers 1 and 2:
add64 1 2
The following output is displayed:
3
2. Calculate the sum of integers 10000 and 2345:
add64 10000 2345
The following output is displayed:
12345
3. Calculate the sum of integers 1 and 10000000000000000000:
add64 1 10000000000000000000
The following calculation error is displayed:
-8446744973709551615
10 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
and64 -- performs a logical AND operation on two 64-bit integers.
TCL SYNTAX
and64 integer1 integer2
DESCRIPTION
The and64 command performs a bitwise logical AND operation between two integers (the operands) and
displays the result. A bitwise AND performs the logical AND operation on each pair of corresponding bits
between two binary representations of equal length. In each bit pair, the result is 1 if the first bit is 1 and the
second bit is 1. Otherwise, the result is zero.
ARGUMENTS
integer1 Specifies the first operand in the AND operation.
integer2 Specifies the second operand in the AND operation.
EXAMPLE
1. Find the result of the logical AND operation between 1 and 2:
and64 1 2
The following output is displayed:
0
2. Find the result of the logical AND operation between 1 and 9:
and64 1 9
The following output is displayed:
1
11Performing 64-Bit Arithmetic Operations in the Simulation Environment
NAME
compare64 -- compares two 64-bit integers.
TCL SYNTAX
compare64 integer1 integer2
DESCRIPTION
The compare64 command evaluates two 64-bit integers and returns a return value to indicate whether the
first integer is numerically less than, equal to, or greater than the second integer. The result is -1 if the first
integer is less than the second integer, 0 if the two integers are equal, and 1 if the first integer is greater than
the second.
ARGUMENTS
integer1 Specifies the first operand in the compare operation.
integer2 Specifies the operand that is compared to integer1.
EXAMPLE
1. Determine the relationship between 1 and 2:
compare64 1 2
The following output is displayed:
-1
2. Determine the relationship between 2 and 1:
compare64 2 1
The following output is displayed:
1
3. Determine the relationship between 2 and 2:
compare64 2 2
The following output is displayed:
0
4. Determine the relationship between 1000000000000000000000 and 2:
compare64 1000000000000000000000 2
The following output is displayed:
0
12 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
div64 -- divides a 64-bit integer value by a second 64-bit integer.
TCL SYNTAX
div64 integer1 integer2
DESCRIPTION
The div64 command divides an integer by a second integer, and returns only the integer portion of the
resulting quotient (the decimal part of the quotient is not displayed).
ARGUMENTS
integer1 Specifies the dividend of the division operation.
integer2 Specifies the divisor by which integer1 is divided.
EXAMPLE
1. Divide 10000000000 and 2:
div64 10000000000 2
The following output is displayed:
5000000000
2. Divide 44 and 8:
div64 44 8
The following output is displayed:
5
3. Divide 500 and 3:
div64 500 2
The following output is displayed:
166
13Performing 64-Bit Arithmetic Operations in the Simulation Environment
NAME
format64 -- generates a formatted string in the style of sprintf.
TCL SYNTAX
format64 formatString value
DESCRIPTION
The format64 command is the Tcl equivalent of the C sprintf library function used to generate a formatted
string.
ARGUMENTS
formatString Specifies a data formatting substring that indicates how to format the result. This string can
include a mix of characters that are passed unchanged to the result string (including special
characters such as newlines, tabs, and spaces) along with data formatting characters that are
specified using the % (percent sign) conversion specifier. The general format for formatString
follows:
"[optional_characters]%ll{conversion_specifier}"
where the ll specification denotes that the format string is a long long number, and the
conversion specifier controls the conversion of the value to a specified format. The
conversion_specifier can be one of the following values:
d Converts an integer value to a decimal string.
i Converts an integer value to a decimal string.
o Converts an integer value to an octal string.
c Converts an integer value to the 8-bit character represented by this integer.
x or X Convert integer value to unsigned hexadecimal string, where the resulting output is
generated in the same case as the data indicator.
value The integer value that is converted to the specified format.
EXAMPLE
1. Convert the number 34 to an octal string that is preceded with the phase The answer is:
format64 “The answer is %llo.” 34
The following output is displayed:
The answer is 42.
2. Convert the number 1234 to a hexadecimal string that is followed by the phase is a hexadecimal number.:
14 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
format64 “%llX is a hexadecimal number.” 1234
The following output is displayed:
4D2 is a hexadecimal number.
3. Convert the number 126 to a character string that is preceded with the phase This is a tilda character: :
format64 “This is a tilda character: %llc” 126
The following output is displayed:
This is a tilda character: ~
15Performing 64-Bit Arithmetic Operations in the Simulation Environment
NAME
incr64 -- increments a TCL variable by an optional increment amount.
TCL SYNTAX
incr64 variable_string integer
DESCRIPTION
The incr64 command increments the value of a TCL variable by an optional integer value. If an increment
amount is not specified, by default the variable is incremented by 1.
ARGUMENTS
variable_string Specifies the name of the Tcl variable.
integer Specifies an integer value by which the Tcl counter is incremented or decremented. A negative
value is passed to decrement the counter.
EXAMPLE
1. Increment the variable myVar that is initially set to 1by 1234567890123:
set myVar 1incr64 myVar 1234567890123
The following output is displayed after the incr64 command is applied:
1234567890124
2. Decrement the variable myVar set in Step 1 by 2:
incr64 i –2
The following output is displayed after the incr64 command is applied:
1234567890122
16 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
lessthan_u64 -- determines which of two 64-bit integers is less than the other.
TCL SYNTAX
lessthan_u64 integer1 integer2
DESCRIPTION
The lessthan_u64 command evaluates which of two 64-bit integers is less than the other, and outputs a
return value to indicate whether the first integer is numerically less than the second integer or vice versa. The
return value is 1 if the first integer is less than the second integer, and 0 if the second integer is less than the
first.
ARGUMENTS
integer1 Specifies the first operand in the operation.
integer2 Specifies the operand that is evaluated against integer1.
EXAMPLE
1. Determine if 1 is less than 2:
lessthan_u64 1 2
The following output is displayed:
1
2. Determine if 10000000000000000000000000000 is less than 12345:
lessthan_u64 10000000000000000000000000000 12345
The following output is displayed:
0
17Performing 64-Bit Arithmetic Operations in the Simulation Environment
18 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
CHAPTER 3
Defining, Configuring, and Instantiating a
Machine from a Configuration Object
This chapter describes commands that are used to define and configure a configuration object that is
used to create a machine for the simulation environment. Chapter 1, “Introduction to the IBM Full-
System Simulator Command Syntax and Usage,” introduces concepts that are helpful in
understanding how to configure and use a simulated machine in the IBM Full-System Simulator
environment. In particular, “Defining and Managing a Simulated Machine” on page 3 illustrates the
process by which a configuration object is defined, configured, and used to instantiate the simulated
machine.
19© International Business Machines Corporation. All rights reserved.
NAME
define config -- defines a new configuration object.
TCL SYNTAX
define config new_configuration_object
DESCRIPTION
The define config command creates a new configuration object. A configuration object is a named
collection, such as myconf, of machine properties that are used to instantiate a machine that is run in the
simulator. The define config command creates and populates a new configuration object with default
properties that have been defined for a machine type. Once an object is defined, the default properties may be
reconfigured with the {configuration_object} config command before the define machine command is
used to instantiate a machine object from this configuration.
ARGUMENTS
new_configuration_object Specifies the name of the new configuration object.
EXAMPLE
define config myconf
where myconf is a configuration object that defines baseline settings for a machine that can be run in a
simulation.
SEE ALSO
define dup, define machine, display configures
20 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
define dup -- defines a duplicate configuration object based on an existing machine type.
TCL SYNTAX
define dup existing_configuration_object new_configuration_object
DESCRIPTION
The define dup command duplicates an configuration object from an existing configuration. A configuration
object is a named collection, such as myconf, of machine properties that are used to instantiate a machine
that is run in the simulator. Although the define dup command provides similar functionality as the define
config command, unlike define config it requires an existing configuration object and can not be used to
create a new configuration object.
ARGUMENTS
existing_configuration_object Specifies the name of an existing configuration object that will be duplicated.
new_configuration_object Specifies the name of the duplicate configuration object to be created.
EXAMPLE
1. Define a myconf configuration object into which all properties and values of the pre-defined gpul
configuration object for the PowerPC 970 are duplicated. This myconf object can then be used to modify one
or more configurations and instantiate a custom PowerPC 970 machine based on the revised settings:
define dup gpul myconf
2. Define an anotherconf configuration object to duplicate the myconf configuration object created in Step 1:
define dup myconf anotherconf
SEE ALSO
define config, define machine, display configures
21Defining, Configuring, and Instantiating a Machine from a Configuration Object
NAME
define list -- lists all machines that are active in a simulation.
TCL SYNTAX
define list
DESCRIPTION
The define list command enumerates a list of machines that are active in the simulation environment.
EXAMPLE
Output the name of all existing machines that have been created from configurations. In the case where the
mysim and anothersim machines are defined, typing the define list command at the simulator prompt
displays the following output:
anothersim mysim
SEE ALSO
define config, define dup, define machine
22 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
define machine -- instantiates a machine from a configuration object.
TCL SYNTAX
define machine configuration_object_name machine_name
DESCRIPTION
The define machine command instantiates a machine that is used in a simulation. Multiple machines may be
created in the simulator based on a single configuration object.
ARGUMENTS
configuration_object_name Specifies the name of an existing configuration object that will be duplicated.
machine_name Specifies the name of the duplicate configuration object to be created.
EXAMPLE
Instantiate a mysim machine from the myconf configuration object:
define machine myconf mysim
Once created, the mysim machine can be run in a simulation to capture details about the functionality and
performance of this machine configuration.
SEE ALSO
define config, define dup, define list
23Defining, Configuring, and Instantiating a Machine from a Configuration Object
NAME
{configuration_object} config -- Assigns a value to a configuration property.
TCL SYNTAX
configuration_object config property_name property_value
DESCRIPTION
The {configuration_object} config command assigns a new value to an existing property in a configuration
object.
ARGUMENTS
property_name Specifies the name of an existing configuration property whose current value is replaced
with the specified value.
property_value Specifies the value that is assigned to the configuration property.
EXAMPLE
1. Reconfigure the default memory_size property in the myconf configuration object to be 128M:
myconf config memory_size 128M
Note that for properties that specify a size parameter, such as memory_size, the actual size of the value must
be provided. For example, the sample code above sets the machine memory size to 128M, which the IBM Full-
System Simulator interprets as a scaled integer and sets the memory size to 128 megabytes. If the value 128 is
specified, the memory size is set to 128 bytes.
2. Verify that the memory_size parameter for myconf has been modified:
myconf display memory_size
The following output is displayed:
myconf:memory_size = 128M
SEE ALSO
define config, {configuration_object} display
24 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{configuration_object} delete -- deletes a property from a configuration object.
TCL SYNTAX
configuration_object delete property_name
DESCRIPTION
The {configuration_object} delete command removes a property from the specified configuration object. Note
that deleting a property from a configuration object removes it from the object specification, which may result
in errors when instantiating a machine from this configuration object. To reconfigure a configuration property,
use the {configuration_obejct} config command (as shown in the following Examples section).
ARGUMENTS
property_name Specifies the name of an existing configuration property that is deleted from the
configuration object.
EXAMPLE
1. The default memory_size property has been deleted from the myconf configuration object. The following
myconf config command is used to reassign a value for the memory_size property:
myconf config memory_size 128M
2. Verify that the memory_size parameter for myconf has been recovered:
myconf display memory_size
The following output is displayed:
myconf:memory_size = 128M
SEE ALSO
{configuration_object} config, {configuration_object} display
25Defining, Configuring, and Instantiating a Machine from a Configuration Object
NAME
{configuration_object} display -- displays a list of configuration properties.
TCL SYNTAX
configuration_object display $property_name$
DESCRIPTION
The {configuration_object} display command outputs the name and value of all properties that correspond to
the specified search string for the given configuration object. If a property name is not specified, the entire list
of properties for the configuration object is displayed. A valid search string can include any sequence of
characters, based on which the simulator returns information about all properties that contain the given string.
ARGUMENTS
property_name (Optional) Specifies the name of an existing configuration property that is displayed to
standard output. If property_name is not specified, the entire list of properties for the
configuration object is displayed.
EXAMPLE
1. View all configuration properties containing the string, memory:
myconf display memory
The following output is displayed:
myconf:memory_size = 64M (number of bytes of memory)memory_start = 0 (address of first byte of memory)
2. View all configuration properties containing the string, M:
myconf display memory
The following output is displayed:
myconf:dERAT_depth = 2 (size of congruence class for dERAT) dERAT_entries = 128 (number of entries in the dERAT) iERAT_depth = 2 (size of congruence class for iERAT) iERAT_entries = 128 (number of entries in the iERAT)
SEE ALSO
{configuration_object} config, {configuration_object} define, {configuration_object} delete
26 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{configuration_object} exit -- Deletes a configuration object.
TCL SYNTAX
configuration_object exit
DESCRIPTION
The {configuration_object} exit command removes the specified configuration object from the simulation
environment. The {configuration_object} exit command performs the same operation as the
{configuration_object} quit command.
EXAMPLE
1. Delete the tmpconf configuration object from the simulation environment:
tmpconf delete
Note that {configuration_object} exit command permanently removes the object from the system. Before
removing a configuration object, ensure that you do not need the configurations specified in this object.
2. Verify that the tmpconf object has been removed by listing all active configuration objects and machines in
the system:
display configures
SEE ALSO
{configuration_object} quit, display configures, {configuration_object} display
27Defining, Configuring, and Instantiating a Machine from a Configuration Object
NAME
{configuration_object} query -- displays the value of a configuration object property.
TCL SYNTAX
configuration_object query full_property_name
DESCRIPTION
The {configuration_object} query command returns the value of the specified property for the given
configuration object. Although the {configuration_object} display command provides similar functionality as
{configuration_object} query, the return value from {configuration_object} query is formatted such that it
can be conveniently used as input in a Tcl procedure.
ARGUMENTS
full_ property_name Specifies the complete name of an existing configuration property.
EXAMPLE
View the value assigned to the memory_size configuration property:
myconf query memory_size
The following output is displayed:
64M
Alternatively, using the {configuration_object} display command to view memory size would result in the
following output:
myconf:memory_size = 64M (number of bytes of memory)
SEE ALSO
{configuration_object} display
28 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{configuration_object} quit -- Deletes a configuration object.
TCL SYNTAX
configuration_object quit
DESCRIPTION
The {configuration_object} quit command removes the specified configuration object from the simulation
environment. The {configuration_object} quit command performs the same operation as the
{configuration_object} exit command.
EXAMPLE
1. Delete the tmpconf configuration object from the simulation environment:
tmpconf delete
Note that {configuration_object} exit command permanently removes the object from the system. Before
removing a configuration object, ensure that you do not need the configurations specified in this object.
2. Verify that the tmpconf object has been removed by listing all active configuration objects and machines in
the system:
display configures
SEE ALSO
{configuration_object} exit , display configures, {configuration_object} display
29Defining, Configuring, and Instantiating a Machine from a Configuration Object
30 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
CHAPTER 4
Configuring and Modifying Machine
Properties in the Simulation Environment
This chapter describes commands that are used to define, instantiate, and configure a machine that is
run in the simulation environment. “Defining and Managing a Simulated Machine” on page 3
illustrates the process by which a simulated machine is instantiated from a configuration object.‘
31© International Business Machines Corporation. All rights reserved.
NAME
{machine} config_on -- starts the processor component.
TCL SYNTAX
machine config_on
DESCRIPTION
The {machine} config_on command performs the same operation as the {machine} cpu 0 config_on
command to control the state of the default processor (CPU 0). In hardware, this operation is generally
implemented by moving a mode bit in the processor's MSR (machine state register).
When a machine is created in the simulator, the processor is by default set to off. In a typical IBM Full-System
Simulator environment, the processor is turned on as a side-effect of loading the machine, which initializes
machine state. The {machine} config_on command is necessary only in the case where the machine is state
is not defined by any initial processing.
EXAMPLE
In a machine with a single processor, start the processor:
mysim config_on
The following message is displayed to confirm that the processor is started:
CPU 0 set running
SEE ALSO
{machine} stall, {machine} cpu
32 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} cycle -- advances the simulator by a specified number of cycles.
TCL SYNTAX
machine cycle number_of_cycles
DESCRIPTION
The {machine} cycle command advances the simulated machine by a specified number of cycles. This
command is useful for quickly forwarding a simulation to a specific point at which relevant metrics can be
gathered for performance analysis and correlation.
ARGUMENTS
number_of_cycles Specifies the number of cycles to advance the machine.
EXAMPLE
The following sample code illustrates example Tcl steps used to advance a simulation in fast mode to the point
at which the boot process is complete. At this time, the fast mode is turned off, the simulator is advanced by a
specified number of cycles, and a trace generator procedure is started in order to verify the flow of logic or
identify bottlenecks within an application:
SEE ALSO
{machine} tick, {machine} step, {machine} modify time_domain_for_step
. . .
6: # duplicate configuration and create a PowerPC 970 machine 7: define dup gpul myconf 8: define machine myconf mysim
. . .
14: # run through boot instructions in fast mode 15: mysim modify fast on 16: 17: # advance to specific point in boot process 18: mysim cycle 160000000 19: 20: # advance to specific point in boot process 21: mysim modify fast off 22: 23: # start trace generator 24: proc start_emitter_readers { simulator } {
. . .
33Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} dtranslate -- translates addresses for data loads and stores.
TCL SYNTAX
machine dtranslate address
DESCRIPTION
The {machine} dtranslate command translates an effective address to a real address for data loads and
stores.
ARGUMENTS
address Specifies the address to be translated.
EXAMPLE
The following {machine} dtranslate command translates the 0xC000000000011B20 effective address to
the corresponding real address:
mysim dtranslate 0xC000000000011B20
The simulator displays the following result for this translation:
0x0000000000011B20
SEE ALSO
{machine} itranslate, {machine} dtranslate_wimg, {machine} itranslate_wimg
34 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} dtranslate_wimg -- displays the WIMG storage control attributes for a data address translation.
TCL SYNTAX
machine dtranslate_wimg address
DESCRIPTION
TLB entries contain bits that control and provide information about the storage control attributes. Four such
attributes, referred to WIMG attributes, are defined in the PowerPC Architecture.1 The {machine}
dtranslate_wimg command displays the WIMG bits that have been enabled during a translation from an
effective address to a real address for data loads and stores.
ARGUMENTS
address Specifies the address to be translated.
1. E. Silha, R. Simpson, C. May, H. Warren, The PowerPC Architecture: A Specification for a New Family of RISC Processors, Morgan Kaufmann
Publishers Inc., San Francisco, CA, 1994
Table 4-1. WIMG Output Mapping
Hex Output WIMG Bits Set Bits Set
0x01 0000 No WIMG bits set
0x02 0001 Guarded
0x03 0010 Memory-coherent
0x04 0011 Memory-coherent, Guarded
0x05 0100 Cache-inhibited
0x06 0101 Cache-inhibited, Guarded
0x07 0110 Cache-inhibited, Memory-coherent
0x08 0111 Cache-inhibited, Memory-coherent, Guarded
0x09 1000 Write-through
0x0A 1001 Write-through, Guarded
0x0B 1011 Write-through, Memory-coherent, Guarded
0x0C 1100 Write-through, Cache-inhibited
0x0D 1101 Write-through, Cache-inhibited, Guarded
0x0E 1110 Write-through, Cache-inhibited, Memory-coherent
0x0F 1111 All WIMG bits set
35Configuring and Modifying Machine Properties in the Simulation Environment
EXAMPLE
View the WIMG bits that are enabled when 0xC000000000011B20:
mysim dtranslate_wimg 0xC000000000011B20
The simulator displays the following result for this translation:
0x03 Memory-Coherent, Guarded
SEE ALSO
{machine} dtranslate, {machine} itranslate_wimg, {machine} itranslate
36 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} exit -- removes a machine from the simulation environment.
TCL SYNTAX
machine exit
DESCRIPTION
The {machine} exit command permanently removes the specified simulation machine from the simulation
environment and returns to the systemsim % command line prompt. The {machine} exit command
performs the same operation as the {machine} quit command. The define machine command may be used
to create a new simulation machine.
EXAMPLE
Remove the mysim machine from the simulation environment:
mysim exit
SEE ALSO
{machine} quit, define machine
37Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} go -- starts running a machine in simulation.
TCL SYNTAX
machine go
DESCRIPTION
The {machine} go command causes the simulated machine to advance its state indefinitely. The simulation
continues until a stop condition is reached, which can include any of the following:
Typing CTRL+C to interrupt a running simulation. The IBM Full-System Simulator halts the simulation
and returns to the systemsim % command line prompt.
Issuing a trigger simstop command (see the command page for trigger simstop).
An error condition that is encountered during simulation or if no processor activity occurs for three
seconds after advancing the machine.
EXAMPLE
The following command starts the mysim machine:
mysim go
SEE ALSO
{configuration_object} define
38 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} itranslate -- translates instruction addresses from an effective address to a real address.
TCL SYNTAX
machine itranslate address
DESCRIPTION
The {machine} idtranslate command translates an effective address to a real address for instructions.
ARGUMENTS
address Specifies the address to be translated.
EXAMPLE
The following {machine} itranslate command translates the 0xC000000000011B20 effective address to
the corresponding real address:
mysim itranslate 0xC000000000011B20
The simulator displays the following result for this translation:
0x0000000000011B20
SEE ALSO
{machine} dtranslate, {machine} itranslate_wimg, {machine} dtranslate_wimg
39Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} itranslate_wimg -- displays the WIMG attributes for an instruction address translation.
TCL SYNTAX
machine itranslate_wimg address
DESCRIPTION
TLB entries contain bits that control and provide information about the storage control attributes. Four such
attributes, referred to WIMG attributes, are defined in the PowerPC Architecture that control the following
functionality. The {machine} itranslate_wimg command displays the WIMG bits that have been enabled
during a translation from an effective address to a real address for instruction address.
ARGUMENTS
address Specifies the address to be translated.
EXAMPLE
View the WIMG bits that are enabled when 0xC000000000011B20:
mysim itranslate_wimg 0xC000000000011B20
The simulator displays the following result for this translation:
Table 4-2. WIMG Output Mapping
Hex Output WIMG Bits Set Bits Set
0x01 0000 No WIMG bits set
0x02 0001 Guarded
0x03 0010 Memory-coherent
0x04 0011 Memory-coherent, Guarded
0x05 0100 Cache-inhibited
0x06 0101 Cache-inhibited, Guarded
0x07 0110 Cache-inhibited, Memory-coherent
0x08 0111 Cache-inhibited, Memory-coherent, Guarded
0x09 1000 Write-through
0x0A 1001 Write-through, Guarded
0x0B 1011 Write-through, Memory-coherent, Guarded
0x0C 1100 Write-through, Cache-inhibited
0x0D 1101 Write-through, Cache-inhibited, Guarded
0x0E 1110 Write-through, Cache-inhibited, Memory-coherent
0x0F 1111 All WIMG bits set
40 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
0x03 Memory-Coherent, Guarded
SEE ALSO
{machine} dtranslate_wimg, {machine} itranslate, {machine} dtranslate
41Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} quit -- removes a machine from the simulation environment.
TCL SYNTAX
machine quit
DESCRIPTION
The {machine} quit command permanently removes the specified simulation machine from the simulation
environment and returns to the systemsim % command line prompt. The {machine} quit command
performs the same operation as the {machine} exit command. The define machine command may be used
to create a new simulation machine.
EXAMPLE
Remove the mysim machine from the simulation environment:
mysim quit
SEE ALSO
{machine} exit, define machine
42 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
s
NAME
{machine} setargs -- passes command line arguments to standalone applications.
TCL SYNTAX
machine setargs arguments_list
DESCRIPTION
The {machine} setargs command passes command line arguments to standalone applications. The command
determines the number of arguments that are being passed and the amount of address space that will be
needed to store the arguments, allocates this amount of space in the data segment before the first text
segment, and places the values or references in the newly-allotted space. The contents of GPR[3] and GPR[4]
are modified accordingly.
ARGUMENTS
arguments_list Enumerates the list of arguments that are passed to the application.
EXAMPLE
The following sample lines of code are added in the myApp.tcl application file to validate MIP DMA on a
multiprocessor standalone system. The CPU number is specified with the {machine} setargs command (line
16):
SEE ALSO
{machine} load, {machine} cpu
. . .
6: # define a machine of given MIP size, and number of chip and CPU 7: myconf config mip_size 0x10000000 8: myconf config standalone-app on 9: myconf config chips 1
10: myconf config cpus 1 11: 12: define machine myconf mysim
. . .
14: # load the application image and pass arguments 15: mysim load elf $IMAGES/my_machine/standalone/mip_dma_test.img 16: mysim cpu 0 setargs 32769
. . .
22: mysim go
43Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} stall -- stops the processor component.
TCL SYNTAX
machine stall
DESCRIPTION
The {machine} stall command controls the state of the default processor (CPU 0) by putting the processor in
the stall state (the opposite of the {machine} config_on command operation). In hardware, this operation is
generally implemented by executing a halt instruction or by moving a mode bit in the processor's MSR
(machine state register). The {machine} stall command is useful for dynamically switching off a processor, for
example, when a standalone application (that has been running in a multiprocessor environment) needs to
validate functionality on a single-processor system. In this case, the stall command can be issued for the CPU
that must be stopped (i.e, mysim stall cpu 1 stall to stop CPU 1).
EXAMPLE
In a machine with a single processor, start the processor:
mysim stall
The following message is displayed to confirm that the processor has stopped:
Thread 0 stalledCPU 0 stalled
SEE ALSO
{machine} config_on, {machine} cpu
44 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} step -- advances the simulator by a specified number of cycles.
TCL SYNTAX
machine step number_of_steps
DESCRIPTION
The {machine} step command advances the simulated machine by a specified number of instructions.
Although this command is sometimes used for quickly forwarding the simulator to a specific point in the
simulation, the {machine} cycle and {machine} tick commands are more commonly used to advance the
system accordingly.
ARGUMENTS
number_of_steps Specifies the number of cycles to advance the machine.
EXAMPLE
Advance the simulator by 10000 steps:
mysim step 10000
SEE ALSO
{machine} cycle, {machine} tick
45Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} tick -- advances the simulator by a specified number of ticks.
TCL SYNTAX
machine tick number_of_ticks
DESCRIPTION
The {machine} tick command advances the simulated machine by a specified number of ticks. In the
simulation environment, a tick is a unifying representation of time as a function of the collective frequencies in
the simulation system. In real systems, individual components most likely have different perceptions of time—
their individual time domains. A time domain defines a frequency that sets the duration of a cycle. Events in a
time domain are expressed in terms of its frequency cycles. In a simulation, time domains are encapsulated
and declared as rational values relative to a base frequency. In this approach, each component can declare its
own time domain to define its perception of time.
Figure 4-1 illustrates the relationship between the
computation of a tick value and frequency cycles in the
system. To calculate the value of a tick, the simulator
computes the least common multiple of the frequencies
in the system. Then, for example, if a system contains n
number of components whose frequencies are defined as:
freq1 = 2 GHz, freq2 = 4 GHz, freq3 = 6 GHz, and freqn = 12 GHz, then one tick in this simulated system
represents 1/12,000,000 of a second.
ARGUMENTS
number_of_ticks Specifies the number of ticks to advance the machine.
EXAMPLE
Advance the simulator by 10000 ticks:
mysim tick 10000
SEE ALSO
{machine} display ticks, {machine} cycle, {machine} step
freq1 freq2 freq3
cycle1 cycle2 cycle3
freqn
cyclen
...
...
freqt
tick
least common multiple
Figure 4-1. Calculating Ticks in the System
46 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} to_cycle -- advances the simulator to a specified point in the simulation.
TCL SYNTAX
machine to_cycle number
DESCRIPTION
The {machine} to_cycle command advances the simulated machine to the specified point in the simulation.
This command is useful for forwarding a simulation to a specific point, such as for debugging an application
issue.
ARGUMENTS
number Specifies the point in the simulation to advance the machine.
EXAMPLE
The following sample code illustrates example Tcl steps used to advance a simulation in fast mode to a given
point in the simulation:
SEE ALSO
{machine} cycle, {machine} tick, {machine} step
. . .
16: # duplicate configuration and create a PowerPC 970 machine 17: define dup gpul myconf 18: define machine myconf mysim
. . .
21: # advance the simulation in fast mode 22: mysim modify fast on 23: 24: # advance to specific point in boot process 24: mysim to_cycle 160000000 25: 26: # start trace generator 27: proc start_emitter_readers { simulator } { 28: . 29: . 30: .
47Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} allow tlbia -- enables or disables tlbia instructions in the simulation system.
TCL SYNTAX
machine allow tlbia on|off
DESCRIPTION
The {machine} allow tlbia command enables the simulator to interpret tlbia instructions.
ARGUMENTS
on|off Specifies whether line buffering for all consoles in the system is enabled (on) or disabled (off).
EXAMPLE
The following sample command lines enable and then disable tlbia instructions in the simulation environment:
mysim allow tlbia onmysim allow tlbia off
SEE ALSO
{machine} allow
48 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} bogus disk cleanup -- removes a bogus disk from the system.
TCL SYNTAX
machine bogus disk cleanup
DESCRIPTION
Bogus disk support provides a high-performance call-thru interface to block devices, disk images, or both that
reside on the host system The {machine} bogus disk cleanup command extends functionality provided by
{machine} bogus disk cleanup by synchronizing all data and cleaning up all references to virtual disk device
images that have been loaded in the simulation. Although the bogus disk command integrates this
functionality into its exit routines, issuing the {machine} bogus disk cleanup command before exiting a
simulation ensures that files are properly synchronized.
EXAMPLE
Issue the {machine} bogus disk cleanup command to synchronize disk images in the system:
mysim bogus disk cleanup
The simulator prints a confirmation message:
ok
SEE ALSO
{machine} bogus disk symc, {machine} bogus disk init
49Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} bogus disk init -- loads and initializes a virtual disk device into simulation.
TCL SYNTAX
machine bogus disk init devicenum imagepath accesstype ?cowpath? $hash_size?
DESCRIPTION
Bogus disk support provides a high-performance call-thru interface to block devices, disk images, or both that
reside on the host system The {machine} bogus disk init command loads a disk image residing on the host
machine into the simulation environment. This command interface serves as the BIOS of a regular machine that
links a specific hard drive/rootdisk to a internal device number.
Before the newly-instantiated machine can run in simulation, a rootdisk image must be loaded in the system,
which contains the root environment for the system. This image provides a snapshot of a functioning Linux
system that is available inside the simulator, including all tools, libraries, and debuggers that are required to
run an actual Linux system. This enables the simulator to provide the appropriate run-time support to run
applications as they are executed in an actual Linux environment. The simulator is designed to optimize the
execution of the Linux kernel by reading contents of the rootdisk image as the simulator traverses the root
filesystem in the simulator environment.
ARGUMENTS
devicenum Specifies a device number (starting at 0) that correlates to a device in Linux.
imagepath Specifies the full path name to the disk image.
accesstype Specifies the access type to the disk file. Supported access types include read (r), write only
(w), read-write (rw), copy-on-write (cow), or an alternate copy-on-write (newcow) method.
The cow access type is an optimization strategy that specifies that all write operations are
performed on a snapshot of the original disk image, so that the state of the original image is
maintained. If the simulation fails or is stopped, it can be resumed from either the point at
which it stopped, or it can revert to the original disk image. The newcow access type provides
another type of the copy-on-write functionality in which a new version of the disk image is
created each time the simulation starts.
cowpath Specifies the file path of the snapshot disk image.2
hashsize Specifies the size of the hash table that is storing the snapshot images. The hash table size is a
performance-to-memory trade-off.
2. A cowpath.table is an internal hash table that is used to map sectors in the original disk image to sectors in the snapshot image file. When a disk
image is loaded for the first time with the cow access method, the snapshot disk file and cowpath.table file are automatically created. If these files
already exist, however, the mapping in the cowpath.table is used to load the current state of the disk image file—in essence, all changes from the
previous session are loaded and Mambo can continue from that point.
50 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
ine
EXAMPLE
The following sample lines of code are added in the .systemsim.tcl configuration and startup file to mount
the Linux kernel and rootdisk images. As illustrated in this code, the simulator provides distinct commands for
loading the Linux kernel (line 15) versus loading the rootdisk image (lines 16).
The {machine} bogus disk command shown below creates a copy-on-write disk image located in /tmp/
hdisk0cow and a copy-on-write table at /tmp/hdisk0cow.table. The internal hash table size is set to
1024. The hash-table size is a performance-to-memory trade-off—increasing the hash-table size improves
performance in an environment where many changes are made.
SEE ALSO
{machine} bogus disk sync, {machine} load vmlinux
. . .
6: # duplicate configuration and create a PowerPC 970 machine 7: define dup gpul myconf 8: define machine myconf mysim
. . .
14: # load the kernel and rootdisk images used by the simulated mach 15: mysim load vmlinux /tmp/vmlinux.img 0 16: mysim bogus disk init 0 /tmp/hdisk0 cow /tmp/hdisk0cow 1024
. . .
51Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} bogus disk sync -- synchronizes a copy-on-write file for subsequent usage.
TCL SYNTAX
machine bogus disk sync devicenum
DESCRIPTION
The {machine} bogus disk sync maintains the integrity of an existing copy-on-write image file so that it is
usable in subsequent sessions. Although the bogus disk command integrates this functionality into its exit
routines, issuing this command before exiting a simulation ensures that the copy-on-write file is properly
synchronized.
ARGUMENTS
devicenum Specifies a device number used when the disk was initialized.
EXAMPLE
The following {machine} bogus disk sync command synchronizes the mambobd0 disk image and writes
the copy-on-write image and table files:
mysim bogus disk sync 0
SEE ALSO
{machine} bogus disk init
52 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} bogus net init -- loads and initializes a virtual ethernet device.
TCL SYNTAX
machine bogus net init devicenum MACaddr socket_file IRQ IRQ_offset
DESCRIPTION
The {machine} bogus net init command supports a call-thru interface to an ethernet network. This interface
is provided via an emulated ethernet device (mambonet0) and a separate utility that interfaces with a
network device on the host system. Before starting the bogus network support, an netap application must first
be running on the host. Located in the installation tree in the mambo-host-tools directory, the netap
application is started (by root) by specifying a network device to tap:
% netap eth0
Note that only one netap should be running on a device at a time; running more than one device may result in
errors. The netap command sets up a packet filter to capture all broadcast packets and packets that are not
addressed to the underlying device. Because of the overhead of filtering packets, running netap on your
primary network interface (or on a network interface that is not connected to a switched network) is not
recommended.
Once netap is running, the {machine} bogus net init can be used to start the IBM Full-System Simulator
and configure the network device with the command line options provided below.
ARGUMENTS
devicenum Specifies a device number (starting at 0) that correlates to a device in Linux.
MACaddr Specifies the MAC hardware address that the emulated ethernet will use. This should be a
unique address on the network (i.e., one that is not used by any other emulated hosts or by any
host network adapter).
socket_file Specifies the path to the socket file. The default path is /tmp/serversockdevicename, where
devicename is appended to the path. For example, where /tmp/serversocketh0 specifies
that server socket is connected to the eth0 network device. Alternatively, tap may be used to
specify that the Linux tun/tap driver is used as opposed to netap.
IRQ (Optional) Specifies an interrupt.3
IRQ_offset (Optional) Specifies an interrupt offset.
3. If an interrupt and interrupt offset are not specified, by default the polled mode is used.
53Configuring and Modifying Machine Properties in the Simulation Environment
EXAMPLE
The following {machine} bogus net init command interfaces with the eth0 network device using the
de:ad:ca:fe:ba:be Mac address where the default netapp socket and IRQ offset are used:
mysim bogus net init de:ad:ca:fe:ba:be /tmp/serversocketh0
SEE ALSO
{machine} bogus disk init, {machine} bogus net cleanup
54 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} bogushalt -- suspends simulator activity for a specified amount of time.
TCL SYNTAX
machine bogushalt delay delay_in_ticksmachine bogushalt disablemachine bogushalt displaymachine bogushalt enable
DESCRIPTION
The {machine} bogushalt command simulates a PowerPC halt instruction. When the simulator encounters a
{machine} bogushalt delay, it suspends activity for the specified number of seconds and waits for another
instruction. The following subcommands are available in the {machine} bogushalt set of commands:
{machine} bogushalt delay {integer}
Specifies a halt instruction with the specified delay.
{machine} bogushalt disable
Disables the {machine} bogushalt delay command.
{machine} bogushalt display
Prints the current status of the {machine} bogushalt command.
{machine} bogushalt enable
Enables the {machine} bogushalt delay command.
ARGUMENTS
delay_in_ticks Specifies an integer amount for the number of ticks that simulator will delay processing
instructions.
EXAMPLE
Set a delay of 120 ticks before reading the next instruction:
mysim bogushalt delay 120
The following output is displayed:
Bogus halt delay is set to 120 ticks
SEE ALSO
{machine} bogus disk init
55Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} caches stats -- configures and displays cache statistics.
TCL SYNTAX
machine caches stats on|off|print|export|reset
DESCRIPTION
The {machine} caches stats command configures whether cache statistics are turned on or off. It also
enables values in the statistics counters to be printed and reset.
ARGUMENTS
on Specifies that caches statistics counters are turned on.
off Specifies that caches statistics counters are turned off.
print Generates command output in human-readable format where information about operations at each
cache level is printed sequentially between the :::Begin Cache Statistics::: and :::End Cache
Statistics::: delimiters.
export Generate command output in a format that can be easily captured and directly passed as input in Tcl
scripts. This command option lists the number of read/writes accesses and misses that have occurred
for each cache level.
reset Resets the cache statistics counters.
EXAMPLE
Export cache statistics to a format that can be used as Tcl input:
mysim cache stats export
The simulator confirms that the counters have been turned off:
L1D_read_accesses 0 L1D_read_misses 0 L1D_write_accesses 0 L1D_write_misses 0 L1I_read_accesses 0 L1I_read_misses 0 L1I_write_accesses 0 L1I_write_misses 0 L2_read_accesses 0 L2_read_misses 0 L2_write_accesses 0 L2_write_misses 0 L3_read_accesses 0 L3_read_misses 0 L3_write_accesses 0 L3_write_misses 0
SEE ALSO
{machine} caches modify, {machine} caches display
56 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} caches display -- displays cache status and cache look-up delays.
TCL SYNTAX
machine caches display cache_lookup_delaymachine caches display status
DESCRIPTION
The {machine} caches display commands list the currently set cache mode and display the tag or data look-
up setting for a specified cache level, where the cache_lookup_delay argument can be one of the following
options:
L1D_Data_Delay Displays the current data look-up delay for the L1 data cache.
L1D_Tag_Delay Displays the current tag look-up delay for the L1 data cache.
L1I_Data_Delay Displays the current data look-up delay for the L1 instruction cache.
L1I_Tag_Delay Displays the current tag look-up delay for the L1 instruction cache.
L2_Data_Delay Displays the current data look-up delay for the L2 cache.
L2_Tag_Delay Displays the current tag look-up delay for the L2 cache.
L3_Data_Delay Displays the current data look-up delay for the L3 cache.
EXAMPLE
1. Display the current cache mode:
mysim caches display status
The simulator prints the cache status, as follows:
on full mode
2. Display the data look-up delay that is set for the L2 cache:
mysim caches display L2_Tag_Delay
The simulator prints the current delay:
L2_Data_Delay: 9
SEE ALSO
{machine} caches modify, {machine} caches stats
57Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} caches modify -- provides functionality for dynamically configuring caches.
TCL SYNTAX
machine caches modify onmachine caches modify offmachine caches modify statusmachine caches modify cache_lookup_delay delay_cycles
DESCRIPTION
The IBM Full-System Simulator allows dynamic configurability of caches in some processor models, such as by
allowing caches to be turned on or off. The {machine} caches modify commands provide a set of
functionality for enabling or disabling caches, viewing status of caches, and setting delays for tag and data look-
ups. The following cache commands are available in most processor models:
{machine} caches modify on
Enables caches to be turned on. The output of this command lists the sizes for the L1 data and instruction
caches, the L2 cache, and the L3 cache. In most processor models, caches are turned on by default.
{machine} caches modify off
Enables caches to be turned off in processor models that support this feature.
{machine} caches modify status
Lists the current state of the caches, and can be used to verify whether caches are turned on and their
mode of operation. By default, most processor models automatically run caches in full mode.
{machine} caches modify cache_lookup_delay delay_cycles
Enables a delay to be set, as specified by delay_cycles, for a given cache tag or data look-up operation, as
denoted by the cache_lookup_delay input. Specifying multiple levels of tag or data look-up delays results
in a cumulative delay in which the simulator determines the number of cycles to wait for L1 data and
instruction look-up delays, then for L2 caches, and finally for L3 caches. The following options for the
cache_lookup_delay argument are available:
L1D_Data_Delay Sets a data look-up delay for the L1 data cache.
L1D_Tag_Delay Sets a tag look-up delay for the L1 data cache.
L1I_Data_Delay Sets a data look-up delay for the L1 instruction cache.
L1I_Tag_Delay Sets a tag look-up delay for the L1 instruction cache.
L2_Data_Delay Sets a data look-up delay for the L2 cache.
L2_Tag_Delay Sets a tag look-up delay for the L2 cache.
L3_Data_Delay Sets a data look-up delay for the L3 cache.
58 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
L3_Tag_Delay Sets a tag look-up delay for the L3 cache.
ARGUMENTS
delay_cycles Specifies a look-up delay in cycles.
EXAMPLE
1. Turn on caches:
mysim caches modify on
The simulator prints the current cache sizes and echoes the command:
Caches sizes ==> L1D is 32768 bytes, L1I is 32768 bytes, L2 is 1048576 bytes, L3 is 2097152 bytesmysim caches modify on
2. View cache status:
mysim caches modify status
The simulator prints the current cache status:
on full mode
SEE ALSO
{machine} caches display, {machine} caches stats
59Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} console destroy -- removes the specified console.
TCL SYNTAX
machine console destroy console_id
DESCRIPTION
The {machine} console destroy command removes the specified console from its use in input and output,
and deletes all its supporting data structures. An EOF is generated for any output file or socket.
ARGUMENTS
console_id Specifies a name of the console to be removed.
EXAMPLE
The following sample command line removes the c0 console from the simulation:
mysim console destroy c0
SEE ALSO
{machine} console create, {machine} console list, {machine} console enable, {machine} console
disable
60 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} console disable -- disables a simulation console.
TCL SYNTAX
machine console disable console_id
DESCRIPTION
Once created, an input console can be disabled so that it can not read input characters; likewise, an disabled
output console does not generate output characters from the machine. The {machine} console disable
command suspends the specified console from its use in input and output.
ARGUMENTS
console_id Specifies a name of the console to be disabled.
EXAMPLE
The following sample command line disables the c0 console from the simulation:
mysim console disable c0
SEE ALSO
{machine} console create, {machine} console enable
61Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} console enable -- enables a simulation console.
TCL SYNTAX
machine console enable console_id
DESCRIPTION
An enabled input console provides input characters to the simulation; likewise, an enabled output console
accepts output characters from the machine. The {machine} console enable command renders the specified
functional for input and output.
ARGUMENTS
console_id Specifies a name of the console to be enabled.
EXAMPLE
The following sample command line enables the c0 console in the simulation:
mysim console enable c0
SEE ALSO
{machine} console create, {machine} console disable
62 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} console list -- lists information about currently defined consoles.
TCL SYNTAX
machine console list
DESCRIPTION
The {machine} console list command lists all currently defined consoles by their respective console
identifiers. For each console, the command output indicates whether the console is enabled or disabled,
whether it is used for inputting, outputting (or both) characters, the console type (file, listen, program,
socket, or string) and the parameters for the listed console.
EXAMPLE
The following sample lines of code demonstrate command output that is generated when the following
{machine} console create commands are issued in a simulation:
mysim console create c0 in program xtermmysim console create c1 in string "ls\nexit"mysim console create outfile out file /tmp/saved_outputmysim console create input in string "callthru exit"
Once the above consoles are created, enabled, and disabled, the {machine} console list command will
display the following output:
c0 :: DISABLE input program : xtermc1 :: ENABLE input string : ls\nexitoutfile :: DISABLE output file : /tmp/saved_outputinput :: ENABLE input string : callthru exit
SEE ALSO
{machine} console create, {machine} console destroy, {machine} console enable, {machine} console
disable
63Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} console create -- defines the source (or sink) of characters for the simulation console.
TCL SYNTAX
machine console create console_id in|inout|out file file_namemachine console create console_id in|inout|out listen port machine console create console_id in|inout|out program program_name machine console create console_id in|inout|out socket host:port machine console create console_id in|inout|out string input_string
DESCRIPTION
The {machine} console create command feeds characters from the specified source into the simulation and
vice versa. The simulated machine is designed to accept input from the user, which normally is typed directly
into the simulator console window. However, in the case of pre-defined scripts, the input can be obtained from
additional sources, such as text files or programs. The input characters are copied to the simulation as if they
are typed into the console interface. The simulation environment provides different {machine} console
create commands, each of which defines the source (or sink) of the characters for the console. These
command options are listed in the Arguments section below.
ARGUMENTS
console_id Specifies a user-defined console name. This identifier is a unique name associated with
a console. The console_id enables the console that is being created to be identified in
a list and is used with other console-related commands, such as enabling, disabling, or
deleting a console.
in|inout|out Specifies whether the console will be used for input (in), output (out), or input and
output (inout), where input consoles provide characters that are given to the
machine, and output consoles display any characters that the computer generates.
file filename Indicates that the specified file is used to read input or record output results, or both.
listen port Indicates that the simulator will create the specified port, and then listen for another
program to attach to this port.
program prog_name Indicates that characters will be sent to or from a specified program. For example, an
Xterm window is an instance of the program option, since it is normally the display for
the machine console. When the program option is used communication occurs over
pseudo-terminals. The pseudo-TTYS provide interfaces to receive non-blocking input as
well as to send terminal control characters.
socket host:port Indicates that the simulator will attempt to connect to the named host and port.
64 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
o.c"
string input_string Indicates that the source input is given in the string command. Strings cannot be used
for output consoles.
EXAMPLE
The following sample lines of code are added in the .systemsim.tcl configuration and startup file to manage
the simulation from the console window. The console callthru exit command (line 17) exits the Mambo
console. A simple GCC compile operation on source that is called from the host to the simulated system (lines
22–25) is executed to exercise the caches and measure the overall impact of the compile operation on the
cache hierarchy. The simulation is then started.
SEE ALSO
{machine} console create, {machine} console destroy, {machine} modify uart_interval
. . .
16: # exit Mambo console to start simulation 17: mysim console create input in string "callthru exit"
. . .
21: # invoke call-thrus to start instructions to compile C program 22: mysim console create input in string "callthru source hello.c > hell 23: mysim console create input in string "gcc -o hello hello.c" 24: mysim console create input in string "./hello" 25: mysim console create input in string "callthru exit"
65Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} console display buffered -- displays the status of console line buffering.
TCL SYNTAX
machine console display buffered
DESCRIPTION
The {machine} console display buffered command displays whether or not line buffering is currently
enabled in the system. The simulator is able to buffer output until an end-of-line character (\n) is generated. If
two or more MCMs (multi-chip modules) are outputting to the save console, buffering allow the console lines
from the different MCMs to be separated. In contrast, if buffering is disabled, the characters output by the
various MCMs are interleaved by time.
EXAMPLE
The following command line displays whether buffering in enabled in the simulation environment:
mysim console display buffered
Displays the following output:
on
SEE ALSO
{machine} console create, {machine} console modify buffered
66 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} console modify buffered -- configures console line buffering in the system.
TCL SYNTAX
machine console modify buffered on|off
DESCRIPTION
The {machine} console modify buffered command enables the simulator to buffer output until an end-of-
line character (\n) is generated. If two or more MCMs (multi-chip modules) are outputting to the save console,
this command extracts the console lines from the different MCMs. In contrast, if buffering is disabled, the
characters output by the various MCMs are interleaved by time. By default line buffering is set to off, unless
more than one MCM exists, in which case it is set to on by default.
ARGUMENTS
on|off Specifies whether line buffering for all consoles in the system is enabled (on) or disabled (off).
EXAMPLE
The following sample command lines enable and then disable line buffering in the simulation environment:
mysim console modify buffered onmysim console modify buffered off
SEE ALSO
{machine} console create, {machine} console display buffered
67Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} cpu -- enables simulator commands to be called on the specified CPU.
TCL SYNTAX
machine cpu cpu_number simulator_command
DESCRIPTION
The IBM Full-System Simulator is designed to simulate a system in
which multiple, separate processors are running on an MCM
(multichip module). The {machine} cpu command is a wrapper
command that runs a subset of simulator commands on the processor
that is specified by cpu_number. To view a complete list of
processor-related commands, type {machine} cpu at the simulator
command line.
For instance, the {machine} mcm mcm_number cpu cpu_number
modify name command enables users to set a name for the specified
CPU. This is useful functionality if, for example, mcm 1 contains cpu
0 and cpu 1, both of which are running separate applications. In this case, separate commands can be used to
name the two CPUs (see the Example section below for sample commands).
ARGUMENTS
cpu_number Specifies the name of the processor on which the command operation (defined by
the simulator_command input) is performed.
simulator_command Specifies the command input that is run on the specified processor.
EXAMPLE
Rename the CPUs on the mysim machine to reflect that type of application that is running on processors in
mcm 1 in the system:
mysim mcm 1 cpu 0 modify name cpu_app1mysim mcm 1 cpu 1 modify name cpu_app2
The simulator prints a the following messages to confirm that the names have been reassigned:
Processor 0 name is cpu_app1Processor 1 name is cpu_app2
SEE ALSO
{machine} mcm, {machine} thread
MC
M 0
MC
M 1
)(
)(... )
()(...
Figure 4-2. Multichip Module System
)(
)(... )
()(... )
()(... )
()(...
CPU
0
CPU
1
68 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display config -- displays a list of current machine settings.
TCL SYNTAX
machine display config ?string_match?
DESCRIPTION.
The {machine} display config command displays the list of current settings for the specified machine. An
optional input string may be passed to this command to filter all machine settings whose names match an
arbitrary string pattern—for example, {machine} display config mem will display all settings that being with
the mem characters, such as memory_size and memory_start. If the string_match parameter is not
specified, the entire list of machine settings is listed.
ARGUMENTS
string_match (Optional) Specifies a character string that is used to filter the machine settings.
EXAMPLE
1. The following sample command lists all settings for the mysim machine that being with the mem string:
mysim display config mem
The simulator displays the following output:
mysim:memory_size = 64M (number of bytes of memory)memory_start = 0 (address of first byte of memory)
SEE ALSO
display configures
69Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display console_format -- displays the console output format.
TCL SYNTAX
machine display console_format
DESCRIPTION
The {machine} display console_format command lists the current console format option that is used to
display console output.
EXAMPLE
Display the console format option:
mysim display console_format 0xF
The following output is displayed:
Console format is 0x3
SEE ALSO
{machine} modify console_format
70 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display cpi -- displays the current CPI value used for functional simulation.
TCL SYNTAX
machine display cpi
DESCRIPTION
The {machine} display cpi command displays the status of the cycles-per-instruction (CPI) value for
functional processor simulation. The processor model uses the target CPI to determine how to advance the
clock in relation to the execution of instructions. When the target CPI value is not integer-valued, the processor
model advances time in a way that approximates the CPI over a sequence of instructions.
EXAMPLE
Display the current CPI value:
mysim display cpi
The following output is displayed:
Processor 0: cpi is off
SEE ALSO
{machine} modify cpi
71Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display number_of_cpus -- displays the number of CPUS in the system.
TCL SYNTAX
machine display number_of_cpus
DESCRIPTION
The {machine} display number_of_cpus command displays an integer that represents the number of CPUs
that are currently configured in the simulation. The output of this command is similar to the {machine}
display config cpu command—however, unlike {machine} display config cpu, which displays formatted
output that lists the machine name, CPU configuration, and a brief summary of the setting, the {machine}
display number_of_cpus command simply lists the number of CPUs in the system as an integer. The
output of this command can be easily captured and directly passed as input in Tcl scripts.
EXAMPLE
Display the number of CPUs in the simulation system:
mysim display number_of_cpus
The following output is displayed:
1
SEE ALSO
{machine} display config cpu
72 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display cycle_mode -- lists whether the timing model (if available) is enabled.
TCL SYNTAX
machine display cycle_mode
DESCRIPTION
The {machine} display cycle_mode displays whether the cycle-accurate model is currently enabled or
disabled. If the simulation system is not a cycle-accurate model, a message is displayed to indicate that the
cycle-accurate mode is not supported in the current system.
EXAMPLE
1. Display if the processor timing model (cycle mode) is enabled in a system that supports cycle-accurate timing:
mysim display cycle_mode
The simulator displays the following message:
on
2. Display if the timing model is enabled in a system that does not support cycle-accurate timing:
mysim display cycle_mode
The simulator displays the following message:
unsupported
SEE ALSO
{machine} modify cycle_mode
73Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display cycles -- displays the current cycle count.
TCL SYNTAX
machine display cycles
DESCRIPTION
The {machine} display cycles displays the current cycle count. Output from this command is easily captured
and directly passed as input in Tcl scripts to track the number of cycles that an application or process has run.
EXAMPLE
Display the cycle count after advancing the simulator 10 cycles with the {machine} cycle command:
mysim cycle 10
The simulator advances by the specified number of cycles, after which the {machine} display cycles
command can be used to view how many cycles have elapsed:
mysim display cycles
The simulator summarizes the count as follows:
10
SEE ALSO
{machine} cycle
74 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display die_on_illegal_inst -- displays if the simulator is set to stop on an illegal instruction.
TCL SYNTAX
machine display die_on_illegal_inst
DESCRIPTION
The {machine} display die_on_illegal_inst specifies whether the simulator is configured to raise a
program interrupt upon encountering an illegal instruction (the architected behavior where the command is set
to off), or if it is configured to stop the simulation when it detects an illegal instruction (command set to on).
EXAMPLE
Verify that the simulation will stop when it encounters an illegal instruction:
mysim display die_on_illegal_inst
The following setting is displayed:
on
SEE ALSO
{machine} modify die_on_illegal_inst
75Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display emulate_floating_point -- displays if floating point instructions are emulated.
TCL SYNTAX
machine display emulate_floating_point
DESCRIPTION
The {machine} display emulate_floating_point displays whether the feature to emulate floating point
instructions is enabled or disabled. When floating point emulation is disabled, the simulator utilizes the
floating point instructions of the host system to compute floating point operations.
EXAMPLE
Verify that the simulator is configured to use the host system floating point instructions:
mysim display emulate_floating_point
The following setting is displayed:
on
SEE ALSO
{machine} modify emulate_floating_point
76 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display fast -- displays whether fast simulation mode is enabled.
TCL SYNTAX
machine display fast
DESCRIPTION
The {machine} display fast command displays whether the fast simulation mode is enabled or disabled. Fast
mode is commonly used to rapidly execute startup code to bring the system to a point where more detailed
simulation is performed—for instance, to quickly boot the Linux operating system until the console prompt is
detected, at which point the simulator may be switched to one of the other modes to perform more detailed
simulation.
EXAMPLE
Verify that the simulator is configured to use the fast simulation mode:
mysim display fast
The simulator displays the status of fast simulation mode:
on
SEE ALSO
{machine} modify fast, {machine} display loose
77Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display features -- TBA.
TCL SYNTAX
machine display features
DESCRIPTION
The {machine} display features command displays a summary of features that are enabled in the simulation
system. The following features are available:
FLOATING_POINT Indicates that floating point instructions are enabled.
VMX Indicates that the VMX instruction set is supported.
VMX128 Indicates that the VMX 2.0 instruction set is supported.
EXAMPLE
Check which features are enabled for the mysim simulation machine:
mysim display features
The following features are displayed for this machine:
FLOATING_POINT VMX
SEE ALSO
{machine} display
78 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display frequency -- displays the machine CPU clock frequency.
TCL SYNTAX
machine display frequency
DESCRIPTION
The {machine} display frequency command displays the current CPU clock frequency in KHz.
EXAMPLE
Verify the CPU clock frequency setting for the mysim machine:
mysim display frequecy
The following setting is displayed:
CPU Frequency is 1500000 KHz
SEE ALSO
{machine} modify frequency
79Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display gdb_port -- displays the GDB connection port.
TCL SYNTAX
machine display gdb_port
DESCRIPTION
The {machine} display gdb_port command displays the number of the port that connects the simulator to
GDB (GNU Debugger).
EXAMPLE
Display the port number that connects the simulator to GDB:
mysim display gdb_port
The following setting is displayed:
GDB port is 1024
SEE ALSO
{machine} modify gdb_port
80 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display hexdump_file_name -- displays the file name used for a memory dump call-thru.
TCL SYNTAX
machine display hexdump_file_name
DESCRIPTION
The {machine} display hexdump_file_name command displays the name of the file that is used to
capture a memory dump4, which may be used for used for analysis and trouble shooting. By default, the hex
dump is made to stderr.
EXAMPLE
Verify which file is used for the MamboDumpMemory callthru:
mysim display hexdump_file_name
The following setting is displayed:
File used for dump memory callthrough will be memory_stats
SEE ALSO
{machine} modify hexdump_file_name
4. The IBM-Full-System Simulator provides a set of call-thru wrapper functions that can be invoked by an application running in simulation to notify
the simulator of events, capture simulation data, or modify simulator behavior. A call-thru function executes a specialized PowerPC instruction (opcode
0x000EAEB0) that suspends the execution of instructions in the simulation, and instead starts executing instructions on the simulator itself. The
MamboDumpMemory callthru causes the simulator to dump memory contents in hexadecimal format to a specified file. The callthru_config.h
File Reference (available at http://mambo.austin.ibm.com/how-to/callthru__config_8h.html) provides syntax and usage information for call-thru
wrapper functions that can be invoked by the simulated program. The callthru_config.h file is compiled with programs that are executed under
the simulator, such as stand-alone programs or operating systems.
81Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display inst_profile -- displays whether the instruction profiling feature is enabled.
TCL SYNTAX
machine display inst_profile
DESCRIPTION
The {machine} display inst_profile command displays whether the build-time configuration for generating a
detailed instruction profile is enabled. Note that this feature is not available in the current simulator build; the
output of {machine} display inst_profile displays a message to indicate that the build is not configured to
support this feature.
EXAMPLE
Verify whether the feature to generate an instruction profile is enabled:
mysim display inst_profile
The following message is displayed:
Instruction profiling is a build-time configuration. The configuration is not enabled in this build.
SEE ALSO
{machine} modify inst_profile
82 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display instruction_count -- displays the current instruction count.
TCL SYNTAX
machine display instruction_count
DESCRIPTION
The {machine} display instruction_count displays the current instruction count. Output from this
command easily captured and directly passed as input in Tcl scripts to track the number of instructions that an
application or process has run.
EXAMPLE
Display the instruction count after advancing the simulator 1000 cycles with the {machine} cycle command:
mysim cycle 1000
The simulator advances by the specified number of cycles, after which the {machine} display
instruction_count command can be used to view how many instructions have elapsed:
mysim display instruction_countThe simulator displays the count as follows:
1001
SEE ALSO
{machine} display cycles, {machine} cycle
.
83Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display kdebug_enable -- displays whether GDB address translation is enabled.
TCL SYNTAX
machine display kdebug_enable
DESCRIPTION
The {machine} display kdebug_enable command verifies if simplified address translation of GDB virtual
addresses to real addresses is enabled or disabled. GDB (GNU Debugger) sends memory accesses and
breakpoints to the simulator using virtual addresses.
EXAMPLE
Verify if GDB agent kernel address translation is enabled in the simulation environment:
mysim display kdebug enable 1
The following setting is displayed:
1
SEE ALSO
{machine} modify kdebug_enable, {machine} display kdebug_virtual, {machine} display
kdebug_real, {machine} display kdebug_size
84 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display kdebug_real -- displays the base real address for GDB agent address translation.
TCL SYNTAX
machine display kdebug_real
DESCRIPTION
The {machine} display kdebug_real command displays the real base address used for GDB agent kernel
address translation.
EXAMPLE
Display the real base address for GDB agent translation:
mysim display kdebug_real
The following setting is displayed:
0x0000000001000000
SEE ALSO
{machine} modify kdebug_real, {machine} display kdebug_enable, {machine} display
kdebug_virtual, {machine} display kdebug_size
85Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display kdebug_size -- displays the size of the GDB agent translation segment.
TCL SYNTAX
machine display kdebug_size
DESCRIPTION
The {machine} display kdebug_size command displays the size of the segment used for GDB agent kernel
address translation.
EXAMPLE
Display the size of the segment for GDB agent address translation:
mysim display kdebug_size
The following setting is displayed:
4247552
SEE ALSO
{machine} modify kdebug_size, {machine} display kdebug_enable, {machine} display
kdebug_virtual, {machine} display kdebug_real
86 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display kdebug_virtual -- displays the virtual base address for GDB agent address translation.
TCL SYNTAX
machine display kdebug_virtual
DESCRIPTION
The {machine} display kdebug_virtual command displays the segment virtual base address used for GDB
agent kernel address translation.
EXAMPLE
Display the virtual segment base address for GDB agent translation:
mysim display kdebug_virtual
The following setting is displayed:
0xC000000000000000
SEE ALSO
{machine} modify kdebug_virtual, {machine} display kdebug_real, {machine} display
kdebug_enable, {machine} display kdebug_size
87Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display kips_format -- display the format of simulator KIPS messages.
TCL SYNTAX
machine display kips_format
DESCRIPTION
The {machine} display kips_format command displays the format for simulation runtime performance
messages that are produced periodically (every 4 seconds). The messages include a measurement for
simulation performance given in KIPS (Kilo-Instructions executed Per Second). The general format of the KIPS
message is:
[optional_info]: [thread_number]: PC:{program_counter_address} : {KIPS_measurements}
The KIPS message format is set with the {machine} modify kips_format command, which requires a
format_flag input parameter to specify the formatting convention. This parameter is an integer ranging from 0
to 7 and is interpreted as a bitwise logical OR of the flag values (i.e., format_flag & flag_value != 0), where
flag_value is defined as follows:
1 Indicates that the KIPS messages will include the current cycle count (in ticks) in the time domain given
by {machine} modify time_domain_for_display (by default, the CPU domain). This value is
represented as: format_flag & 0x1 != 0.
2 Indicates that the KIPS messages will include the count of instructions executed by the simulator. This
value is represented as: format_flag & 0x2 != 0.
4 Indicates that the KIPS messages will include the time of day when the message is written, in hh:mm:ss
notation. This value is represented as: format_flag & 0x4 != 0.
Note that if format_flag is 0, a KIPS message is not printed
EXAMPLE
Display the value that is set for KIPS messages in the simulation system:
mysim display kips_format
The simulator displays the status of the KIPS format:
KIPS format is 1
SEE ALSO
{machine} modify kips_format
88 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display latency -- displays whether cycle-approximate latency modeling is enabled.
TCL SYNTAX
machine display latency
DESCRIPTION
The {machine} display latency command displays the status of the cycle-approximate latency feature in the
simulation. Cycle-approximate latency is configured with the {machine} modify latency command, which
notifies each simulated component model that, if possible, it should assign cycle-approximate latency to its
operations. The manner in which a given modeled component responds to this command, as well as the degree
to which the component reflects operation latencies accurately, depends on the individual model
EXAMPLE
Verify if cycle-approximate latency is enabled in the system:
mysim display latency
The simulator displays the status of cycle-approximate latency:
on
SEE ALSO
{machine} modify latency
89Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display loose -- displays whether the loose simulation mode is enabled.
TCL SYNTAX
machine display loose
DESCRIPTION
The {machine} display loose command displays whether the loose simulation mode is enabled or disabled.
Loose mode allows a processor to advance independently in the system (for 100,000 instructions) without
considering any instructions that are performed by other components or processors in the system.
EXAMPLE
Verify that the simulator is configured to use the loose simulation mode:
mysim display loose
The following setting is displayed:
on
SEE ALSO
{machine} modify loose, {machine} display loose
90 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display mcm_attachment -- displays the type of memory map attachment that is used.
TCL SYNTAX
machine display mcm_attachment
DESCRIPTION
Certain processor models can support two or more MCMs (multi-chip modules), each of which defines its own
memory map. Based on the processor model, the memory maps of each MCM can be either shared (in which
each MCM uses a single memory space for its processors), or each can be configured as a cluster (in which
each MCM maintains a private memory map that is not accessible to other MCMs). The {machine} display
mcm_attachment command displays the type of attachment method that is used by the simulated model.
Note that in models with only one MCM, the default attachment method is a cluster.
EXAMPLE
Determine if the MCM attachment method:
mysim display mcm_attachmentThe following setting is displayed:
cluster
SEE ALSO
{configuration_object} display
91Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display memorymap -- displays information about the memory map configuration.
TCL SYNTAX
machine display memorymap ?format_type?
DESCRIPTION
The {machine} display memorymap command displays a memory map that contains information about the
start and end addresses for the memory, ROM, and PIC components.
ARGUMENTS
format_type (Optional) Specifies the format type for listing memory map information. The following
format_type options are available:
active Generates command output in tabular format where information about the
start and end addresses for memory, ROM, and PIC resources is listed. If a
format_type is not specified with the command, the active option is the
default display type.
listformat Presents the command output in a format that can be easily captured and
directly passed as input in Tcl scripts.
EXAMPLE
1. View a memory map for the simulation in the default format:
mysim display memorymap
The simulator displays the mapping, as follows:
2. View a memory map for the simulation in list format:
mysim display memorymap listformat
The simulator displays the mapping, as follows:
{NAME {MEMORY} START 0x0000000000000000 END 0x0000000003FFFFFF} {NAME {ROM} START 0x00000000F0000000 END 0x00000000F000007F} {NAME {PIC} START 0x00000000FFC00000 END 0x00000000FFC3FFFF}
SEE ALSO
{machine} memory display, {machine} job display
NAME: MEMORY START: 0x0000000000000000 END:0x0000000003FFFFFF NAME: ROM START: 0x00000000F0000000 END:0x00000000F000007F NAME: PIC START: 0x00000000FFC00000 END:0x00000000FFC3FFFF
92 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display number_of_MCMs -- displays the number of MCMs in the system.
TCL SYNTAX
machine display number_of_MCMs
DESCRIPTION
The {machine} display number_of_MCMs command displays an integer that represents the number of
MCMs that are currently configured in the simulation. The output of this command is similar to the {machine}
display config number_of_MCMs command—however, unlike {machine} display config
number_of_MCMs, which displays formatted output that lists the machine name and MCM configuration,
the {machine} display number_of_MCMs command simply lists the number of MCMs in the system as an
integer. The output of this command can be easily captured and directly passed as input in Tcl scripts.
EXAMPLE
Display the number of MCMs in the simulation system:
mysim display number_of_MCMsThe following output is displayed:
1
SEE ALSO
{machine} display config number_of_MCMs
93Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display sim_support_enable -- displays whether simulator call-thru support is enabled.
TCL SYNTAX
machine display sim_support_enable
DESCRIPTION
The {machine} display sim_support_enable command displays whether support for call-thru functions in
the simulation environment is enabled or disabled.5
EXAMPLE
Verify if simulation callthru support is enabled for mysim machine:
mysim modify sim_support_enable
The following output is displayed:
on
SEE ALSO
{machine} modify sim_support_enable
5. The IBM-Full-System Simulator provides a set of call-thru wrapper functions that can be invoked by an application running in simulation to notify
the simulator of events, capture simulation data, or modify simulator behavior. A call-thru function executes a specialized PowerPC instruction (opcode
0x000EAEB0) that suspends the execution of instructions in the simulation, and instead starts executing instructions on the simulator itself. The
callthru_config.h File Reference (available at http://mambo.austin.ibm.com/how-to/callthru__config_8h.html) provides syntax and usage
information for call-thru wrapper functions that can be invoked by the simulated program. The callthru_config.h file is compiled with programs
that are executed under the simulator, such as stand-alone programs or operating systems.
94 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display strict -- displays whether strict adherence to hardware behaviors is enabled.
TCL SYNTAX
machine display strict
DESCRIPTION
The {machine} display strict command displays whether the simulator’s strict adherence to hardware
behaviors is enabled or disabled. By default, the simulator strictly adheres to hardware functional behavior
(where strict mode is enabled). When the strict mode is disabled, the simulator manages certain operations in
a more convenient way. See the command page for the {machine} modify strict command for information
about operations that are performed when strict mode is disabled.
EXAMPLE
Verify if strict mode is enabled in the simulation:
mysim display strict
The following output is displayed:
on
SEE ALSO
{machine} modify strict
95Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display thinwire_port -- display the port number of the thinwire connection.
TCL SYNTAX
machine display thinwire_port
DESCRIPTION
Thinwire is a technique used to multiplex multiple communications channels over a single (possibly emulated)
serial line to a set of sockets. The simulator provides support to allow it to connect to thinwire servers. The
{machine} display thinwire_port command lists the port number the simulator will use to listen for the
thinwire socket connection.
EXAMPLE
View the thinwire connection port:
mysim display thinwire_port
The following output is displayed:
Thinwire port is 2101
SEE ALSO
{machine} modify thinwire_port
96 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display ticks -- displays the current tick count.
TCL SYNTAX
machine display ticks
DESCRIPTION
The {machine} display ticks displays the current tick count. Output from command is displayed as the
numbert, where number is the number of ticks. See the {machine} tick command page for more information
about how ticks are used to represent time in the simulated system.
EXAMPLE
Advance the simulator 1000000 ticks with the {machine} tick command:
mysim tick 1000000
The simulator advances by the specified number of ticks, after which the {machine} display ticks command
can be used to view how many ticks have elapsed:
mysim display ticks
The simulator summarizes the count as follows:
1000000t
SEE ALSO
{machine} tick, {machine} cycle
97Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display time_domain_for_display -- displays the time domain for cycle counts in messages.
TCL SYNTAX
machine display time_domain_for_display
DESCRIPTION
The {machine} display time_domain_for_display command displays the time domain that is used for the
cycle counts display in simulator messages. The list of available domains depends upon the machine
configuration, and can be obtained using the {machine} modify tdomains display or {machine} modify
tdomains list commands.
EXAMPLE
Determine which domain is used for the cycle count display:
mysim display time_domain_for_display
The simulator displays the setting, as follows:
Selected Time Domain is cpu
SEE ALSO
{machine} modify time_domain_for_display, {machine} modify tdomains display, {machine}
modify tdomains list
98 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display time_domain_for_step -- displays the time domain for cycle counts.
TCL SYNTAX
machine display time_domain_for_step
DESCRIPTION
The {machine} display time_domain_for_step command displays the time domain for cycle counts in the
system. The list of available domains depends upon the machine configuration, and can be obtained using the
{machine} modify tdomains display or {machine} modify tdomains list commands.
EXAMPLE
Determine which domain is used for the cycle count display:
mysim display time_domain_for_stepThe simulator displays the setting, as follows:
step cycle time domain is cpu
SEE ALSO
{machine} display time_domain_for_step, {machine} modify tdomains display, {machine} modify
tdomains list, {machine} cycle
99Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} display timer_slowdown_ratio -- displays the decrementer tick ratio for the CPU clock.
TCL SYNTAX
machine display timer_slowdown_ratio
DESCRIPTION
By default, the machine decrementer timer runs at the same rate as the CPU clock (i.e., for each CPU clock
tick, the decrementer register value is decreased by 1). The {machine} display timer_slowdown_ratio
command lists the current scaling factor that has been applied to the CPU clock.
EXAMPLE
Determine the current decrementer ratio for the CPU clock:
mysim display timer_slowdown_ratio
The simulator displays the scaling ratio:
timer-slowdown ratio = 1
SEE ALSO
{machine} display timer_slowdown_ratio
100 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} display uart_interval -- displays the frequency at which the simulator polls for input.
TCL SYNTAX
machine display uart_interval
DESCRIPTION
As the simulator iterates through its instruction loop, it periodically checks for instructions to read input
characters into the simulated UART window. The {machine} display uart_interval lists the current
frequency at which the simulator poll the system for this input. By default, the simulator polls for input every
100,000 CPU cycles.
EXAMPLE
Determine the current polling frequency:
mysim display uart_intervalThe simulator displays the current UART polling frequency:
100000
SEE ALSO
{machine} modify uart_interval
101Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} dynlib open -- enables shared libraries to be loaded in the simulation.
TCL SYNTAX
machine dynlib open lib_name init_fun
DESCRIPTION.
The {machine} dynlib open command enables shared libraries (*.so files) to be loaded in the simulator.
Once the library is loaded, the initial member function is called.
ARGUMENTS
lib_name Specifies the name of the library to open.
init_fun Specifies the name of the initial function from the dynamic library to load and execute. The
initial function should be declared as:
void init_fun(shim_handle*, Tcl_Interp*)
EXAMPLE
The following sample command line opens the shim/regress/netdev shared library in which the
NeLibInit function is the initial function to call:
mysim dynlib open shim/regress/netdev.so NeLibInit
SEE ALSO
{machine} dunlib close
102 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} dynlib close -- disables the loading of shared libraries n the simulation.
TCL SYNTAX
machine dynlib close lib_name
DESCRIPTION.
The {machine} dynlib close command disables the loading of shared libraries (*.so files) in the simulator.
ARGUMENTS
lib_name Specifies the name of the library to close.
EXAMPLE
The following sample command line closes the shim/regress/netdev shared library:
mysim dynlib close shim/regress/netdev.so
SEE ALSO
{machine} dynlib open
103Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} interrupt -- schedule an interrupt of a given interrupt type.
TCL SYNTAX
machine interrupt interrupt_type
DESCRIPTION
The {machine} interrupt command forces an exception (typically, synchronous interrupts) of the given type
to be raised. When the simulator subsequently is run, it performs actions defined by the core architecture to
service the specified exception (i.e., save machine state in appropriate registers, vector to the associated
exception handler code location, and so on). This command is intended as a convenient mechanism to raise
exceptions artificially, for the purposes of debugging exception handlers.
ARGUMENTS
interrupt_type Specifies the type of interrupt that will be used performed during a simulation. The
following interrupt_type options are available:
If the interrupt command is issued without the interrupt_type argument, it lists all available
exception types.
EXAMPLE
Force a load address alignment exception after first enabling the EXCEPTIONS debugging simulator messages,
so that the interrupt scheduling can be verified. The simulator is run afterwards, in order for the exception
handling to take place:
1. Set the level of exception debugging messages:
AlignmentException InstStorageG1
DABRMatch IPI
DataStoragePageFault MachineCheck
DataStorageProtection MER
DataStorageReservationWithWriteThrough PreciseMachineCheck
DataStorageSegmentFault dar_value PrivilegedInstruction
Decrementer SystemCall
FPUnavailable SystemError
HV_Decrementer TrapInstruction
HvSystemCall VMX_Assist
IABRMatch VMXUnavailable
IllegalInstruction
104 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
9032
000000F63C
simdebug set exception 1
The simulator confirms the new setting:
EXCEPTIONS = 1
2. Set a load address alignment exception:
mysim interrupt AlignmentException Load
The simulator prints the current state of the machine and schedules the interrupt:
3. Set the cycle number to 1000:
mysim cycle 1000
The simulator prints the following debug messages:
SEE ALSO
{machine} simdebug
DEBUG: 838521168: EXCEPTIONS : Scheduling an Alignment Interrupt: user generatedDEBUG: 838521168: EXCEPTIONS : DAR=0xC000000000370080 DSISR=0x42000000[0]: 838521168t:0xC00000000000F63C : mr r31,r31
lr:0xC00000000000F668 ctr:0xC0000000001B26C8 cr:0x22000088msr:0x9000000000009032 32,SUPVR,HV srr0:0xC00000000000F644 srr1:0x900000000000tb:0x0000000031FAD150 dec:0x000E92C9 fpscr:0x00000000
r00:0x0000000000000010 r01:0xC000000000373D40 r02:0xC0000000004792D0 r03:0x000000000000007E r04:0xC0000000003D9F90 r05:0x0000000000000001 r06:0x0000000022000082 r07:0xC000000000011364 r08:0x0000000000000000 r09:0xC000000000370000 r10:0x0000000000000000 r11:0xC000000000370080r12:0x0000000044000028 r13:0xC0000000003C4C00 r14:0x0000000000000000 r15:0x0000000000000000 r16:0x0000000000000000 r17:0x0000000000000000 r18:0x0000000000000000 r19:0x0000000000000039 r20:0x000000000031D9D8 r21:0xC000000000000000 r22:0x0000000003FFFE84 r23:0x0000000003FFFDB4r24:0xC0000000003C4C00 r25:0xC000000000476208 r26:0xC00000000036EB70 r27:0x0000000000000010 r28:0x0000000000000008 r29:0xC000000000370000r30:0xC000000000370000 r31:0xC000000000370080
Scheduled mysim interrupt AlignmentException Interrupt
DEBUG: 838521169: EXCEPTIONS : Scheduling Exception(Cause=Alignment), PC=0xC00000DEBUG: 838521169: EXCEPTIONS : Delivering Exception type 5 (Alignment)
105Configuring and Modifying Machine Properties in the Simulation Environment
loop">
NAME
{machine} job display -- lists information about the current set of jobs.
TCL SYNTAX
machine job display ?format_type?
DESCRIPTION
Internally in the IBM-Full System Simulator, individually schedulable threads, referred to as jobs, are created to
simulate a component or collection of components. If a thread must defer processing, it requests to be
blocked, and continues execution when awakened. Any local (stack) state is preserved to mitigate the need for
allocating save areas to save and restore this state. The {machine} job display command lists the current set
of jobs for the simulated machine and provides information about each job.
Note that the set of {machine} job commands generally are useful only for maintaining and developing the
simulator. It is strongly recommended, therefore, that only the IBM Full-System Simulator development and
maintenance teams use the {machine} job showdebug command.
ARGUMENTS
format_type (Optional) Specifies the format type for listing jobs. The following format_type options are
available:
active Generates command output in tabular format where information about
currently active jobs, whether frozen or active, are listed. If a format_type is
not specified with the command, the active option is the default display type.
listformat Presents the command output in a format that can be easily captured and
directly passed as input in Tcl scripts
EXAMPLE
The following sample {machine} job display output illustrates how the output is formatted in the various
display modes. Executing mysim job display, the default command (where no formatting option is
specified), generates the following sample output6. Note that data about both frozen and active jobs is listed:
"hdec" -> frozen proxy[0]: on ready-queue for time 118111600640 with priority=1 and rc=(nil).
. . .
"Advance PPC 0" -> active proxy[0]: on ready-queue for time 114937458591 with priority=1 and rc=(nil). "activity monitor" -> active proxy[0]: on ready-queue for time 116000000000 with priority=1 and rc=(nil). "loop job" -> active proxy[0]: on ready-queue for time 114940000000 with priority=1 and rc=(nil). proxy[1]: blocked on "counter queue" with priority=1 and rc=0x1 <counter: "
106 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
loop">
Executing mysim job display listformat generates the following sample output:
{{hdec} frozen showing}{{dec 0} frozen showing}{{Advance PPC 0} thawed showing}{{activity monitor} thawed showing}{{loop job} thawed showing}{{loop job} thawed showing}
Executing mysim job display active generates the following sample output:
SEE ALSO
{machine} job freeze, {machine} job thaw, {machine} job readyq, {machine} job showdebug
6. The sample code is provided for illustrative purposes; some parts of sample code, therefore, are abridged to highlight output that is typically
generated by this command.
"Advance PPC 0" -> active proxy[0]: on ready-queue for time 114937458591 with priority=1 and rc=(nil). "activity monitor" -> active proxy[0]: on ready-queue for time 116000000000 with priority=1 and rc=(nil). "loop job" -> active proxy[0]: on ready-queue for time 114940000000 with priority=1 and rc=(nil). proxy[1]: blocked on "counter queue" with priority=1 and rc=0x1 <counter: "
107Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} job freeze -- disables a simulation job.
TCL SYNTAX
machine job freeze job_name
DESCRIPTION
Internally in the IBM-Full System Simulator, individually schedulable threads, referred to as jobs, are created to
simulate a component or collection of components. If a thread must defer processing, it requests to be
blocked, and continues execution when awakened. In this manner, jobs are either running (in the ready queue)
or waiting for some resource. Jobs can be disabled (frozen) and later re-enabled (thawed). Note, however, that
freezing and thawing jobs can have a major impact on how the simulator works, both in terms of its
functionality and accuracy. The {machine} job freeze command disables a job that is scheduled in the ready
queue.
Note that the set of {machine} job commands generally are useful only for maintaining and developing the
simulator. It is strongly recommended, therefore, that only the IBM Full-System Simulator development and
maintenance teams use the {machine} job freeze command.
ARGUMENTS
job_name Specifies the name of the job. Job names are listed in the output of the {machine} job
display command or the {machine} job readyq command. Job names containing a space
character must be delimited with quotes; for example, {machine} job freeze activity
monitor.
EXAMPLE
Freeze the simulation job name rtc:
mysim job freeze rtc
SEE ALSO
{machine} job display, {machine} job thaw, {machine} job readyq, {machine} job showdebug
108 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} job readyq -- lists all simulation jobs that are ready for execution.
TCL SYNTAX
machine job readyq
DESCRIPTION
Internally in the IBM-Full System Simulator, individually schedulable threads, referred to as jobs, are created to
simulate a component or collection of components. The {machine} job readyq command lists the current set
of jobs in the simulator ready queue, which contains all active threads (i.e., all threads that are immediately
ready for execution and that may have been previously under execution).
Note that the set of {machine} job commands generally are useful only for maintaining and developing the
simulator. It is strongly recommended, therefore, that only the IBM Full-System Simulator development and
maintenance teams use the {machine} job showdebug command.
EXAMPLE
Running the {machine} job readyq command generates the following sample output:
ReadyQ for time 0Job="dec 0", priority=2147483645Job="Advance PPC 0", priority=1Job="uart", priority=1Job="rtc", priority=1
SEE ALSO
{machine} job display, {machine} job freeze, {machine} job thaw, {machine} job showdebug
109Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} job showdebug -- enables low-level debugging for a simulation job.
TCL SYNTAX
machine job showdebug job_name 0|1
DESCRIPTION
Internally in the IBM-Full System Simulator, individually schedulable threads, referred to as jobs, are created to
simulate a component or collection of components. The {machine} job showdebug command enables or
disables low-level debugging functionality for a specified simulation job.
Note that the set of {machine} job commands generally are useful only for maintaining and developing the
simulator. It is strongly recommended, therefore, that only the IBM Full-System Simulator development and
maintenance teams use the {machine} job showdebug command.
ARGUMENTS
job_name Specifies the name of the job. Job names are listed in the output of the {machine} job
display command or the {machine} job readyq command. Note that space characters in
a job_name are not recognized (such as “activity monitor”).
0|1 Specifies whether the debugging mechanism is turned on (default) or off, where 1 indicates
that debugging is on and 0 indicates that it is turned off.
EXAMPLE
Enable debugging for the hdec job:
mysim job showdebug hdec 1
Disable debugging for the hdec job:
mysim job showdebug hdec 0
SEE ALSO
simdebug set, {machine} job display, {machine} job readyq
110 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} job thaw -- reschedules a simulation job.
TCL SYNTAX
machine job thaw job_name
DESCRIPTION
Internally in the IBM-Full System Simulator, individually schedulable threads, referred to as jobs, are created to
simulate a component or collection of components. Jobs can be disabled (frozen) and later re-enabled
(thawed). The {machine} job thaw command reschedules a previously frozen job in the ready queue. Note,
however, that freezing and thawing jobs can have a major impact on how the simulator works, both in terms of
its functionality and accuracy.
Note that the set of {machine} job commands generally are useful only for maintaining and developing the
simulator. It is strongly recommended, therefore, that only the IBM Full-System Simulator development and
maintenance teams use the {machine} job thaw command.
ARGUMENTS
job_name Specifies the name of the job. Job names are listed in the output of the {machine} job
display command or the {machine} job readyq command. Job names containing a space
character must be delimited with quotes; for example, {machine} job thaw “activity
monitor”.
EXAMPLE
Thaw the simulation job name rtc:
mysim job thaw rtc
SEE ALSO
{machine} job display, {machine} job freeze, {machine} job readyq, {machine} job showdebug
111Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} load elf -- loads an ELF file into simulation memory.
TCL SYNTAX
machine load elf filename
DESCRIPTION
The {machine} load elf command loads a properly formatted ELF (Executable and Linking Format) file into
the memory of the simulated machine. Executing this command sets the initial PC and stack pointer for the
program, and turns on cpu 0.
ARGUMENTS
filename Specifies the name of the ELF file to load.
EXAMPLE
Load the myprog.elf executable into memory:
mysim load elf /tmp/myprog.elf
SEE ALSO
{machine} load xcoff, {machine} load linux, {machine} load vmlinux, {machine} load qtrace
112 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} load linux -- loads a Linux image into simulation memory.
TCL SYNTAX
machine load linux filename
DESCRIPTION
The {machine} load linux command loads a properly created Linux boot image into the memory of the
simulated machine. Executing this command sets the initial PC and stack pointer for the program, and turns on
cpu 0.
ARGUMENTS
filename Specifies the name of the Linux image to load.
EXAMPLE
Load the zImage.initrd.treeboot Linux image into memory:
mysim load image zImage.initrd.treeboot
SEE ALSO
{machine} load xcoff, {machine} load elf, {machine} load vmlinux, {machine} load qtrace
113Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} load qtrace -- loads a qtrace into simulation memory.
TCL SYNTAX
machine load qtrace filename
DESCRIPTION
A qtrace is an internal IBM format for a trace of memory references. The {machine} load qtrace command
loads the memory trace into the simulator, and then uses the memory trace to drive the cache and bus model
to determine performance statistics for the machine.
ARGUMENTS
filename Specifies the name of the trace file to load.
EXAMPLE
Load the mm.qtrace file into memory:
mysim load qtrace mm.qtrace
SEE ALSO
{machine} load xcoff, {machine} load linux, {machine} load vmlinux, {machine} load elf
114 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} load vmlinux -- loads a vmlinux image into simulation memory.
TCL SYNTAX
machine load vmlinux filename address
DESCRIPTION
The {machine} load vmlinux command loads a Linux kernel image into the memory of the machine. The
vmlinux kernel is a modified Linux kernel that has been developed to simulate the process of loading and
transferring control to the operating system kernel software. The vmlinux kernel essentially acts as a boot
loader (lilo/grub) in a regular system. The {machine} load vmlinux command loads the modified kernel
image into the memory of the simulated machine. Executing this command sets the initial PC and stack pointer
for the program, and turns on cpu 0.
ARGUMENTS
filename Specifies the name of the vmlinux file to load.
address Specifies the physical address in memory where the image should be loaded.
EXAMPLE
Load the vmlinux_2.6.7 kernel image file into memory address 0:
mysim load vmlinux $IMAGE_PATH/vmlinux_2.6.7 0
SEE ALSO
{machine} load linux, {machine} load qtrace, {machine} load xcoff, {machine} load elf
115Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} load xcoff -- loads the contents of an XCOFF file into simulation memory.
TCL SYNTAX
machine load xcoff filename
DESCRIPTION
The {machine} load xcoff command loads a properly formatted XCOFF (eXtended Common Object File
Format) file into the memory of the simulated machine. Executing this command sets the initial PC and stack
pointer for the program, and turns on cpu 0.
ARGUMENTS
filename Specifies the name of the xcoff file to load.
EXAMPLE
Load the XCOFF file into memory:
mysim load xcoff /tmp/myobject.x
SEE ALSO
{machine} load linux, {machine} load vmlinux, {machine} load qtrace, {machine} load elf
116 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} mcm -- enables simulator commands to be called on the specified MCM.
TCL SYNTAX
machine mcm mcm_number simulator_command
DESCRIPTION
The IBM Full-System Simulator is designed to simulate a system in
which more than one MCM (multichip module) can run its multiple,
separate processors. The {machine} mcm command is a wrapper
command that runs a subset of simulator commands on the MCM that
is specified by mcm_number. To view a complete list of MCM-related
commands, type {machine} mcm at the simulator command line.
For instance, the {machine} mcm mcm_number modify name
command enables users to set a name for the specified MCM. This is
useful functionality if, for example, mcm 0 is running a client
application and mcm 1 is running a server application, inwhich case
the separate commands can be used to name the two MCM instances (see the Example section below for
sample commands).
ARGUMENTS
mcm_number Specifies the name of the MCM (multichip module) on which the command
operation (defined by the simulator_command input) is performed.
simulator_command Specifies the command input that is run on the specified MCM.
EXAMPLE
Rename the MCMs on the mysim machine to reflect that type of application that is running on the separate
MCMs in the system:
mysim mcm 0 modify name mcm_for_clientmysim mcm 1 modify name mcm_for_server
The simulator prints a the following messages to confirm that the names have been reassigned:
MCM 0 name is mcm_for_clientMCM 1 name is mcm_for_server
SEE ALSO
{machine} cpu, {machine} thread
MC
M 0
MC
M 1
)(
)(... )
()(...
Figure 4-3. Multichip Module System
)(
)(... )
()(... )
()(... )
()(...
117Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} memory display -- displays memory addresses.
TCL SYNTAX
machine memory display address unit_size ?repeat_count?machine memory display address STRING
DESCRIPTION
The {machine} memory display command provides two display options for viewing memory resources. The
first command displays a sequence of memory addresses starting at a given address based on a specified unit
size. The unit size can be represented in bytes, halfwords (two bytes), words (four bytes), or doublewords
(eight bytes).
The second {machine} memory display command returns the character that corresponds to a memory
address. This command is useful for verifying whether the character that occurs at a given address matches the
expected output, for example when developing applications.
ARGUMENTS
address Specifies the physical address where the display will begin.
unit_size Specifies the size of each unit, where:
1 Displays the address as a byte.
2 Displays the address as a halfword.
4 Displays the address as a word.
8 Displays the address as a doubleword.
repeat_count (Optional) Specifies the number of units to display. If a count is not specified, the repeat
count is 1 by default.
STRING Specifies that the command will display the character that corresponds to a memory
address. The literal STRING option (all capital letters) must be passed.
EXAMPLE
1. Display the sequence of memory addresses starting at 0x00B60C repeated 20 times in word format:
mysim memory display 0x00B60C 4 20
The output of this command results in the following:
0x28250000 0x40820038 0x7C7F1B78 0x7C9E23780x4800070D 0x4801B3B5 0x3B000000 0x3C8000000x60840000 0x788407C6 0x64840000 0x6084B6A00x7C84F214 0x4BFFFFA9 0x4800005C 0x7C7F1B78
118 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
0x7C9E2378 0x7CBD2B78 0x7CDC3378 0x7CFB3B78
2. Display the character the corresponds to the memory address:
mysim memory display 100 STRING
The output of this command results in the following:
c.
3. Display the memory address occurring after 0x00B60C in doubleword format:
mysim memory display 0x00B60C 8
The output of this command results in the following:
0x2825000040820038
4. Display the sequence of memory addresses starting at 0x00B60C repeated 18 times in byte format:
mysim memory display 0x00B60C 1 18
The output of this command results in the following:
0x28 0x25 0x00 0x00 0x40 0x82 0x00 0x38 0x7C 0x7F 0x1B 0x78 0x7C 0x9E 0x23 0x78 0x48 0x00
5. Display the sequence of memory addresses starting at 0x00B60C repeated 18 times in byte format:
mysim memory display 0x00B60C 1 18
The output of this command results in the following:
0x28 0x25 0x00 0x00 0x40 0x82 0x00 0x38 0x7C 0x7F 0x1B 0x78 0x7C 0x9E 0x23 0x78 0x48 0x00
SEE ALSO
{machine} memory set, {machine} memory fread, {machine} memory fwrite
119Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} memory fread -- read directly from a file into memory.
TCL SYNTAX
machine memory fread address number_of_bytes filename
DESCRIPTION
The {machine} memory fread command implements the Unix fread() function. This command reads the
specified number of bytes from the specified input source into the given memory address. See the fread
manual page for more information about command functionality.
ARGUMENTS
address Specifies the physical address into which data from the input is read.
number_of_bytes Specifies the number of bytes to read.
filename Specifies the name of the input file that contains the data to read into memory.
EXAMPLE
Read data from the saved_memory input source into the 0x0 memory address:
mysim memory fread 0x0 0x4000 saved_memory
SEE ALSO
{machine} memory fwrite, {machine} memory set, {machine} memory display
120 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} memory fwrite -- write directly from memory into an output file.
TCL SYNTAX
machine memory fwrite address number_of_bytes filename
DESCRIPTION
The {machine} memory fwrite command implements the Unix fwrite() function. This command wries the
specified number of bytes from the specified memory address into the output file. See the fwrite manual page
for more information about command functionality.
ARGUMENTS
address Specifies the physical address from which data is read.
number_of_bytes Specifies the number of bytes to read.
filename Specifies the name of the output file into which data from memory is written.
EXAMPLE
Write data from the 0x0 memory address into the saved_memory output file:
mysim memory fread 0x0 0x4000 saved_memory
SEE ALSO
{machine} memory fread, {machine} memory set, {machine} memory display
121Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} memory set -- sets memory address to a specified value.
TCL SYNTAX
machine memory set address unit_size 64-bit_value
DESCRIPTION
The {machine} memory set command sets a small section of memory to the given value based on a specified
size of memory (the unit size). The unit size can be represented in bytes, halfwords (two bytes), words (four
bytes), or doublewords (eight bytes).
ARGUMENTS
address Specifies the physical memory address to be written.
unit_size Specifies the number of bytes to be written, where:
1 Represents a byte of memory.
2 Represents a halfword of memory.
4 Represents a word of memory.
8 Represents a doubleword of memory.
64-bit_value Specifies the value to be written into the memory address.
EXAMPLE
Set the memory address at 0x40562 to the 0x0003C00 64-bit value:
mysim memory set 0x40562 4 0x00003C00
Set the memory address at 0x40562 to the 0x00503D6020C43D40 64-bit value:
mysim memory set 0x40562 8 0x00503D6020C43D40
SEE ALSO
{machine} memory display, {machine} memory fread, {machine} memory fwrite
122 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
tion
tion
NAME
{machine} modify console_format -- modifies format of console output.
TCL SYNTAX
machine modify console_format format_flag
DESCRIPTION
The {machine} modify console_format command specifies formatting options to be used for console
output that is generated by the simulated system and is displayed in the simulator command line. The console
output displayed in the simulated UART window is not affected by the console formatting options setting.
ARGUMENTS
format_flag Specifies the format of the display with a bit mask, where each bit signifies whether a particular
option is enabled (set to 1) or disabled (set to 0). Available options are:
0x01 Indicates a bit position that adds the current cycle count to the beginning of each line
of console output.
0x02 Indicates a bit position that adds the current instruction count to the beginning of each
line of console output.
0x04 Indicates a bit position that adds a time stamp (host time) to the beginning of each
line of console output.
0x08 Indicates a bit position that adds the name of the processor (thread) that wrote the
console line to the beginning of each line of console output.
When multiple format options are specified, the order in which the options appear is:
{timestamp}: {cycle_count}: [instruction_count]: {thread_name}:
EXAMPLE
Turn on all console output format options:
mysim modify console_format 0xF
The simulator echoes the format setting; when the simulation is started, the following messages are displayed
for the 0xF option:
SEE ALSO
{machine} display console_format
11:06:45: 137371419: (137079791): mysim: eth0: bogus network driver initializa 11:06:45: 139660218: (139368565): mysim: No IRQ retreived 11:06:45: 139690740: (139398771): mysim: eth1: bogus network driver initializa
123Configuring and Modifying Machine Properties in the Simulation Environment
124 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify cpi -- sets the target CPI value for functional simulation.
TCL SYNTAX
machine modify cpi cpi_value
DESCRIPTION
The {machine} modify cpi command sets the target cycles-per-instruction (CPI) value for functional processor
simulation. The processor model uses the target CPI to determine how to advance the clock in relation to the
execution of instructions. When the target CPI value is not integer-valued, the processor model advances time
in a way that approximates the CPI over a sequence of instructions.
The target CPI can be set for each processor independently with the cpu 0 qualifier.
ARGUMENTS
cpi_value Specifies an integer for floating point value that defines the target CPI of the processor. A
cpi_value of 0 indicates that the processor model should apply fixed latencies to instructions
based on the instruction type.
EXAMPLE
1. Set the target CPI for processor 0 to 3:
mysim modify cpi 3
The simulator echoes the new setting for processor 0:
Processor 0: cpi is 3.00
2. Set the target CPI for processor 1 to 2:
mysim cpu 1 modify cpi 2
The simulator echoes the new setting for processor 1:
Processor 1: cpi is 2.00
SEE ALSO
{machine} cpu, {machine} display cpi
125Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} modify cycle_mode -- enables or disables detailing timing models.
TCL SYNTAX
machine modify cycle_mode on|off
DESCRIPTION
The {machine} modify cycle_mode command enables or disables detailing timing models for certain
processors. Processor timing models attempt to simulate the time required to execute instructions in addition
to the functional results of these instructions. Enabling timing models may significantly reduce simulator
performance. Timing models are not available for all processors.
ARGUMENTS
on|off Specifies an integer for floating point value that defines the target CPI of the processor. A
cpi_value of 0 indicates that the processor model should apply fixed latencies to instructions
based on the instruction type.
EXAMPLE
Enable the processor timing models (cycle mode):
mysim modify cycle_mode on
The simulator echoes the new setting.
SEE ALSO
{machine} cpu, {machine} display cycle_mode
126 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify die_on_illegal_inst -- specifies an action to take if model executes illegal instruction.
TCL SYNTAX
machine modify die_on_illegal_inst on|off
DESCRIPTION
The {machine} modify die_on_illegal_inst command specifies the action that the simulator should take
when the processor model attempts to execute an illegal instruction. The architected behavior for executing an
illegal instruction is to raise a program interrupt. Based on the die_on_illegal_inst setting, the simulator
either raises a program interrupt or stops the simulation when it encounters an illegal instruction. In most
situations, the execution of an illegal instruction indicates a software error that the user will want to diagnose
and correct. By stopping at the point where the illegal instruction is detected, the simulator allows the user to
gather diagnostic information on the error making it easier to identify and correct.
ARGUMENTS
on|off Specifies whether the simulation raises a program interrupt when an illegal instruction is
encountered (die_on_illegal_inst is set to off) or if it simply stops the simulation after an
illegal instruction (die_on_illegal_inst is set to on).
EXAMPLE
Specify that the simulator should immediately stop the simulation when the processor model attempts to
execute an illegal instruction:
mysim modify die_on_illegal_inst on
The simulator echoes the new setting.
SEE ALSO
{machine} display die_on_illegal_inst
127Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} modify emulate_floating_point -- specifies whether floating point instructions are emulated.
TCL SYNTAX
machine modify emulate_floating_point on|off
DESCRIPTION
The {machine} modify emulate_floating_point command enables or disables the emulation of floating
point instructions. When floating point emulation is disabled, the simulator utilizes the floating point
instructions of the host system to compute floating point operations. Although disabling floating point
emulation can increase simulator performance, the results of floating point operations may not match actual
hardware results due to differences in floating point implementations between the host and target platforms.
ARGUMENTS
on|off Specifies whether floating point instructions are emulated (emulate_floating_point is set to
on) or if the simulator should use the floating point instructions of the host system to compute
floating point operations (die_on_illegal_inst is set to off).
EXAMPLE
Disable emulation of floating point instructions:
mysim modify emulate_floating_point off
The simulator echoes the new setting.
SEE ALSO
{machine} display emulate_floating_point
128 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify fast -- enables or disables the fast simulation mode.
TCL SYNTAX
machine modify fast on|off
DESCRIPTION
The {machine} modify fast command toggles the fast simulation mode. Fast mode accelerates functional
simulation by a number of techniques, such as temporarily disabling simulator instrumentation used to produce
debugging messages, accumulate statistics, produce emitter records, and check for breakpoints. This mode
generally is used to advance a simulation to a specific point interest in an application, which is particularly
useful for bypassing time-consuming operations that do not impact or are orthogonal to performance analysis.
Fast mode is most commonly used to rapidly execute startup code to bring the system to a point where more
detailed simulation is performed—for instance, to quickly boot the Linux operating system until the console
prompt is detected, at which point the simulator may be switched to one of the other modes to perform more
detailed simulation.
ARGUMENTS
on|off Specifies whether fast mode is enabled (on) or disabled (off).
EXAMPLE
The following sample Tcl script is used to run in fast mode until a Linux prompt is detected:
# trigger fires when the linux prompt in the console is detectedproc linux_booted { sim mcm args } {
array set trig_info $args$sim mcm $mcm trigger clear console $trig_info(match)$sim modify fast off
}
# procedure to wait until a linux prompt is detected# (uses the linux_booted Tcl procedure defined above as the trigger)proc wait_for_linux_prompt { {mcm 0} {sim mysim} } {$sim mcm $mcm trigger set console "INIT: Entering runlevel: 5" [list \
linux_booted $sim $mcm]$sim modify fast on$sim go
}
SEE ALSO
{machine} display fast, {machine} modify loose
129Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} modify frequency -- modifies the machine CPU clock frequency.
TCL SYNTAX
machine modify frequency cpu_frequency
DESCRIPTION
The {machine} modify frequency command sets the CPU clock frequency. By default, the frequency value is
specified in units of Hz (hertz), where one of the following suffixes may be optionally be supplied to denote a
unit (as defined below). Upon completion, the {machine} modify frequency command displays the current
CPU frequency in KHz.
ARGUMENTS
cpu_frequency Sets the CPU clock frequency, where one of the following units may be optionally specified
to denote a clock speed:
G Specifies the frequency in GHz (10^9 Hz).
M Specifies the frequency in MHz (10^6 Hz).
K Specifies the frequency in KHz (10^3 Hz).
Note that non-integer values for the cpu_frequency are not currently supported.
EXAMPLE
Set the clock frequency of the mysim machine to 150 MHz:
mysim modify frequecy 1500M
The simulator confirms the new frequency setting, as follows:
CPU Frequency is 1500000 KHz
SEE ALSO
{machine} display frequency
130 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify gdb_port -- sets the GDB connection port.
TCL SYNTAX
machine modify gdb_port port
DESCRIPTION
The {machine} modify gdb_port command causes the simulator's GDB (GNU Debugger) agent to attempt to
open a socket and listen for a GDB connection at the requested port. Repeated attempts are made by
incrementing the value of port until the connection is successful, or the value of port reaches 65535.
ARGUMENTS
port Specifies the port number used to connect to the GDB agent.
EXAMPLE
Attempt to connect with GDB starting at port 100:
mysim modify gdb_port 100
The simulator attempts the connection by closing the current connection and opening a new connection at the
specified port. If the connection to the specified port fails, the simulator opens a new connection, as illustrated
in the following message:
WARNING 0: Closing gdb listener on port 2346, reopening on port 100WARNING 0: gdb bind returns -1Previous Message Repeated 923 timesWARNING 0: Unable to open gdb listener on 100, using port 1024 insteadGDB port is 1024
SEE ALSO
{machine} display gdb_port
131Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} modify heartbeat -- sets the simulation heartbeat period.
TCL SYNTAX
machine modify heartbeat period
DESCRIPTION
The simulator produces a heartbeat message periodically to display the advance of simulation time. The
{machine} modify heartbeat command alters the period (given in CPU cycles) at which these heartbeat
messages are generated when the simulation is started.
ARGUMENTS
period Specifies the interval at which the heartbeat is displayed. If the period is 0 (zero), the heartbeats
is disabled. Note that the value for period can not include special characters, such as a , (comma
character).
EXAMPLE
Change the period of the heartbeats to generate messages every 100,000 CPU cycles:
mysim modify heartbeat 100000
The simulator echoes the new heartbeat setting. When the simulation is started, new heartbeat message are
printed at the specified interval:
...LOG-ENTRY (HEARTBEAT:0) : 98,270,207 instrs, 4s elapsed, PC = 0xC000000000011B20 LR = 0xC000000000011B4C CLOCK=329178837t...LOG-ENTRY (HEARTBEAT:0) : 98,270,531 instrs, 5s elapsed, PC = 0xC000000000011B20 LR = 0xC000000000011B4C CLOCK=329232837t...
SEE ALSO
Additional {machine} modify commands
132 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify hexdump_file_name -- sets the file name used for a memory dump call-thru.
TCL SYNTAX
machine modify hexdump_file_name filename
DESCRIPTION
The IBM-Full-System Simulator provides a set of call-thru wrapper functions that can be invoked by an
application running in simulation to notify the simulator of events, capture simulation data, or modify
simulator behavior. A call-thru function executes a specialized PowerPC instruction (opcode 0x000EAEB0) that
suspends the execution of instructions in the simulation, and instead starts executing instructions on the
simulator itself. The MamboDumpMemory callthru7 causes the simulator to dump memory contents in
hexadecimal format to a specified file. The {machine} modify hexdump_file_name command sets the
name of the file that is used to capture the memory dump. By default, the hex dump is made to stderr.
ARGUMENTS
filename Specifies the name of file used to capture the memory dump.
EXAMPLE
Set the memory_stats file for the MamboDumpMemory callthru:
mysim modify hexdump_file_name memory_stats
The simulator confirms the file setting, as follows:
File used for dump memory callthrough will be memory_stats
SEE ALSO
{machine} display hexdump_file_name
7. The callthru_config.h File Reference (available at http://mambo.austin.ibm.com/how-to/callthru__config_8h.html) provides syntax and usage
information for call-thru wrapper functions that can be invoked by the simulated program. The callthru_config.h file is compiled with programs
that are executed under the simulator, such as stand-alone programs or operating systems.
133Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} modify inst_profile -- enables feature to generate an instruction profile.
TCL SYNTAX
machine modify inst_profile on|off
DESCRIPTION
The {machine} modify inst_profile command is a build-time configuration that enables the simulator to
generate a detailed instruction profile. Note that this feature is not available in the current simulator build; the
output of {machine} display inst_profile displays a message to indicate whether the build is configured to
support this feature.
ARGUMENTS
on|off Specifies whether the instruction profile feature is enabled (set to on) or disabled (set to off).
SEE ALSO
{machine} display inst_profile
134 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify kdebug_enable -- enables GDB address translation.
TCL SYNTAX
machine modify kdebug_enable 0|1
DESCRIPTION
GDB (GNU Debugger) sends memory accesses and breakpoints to the simulator using virtual addresses. When
debugging kernel images in real mode (i.e., before address translation is enabled in the simulated machine’s
MMU), the {machine} modify kdebug_enable command enables facilities in the simulator's GDB agent to
perform simplified address translation of GDB virtual addresses to real addresses.
In addition to {machine} modify kdebug_enable, the simulator provides additional commands to set the
base address of the virtual segment (see {machine} modify kdebug_virtual), to set the corresponding real
base address (see {machine} modify kdebug_real), and configure the size of the segment (see {machine}
modify kdebug_size).
ARGUMENTS
0|1 Specifies whether the address translation facility is enabled (set to 1) or disabled (set to 0).
EXAMPLE
Enable GDB agent kernel address translation in the simulation environment:
mysim modify kdebug enable 1
The simulator confirms that address translation is enabled by echoing the setting, as follows:
1
SEE ALSO
{machine} display kdebug_enable, {machine} modify kdebug_virtual, {machine} modify
kdebug_real, {machine} modify kdebug_size
135Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} modify kdebug_real -- sets the base real address for GDB agent address translation.
TCL SYNTAX
machine modify kdebug_real hex_address
DESCRIPTION
The {machine} modify kdebug_real command sets the real base address used for GDB (GNU Debugger)
agent kernel address translation. Refer to the {machine} modify kdebug_enable command page for an
overview of address translation in the simulation environment.
ARGUMENTS
hex_address Specifies a hexadecimal value for the real base address that is used.
EXAMPLE
Set the real base address for GDB agent translation to 0x0000000001000000:
mysim modify kdebug_real 0x0000000001000000
The simulator confirms the setting by echoing the address value, as follows:
0x0000000001000000
SEE ALSO
{machine} display kdebug_real, {machine} modify kdebug_enable, {machine} modify
kdebug_virtual, {machine} modify kdebug_size
136 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify kdebug_size -- sets the size of the GDB agent translation segment.
TCL SYNTAX
machine modify kdebug_size address_size
DESCRIPTION
The {machine} modify kdebug_size command sets the size of the segment used for GDB agent kernel
address translation. Refer to the {machine} modify kdebug_enable command page for an overview of
address translation in the simulation environment.
ARGUMENTS
address_size Specifies the size of the segment, in bytes, for GDB agent address translation.
EXAMPLE
Set the size of the segment for GDB agent address translation to 4096 bytes:
mysim modify kdebug_size 4096
The simulator confirms the setting by echoing the segment size, as follows:
4096
SEE ALSO
{machine} display kdebug_size, {machine} modify kdebug_enable, {machine} modify
kdebug_virtual, {machine} modify kdebug_real
137Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} modify kdebug_virtual -- sets the virtual base address for GDB agent address translation.
TCL SYNTAX
machine modify kdebug_virtual hex_address
DESCRIPTION
The {machine} modify kdebug_virtual command sets the segment virtual base address used for GDB agent
kernel address translation. Refer to the {machine} modify kdebug_enable command page for an overview
of address translation in the simulation environment.
ARGUMENTS
hex_address Specifies a hexadecimal value for the real base address that is used.
EXAMPLE
Set the virtual segment base address for GDB agent translation to 0xC000000000000000:
mysim modify kdebug_virtual 0xC000000000000000
The simulator confirms the setting by echoing the address, as follows:
0xC000000000000000
SEE ALSO
{machine} display kdebug_virtual, {machine} modify kdebug_real, {machine} modify
kdebug_enable, {machine} modify kdebug_size
138 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify kips_format -- sets the format for simulator KIPS messages.
TCL SYNTAX
machine modify kips_format format_flag
DESCRIPTION
The {machine} modify kips_format command determines the format for simulation runtime performance
messages that are produced periodically (every 4 seconds). The messages include a measurement for
simulation performance given in KIPS (Kilo-Instructions executed Per Second). The general format of the KIPS
message is:
[optional_info]: [thread_number]: PC:{program_counter_address} : {KIPS_measurements}
ARGUMENTS
format_flag Specifies an integer ranging from 0 to 7 and is interpreted as a bitwise logical OR of the flag
values (i.e., format_flag & flag_value != 0), where the flag_value is defined as follows:
1 Indicates that the KIPS messages will include the current cycle count (in ticks) in the time
domain given by {machine} modify time_domain_for_display (by default, the CPU
domain). This value is represented as: format_flag & 0x1 != 0.
2 Indicates that the KIPS messages will include the count of instructions executed by the
simulator. This value is represented as: format_flag & 0x2 != 0.
4 Indicates that the KIPS messages will include the time of day when the message is written,
in hh:mm:ss notation. This value is represented as: format_flag & 0x4 != 0.
Note that if format_flag is 0, a KIPS message is not printed.
EXAMPLE
1. Disable KIPS messages:
mysim modify kips_format 0
The simulator confirms the new frequency setting, as follows:
KIPS format is 0
2. Produce KIPS messages with the current CPU cycle count:
mysim modify kips_format 1
The simulator echoes the new KIPS format setting. When the simulation is started, new messages are printed in
the specified format:
...
139Configuring and Modifying Machine Properties in the Simulation Environment
es/Seces/Sec
les/Secles/Sec
/Sec
3. Produce KIPS messages with the current simulated instruction count:
mysim modify kips_format 2
The simulator echoes the new KIPS format setting. When the simulation is started, new messages are printed in
the specified format:
4. Produce KIPS messages with the current time of day:
mysim modify kips_format 4
The simulator echoes the new KIPS format setting. When the simulation is started, new messages are printed in
the specified format:
5. Produce KIPS messages with all available information:
mysim modify kips_format 7
The simulator echoes the new KIPS format setting. When the simulation is started, new messages are printed in
the specified format:
... 16:18:00 354526280000000: [0]: (132596803) (PC:0xC000000000011B2C) : 0.0 Kilo-Inst/Sec : 378539302.3 Kilo-Cycles/Sec : 157.1 hours to armageddon ...
SEE ALSO
{machine} display kips_format
380000000: [0]: (PC:0xC000000000011B20) : 1.4 Kilo-Inst/Sec : 14.9 Kilo-Cycl 940000000: [0]: (PC:0xC000000000011B20) : 9.1 Kilo-Inst/Sec : 1120.0 Kilo-Cycl
... [0]: (123406298) (PC:0xC000000000011B20) : 24.7 Kilo-Inst/Sec : 325.0 Kilo-Cyc [0]: (127305752) (PC:0xC000000000011B20) : 77.9 Kilo-Inst/Sec : 1040.0 Kilo-Cyc
... 11:16:19 [0]: (PC:0xC000000000011B20) : 1.7 Kilo-Inst/Sec : 15555.6 Kilo-Cycles ...
140 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify latency -- enables or disables cycle-approximate latency modeling.
TCL SYNTAX
machine modify latency on|off
DESCRIPTION
The {machine} modify latency command notifies each simulated component model that, if possible, it
should assign cycle-approximate latency to its operations. The manner in which a given modeled component
responds to this command, as well as the degree to which the component reflects operation latencies
accurately, depends on the individual model.
ARGUMENTS
on|off Specifies whether cycle-approximate latency modeling is enabled (on) or disabled (off).
EXAMPLE
Enable latency modeling for components so equipped:
mysim modify latency on
The simulator confirms the setting by echoing the address, as follows:
on
SEE ALSO
{machine} cache modify
141Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} modify loose -- enables or disables loose simulation mode.
TCL SYNTAX
machine modify loose on|off
DESCRIPTION
The {machine} modify loose command toggles the loose simulation mode. The loose mode is similar to the
fast mode in that it is used to accelerate functional simulation; however, unlike fast mode, which provides
realistic instruction interleaving between multiprocessors, loose mode allows a processor to advance
independently in the system (for 100,000 instructions) without considering any instructions that are performed
by other components or processors in the system. As a result, loose more is less observant of timing
considerations than fast mode, and is generally used when timing data is not at all relevant in a specific part of
a simulation. For more information about setting a simulation to run in fast mode, see the command page for
the {machine} modify fast command.
ARGUMENTS
on|off Specifies whether loose mode is enabled (on) or disabled (off)
EXAMPLE
The following sample Tcl script boots Linux in loose mode and reads the network setup commands from the
sample_input.input file:
...# create a simulator called mysim and turn on simulation loose modedefine machine myconf mysimmysim loose on
# load kernel and disk...
# use loose mode to boot Linux until the prompt is displayed and call a procedure to reset statistics when application startswait_for_linux_promptwait_for_appStart
# connect console input file to console and start the simulationmysim console create file_input in file sample_input.inputmysim go
SEE ALSO
{machine} display loose, {machine} modify fast
142 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify sim_support_enable -- enables or disables the simulator call-thru support.
TCL SYNTAX
machine modify sim_support_enable on|off
DESCRIPTION
The {machine} modify sim_support_enable command toggles support for call-thru functions in the
simulation environment. The IBM-Full-System Simulator provides a set of call-thru wrapper functions that can
be invoked by an application running in simulation to notify the simulator of events, capture simulation data, or
modify simulator behavior. A call-thru function executes a specialized PowerPC instruction (opcode
0x000EAEB0) that suspends the execution of instructions in the simulation, and instead starts executing
instructions on the simulator itself.
The callthru_config.h File Reference (at http://mambo.austin.ibm.com/how-to/callthru__config_8h.html)
provides syntax and usage information for call-thru wrapper functions that can be invoked by the simulated
program. The callthru_config.h file is compiled with programs that are executed under the simulator, such
as stand-alone programs or operating systems.
ARGUMENTS
on|off Specifies whether the simulator call-thru support is enabled (on) or disabled (off). By default,
call-thru support is enabled in the simulation environment. Note that since callthru functions are
implemented using specially-formed no-op or system call instructions, program exceptions are
possible if an application invokes call-thru functions when the call-thru support disabled.
EXAMPLE
Disable simulation callthru support for mysim machine:
mysim modify sim_support_enable off
The simulator echoes the revised setting:
off
SEE ALSO
{machine} display sim_support_enable
143Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} modify strict -- enables or disables the simulator’s strict adherence to hardware behaviors.
TCL SYNTAX
machine modify strict on|off
DESCRIPTION
The {machine} modify strict command toggles the simulator’s strict adherence to hardware behaviors. By
default, the simulator strictly adheres to hardware functional behavior (where strict mode is enabled). When
the strict mode is disabled, the simulator manages certain operations in a more convenient way. Specifically,
when strict mode is disabled:
Attempts to access an invalid real address produce a simulator error rather than a machine check.
Attempts to set or display an invalid SPR from the Tcl command interface produce warning output without
error.
Applications attempting to read from an invalid SPR (mfspr) obtain a zero.
Sanity checking is performed on values written to the ASR (mtspr) to detect invalid values before address
translation.
Applications attempting to write to an invalid SPR (mtspr) do so without effect.
ARGUMENTS
on|off Specifies whether the strict mode is enabled (on) or disabled (off).
EXAMPLE
Disable strict mode:
mysim modify strict off
The simulator echoes the revised setting:
off
SEE ALSO
{machine} display strict
144 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify thinwire_port -- determine the thinwire connection port.
TCL SYNTAX
machine modify thinwire_port port_number
DESCRIPTION
Thinwire is a technique used to multiplex multiple communications channels over a single (possibly emulated)
serial line to a set of sockets. The simulator provides support to allow it to connect to thinwire servers. The
{machine} modify thinwire_port command determines the port number the simulator will use to listen for
the thinwire socket connection.
ARGUMENTS
port_number Specifies the port number used to listen for a thinwire connection.
EXAMPLE
Set the thinwire connection port to 1024:
mysim modify thinwire_port 1024
The simulator confirms the port setting, as follows:
Thinwire port is 1024
SEE ALSO
{machine} display thinwire_port
145Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} modify time_domain_for_display -- sets the time domain for cycle counts in messages.
TCL SYNTAX
machine modify time_domain_for_display domain_name
DESCRIPTION
The {machine} modify time_domain_for_display command sets the time domain to be used for cycle
counts displayed in simulator messages. The list of available domains depends upon the machine configuration,
and can be obtained using the {machine} modify tdomains display or {machine} modify tdomains list
commands.
ARGUMENTS
domain_name Specifies name of the time domain used for displaying cycle counts in simulator messages.
By default, the cpu domain is used.
EXAMPLE
Use the bus domain for the cycle count display:
mysim modify time_domain_for_display bus
The simulator confirms the new display setting, as follows:
Selected Time Domain is bus
SEE ALSO
{machine} modify tdomains display, {machine} modify tdomains list
146 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify time_domain_for_step -- sets the time domain for cycle advance.
TCL SYNTAX
machine modify time_domain_for_step domain_name
DESCRIPTION
The {machine} modify time_domain_for_step command sets the time domain for cycle counts specified
by the {machine} cycle command. The list of available domains depends upon the machine configuration, and
can be obtained using the {machine} modify tdomains display or {machine} modify tdomains list
commands.
ARGUMENTS
domain_name Specifies the time domain name. By default, the cpu domain is used.
EXAMPLE
The following procedure steps through the series of commands that step through x number of cycles,
determine which domains are configured, and set a new cycle-step domain:
1. Advance the simulated machine by 10 cycles.
mysim cycle 10
The simulator confirms advance operation:
462812600000153: ** finished running 132596803 instructions **
2. Advance the simulated machine again by 10 cycles.
mysim cycle 10
The simulator confirms the operation to advance the simulation:
462812600000163: ** finished running 132596803 instructions **
3. Display the time domains for cycle counts:
mysim tdomain display
The simulator confirms the operation to advance the simulation:
...bus 1GHz (1/2)cpu 2GHz (2G)dram 200MHz (1/10)...
4. Set the cycle-step domain to the dram domain:
mysim tdomain display
147Configuring and Modifying Machine Properties in the Simulation Environment
The simulator confirms the operation to new setting:
step cycle time domain is dram
5. Advance the simulated machine again by 10 cycles. This time the simulator steps through the simulation
with the new dram cycle count, or 100 cycles. This value is determined by the ratio of the dram time
domain (10:1) as evaluated with the ratio of the cpu time domain (1:1); so that dram cycles amount to 100
cpu cycles:
mysim cycle 10
The simulator confirms the operation to advance the simulation:
462812600000263: ** finished running 132596803 instructions **
SEE ALSO
{machine} display time_domain_for_step, {machine} modify tdomains display, {machine} modify
tdomains list, {machine} cycle
148 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} modify timer_slowdown_ratio -- sets the decrementer tick ratio for the CPU clock.
TCL SYNTAX
machine modify timer_slowdown_ratio scale_factor
DESCRIPTION
By default, the machine decrementer timer runs at the same rate as the CPU clock (i.e., for each CPU clock
tick, the decrementer register value is decreased by 1). The {machine} modify timer_slowdown_ratio
command applies a scaling factor to the CPU clock to decrease the decrementer by 1 after the scale_factor CPU
clock cycles have elapsed.
ARGUMENTS
scale_factor Specifies the factor used for scaling the decrementer timer.
EXAMPLE
Set the decrementer rate to tick down once every 20 CPU clock cycles:
mysim modify timer_slowdown_ratio 20
The simulator confirms the scaling operation:
timer-slowdown ratio = 20
SEE ALSO
{machine} display timer_slowdown_ratio
149Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} modify uart_interval -- sets the frequency at which the simulator polls for input.
TCL SYNTAX
machine modify uart_interval polling_frequency
DESCRIPTION
As the simulator iterates through its instruction loop, it periodically checks for instructions to read input
characters into the simulated UART window. The {machine} modify uart_interval specifies the frequency at
which the simulator poll the system for this input. By default, the simulator polls for input every 100,000 CPU
cycles. Specifying a smaller polling_frequency value enables a more responsive simulation environment;
alternately, specifying a larger polling_frequency value enables more efficient execution of the simulation.
ARGUMENTS
polling_frequency Specifies the frequency, in CPU cycles, at which the simulator polls the system for
input.
EXAMPLE
Determine the current polling frequency and set a new frequency that checks for input more often:
1. Determine the current polling frequency:
mysim display uart_intervalThe simulator displays the current UART polling frequency:
100000
2. Set the polling frequency to check for input every 50,000 CPU cycles:
mysim modify uart_interval 50000The simulator echoes the new UART polling frequency setting:
50000
SEE ALSO
{machine} display uart_interval
150 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} ram -- restores the saved contents of memory. registers, or both from a file.
TCL SYNTAX
machine ram both ?name?machine ram memory ?name?machine ram registers ?name?
DESCRIPTION
The {machine} ram command restores the saved contents of memory. registers, or both from a file after
contents of these processor components have been saved using the {machine} save command.
ARGUMENTS
name Specifies the name of a directory that contains the contents of memory or registers to be
restored.
If a directory is not specified, the simulator creates a new name by appending a .integer to the
end of the specified name in order to generate a unique directory, where integer is an
automatically generated number starting at 0. Registers are saved in ASCII format in the name/
registers path. Memory is saved in binary format in the name/memory path.
EXAMPLE
1. Restore the contents of memory from the set1 directory:
mysim ram memory set1
The simulator displays the following message to confirm the save operation:
set1/memory restored
2. Restore the contents of both registers and memory without specifying a directory name:
mysim ram both
The simulator displays the following message to confirm the save operation:
save restored
SEE ALSO
{machine} save
151Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} save -- writes the contents of memory. registers, or both to a file.
TCL SYNTAX
machine save both ?name?machine save memory ?name?machine save registers ?name?
DESCRIPTION
The {machine} save command allows the contents of the specified processor component (memory,
registers, or both) to be written to a file. The contents can be restored subsequently using the {machine}
ram command.
ARGUMENTS
name (Optional) Specifies the name of a directory within which the contents of memory or registers
are to be saved. Register contents are saved in ASCII format in the name/registers path.
Memory contents are saved in binary format in the name/memory path.
If the specified directory name already exists, the simulator creates a new name by appending a
.integer to the end of the specified name in order to generate a unique directory, where integer
is an automatically generated number starting at 0. If the name input is not specified, the
simulator saves contents of the processor component in the save/ directory, using the same
numbering convention described above.
EXAMPLE
1. Save the contents of memory in the set1 directory:
mysim save memory set1
The simulator displays the following message to confirm the save operation:
set1/memory written
2. Save the contents of registers in the set1 directory:
mysim save registers set1
The simulator displays the following message to confirm the save operation:
set1.0/memory written
3. Save the contents of both registers and memory in the set1 directory:
mysim save both set1
The simulator displays the following message to confirm the save operation:
152 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
set1.1 written
Note that in examples 2 and 3 the directory name in the command output reflects the newly-created directory
name that the simulator has generated.
4. Save the contents of both registers and memory without specifying a directory name:
mysim save both
The simulator displays the following message to confirm the save operation:
save written
SEE ALSO
{machine} ram
153Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} set -- sets the specified register to a given value.
TCL SYNTAX
machine set fpr register_number valuemachine set gpr register_number valuemachine set slbe register_number valuemachine set slbv register_number valuemachine set spr register_name valuemachine set tlbr register_number valuemachine set tlbv register_number valuemachine set vmx register_number size index value machine set vmxr register_number hex_value
DESCRIPTION
During a simulation, it is useful to be able to set the registers of a CPU to a specific desired value. The
{machine} set commands allow the general purpose register (GPR), floating point registers (FPR), special
purpose registers (SPR), VMX registers (VMX), the translation look-aside buffer (TLB), and the segment look-
aside buffers (SLB) to be set.
With the exception of the SPR, which is set by specifying a register name, all registers are set by specifying a
register number. The names of the SPRs can be listed with the {machine} cpu 0 display spr list command.
The VMX registers can be loaded either as one large value or in pieces. The {machine} set vmxr command
sets the entire VMX register to the given hex value of up to 32 hex digits. Values with less than 32 hex digits are
right-justified to which leading zeros are added. In contrast, the {machine} set vmx command allows a part of
a VMX register to be set whose size is comprised of 1, 2, 4, 8, or 16 bytes. The index indicates which part (of
the given size) is to be set, where zero indicates the left-most part.
In the case of the TLBs, the {machine} set tlbr command sets the lower register (real address), and the
{machine} set tlbv command sets the upper register (virtual address). For the SLBs, the {machine} set slbe
command sets the ESID (Effective Segment ID) and V-BIT; the {machine} set slbv command sets the VSID
(Virtual Segment ID) and associated bits.
ARGUMENTS
register-number Specifies a register number. All register numbers start at 0.
register-name Specifies the name of a special purpose register (SPR).
value Specifies the value to be stored in the register.
size Specifies the size of the VMX register that is set. The size value can be 1, 2, 4, 8, or 16 bytes.
index Specifies a integer from 0 to 15 indicating the part of the VMX register to change.
154 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
EXAMPLE
1. Set the contents of GPR4 to 0x14CE838D:
mysim set gpr 4 0x14CE838D
The simulator echoes the newly-set register value:
0x14CE838D
2. Set the contents of FPR17 to 0x44059803947:
mysim set fpr 17 0x44059803947
The simulator echoes the newly-set register value:
0x44059803947
3. Set the contents of the SPR named pc to 0x001D31C0:
mysim set spr pc 0x001D31C0
The simulator displays the following message to confirm the save operation:
0x001D31C0
SEE ALSO
{machine} display spr list
155Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} tdomains -- displays a list of time domains.
TCL SYNTAX
machine tdomains display machine tdomains list
DESCRIPTION
A Mambo simulation may consist of various components that operate at different frequencies, each of which
defines a time domain. Time domains in the simulation are named and have a frequency. To model time
domains for different components in the system, the simulator defines a tick—a special unit of time that
represents the finest granularity of time available in the simulation. The frequency of a tick is calculated as the
least common multiple of the frequencies of all time domains. Each time domain measurement is, then, a
scaled instance of this calculated tick frequency. For more information about how ticks are calculated in the
simulation environment, see the command page for {machine} tick on page 46.
The {machine} tdomains display command generates command output in human-readable format where
information about current time domains includes the name and frequency of each time domain, and indicates
if the frequency is absolute (given by a specific numeric frequency) or relative (given as a ratio to the cpu
frequency). Alternately, the {machine} tdomains list presents the command output in a format that can be
easily captured and directly passed as input in Tcl scripts. This command provides the time domain name, the
frequency, and the scale factor (relative to ticks).
EXAMPLE
1. Display all current time domains in human-readable format:
mysim todomains display
The simulator displays the following output for this command:
2. Display all current time domains as input to a Tcl procedure:
mysim set fpr 17 0x44059803947
The simulator displays the following output for this command:
"dram" {freq 1/8, scale 8} "bus" {freq 1/4, scale 4} "cpu" {freq 4G,scale 1}
SEE ALSO
{machine} display frequency, {machine} modify frequency, {machine} display
time_domain_for_step, {machine} display time_domain_for_display
bus 1GHz (1/4) cpu 4Ghz (4G) dram 500MHz (1/8)
156 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} thread -- enables simulator commands to be called on the specified thread.
TCL SYNTAX
machine thread thread_number simulator_command
DESCRIPTION
The IBM Full-System Simulator is designed to simulate a system in
which one or more processors can run multiple threads on an MCM
(multichip module). The {machine} thread command is a wrapper
command that runs a subset of simulator commands on the thread
that is specified by thread_number. To view a complete list of
thread-related commands, type {machine} thread at the simulator
command line.
For instance, the {machine} mcm mcm_number cpu cpu_number
mcm_number thread modify name command enables users to
set a name for the specified thread. This is useful functionality if, for
example, cpu 0 in mcm 1 contains a thread that is running a specific process. In this case, a command can
be used to name the process to facilitate debugging (see the Example section below for sample commands).
ARGUMENTS
thread_number Specifies the name of the thread on which the command operation (defined by
the simulator_command input) is performed.
simulator_command Specifies the command input that is run on the specified thread.
EXAMPLE
Rename the thread 0 to reflect that type of process that is running on the mysim machine:
mysim mcm 1 cpu 0 thread 0 modify name my_proc
The simulator prints a the following message to confirm that the name has been reassigned:
Thread 0 is my_proc
SEE ALSO
{machine} mcm, {machine} cpu
MC
M 0
MC
M 1
)(
)(... )
()(...
Figure 4-4. Multichip Module System
)(
)(... )
()(... )
()(... )
()(...
CPU
0
CPU
1
thre
ad 0
157Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} trigger clear assoc -- removes an associative trigger from the simulation system.
TCL SYNTAX
machine trigger clear assoc event_name
DESCRIPTION
Associative triggers are a class of Tcl handlers that are associated with a set of predefined simulator events—
when a specified simulator event occurs, the simulator invokes a Tcl procedure that has been associated with
this event. The {machine} trigger clear assoc command removes an associative trigger that has been set for
the specified event.
ARGUMENTS
event_name Specifies the name of the event for which a previously set trigger is removed.
EXAMPLE
1. Display the list of events that are currently associated with a Tcl procedure:
mysim trigger display assoc list
The simulator displays a list of currently active event-to-trigger mapping:
SIM_START -> cpu_startSIM_STOP -> cpu_stop
2. Remove the associative trigger for the SIM_STOP event:
mysim trigger clear assoc SIM_STOP
The simulator lists the name of the Tcl procedure for which the association is removed:
cpu_stop
3. After the association for the SIM_STOP event is removed, display the current list of associative triggers:
mysim trigger display assoc list
The simulator displays the current event-to-trigger mapping:
SIM_START -> cpu_start
SEE ALSO
{machine} trigger set assoc, {machine} trigger display assoc
158 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} trigger clear console -- removes a console trigger from the simulation system.
TCL SYNTAX
machine trigger clear conole console_string
DESCRIPTION
Console triggers are a class of Tcl handlers that enable data to be written to the simulator UART console. The
{machine} trigger clear console command removes a console trigger that has been set for the specified
console string.
EXAMPLE
1. Display the list of console triggers that are set for the mysim machine:
mysim trigger display console list
The simulator displays a list of currently active console triggers:
"INIT:Level:5" -> { c_trig "Linux boot" clear }"PCI:" -> { c_trig "PCI" noclear }"Firmware" -> { c_trig "ROM booted" clear }
2. Remove the console trigger for the Firmware string:
mysim trigger clear console “Firmware”
The simulator lists the name of the Tcl procedure for which the association is removed:
c_trig "Linux boot" clear
3. After the association for the string is removed, display the current list of console triggers:
mysim trigger display console list
The simulator displays the current string-to-trigger mapping:
"INIT:Level:5" -> { c_trig "Linux boot" clear }"PCI:" -> { c_trig "PCI" noclear }
SEE ALSO
{machine} trigger set console, {machine} trigger display console
159Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} trigger clear pc -- removes a program counter trigger from the simulation system.
TCL SYNTAX
machine trigger clear pc address
DESCRIPTION
PC, or program counter, triggers are a class of Tcl handlers that execute a Tcl procedure based on the simulator
program counter. The {machine} trigger clear pc addr command removes a PC trigger that has been set for
a specified memory address.
EXAMPLE
1. Display the name of the Tcl procedure that is invoked when the 0xC0000000003921A4 address is reached:
mysim trigger display pc addr 0xC0000000003921A4
The simulator displays the following output:
my_break_point mysim
2. Remove the PC trigger that is set for the 0xC0000000003921A4 address:
mysim trigger clear pc 0xC0000000003921A4
The simulator lists the name of the Tcl procedure for which the association is removed:
my_break_point mysim
SEE ALSO
{machine} trigger set pc, {machine} trigger display pc
160 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} trigger clear real_pc -- removes a program counter trigger from the simulation system.
TCL SYNTAX
machine trigger clear real_pc address
DESCRIPTION
PC, or program counter, triggers are a class of Tcl handlers that execute a Tcl procedure based on the simulator
program counter. The {machine} trigger clear real_pc addr command removes a PC trigger that has been
set for a specified real address.
EXAMPLE
1. Display the name of the Tcl procedure that is invoked when the 0xC0000000003921A4 address is reached:
mysim trigger display pc addr 0xC0000000003921A4
The simulator displays the following output:
my_break_point mysim
2. Remove the PC trigger that is set for the 0xC0000000003921A4 address:
mysim trigger clear real_pc 0xC0000000003921A4
The simulator lists the name of the Tcl procedure for which the association is removed:
my_break_point mysim
SEE ALSO
{machine} trigger set real_pc, {machine} trigger display real_pc
161Configuring and Modifying Machine Properties in the Simulation Environment
_0" }_0" }
NAME
{machine} trigger clear memory system -- removes a memory trigger from the simulation system.
TCL SYNTAX
machine trigger clear memory system r|rw|w address1 address2
DESCRIPTION
Memory triggers are a class of Tcl handlers that execute a Tcl procedure based on activity that occurs in a range
of memory addresses. The {machine} trigger clear memory system removes a memory trigger that has
been set for a specified range of memory addresses.
EXAMPLE
1. Display the list of memory triggers that are set for the mysim machine:
mysim trigger display memory system list
The simulator displays a list of currently active memory triggers:
SEE ALSO
{machine} trigger set memory, {machine} trigger clear memory
{ R addr1 0x0000000001BF3CC0 addr2 0x0000000001BF3CCF translate 0 proc "memwrite{ W addr1 0x0000000001BF3D60 addr2 0x0000000001BF3D66 translate 0 proc "memwrite
2. Remove the PC trigger that is set for the 0xC0000000003921A4 address:
mysim trigger clear memory system w 0x1bf3d60 0x1bf3d6f
The simulator lists the name of the Tcl procedure for which the association is removed:
memwrite_0
162 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} trigger display assoc -- displays a list of available or currently active associative triggers.
TCL SYNTAX
machine trigger display assoc availmachine trigger display assoc list
DESCRIPTION
Associative triggers are a class of Tcl handlers that are associated with a set of predefined simulator events—
when a specified simulator event occurs, the simulator invokes a Tcl procedure that has been associated with
this event. The {machine} trigger display assoc avail command lists a mapping of all available event types
with any associations that have been set; if an event type has not been associated with a Tcl procedure, it is
listed as inactive. The {machine} trigger display assoc list command lists a mapping of event-to-
procedure associations that are currently active.
Events types are model-specific; the following event types, for example, are available for the PowerPC 970
processor model:
FATAL_ERROR Calls a Tcl procedure when a fatal simulator error is encountered.
INTERNAL_ERROR Calls a Tcl procedure when a internal simulator error is encountered.
SIM_START Calls a Tcl procedure when a simulation starts (or resumes).
SIM_STOP Calls a Tcl procedure when a simulation stops (or halts).
CALLTHRU Calls a Tcl procedure when a CPU-side application callthru is executed in the
simulation.
NOOP_n Calls a Tcl procedure when a no-op instruction is executed in the simulation,
where n is an integer ranging from 11 to 30.
EXAMPLE
1. Display the list of event types that are available for a PowerPC 970 machine:
mysim trigger display assoc avail
The simulator displays the entire list of event types with it associated procedure (if applicable, otherwise the
event type is inactive):
NOOP_14 -> inactiveFATAL_ERROR -> inactiveNOOP_15 -> inactiveNOOP_16 -> inactiveNOOP_17 -> inactiveNOOP_18 -> inactiveNOOP_20 -> inactiveNOOP_19 -> inactive
163Configuring and Modifying Machine Properties in the Simulation Environment
NOOP_21 -> inactiveSIM_START -> cpu_startINTERNAL_ERROR -> inactiveNOOP_22 -> inactiveCALLTHRU -> inactiveNOOP_23 -> inactiveNOOP_24 -> inactiveNOOP_25 -> inactiveNOOP_26 -> inactiveNOOP_27 -> inactiveNOOP_10 -> inactiveNOOP_28 -> inactiveNOOP_11 -> inactiveNOOP_30 -> inactiveNOOP_29 -> inactiveSIM_STOP -> cpu_stopNOOP_12 -> inactiveNOOP_31 -> inactiveNOOP_13 -> inactive
2. Display the list of events that are currently associated with a Tcl procedure:
mysim trigger display assoc list
The simulator displays a list of currently active event-to-trigger mapping:
SIM_START -> cpu_startSIM_STOP -> cpu_stop
SEE ALSO
{machine} trigger set assoc, {machine} trigger clear assoc
164 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} trigger display console -- displays a list of currently active console triggers.
TCL SYNTAX
machine trigger display console list
DESCRIPTION
Console triggers are a class of Tcl handlers that enable data to be written to the simulator UART console. The
{machine} trigger display console command displays a mapping of console triggers that are currently
active.
EXAMPLE
Display the list of console triggers that are set for the mysim machine:
mysim trigger display console list
The simulator displays a list of currently active console triggers:
"INIT:Level:5" -> { c_trig "Linux boot" clear }"PCI:" -> { c_trig "PCI" noclear }"Firmware" -> { c_trig "ROM booted" clear }
SEE ALSO
{machine} trigger set console, {machine} trigger clear console
165Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} trigger display pc -- displays a list of currently active program counter triggers.
TCL SYNTAX
machine trigger display pc addr addressmachine trigger display pc list
DESCRIPTION
PC, or program counter, triggers are a class of Tcl handlers that execute a Tcl procedure based on the simulator
program counter. The {machine} trigger display pc addr command displays the name of the Tcl procedure
that has been set for a specified memory address. The {machine} trigger display pc list command, in turn,
displays a list of memory addresses for which a PC trigger has been set.
EXAMPLE
Set the following PC trigger:
mysim trigger set pc 0xC0000000003921A4 "my_break_point mysim"
1. Display the name of the Tcl procedure that is invoked when the 0xC0000000003921A4 address is
reached:
mysim trigger display pc addr 0xC0000000003921A4
The simulator displays the following output:
my_break_point mysim
2. Display a list of memory addresses for which a PC trigger is set:
mysim trigger display pc list
The simulator displays a list of addresses:
0xC0000000003921A4
SEE ALSO
{machine} trigger set pc, {machine} trigger clear pc
166 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} trigger display real_pc -- displays a list of currently active program counter triggers.
TCL SYNTAX
machine trigger display real_pc addr addressmachine trigger display real_pc list
DESCRIPTION
PC, or program counter, triggers are a class of Tcl handlers that execute a Tcl procedure based on the simulator
program counter. The {machine} trigger display real_pc addr command displays the name of the Tcl
procedure that has been set for a specified real address. The {machine} trigger display pc list command, in
turn, displays a list of real addresses for which a PC trigger has been set.
EXAMPLE
Set the following PC trigger:
mysim trigger set real_pc 0xC0000000003921A4 "my_break_point mysim"
1. Display the name of the Tcl procedure that is invoked when the 0xC0000000003921A4 real address is
reached:
mysim trigger display real_pc addr 0xC0000000003921A4
The simulator displays the following output:
my_break_point mysim
2. Display a list of real addresses for which a PC trigger is set:
mysim trigger display real_pc list
The simulator displays a list of addresses:
0xC0000000003921A4
SEE ALSO
{machine} trigger set real_pc, {machine} trigger clear real_pc
167Configuring and Modifying Machine Properties in the Simulation Environment
_0" }_0" }
NAME
{machine} trigger display memory -- displays a list of currently active memory triggers.
TCL SYNTAX
machine trigger display memory system list
DESCRIPTION
Memory triggers are a class of Tcl handlers that execute a Tcl procedure based on activity that occurs in a range
of memory addresses. The {machine} trigger display memory system command displays a mapping of
memory triggers that are currently active.
EXAMPLE
Display the list of memory triggers that are set for the mysim machine:
mysim trigger display memory system list
The simulator displays a list of currently active memory triggers:
SEE ALSO
{machine} trigger set memory, {machine} trigger clear memory
{ R addr1 0x0000000001BF3CC0 addr2 0x0000000001BF3CCF translate 0 proc "memwrite{ W addr1 0x0000000001BF3D60 addr2 0x0000000001BF3D66 translate 0 proc "memwrite
168 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} trigger set assoc -- sets a trigger associated with one of a set of predefined simulator events.
TCL SYNTAX
machine trigger set assoc event_name Tcl_procedure
DESCRIPTION
Associative triggers are a class of Tcl handlers8 that are associated with a set of predefined simulator events.
These triggers can be used in conjunction with call-thru instructions to broaden the scope of performance data
that is collected during a simulation. The {machine} trigger set assoc command invokes a TCL procedure
when a specified simulator event occurs, such as when a simulation starts (or resumes), when a simulation
stops (or halts), or if a simulation error arises.
The simulator defines a set of events that can be used with associative triggers. Note that these events types are
model-specific; to view a list of available event types for a specific model, type mysim trigger display
assoc avail at the simulator command line. The following event types, for example, are available for the
PowerPC 970 processor model:
FATAL_ERROR Calls a Tcl procedure when a fatal simulator error is encountered.
INTERNAL_ERROR Calls a Tcl procedure when a internal simulator error is encountered.
SIM_START Calls a Tcl procedure when a simulation starts (or resumes).
SIM_STOP Calls a Tcl procedure when a simulation stops (or halts).
CALLTHRU Calls a Tcl procedure when a CPU-side application callthru is executed in the
simulation.
NOOP_n Calls a Tcl procedure when a no-op instruction is executed in the simulation,
where n is an integer ranging from 11 to 30.
ARGUMENTS
event_name Specifies an event or state that can occur within the simulated system, which results in the
execution of the TCL procedure defined in Tcl_procedure.
Tcl_procedure Specifies the TCL procedure that is executed when an event (specified by event_name) is
encountered in the simulation. This procedure defines the action that is taken in response
to the event.
8. In a simulated system, a trigger is an event that signals the simulator to invoke a pre-defined Tcl procedure, the trigger action. The simulator provides
several classes of triggers, each of which provides a specific type of visibility to the state and function of the simulation environment. Triggers can be
used to instruct the system to take any number of actions when a specified event occurs.
169Configuring and Modifying Machine Properties in the Simulation Environment
EXAMPLE
1. The following trigger code sample shows command definitions for two associative triggers to monitor CPU run
status, where the cpu_start and cpu_stop trigger actions are created to parse the input argument and print
a message indicating the cycles at which a CPU is started and stopped. The format of argument 0 in the sample
is similar to "{ cpu 0 cycle 1000230 }",
#--------- start CPU counter ---------proc cpu_start {args} {
scan [lindex $args 0] " cpu %d cycle %s" cpunum cyclesputs "Start Counter: CPU $cpunum started at $cycles cycles"
}
#--------- stop CPU counter ---------proc cpu_stop {args} {
scan [lindex $args 0] " cpu %d cycle %s" cpunum cyclesputs "Stop Counter: CPU $cpunum stopped at $cycles cycles"
}
2. The following sample commands, then, can be used to invoke the CPU counter triggers defined in the sample
code above:
#--------- set triggers to monitor CPU run status ---------mysim trigger set assoc "SIM_START" cpu_startmysim trigger set assoc "SIM_STOP" cpu_stop
SEE ALSO
{machine} trigger display assoc avail, {machine} trigger display assoc list, {machine} trigger clear
assoc
170 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} trigger set console -- sets a trigger to enable data to be written to the simulator's console.
TCL SYNTAX
machine trigger set console console_string procedure_name
DESCRIPTION
Console triggers are a class of Tcl handlers9 that enable data to be written to the simulator UART console. The
{machine} trigger set console command invokes a TCL procedure when a specific string appears in the
console output. There is no limit on the number of console triggers that can be created, but the triggers should
be deleted if they are no longer needed to avoid slowing down the console writes.
ARGUMENTS
console_string Specifies the console string that invokes the TCL procedure defined in Tcl_procedure.
Tcl_procedure Specifies the TCL procedure that is executed when a console string (specified by
console_string) is encountered in the simulation. This procedure defines the action that is
taken in response to the console output.
EXAMPLE
1. The following trigger code sample shows command definitions for a console trigger that prints a message if a
specified string appears in the console and then stops the simulation; if a clear action is encountered, the
simulator removes the trigger. The format of argument 0 in the sample is similar to match {xxx} linenum n line
{yyy}:
#--------- performs operations for console string ---------proc c_trig {title action args} {
array set triginfo $argsif {$action == "clear"} {
mysim trigger clear console $triginfo(match)}puts "$title console trigger : $triginfo(match)"puts "console line: $triginfo(linenum): [string trim
$triginfo(line) "\r\n"]" puts "Stopping"simstop
}
9. In a simulated system, a trigger is an event that signals the simulator to invoke a pre-defined Tcl procedure, the trigger action. The simulator provides
several classes of triggers, each of which provides a specific type of visibility to the state and function of the simulation environment. Triggers can be
used to instruct the system to take any number of actions when a specified event occurs.
171Configuring and Modifying Machine Properties in the Simulation Environment
2. The following sample commands, then, can be used to invoke the console trigger defined in the sample code
above:
#--------- set triggers to monitor CPU run status ---------mysim trigger set console "Firmware" { c_trig "ROM booted" clear }mysim trigger set console "PCI:" { c_trig "PCI" noclear }mysim trigger set console "INIT:Level:5" { c_trig "Linux boot" clear }
SEE ALSO
{machine} trigger display console list, {machine} trigger clear console
172 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} trigger set cycle -- sets a trigger to invoke a procedure when a specific cycle count is reached.
TCL SYNTAX
machine trigger set cycle cycles Tcl_procedure
DESCRIPTION
Cycle triggers are a class of Tcl handlers10 that execute a Tcl procedure at a particular cycle count or on a
periodic basis. The {machine} trigger set cycle command invokes a TCL procedure when the simulator's
cycle count reaches a desired cycle count. Note that displaying or clearing a cycle trigger is not supported.
ARGUMENTS
cycles Specifies the cycle count at which the TCL procedure defined in Tcl_procedure is invoked.
Tcl_procedure Specifies the TCL procedure that is executed when the cycle count (specified by cycles) is
encountered in the simulation. This procedure defines the action that is taken in response
to the console output.
EXAMPLE
1. The following trigger code sample shows command definitions for two cycle triggers: the first trigger runs every
200000 cycles by rearming itself within the body of the specified Tcl procedure; the second trigger executes
only once when the cycle count reaches 20000000, and is used to notify the first trigger that it should stop
executing. The procedure my_cycle_proc is used to gather interesting information:
#--------- cycle trigger control variables ---------namespace eval Cycle_triggers {
variable my_interval 200000variable halt_cmd 0
}
#--------- called to stop the cycle triggers ---------proc Cycle_Triggers_Done {} {
puts "Cycle_Triggers_Done"set Cycle_triggers::halt_cmd 1
}
#--- performs an action every $Cycle_triggers::my_interval cycles ---proc my_cycle_proc {cycle} {
puts "$cycle: cycle pc = [mysim cpu 0 display spr pc]"}
10.In a simulated system, a trigger is an event that signals the simulator to invoke a pre-defined Tcl procedure, the trigger action. The simulator
provides several classes of triggers, each of which provides a specific type of visibility to the state and function of the simulation environment. Triggers
can be used to instruct the system to take any number of actions when a specified event occurs.
173Configuring and Modifying Machine Properties in the Simulation Environment
#------- called every $Cycle_triggers::my_interval cycles; --------#- stops creating cycle triggers when Cycle_triggers::halt_cmd set -proc Cycle_Reached {} {
set curcycle [mysim display cycles]my_cycle_proc $curcycleset next_cycle [add64 $curcycle $Cycle_triggers::my_interval]
if { !$Cycle_triggers::halt_cmd } {# rearm cycle triggermysim trigger set cycle $next_cycle {Cycle_Reached}
}}
2. The following sample command, then, can be used to invoke a pair of cycle triggers—the first runs and rearms
itself, after which the second causes the first trigger to stop when the specified condition is reached:
mysim trigger set cycle 200000 {Cycle_Reached}mysim trigger set cycle 20000000 {Cycle_Triggers_Done}
SEE ALSO
{machine} trigger set assoc, {machine} trigger set console, {machine} trigger set pc, {machine}
trigger set real_pc, {machine} trigger set mambo, {machine} trigger set memory
174 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} trigger set pc -- sets a trigger to call a procedure when the program counter reaches an address.
TCL SYNTAX
machine trigger set pc address procedure_name
DESCRIPTION
PC, or program counter, triggers are a class of Tcl handlers11 that execute a Tcl procedure based on the
simulator program counter. The {machine} trigger set pc command invokes a TCL procedure when the
program counter reaches a specified effective address. Simulation breakpoints, for example, are implemented
as PC triggers—when the simulator program counter equals the specified breakpoint address, the trigger
invokes a Tcl procedure to stop the simulation. Breakpoints using the default breakpoint handler can also be
created from the graphical user interface in the PC Tracker window, or in the System Memory windows if
the memory is displayed as instructions. In addition to these functions, PC triggers also can be used to take a
series of snapshots of register contents, and create conditional breakpoints based on hit count or register
contents.
ARGUMENTS
address Specifies the program counter address at which the trigger invokes the TCL procedure
defined in Tcl_procedure.
Tcl_procedure Specifies the TCL procedure that is executed when the program counter address (specified
by address) is encountered in the simulation. This procedure defines the action that is
taken in response to the console output.
EXAMPLE
1. The following trigger code sample shows command definitions for a PC trigger that reads a PC address and
stops the simulation when the address is encountered. The format of argument 0 in the sample is similar to
match {xxx} linenum n line {yyy}:
#-------- PC trigger control variables ---------namespace eval PC_triggers {
variable hit_count 0variable my_thread 0:0
}
#---- pc trigger handler; arg 0 is of the form {address 0x12345} ----proc my_break_point { sim args } {
11.In a simulated system, a trigger is an event that signals the simulator to invoke a pre-defined Tcl procedure, the trigger action. The simulator
provides several classes of triggers, each of which provides a specific type of visibility to the state and function of the simulation environment. Triggers
can be used to instruct the system to take any number of actions when a specified event occurs.
175Configuring and Modifying Machine Properties in the Simulation Environment
#---- read trigger address ---- scan [lindex $args 0] "address %s" pc#--- read thread info and make sure we are on the right thread --- set t [$sim cpu 0 display currentthread]
if {$t == $PC_triggers::my_thread} {incr PC_triggers::hit_countputs "$pc: my breakpoint (count = $PC_triggers::hit_count)"if {$PC_triggers::hit_count >= 4 } {
puts "$pc: stopped by breakpoint "simstop
}}
}
2. The following sample command, then, can be used to invoke a pc trigger when the specified program counter
address is reached:
mysim trigger set pc 0xC0000000003921A4 "my_break_point mysim"
SEE ALSO
{machine} trigger set assoc, {machine} trigger set console, {machine} trigger set cycle, {machine}
trigger set real_pc, {machine} trigger set mambo, {machine} trigger set memory
176 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} trigger set real_pc -- triggers a Tcl procedure when the program counter reaches a real address.
TCL SYNTAX
machine trigger set real_pc address procedure_name
DESCRIPTION
PC, or program counter, triggers are a class of Tcl handlers12 that execute a Tcl procedure based on the
simulator program counter. The {machine} trigger set real_pc command invokes a TCL procedure when the
program counter reaches a specified real address.
ARGUMENTS
address Specifies the program counter address at which the trigger invokes the TCL procedure
defined in Tcl_procedure.
Tcl_procedure Specifies the TCL procedure that is executed when the program counter address (specified
by address) is encountered in the simulation. This procedure defines the action that is
taken in response to the console output.
EXAMPLE
1. The following trigger code sample shows command definitions for a PC trigger that reads a PC address and
stops the simulation when the address is encountered. The format of argument 0 in the sample is similar to
match {xxx} linenum n line {yyy}:
#-------- PC trigger control variables ---------namespace eval realPC_triggers {
variable hit_count 0variable my_thread 0:0
}
#-- real pc trigger handler; arg 0 is of the form {address 0x12345} --proc my_break_point { sim args } {
#---- read trigger address ---- scan [lindex $args 0] "address %s" pc#--- read thread info and make sure we are on the right thread --- set t [$sim cpu 0 display currentthread]
if {$t == $PC_triggers::my_thread} {incr PC_triggers::hit_countputs "$pc: my breakpoint (count = $PC_triggers::hit_count)"
12.In a simulated system, a trigger is an event that signals the simulator to invoke a pre-defined Tcl procedure, the trigger action. The simulator
provides several classes of triggers, each of which provides a specific type of visibility to the state and function of the simulation environment. Triggers
can be used to instruct the system to take any number of actions when a specified event occurs.
177Configuring and Modifying Machine Properties in the Simulation Environment
if {$PC_triggers::hit_count >= 4 } {puts "$pc: stopped by breakpoint "simstop
}}
}
2. The following sample command, then, can be used to invoke a pc trigger when the specified program counter
address is reached:
mysim trigger set real_pc 0xC0000000003921A4 "my_break_point mysim"
SEE ALSO
{machine} trigger set assoc, {machine} trigger set console, {machine} trigger set cycle, {machine}
trigger set pc, {machine} trigger set mambo, {machine} trigger set memory
178 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} trigger set memory system -- sets a trigger to call a procedure for a specified memory range.
TCL SYNTAX
machine trigger set memory system r|rw|w addr1 addr2 0|1 Tcl_proc
DESCRIPTION
Memory triggers are a class of Tcl handlers13 that execute a Tcl procedure based on activity that occurs in a
range of memory addresses. The {machine} trigger set memory command invokes a TCL procedure when a
load, store, or DMA operation references an address in a specified address range. Memory reads for instruction
fetches, however, do not invoke triggers. For efficiency, only two memory triggers can be set at a time: one for
read and one for write memory address ranges. System memory triggers are checked after executing PowerPC
instructions. If the CPU is not running the system memory trigger handler will not be invoked.
The IBM Full-System Simulator graphical user interface provides default memory breakpoint handlers that may
be accessed from the System Memory graphical user interface for memory:
Figure 4-5. IBM Full-System Simulator System Memory Graphical User Interface
ARGUMENTS
r|rw|w Specifies whether the hardware or software code that is accessing the memory address
range will read, write, or both read and write to the memory addresses.
addr1 Specifies the starting address in the memory address range.
addr2 Specifies the ending address in the memory address range.
13.In a simulated system, a trigger is an event that signals the simulator to invoke a pre-defined Tcl procedure, the trigger action. The simulator
provides several classes of triggers, each of which provides a specific type of visibility to the state and function of the simulation environment. Triggers
can be used to instruct the system to take any number of actions when a specified event occurs.
179Configuring and Modifying Machine Properties in the Simulation Environment
0|1 Specifies whether address translation is used, where 0 indicates that address translation is
not used and 1 indicates that it is used.
Tcl_proc Specifies the TCL procedure that is executed when an address in the memory range is
accessed.
EXAMPLE
1. The following trigger code samples shows command definitions for two Tcl procedures that output a message
when a specified memory address is written or read. The format of argument 0 in the sample is similar to
address [xxx] cpu [yyy] type [R|W]:
#-------- PC trigger control variables ---------namespace eval memory_triggers {
variable previous_value 0xffffvariable my_thread 0:0
}
#------- memory trigger handler for writes -------#------- arg 0 is of form {address 0x12345 cpu 0:0 type W} -------proc memwrite_0 {args} {
#---- use args to initialize an array ---- eval array set bpinfo $argsset cycles [mysim display cycles]set new_value [mysim memory display $bpinfo(address) 4]
puts "$cycles: memwrite_0 $args wrote $new_value!"
if {$Memory_triggers::previous_value != $new_value} {puts "memory changed from $Memory_triggers::previous_value to
$new_value"set Memory_triggers::previous_value $new_value}
}
#------- memory trigger handler for reads -------#------- arg 0 is of form {address 0x12345 cpu 0:0 type R } -------proc memread_0 {args} {
set cycles [mysim display cycles]puts "$cycles: memread_0 $args !"
}
2. The following sample commands, then, can be used to invoke a memory trigger if the specified memory
address range is accessed for read or write operations:
mysim trigger set memory system w 0x1bf3d60 0x1bf3d6f 0 "memwrite_0"mysim trigger set memory system r 0x1bf3cc0 0x1bf3ccf 0 "memread_0"
SEE ALSO
{machine} trigger set assoc, {machine} trigger set console, {machine} trigger set cycle, {machine}
trigger set real_pc, {machine} trigger set mambo, {machine} trigger set pc
180 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} util dtranslate -- translate the effective address given to a real address as a data reference.
TCL SYNTAX
machine util dtranslate address
DESCRIPTION
The {machine} util dtranslate command translates the effective address given to a real address as a data
reference. The translation use the DERAT (if there is one) and DTLBs (if there are both instruction and data
TLBs).
ARGUMENTS
address Specifies a 32-bit or 64-bit effective address to be translated.
EXAMPLE
Translate the 0x145772 effective address to a real address:
mysim util dtranslate 0x145772
SEE ALSO
{machine} util itranslate
181Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} util itranslate -- translate the effective address given to a real address as an instruction fetch.
TCL SYNTAX
machine util itranslate address
DESCRIPTION
The {machine} util itranslate command translates the effective address given to a real address as an
instruction fetch. The translation use the IERAT (if there is one) and ITLBs (if there are both instruction and
data TLBs).
ARGUMENTS
address Specifies a 32-bit or 64-bit effective address to be translated.
EXAMPLE
Translate the 0x145772 effective address to a real address:
mysim util itranslate 0x145772
SEE ALSO
{machine} util dtranslate
182 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.
NAME
{machine} util ppc_disasm -- interpret an instruction as a PPC instruction executed at a given address.
TCL SYNTAX
machine util ppc_disasm instruction address
DESCRIPTION
The {machine} util ppc_disasm command interprets the specified instruction as a PowerPC instruction that
can be executed at the given address, and prints the assembly language interpretation of this instruction. The
address input is required for all instructions, but used only for the interpretation of relative addresses, such as
in branches.
ARGUMENTS
instruction Specifies a 32-bit number to be interpreted as an instruction.
address Specifies the address where the instruction is to be stored.
EXAMPLE
Interpret 0x74003100 as an instruction that is stored to the 0x4328 address:
mysim util ppc_disasm 0x74003100 0x4328
The simulator displays following output for this command:
andis. r0,r0,0x3100
SEE ALSO
{machine} util ppc_disasm2
183Configuring and Modifying Machine Properties in the Simulation Environment
NAME
{machine} util ppc_disasm2 -- decodes and prints the assembly form of an extended PPC instruction.
TCL SYNTAX
machine util ppc_disasm2 prefix instruction address
DESCRIPTION
The IBM Full-System Simulator development team has been extending the PowerPC instruction set using a 32-
bit instruction prefix following by a 32-bit instruction. The {machine} util ppc_disasm2 command decodes
such an extended instruction and prints its assembly language form. Note that this command is specifically
used for developing and extending simulator functionality, and it is unlikely to be useful to users external to
this development process. It is strongly recommended, therefore, that only internal development and
maintenance teams use the {machine} util ppc_disasm2 command.
ARGUMENTS
instruction Specifies a 32-bit number to be interpreted as an instruction.
address Specifies the address where the instruction is to be stored.
EXAMPLE
Interpret 0x74003100 as an instruction that is stored to the 0x4328 address:
mysim util ppc_disasm 0x74003100 0x4328
The simulator displays following output for this command:
andis. r0,r0,0x3100
SEE ALSO
{machine} util ppc_disasm2
184 IBM Full-System Simulator Command Reference © IBM Corporation. All rights reserved.