ARM ® RealView ® ESL API v2.0 Developer’sGuide


Table of Contents

Preface
About this document
Intended audience
Organization
Typographical conventions
Terminology
Further reading
Feedback
Feedback on this document
1. Introduction
1.1. Overview
1.2. ESL API interface layers
1.3. Theory of operation
1.4. Components
1.5. Connections
1.5.1. Components with slave ports
1.5.2. Components with master ports
1.5.3. Components with master and slave ports
1.5.4. Synchronous and asynchronous communication
1.6. Cycle based scheduling
1.6.1. Clocking the simulation
1.7. Simulation stages
1.8. Organizing source files for componentsand systems
1.9. Overview of component creation
1.9.1. Defining the component class
1.10. Working with component ports
1.10.1. Using master ports
1.10.2. Using slave ports
1.10.3. Defining the behavior of clocked components
1.10.4. Registering the clock port
1.10.5. Connecting a component to the clock
1.10.6. Defining a factory class for the system
1.10.7. The factory member functions
1.11. Checklist for components
1.11.1. The component class
1.11.2. The port classes
1.11.3. The factory class
1.12. CAInterface extensions
2. The Cycle Accurate Simulation Interface
2.1. Class overview
2.1.1. Interface classes
2.1.2. Port classes
2.1.3. Component and clock classes
2.1.4. Support classes
2.2. The CASIModule class
2.2.1. CASIModule definition
2.2.2. Functions to implement
2.2.3. Functions for the simulation stages
2.2.4. CASIModule::CASIModule()
2.2.5. CASIModule::configure()
2.2.6. CASIModule::init()
2.2.7. CASIModule::interconnect()
2.2.8. CASIModule::reset()
2.2.9. CASIModule::communicate()
2.2.10. CASIModule::update()
2.2.11. CASIModule::terminate()
2.2.12. CASIModule::casi_clocked()
2.2.13. Functions for identification of acomponent
2.2.14. CASIModule::getName()
2.2.15. CASIModule::getType()
2.2.16. CASIModule::getInstanceName()
2.2.17. CASIModule::getInstanceID()
2.2.18. CASIModule::getParent()
2.2.19. CASIModule::getProperty ()
2.2.20. Functions for the configuration ofcomponents
2.2.21. CASIModule::setParameter()
2.2.22. CASIModule::getParameter()
2.2.23. CASIModule::getParameterList()
2.2.24. CASIModule::defineParameter()
2.2.25. CASIModule::testParameter()
2.2.26. Functions for port administration
2.2.27. CASIModule::createPort()
2.2.28. CASIModule::registerPort()
2.2.29. CASIModule::registerPortArray()
2.2.30. CASIModule::exportPort()
2.2.31. CASIModule::findPort()
2.2.32. CASIModule::getPortList()
2.2.33. Functions for connecting components
2.2.34. CASIModule::connect_ports()
2.2.35. CASIModule::connect()
2.2.36. CASIModule::disconnect()
2.2.37. Functions to administer the componenthierarchy
2.2.38. CASIModule::createSubcomponent()
2.2.39. CASIModule::addSubcomponent()
2.2.40. CASIModule::getSubcomponent()
2.2.41. CASIModule::getSubcomponentList()
2.2.42. CASIModule::setSubcomponentParameter()
2.2.43. CASIModule::getComponentLayout()
2.2.44. CASIModule::getObjectLoader()
2.2.45. CASIModule::launchDebugger()
2.2.46. CASIModule::setClockMaster()
2.2.47. CASIModule::getClockMaster()
2.2.48. Miscellaneous functions
2.2.49. CASIModule::message()
2.2.50. CASIModule::getCADI()
2.2.51. CASIModule::getCAPI()
2.2.52. CASIModule::getNumCAMMIs()
2.2.53. CASIModule::getCAMMI()
2.3. The CASIPortIF class
2.3.1. CASIPortIF::getName()
2.3.2. CASIPortIF::getType()
2.3.3. CASIPortIF::getPortInstanceName()
2.3.4. CASIPortIF::setPortInstanceName()
2.3.5. CASIPortIF::setCASIOwner()
2.3.6. CASIPortIF::getCASIOwner()
2.3.7. CASIPortIF::enablePort()
2.3.8. CASIPortIF::isPortEnabled()
2.3.9. CASIPortIF::setConnected()
2.3.10. CASIPortIF::isConnected()
2.3.11. CASIExtPortMapIF
2.4. The clock interface classes
2.4.1. The CASIClockMaster class
2.4.2. CASIClockMaster::registerClockSlave()
2.4.3. CASIClockMaster::unregisterClockSlave()
2.4.4. CASIClockMaster::replaceClockSlave()
2.4.5. CASIClockMaster::disableClockSlave()
2.4.6. CASIClockMaster::enableClockSlave()
2.4.7. CASIClockMaster::registerRealCommunicate()
2.4.8. CASIClockMaster::registerRealUpdate()
2.4.9. CASIClockMaster::addDependency()
2.4.10. CASIClockMaster::schedule()
2.4.11. CASIClockMaster::pmessage()
2.4.12. The CASIClockSlave class
2.5. The transaction interface classes
2.5.1. Introduction to the transaction interface
2.5.2. The CASITransactionProperties structure
2.5.3. CASITransactionProperties.validTimingTable
2.5.4. The CASITransactionIF interface
2.5.5. The CASITransactionSlave class
2.5.6. The CASITransactionMasterIF class
2.5.7. The CASITransactionCallbackIF interfaceclass
2.5.8. The multi-cycle transaction Interface
2.5.9. The CASITransactionInfo structure
2.5.10. The predefined sc_port<CASITransactionIF,1> class
2.5.11. The predefined sc_port< CASITransactionIF,0> class
2.5.12. AXI and AHB transactions
2.6. The signal interface classes
2.6.1. The CASISignalProperties structure
2.6.2. The CASISignalIF Interface
2.6.3. CASISignalIF::driveSignal()
2.6.4. CASISignalIF::readSignal()
2.6.5. The CASISignalSlave class
2.6.6. The CASISignalMasterIF class
2.6.7. The predefined sc_port<CASISignalIF,1> class
2.7. The component factory class CASIFactory
2.7.1. CASIFactory::CASIFactory()
2.7.2. CASIFactory::createInstance()
2.8. The save/restore interface CASISaveRestore
2.8.1. Enabling save/restore support
2.8.2. MyComponent::saveData
2.8.3. MyComponent::restoreData
2.9. Integrating CASI models into OSCISystemC
3. The Cycle Accurate Debug Interface
3.1. Introduction
3.1.1. Simulation control and the CADI interface
3.1.2. Registering the CADI interface withthe component
3.1.3. CADI API overview
3.1.4. CADI Callback API overview
3.2. Defining a CADI interface
3.2.1. The component CADI class declaration
3.2.2. The CADI class constructor
3.2.3. CADI::CADIXfaceGetFeatures()
3.2.4. CADI::CADIXfaceGetError()
3.2.5. CADI::CADIgetDisassembler()
3.2.6. CADI::CADIXfaceAddCallback()
3.2.7. CADI::CADIXfaceRemoveCallback()
3.2.8. CADI::CADIXfaceBypass()
3.2.9. CADI::CADIGetParameterInfo()
3.2.10. CADI::CADIGetTargetInfo()
3.2.11. CADI::CADIGetParameterValues()
3.2.12. CADI::CADIGetParameters()
3.2.13. CADI::CADISetParameters()
3.2.14. CADI::CADIRegGetGroups()
3.2.15. CADI::CADIRegGetMap()
3.2.16. CADI::CADIRegGetCompound()
3.2.17. CADI::CADIRegWrite()
3.2.18. CADI::CADIRegRead()
3.2.19. CADI::CADIGetPC ()
3.2.20. CADI::CADIGetCommittedPCs()
3.2.21. CADI::CADIMemGetSpaces()
3.2.22. CADI::CADIMemGetBlocks()
3.2.23. CADI::CADIMemRead()
3.2.24. CADI::CADIMemWrite()
3.2.25. CADI::CADIMemGetOverlays()
3.2.26. CADI::VirtualToPhysical()
3.2.27. CADI::PhysicalToVirtual()
3.2.28. CADI::CADIGetCacheInfo()
3.2.29. CADI::CADICacheRead()
3.2.30. CADI::CADICacheWrite ()
3.2.31. CADI execution modes
3.2.32. CADI::CADIExecGetModes()
3.2.33. CADI::CADIExecGetResetLevels()
3.2.34. CADI::CADIExecSetMode()
3.2.35. CADI::CADIExecGetMode()
3.2.36. CADI::CADIExecSingleStep()
3.2.37. CADI::CADIExecReset()
3.2.38. CADI::CADIExecContinue()
3.2.39. CADI::CADIExecStop()
3.2.40. CADI::CADIExecGetExceptions()
3.2.41. CADI::CADIExecAssertException()
3.2.42. CADI::CADIExecGetPipeStages()
3.2.43. CADI::CADIExecGetPipeStageFields()
3.2.44. CADI::CADIExecLoadApplication()
3.2.45. CADI::CADIExecUnLoadApplication()
3.2.46. CADI::CADIExecGetLoadedApplication()
3.2.47. CADI::CADIExecSetApplication()
3.2.48. CADI::CADIGetInstructionCount()
3.2.49. CADI::CADIGetCycleCount()
3.2.50. CADI::CADIBptGetList()
3.2.51. CADI::CADIBptRead()
3.2.52. CADI::CADIBptSet()
3.2.53. CADI::CADIBptClear()
3.2.54. CADI::CADIBptConfigure()
3.3. The CADIDisassembler class
3.3.1. CADIDisassembler::getType()
3.3.2. CADIDisassembler::getModeCount()
3.3.3. CADIDisassembler::getModeNames()
3.3.4. CADIDisassembler::getCurrentMode()
3.3.5. CADIDisassembler::getSourceReferenceForAddress()
3.3.6. CADIDisassembler::getAddressForSourceReference()
3.3.7. CADIDisassembler::getDisassembly()
3.3.8. CADIDisassembler::GetInstructionType()
3.3.9. CADIDisassembler::ObtainInterface()
3.3.10. The CADIDisassemblerCB class
3.3.11. CADIDisassemblerCB::ReceiveModeName()
3.3.12. CADIDisassemblerCB::ReceiveSourceReference()
3.3.13. CADIDisassemblerCB::ReceiveDissassembly()
3.4. The CADIProfiling class
3.4.1. CADIProfiling::CADIProfileSetup()
3.4.2. CADIProfiling::CADIProfileControl()
3.4.3. CADIProfiling::CADIProfileTraceControl()
3.4.4. CADIProfiling::CADIProfileGetExecution()
3.4.5. CADIProfiling::CADIProfileGetMemory()
3.4.6. CADIProfiling::CADIProfileGetTrace()
3.4.7. CADIProfiling::CADIProfileGetRegAccesses()
3.4.8. CADIProfiling::CADIProfileSetRegAccesses()
3.4.9. CADIProfiling::CADIProfileGetMemAccesses()
3.4.10. CADIProfiling::CADIProfileSetMemAccesses()
3.4.11. CADIProfiling::CADIProfileGetAddrExecutionFrequency()
3.4.12. CADIProfiling::CADIProfileSetAddrExecutionFrequency()
3.4.13. CADIProfiling::CADIGetNumberOfInstructions()
3.4.14. CADIProfiling::CADIProfileInitInstructionResultArray()
3.4.15. CADIProfiling::CADIProfileGetInstructionExecutionFrequency()
3.4.16. CADIProfiling::CADIProfileSetInstructionExecutionFrequency()
3.4.17. CADIProfiling::CADIProfileRegisterResourceAccessCallBack()
3.4.18. CADIProfiling::CADIProfileUnregisterResourceAccessCallBack()
3.4.19. CADIProfiling::CADIProfileRegisterCallBack()
3.4.20. CADIProfiling::CADIProfileUnregisterCallBack()
3.4.21. CADIProfilingCallbacks::profileResourceAccess()
3.4.22. CADIProfilingCallbacks::profileRegisterHazard()
3.5. The CADICallback class
3.5.1. CADICallbackObj::appliOpen()
3.5.2. CADICallbackObj::appliInput ()
3.5.3. CADICallbackObj::appliOutput ()
3.5.4. CADICallbackObj::appliClose()
3.5.5. CADICallbackObj::doString()
3.5.6. CADI::CADICaptureSemihosting()
3.5.7. CADI::CADIConsoleGetChannels()
3.5.8. CADI::CADIConsoleNotifyInput()
3.5.9. CADI::CADISemiHostingGetInputChannels()
3.5.10. CADI::CADISemiHostingSendInput()
3.5.11. CADICallbackObj::modeChange()
3.5.12. CADICallbackObj::reset()
3.5.13. CADICallbackObj::cycleTick()
3.5.14. CADICallbackObj::killInterface()
3.5.15. CADICallbackObj::bypass()
3.5.16. CADICallbackObj::lookupSymbol()
3.5.17. CADICallbackObj::refresh()
3.6. CADIBroker
3.6.1. CADIBroker::Release()
3.6.2. CADIBroker::GetSimulationFactories()
3.6.3. CADIBroker::GetSimulationInfos()
3.6.4. CADIBroker::SelectSimulation()
3.6.5. CADIErrorCallback::Error()
3.6.6. Creating the CADIBroker
3.7. The CADISimulationFactory class
3.7.1. CADISimulationFactory::Release()
3.7.2. CADISimulationFactory::GetParameterInfos()
3.7.3. CADISimulationFactory::Instantiate()
3.7.4. The CADISimulationCallback class
3.7.5. CADISimulationCallback::simMessage()
3.7.6. CADISimulationCallback::simShutdown()
3.7.7. CADISimulationCallback::simKilled()
3.7.8. The CADIErrorCallback class
3.7.9. CADIErrorCallback::Error()
3.8. CADI data structures
3.8.1. CADITargetFeatures_t structure
3.8.2. CADICallbackType_t
3.8.3. CADICallbackObj
3.8.4. CADIReg_t
3.8.5. CADIRegInfo_t
3.8.6. CADIRegGroup_t
3.8.7. CADIMemSpaceInfo_t
3.8.8. CADIMemBlockInfo_t
3.8.9. CADIPipeStage_t
3.8.10. CADIPipeStageContentInfo_t
3.8.11. CADIBptConfigure_t
3.8.12. CADIDisassemblerStatus
3.8.13. CADI_EXECMODE_t enumeration
3.8.14. CADIExecMode_t structure
3.8.15. CADIFactoryErrorCode_t
3.8.16. CADIFactorySeverityCode_t
3.8.17. CADISimulationInfo_t
3.8.18. CADIBptRequest_t
3.8.19. CADIParameterInfo_t and CADIParameterValue_t
3.8.20. CADIReturn_t
3.8.21. CADIBptCondition_t and CADIBptConditionOperator_t
3.9. Accessing the debug interface fromsc_main()
4. The Cycle Accurate Profiling Interface
4.1. Introduction to CAPI
4.1.1. Profiling streams and channels
4.2. The CAPI classes
4.2.1. The CAPI class
4.2.2. CAPI::CAPIGetProfilingStreams()
4.2.3. CAPI::CAPIFindStream()
4.2.4. CAPI::CAPIGetNumStreams()
4.2.5. CAPI::CAPIGetStream()
4.2.6. CAPI::CAPIGetStream()
4.2.7. CAPI::CAPIClearStreams()
4.2.8. CAPI::CAPIGetTarget()
4.2.9. CAPIRecordEvent1() and CAPIRecordEvent2()
4.3. The CAPIRegistry class
4.3.1. CAPIRegistry::setCAPICallback()
4.3.2. CAPIRegistry::getCAPICallback()
4.3.3. CAPIRegistry::CAPIRegisterInterface()
4.3.4. CAPIRegistry::CAPIUnregisterInterface()
4.3.5. CAPIRegistry::CAPIFindInterface()
4.3.6. CAPIRegistry::CAPIGetNumInterfaces()
4.3.7. CAPIRegistry::CAPIGetInterface()
4.3.8. CAPIRegistry::reset()
4.3.9. CAPIRegistry::clear()
4.3.10. CAPIRegistry::getCAPIRegistry()
4.4. The CAPICallback class
4.4.1. CAPICallback::allocateTraceSegment()
4.4.2. CAPICallback::deallocateTraceSegment()
4.4.3. CAPICallback::getTotalAllocatedMemory()
4.4.4. CAPICallback::getCurrentCycle()
4.5. CAPI data structures
4.5.1. The CAPIStream_t structure
4.5.2. The CAPIStreamInfo_t structure
4.5.3. The CAPIChannelInfo_t structure
4.5.4. The CAPIChannelType_t enumeration
4.5.5. The CAPIChannelSymbolInfo_t structure
4.5.6. The CAPISymbolValue_t structure
4.5.7. The CAPIColor_e enumeration
4.5.8. The CAPITraceSegment_t structure
4.5.9. The CAPIReturn_t enumeration
4.6. Accessing CAPI
4.6.1. The CAPI derived class
4.6.2. Memory Management
4.6.3. Collecting the profiling information
4.7. Example CAPI implementation
4.7.1. The CAPI object
4.7.2. Initializing the channel objects
4.7.3. Using the CAPIGetProfilingStreams()function
4.7.4. Recording events
4.7.5. Reading the recorded profile data
5. The CASI Memory Map Interface
5.1. CASIMMI interfaces
5.1.1. The CASIMMIMemoryMap structure
5.1.2. The CASIMMIMemoryMapRequest structure
5.1.3. CASIMMI class definition
5.1.4. CASIMMI::registerInterface()
5.1.5. CASIMMI::getInterface()
5.1.6. CASIMMI::requestMemoryMaps()
5.1.7. CASIMMI::setEnableMME()
5.1.8. CASIMMI::isMMEEnabled()
5.1.9. CASIMMI::getMMIDetails()
5.1.10. CASIMMI::setMemoryMaps()
5.1.11. CASIMMI::getMemoryMaps()
5.1.12. CASIMMI::setCurrentMemoryMaps()
5.1.13. CASIMMI::getCurrentMemoryMaps()
5.2. Sample implementation
5.2.1. CompBus::CompBus()
5.2.2. CompBus_CASIMMI class Implementationdetails
5.2.3. CompBus_CASIMMI.h file
5.2.4. CompBus_CASIMMI::CASIMMI() constructor
5.2.5. CompBus_CASIMMI::~CASIMMI destructor
5.2.6. CompBus_CASIMMI::requestMemoryMaps
5.2.7. CompBus_CASIMMI::getCurrentMemoryMaps()
5.2.8. slave_port_1_TS::slave_port_1()
5.2.9. slave_port_1_TS::setAddressRegions()
5.2.10. slave_port_1_TS::getMappingConstraints()
A. Static Scheduling of Communication Functions
A.1. Introduction to combinatorial pathscheduling
A.2. Specifying the combinatorial path
A.3. Error checking
A.4. Example implementation
B. AMBA ™ AHB TLM Specificationfor CASI
B.1. Introduction
B.2. AHB control signals
B.2.1. AHB bus state machine
B.3. Implementation details for AHB interfaces
B.3.1. read() and write()
B.3.2. readDbg()
B.3.3. writeDbg()
B.3.4. readReq()
B.3.5. requestAccess()
B.3.6. checkForGrant()
B.3.7. getAddressRegions()
C. AMBA ® AXI TLMSpecification for CASI
C.1. Introduction to AXI
C.1.1. Control and data signals on the AXI channels
C.1.2. Hardware flow control signals
C.2. Introduction to the CASI TLM for AXI
C.2.1. CASITransactionInfo structure
C.2.2. CASITransactionInfo.masterFlags array
C.2.3. AXITransactionInfo class
C.2.4. AXI_TM::notifyEvent()
C.2.5. AXI_TS::driveTransaction()
C.2.6. Transaction properties structure
C.2.7. AXITransactionStepEnum
C.2.8. CASITransactionStatus
C.2.9. AXI transfer sequences
C.2.10. AXI_Master_casi::communicate()
C.2.11. AXI_Master_casi::update()
C.2.12. AXI_Slave_casi::communicate()
C.2.13. AXI_Slave_casi::update()
C.2.14. Example AXI write transaction sequences
C.2.15. Example AXI read transaction sequences
C.2.16. Using the AXI Configurable Interconnect
C.2.17. Example of ACI arbitration for the write channel
C.3. ESL API implementation of the AXITLM
C.3.1. Top-level system
C.3.2. AXI_Master_casi component
C.3.3. AXI_Slave_casi component

