#ident	"@(#)niagara2_perf_api.txt 1.3	06/07/13 SMI"

1.0 Introduction

This document describes the hypervisor API used to support
performance instrumentation on a Niagara2 based system.

Section 2.0 summarizes the overall performance instrumentation
support provided by the Niagara2 processor.

Section 3.0 describes the overall hypervisor API used to access
Niagara2 performance registers.


2.0 Niagara2 CPU and DRAM Performance Instrumentation

Niagara2 processor provides the following performance instrumentation:

	- SPARC performance instrumentation
	- DRAM performance instrumentation
	- PCI-EX Performance instrumentation
	- Ethernet Performance instrumentation

2.1 SPARC Performance Instrumentation

Each hardware strand has a pair of registers to control/ capture
CPU specific instrumentation:

	Description					Access
	-------------------------------------		--------
	SPARC Performance Control Register		ASR=0x10
	SPARC Performance Instrumentation counter	ASR=0x11

These registers are directly accessible by the privileged code. The HT
bit in SPARC PCR controls the counting of hyperprivileged events, can
be set only in hyperprivileged mode.  The hypervisor will provide an
API to allow read/write access to the SPARC performance control
register.  A guest should not assume it can count hyperprivileged
events.  Attempting to set HT bit may result in the API call failing with
ENOACCESS and the guest should handle this gracefully.

2.2 DRAM Performance Instrumentation

Each DRAM channel in Niagara2 has a pair of performance counters, packed 
into a single register, plus a register to control what is counted.
The following table summarizes the location of these counters:

	Description			Location
	--------------------------	------------------
	DRAM Perf Control Register	0x84.0000.n400
	DRAM Perf Counter Register	0x84.0000.n408

where 'n' is 0 through 3 for a total of four different DRAM channels.

The hypervisor will provide an API to allow read/write access to these
registers.


3.0 Hypervisor API for SPARC and DRAM Performance Registers

The hypervisor provides an interface to read and write the SPARC Performance
control register and the DRAM performance registers as they are not directly
accessible by the privileged software.

The guest may not be allowed access to the performance counters and
the interfaces may fail with a status of ENOACCESS.  Code using these
interfaces must handle such a failure gracefully.

3.1 Definitions

Each of the SPARC and DRAM controller performance registers is
assigned a unique performance register (PerfReg) number as follows:


	PerfReg		Description
	-------	------------------------------------

	   0	SPARC Performance Control register

	   1	DRAM Performance Control register 0
	   2	DRAM Performance Counter register 0

	   3	DRAM Performance Control register 1
	   4	DRAM Performance Counter register 1

	   5	DRAM Performance Control register 2
	   6	DRAM Performance Counter register 2

	   7	DRAM Performance Control register 3
	   8	DRAM Performance Counter register 3


NOTE: The interface for reading/writing SPARC performance control
register will pass the entire register value and not just the HT bit.

3.2 API calls

The following function numbers are applicable to accessing Niagara2's
SPARC and DRAM controller performance registers:

	NIAGARA2_GET_PERFREG		0x104
	NIAGARA2_SET_PERFREG		0x105

These API calls are part of the following API group:

	Group#		Description
	-----		------------
	0x202		Niagara2 CPU	

The major and minor version numbers are 1 and 0 respectively.

3.2.1 niagara2_get_perfreg

	    Entry:
		trap#		FAST_TRAP
		function#	NIAGARA2_GET_PERFREG
		arg0		Performance register ID

	    Exit:
		ret0		status (success or error code)
		ret1		Performance register value

This call reads the value of the SPARC or DRAM performance register,
as specified by the argument "Performance register ID".

Upon successful completion the call returns a status of EOK and a performance
register value. Otherwise, it returns one of the following errors:

	EINVAL			Invalid performance register number
	ENOACCESS		No access allowed to the performance register

3.2.2 niaggara2_set_perfreg
	    Entry:
		trap#		FAST_TRAP
		function#	NIAGARA2_SET_PERFREG
		arg0		Performance register ID
		arg1		Performance register value

	    Exit:
		ret0		status (success or error code)

This calls sets the SPARC / DRAM performance register specified by the
argument "Performance register ID", to the value specified by the
argument "Performance register value".

Upon successful completion, it updates the specified performance register
value and returns a status of EOK. Otherwise, it returns one of the following 
errors:

	EINVAL			Invalid performance register number
	ENOACCESS		No access allowed to the performance register