Profile

The Profile object supports profiling of the DSP code. More...

Functions
hpi_err_t	HPI_ProfileOpenAll (const hpi_hsubsys_t *phSubSys, uint16_t wAdapterIndex, uint16_t wProfileIndex, hpi_handle_t *phProfile, uint16_t *pwMaxProfiles)
	Open all the profiles on a particular adapter.
hpi_err_t	HPI_ProfileGet (const hpi_hsubsys_t *phSubSys, hpi_handle_t hProfile, uint16_t wBinIndex, uint16_t *pwProfileInterval, uint32_t *pdwTotalTickCount, uint32_t *pdwCallCount, uint32_t *pdwMaxTickCount, uint32_t *pdwTicksPerMillisecond)
	Reads a single profile from the DSP's profile store.
hpi_err_t	HPI_ProfileGetUtilization (const hpi_hsubsys_t *phSubSys, hpi_handle_t hProfile, uint32_t *pdwUtilization)
	Get the DSP utilization in 1/100 of a percent.
hpi_err_t	HPI_ProfileGetName (const hpi_hsubsys_t *phSubSys, hpi_handle_t hProfile, uint16_t wBinIndex, char *szName, uint16_t nNameLength)
	Get the name of a profile.
hpi_err_t	HPI_ProfileStartAll (const hpi_hsubsys_t *phSubSys, hpi_handle_t hProfile)
	Start profiling running.
hpi_err_t	HPI_ProfileStopAll (const hpi_hsubsys_t *phSubSys, hpi_handle_t hProfile)
	Stop profiling.

---

Detailed Description

The Profile object supports profiling of the DSP code.

It should be used as a development tool for measuring DSP code operation. Comments in AXPROF.H describe the DSP side of the profiling operation. In general this set of functions is intended for AudioScience internel use.

---

Function Documentation

hpi_err_t HPI_ProfileOpenAll	(	const hpi_hsubsys_t *	phSubSys,
		uint16_t	wAdapterIndex,
		uint16_t	wProfileIndex,
		hpi_handle_t *	phProfile,
		uint16_t *	pwMaxProfiles
	)

Open all the profiles on a particular adapter.

If the adapter does not have profiling enabled, the function will return an error, and *phProfile is set to NULL

The complete profile set of all profiles can be thought of as any array of execution timings/profiles. Each indexed profile corresponds to the execution of a particular segment of DSP code.

Note that HPI_ProfileStartAll() must be called after HPI_ProfileOpenAll() to start the profiling operation on the DSP.

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
wAdapterIndex	Adapter index.
wProfileIndex	Corresponds to DSP index.
phProfile	Returned profile handle.
pwMaxProfiles	Returned maximum number of profile bins supported.

References HPI_IndexesToHandle().

hpi_err_t HPI_ProfileGet	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hProfile,
		uint16_t	wBinIndex,
		uint16_t *	pwProfileInterval,
		uint32_t *	pdwTotalTickCount,
		uint32_t *	pdwCallCount,
		uint32_t *	pdwMaxTickCount,
		uint32_t *	pdwTicksPerMillisecond
	)

Reads a single profile from the DSP's profile store.

The input is a handle to the profiles (hProfiles - returned from HPI_ProfileOpenAll()) and an index that addresses one of the profiles (wIndex). The index may range from 0 to wMaxProfiles (returned by HPI_ProfileOpenAll()). The return parameters describe the execution of the profiled section of DSP code.

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hProfile	Handle of profile object.
wBinIndex	Index of the profile to retrieve.
pwProfileInterval	Return number of seconds over which profile counts are accumulated
pdwTotalTickCount	Return total time spent executing the profiled code (measured in ticks)
pdwCallCount	Return number of times the profiled code was executed.
pdwMaxTickCount	Returned maximum ticks for one pass through the profiled code (range 0-8,388,608,).
pdwTicksPerMillisecond	Return the number of ticks in one millisecond.

hpi_err_t HPI_ProfileGetUtilization	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hProfile,
		uint32_t *	pdwUtilization
	)

Get the DSP utilization in 1/100 of a percent.

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hProfile	Handle of profile object.
pdwUtilization	Returned DSP utilization in 100ths of a percent.

hpi_err_t HPI_ProfileGetName	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hProfile,
		uint16_t	wBinIndex,
		char *	szName,
		uint16_t	nNameLength
	)

Get the name of a profile.

A typical adapter can support multiple "named" profiles simultaneously. This function allows an application (or GUI) to read the names of the profiles from the DSP so as to correctly label the returned timing information.

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hProfile	Handle of profile object.
wBinIndex	Index of the profile to retrieve the name of.
szName	Pointer to a string that will have the name returned in it.
nNameLength	Length of the szName string.

hpi_err_t HPI_ProfileStartAll	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hProfile
	)

Start profiling running.

This starts profile counters and timers running. It is up to the user to periodically call HPI_ProfileGet() to retrieve timing information.

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hProfile	Handle of profile object.

hpi_err_t HPI_ProfileStopAll	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hProfile
	)

Stop profiling.

When profiling is stopped counters are no longer updated.

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hProfile	Handle of profile object.