[ Table Of Contents | Keyword Index ]

dbgreg(n) 1.0 dbgreg "Symbolic Cortex-M3 Register Access"

NAME

dbgreg - Symbolic Access to Cortex-M3 Registers

TABLE OF CONTENTS

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    COMMANDS
    CORE COMMANDS
    NVIC COMMANDS
    DATABASE COMMANDS
    SEE ALSO
    KEYWORDS
    COPYRIGHT

SYNOPSIS

package require Tcl 8.5
package require dbgreg ?1.0?
package require dbgreg::core ?1.0?
package require dbgreg::NVIC ?1.0?
package require dbgreg::regDB ?1.0?
package require dbgreg::regDB::m3reg ?1.0?
package require dbgreg::regDB::lmsreg ?1.0?

dbgreg bind
dbgreg regRead blkName regName
dbgreg regReadElements blkName regGroup ?index1? ?index2? ?...?
dbgreg regWrite blkName regName value ?base?
dbgreg regWriteElements blkName regGroup ?index1 value1? ?index2 value2? ?...?
dbgreg regGetAddr blkName regName
dbgreg regComposeValue blkName regName value ?base?
dbgreg regParse blkName regName value ?fieldList?
dbgreg::core haltCore
dbgreg::core resumeCore
dbgreg::core stepCore ?nsteps?
dbgreg::core resetCore
dbgreg::core getCoreRegs ?reg1? ?reg2? ?...?
dbgreg::core setCoreRegs ?reg1 value1? ?reg2 value2? ?...?
dbgreg::NVIC getIntrCtrl control ?interr1? ?interr2? ?...?
dbgreg::NVIC setIntrCtrl control ?interr1? ?interr2? ?...?
dbgreg::NVIC getIntrPriority ?interr1? ?interr2? ?...?
dbgreg::NVIC setIntrPriority ?interr1 priority1? ?interr2 priority2? ?...?
dbgreg::NVIC getSysHandlerPriority ?hander1? ?handler2? ?...?
dbgreg::NVIC setSysHandlerPriority ?handler1 priority1? ?handler2 priority2? ?...?
dbgreg::regDB blockList
dbgreg::regDB regList blockName
dbgreg::regDB regGroupList blockName
dbgreg::regDB fieldList blockName regName
dbgreg::regDB symbolList blockName regName fieldName
dbgreg::regDB serialize file
dbgreg::regDB print

DESCRIPTION

This manpage describes a set of packages that are used in conjunction with the armdbg package to implement symbolic access to register values. The base package is dbgreg which contains procedures to post reads and writes of registers or sets of registers using symbolic names rather than addresses. The dbgreg::core package provides convenient procedures for halting the core and accessing the processor registers. The dbgreg::NVIC package provides convenient procedures to deal with the Cortex-M3 Nested Vector Interrupt Controller. The symbolic names for the registers are part of the dbgreg::regDB package and are held in an internal database there. The dbgreg::regDB::m3reg package contains the definitions for the registers of the Cortex-M3. The dbgreg::regDB::lmsreg package contains the definitions for the Luminary Micro Stellaris series of chips. See the DATABASE COMMANDS for the register naming conventions.

COMMANDS

All the command in the dbgreg only post register reads or writes and thus must be contained within a transaction (see the armdbg package for an explanation of transactions).

dbgreg bind
The dbgreg bind command binds the addresses found in the Cortex-M3 ROM Table to the base addresses of those blocks in the register database. Normally this call is not needed since the default base addresses are those that correspond to the ARM documentation. However, it is possible for an implementation to change the addresses, and the ROM Table is intended to provide the means to locate the starting addresses of all system defined register blocks.

dbgreg regRead blkName regName
The dbgreg regRead command posts a read for the register named regName that is contained in the block given by blkName.

dbgreg regReadElements blkName regGroup ?index1? ?index2? ?...?
The dbgreg regReadElements command posts a read for a set of registers from a register group. The elements of the register group called regGroup are contained in the block given by blkName and are specified by the numerical values of the indexN arguments. Some registers are to have array-like semantics, i.e. they consists of a set of instances at fixed relative offsets from each other. This command is useful for addressing such registers by integer indices.

dbgreg regWrite blkName regName value ?base?
The dbgreg regWrite command posts a write to the register named regName that is contained in the block given by blkName. The value written to the register is given by value. value may either be a single integer or a dictionary. If value is an integer, then that value is written to the register. If value is a dictionary, then the keys are the names of fields within the register and the values are the corresponding values that are to be inserted into the named field. If base if given, then it is used as the starting register value into which the fields are inserted. Otherwise zero is used as the starting value.

dbgreg regWriteElements blkName regGroup ?index1 value1? ?index2 value2? ?...?
The dbgreg regReadElements command posts a write for a set of registers from a register group. The elements of the register group called regGroup are contained in the block given by blkName. The indices and values are specified in pairs.

dbgreg regGetAddr blkName regName
The dbgreg regGetAddr command returns a two element list. The first elmement is the base address of the hardware block given by blkName. The second element is the offset of regName within that block.

dbgreg regComposeValue blkName regName value ?base?
The dbgreg regComposeValue command returns a value that can be written to the block given by blkName and the register given by regName. value is a dictionary keyed by field names containing the field values to be inserted into the appropriate locations in the returned value. If base is present, then the fields are inserted into it. Otherwise, zero is used as the starting value.

