

OSCR Timer for the Intel(R) PCA Processors with Intel(R)
Wireless MMX(TM) technology

readme.txt 


/***********************************************************
Readme for the OSCR Timer Sample Source Code for the Intel(R) 
Integrated Performance Primitives 


03/12/2003
***********************************************************/

Description

This directory contains sample code that shows how to access the 
OSCR timer register in the Intel(R) PCA Processors with Intel(R) 
Wireless MMX(TM) technology using a linux device driver 
interface. The OSCR timer provides a convenient mechanism for 
measuring the performance associated with various Intel(R) IPP 
components.

An effort has been made to keep the software in the ANSI C style 
whenever possible. Although Intel(R) IPP sample code has been 
tested, no warranty, expressed or implied is to be associated 
with these functions as well as all the associated materials in 
this package. All risk assumed is by the user. See the 
Intel(R) Integrated Performance Primitives License Agreement for details.

-------------------------------------------------------------------------------

Installation
1. Before compilation, make sure the OSCR physical address is correct in your 
   Linux operating system. Modify oscr_xsc_mod.c if necessary.

2. Compile the device driver oscr_xsc_mod.c for the target
   platform using the following command:

   /opt/mvlcee/devkit/arm/iwmmxt_le/bin/iwmmxt_le-gcc -DMODULE -D__KERNEL__ -Wall 
   -mcpu=xscale -mtune=xscale -msoft-float -O2 -c oscr_xsc_mod.c

3. After copying the object module oscr_xsc_mod.o to the target 
   system, install it as a loadable kernel module using the 
   following command:

   insmod -f -o oscr oscr_xsc_mod.o

4. Create a symbolic device link to the OSCR device driver using 
   the following command:

   mknod /dev/ixs_oscr c 59 0

5. You can use oscr.sh to instead of manually completing step 2 and 3.

-------------------------------------------------------------------------------

Usage

1. Add the module oscr.c to the application for which you wish to 
   measure performance.

2. The oscr.c module provides a three-function OSCR API (oscr.h):

	a. ixs_open_OSCR(void) - invoke once to open the OSCR device

	b. ixs_get_OSCR_val(unsigned long *val) - invoke to access 
           the current value of the OSCR timer. Use differential 
           measurements to estimate the amount of time required for 
           a set of intervening operations.

	c. ixs_close_OSCR(void) - invoke to close the OSCR device

3. Example

	#include "oscr.h"

	unsigned long tstart,tstop,trun;

	ixs_open_OSCR();
	
	ixs_get_OSCR_val(&tstart);
	{
		/* DO SOME COMPUTATION */
	}
	ixs_get_OSCR_val(&tstop);
	
	trun=tstop-tstart;  /* OSCR is free-running 32-bit counter, 
                               user must handle wrap around */ 	

	The application can convert trun, given in terms of OSCR ticks, 
        into elapsed clock time given the OSCR oscillator frequency.
-------------------------------------------------------------------------------

Changes Since Last Release

None

-------------------------------------------------------------------------------

License Definitions

Please refer to the Intel(R) Integrated Performance Primitives 
license file for the license agreement details.

-------------------------------------------------------------------------------

Information in this document is provided in connection with 
Intel(R) products. No license, express or implied, by estoppel 
or otherwise, to any intellectual property rights is granted by 
this document. Except as provided in Intel's Terms and Conditions 
of Sale for such products, Intel assumes no liability whatsoever, 
and Intel disclaims any express or implied warranty, relating to sale 
and/or use of Intel products including liability or warranties relating 
to fitness for a particular purpose, merchantability, or infringement
of any patent, copyright or other intellectual property right. Intel 
products are not intended for use in medical, life saving, or 
life sustaining applications. 

Intel may make changes to specifications and product descriptions 
at any time, without notice.

Designers must not rely on the absence or characteristics of any 
features or instructions marked "reserved" or "undefined." Intel 
reserves these for future definition and shall have no responsibility 
whatsoever for conflicts or incompatibilities arising from future 
changes to them.

Contact your local Intel sales office or your distributor to 
obtain the latest specifications and before placing your 
product order.

Copies of documents which have an ordering number and are 
referenced in this document, or other Intel literature may 
be obtained by calling 1-800-548-4725 or by visiting Intel's 
website at http://www.intel.com.

Copyright (c) Intel Corporation, 2001-03

Intel and Intel XScale are trademarks or registered trademarks 
of Intel Corporation or its subsidiaries in the United States 
or other countries. 

* Other brands and names are the property of their respective owners.