List of Figures

1.1. Interface layers
1.2. A sample component with properties, parameters, andports
1.3. Signal-based communication
1.4. Transaction-based communication
1.5. Dual ported memory component withtwo transaction slave ports
1.6. CPU component with separate transactionports for data and program memory
1.7. Bus component with a transactionslave and two transaction master ports
1.8. CPU component connected to memoriesthrough bus components
1.9. Single transaction master with multipleslave ports
1.10. Synchronous communication example
1.11. Asynchronous communication with callback example
1.12. Asynchronous communication with shared memory example
1.13. Communicate and update phases
1.14. CASI schedule example for multipleclocks
1.15. Mixed synchronous and asynchronousupdates
1.16. Stages of simulation
1.17. Block diagram of a system simulation
1.18. Files used for the top example
1.19. Class hierarchy showing user defined slave ports
2.1. Class hierarchy of the interface classes
2.2. Class hierarchy for the componentand clock classes
2.3. Asynchronous transactions using callbacks
3.1. CADI class overview
3.2. CADI and CASI interaction
4.1. CAPI data structures and the profilingstream
4.2. CAPI class hierarchy
A.1. Standard communicate and update phases
A.2. System requiring ordered componentcommunication
A.3. Statically scheduled communicateand update phases
A.4. Component connections
A.5. Component function dependency graph
B.1. AHB write
C.1. Block diagram of master and slavecomponents connected over an AXI bus
C.2. READY and VALID handshake signals
C.3. Simplified AXI TLM block diagram
C.4. AXI classes
C.5. Write with no wait states
C.6. Write with wait state in addresschannel
C.7. Write with simultaneous AW and W,no wait states
C.8. Write with consecutive AW and W,no wait states
C.9. Write with simultaneous AW and Wand wait states
C.10. Read with no wait states
C.11. Read with single wait state on addressstep
C.12. Read with wait states on both addressand data steps
C.13. Bus write with ACI