dbgreg regParse blkName regName value ?fieldList?
The dbgreg regParse command returns a dictionary keyed by field names with values extracted from value. The value argument is presumed to have been read from the register called regName in the block given by blkName. If fieldList is missing or empty, then all fields are returned. as well as a field named __REGISTER which contains the entire register value formatted as "0x%08x". If present fieldList only the fields contained in fieldList are returned.

CORE COMMANDS

The commands in dbgreg::core are convenience commands that use the dbgreg package to read and write registers that are particularly associated with the processor core. These command are run as transactions and therefore should not be made part of a larger transaction.

dbgreg::core haltCore
Enables core debugging and halts the core. Returns a dictionary containing the fields of the Debug Halting Control and Status Register.

dbgreg::core resumeCore
Resumes running the core. Debugging remains enabled. Returns a dictionary containing the fields of the Debug Halting Control and Status Register.

dbgreg::core stepCore ?nsteps?
Steps the core nsteps number of times. If nsteps is missing, the core is stepped once. Returns a dictionary containing the fields of the Debug Halting Control and Status Register.

dbgreg::core resetCore
Resets the core by writing to the Application Interrupt/Reset Control Register of the NVIC. In order to reset the core by this method is is halted first.

dbgreg::core getCoreRegs ?reg1? ?reg2? ?...?
Returns a dictionary keyed by the register names given as command arguments with the value of the registers. If no arguments are given, then all register values are returned. The core must be halted before executing this command.

dbgreg::core setCoreRegs ?reg1 value1? ?reg2 value2? ?...?
Sets the values of the registers to those given by the regN valueN arguments. The core must be halted before executing this command.

NVIC COMMANDS

The commands in the dbgreg::NVIC package are convenience commands that can be used to manipulate the interrupt registers within the Cortex-M3 Nested Vectored Interrupt Controller. Since the Cortex-M3 can support up to 240 interrupts, these commands use an index to specify which interrupt is intended. These commands run in a transaction and so do not need to be enclosed in an additional transaction.

dbgreg::NVIC getIntrCtrl control ?interr1? ?interr2? ?...?
Returns a dictionary keyed by the interrN values whose corresponding value is a boolean representing the state of the interrupt control given by control. The group argument must be one of:

ISER
Interrupt Set Enable Register

ICER
Interrupt Clear Enable Register

ISPR
Interrupt Set Pending Register

ICPR
Interrupt Clear Pending Register

IABR
Interrupt Active Bit Register
For example, to determine if interrupts 3 and 7 are enabled:

 
% dbgreg::NVIC getIntrCtrl ISER 3 7
3 0 7 1
%



dbgreg::NVIC setIntrCtrl control ?interr1? ?interr2? ?...?
Sets the interrupt control given by control for each of the interrN arguments. The value of control must be one of those listed in the dbgreg::NVIC getIntrCtrl command. Returns the empty string. For example, to enable interrupts 10 and 27:

 
% dbgreg::NVIC setIntrCtrl ISER 10 27
%



dbgreg::NVIC getIntrPriority ?interr1? ?interr2? ?...?
Returns a dictionary keyed by the interrN interrupt numbers that contains the priority value of the corresponding interrupt.

dbgreg::NVIC setIntrPriority ?interr1 priority1? ?interr2 priority2? ?...?
Sets the interrupt priority for the interrN interrupts to the corresponding priorityN value. Returns the empty string.

dbgreg::NVIC getSysHandlerPriority ?hander1? ?handler2? ?...?
Returns a dictionary of keyed by the system exception handler names, handlerN whose values are the priority of the corresponding system handler. The handlerN arguments are given by one of:

MemManage
Memory Manager Exception

BusFault
Bus Fault Exception

UsageFault
Usage Fault Exception

SVCall
Service Call Exception

DebugMonitor
Debug Monitor Exception

PendSV
Pend Service Exception

SysTick
System Tick Exception
dbgreg::NVIC setSysHandlerPriority ?handler1 priority1? ?handler2 priority2? ?...?
Sets the exception priority for the handlerN system exceptions to the corresponding priorityN value. The handlerN arguments must be one of the set of system exception names given in the dbgreg::NVIC getSysHandlerPriority command. Returns the empty string.

DATABASE COMMANDS

The symbolic names for hardware blocks, registers, fields and enumerated field values are held in an internal database. The commands in the dbgreg::regDB package provide a means of introspection on the database. Since the contents of the database can vary from package version to package version, these procs provide a means of programatically determining the major contents of the database. The database contents itself is divided into two packages: dbgreg::dbgm3reg and dbgreg::lmsreg which contain the register definitions for the Cortex-M3 core and those for the Luminary Micro Stellaris chips, respectively.

dbgreg::regDB blockList
Returns a list of hardware block names.

dbgreg::regDB regList blockName
Returns a list of register names contained in the hardware block given by blockName.

dbgreg::regDB regGroupList blockName
Returns a list of register groups contained in the hardware block given by blockName.

dbgreg::regDB fieldList blockName regName
Returns a list of fields contained in the register, regName, which is part of the hardware block, blockName.

dbgreg::regDB symbolList blockName regName fieldName
Returns a dictionary keyed by the values of a field and whose values are the symbolic encoding for the field given by fieldName in the register given by regName in the block given by blockName.

dbgreg::regDB serialize file
Stores in the file named file the contents of the hardware register database. The database is suitable for use with the ral package.

dbgreg::regDB print
Prints to the standard output the contents of the hardware register database.

SEE ALSO

armdbg, ftd2chan, ftd2jtag

KEYWORDS

JTAG , USB

COPYRIGHT

Copyright © 2007 by G. Andrew Mangogna