Proprietary Notice

Words and logos marked with ® or ™ are registered trademarks or trademarksowned by ARM Limited, except as otherwise stated below in this proprietarynotice. Other brands and names mentioned herein may be the trademarksof their respective owners.

Neither the whole nor any part of the information containedin, or the product described in, this document may be adapted orreproduced in any material form except with the prior written permissionof the copyright holder.

The product described in this document is subject to continuousdevelopments and improvements. All particulars of the product andits use contained in this document are given by ARM in good faith.However, all warranties implied or expressed, including but notlimited to implied warranties of merchantability, or fitness forpurpose, are excluded.

This document is intended only to assist the reader in theuse of the product. ARM Limited shall not be liable for any lossor damage arising from the use of any information in this document,or any error or omission in such information, or any incorrect useof the product.

Where the term ARM is used it means “ARM or any of its subsidiariesas appropriate”.

ConfidentialityStatus

This document is Non-Confidential. The right to use, copyand disclose this document may be subject to license restrictionsin accordance with the terms of the agreement entered into by ARMand the party that ARM delivered this document to.

Product Status

The information in this document is final, that is for a developedproduct.

Revision History
Revision A January2007 New document based on ARM RealView SoC Designer6.1 Developer’s Guide and updated to reflect version 1.1 of theRealView ESL API.
Revision B June2007 Updated for ESL API version 2.0. Mx_ naming conventions replacedwith CASI, CADI, and CAPI.
Copyright © 2007 ARM Limited. All rights reserved. ARM DUI 0359B
Non-Confidential