cctl: (version 0.2beta) 25 Apr 2007

NAME:
	cctl - command line program to turn on/off parts of the TS7200/EP930x
	       and to alter things like the CPU freq.

     
SYNOPSIS:

	cctl [-v] [-w] [-i file] [-o file] commands


DESCRIPTION:

WARNING!

This program is dangerous! It can change many system registers that
control the way the EP930x processor and its subsystems operate.  It
can crash your system. It is also possible to set illegal combinations
of parameters which may have disasterous consequences - e.g. setting
the various clock values too high may cause the CPU to overheat and be
damaged. YOU HAVE BEEN WARNED.

  
Just an extra word of warning, there is an outside chance that running    
cctl to change clock frequencies could corrupt the execution of another   
program. This is an outside possiblity and I've not ever seen it.
This is because this is a userspace program and if it is interrupted  
while loop waiting for the clocks to settle then there could be 
problems.
    

It can also control the TS72xx ethernet interface power, turning it
on/off.

The program can read and decode many of system registers, using names
as used in the Cirrus EP930x user manual. It is urged that this program
be used in conjunction with the processor user manual - available from
Cirrus web site. 

   http://www.cirrus.com/en/pubs/manual/EP9301_User_Guide.pdf

cctl allows the interrogation and decoding of various EP930x system 
registers, and system states on the TS72xx boards. It should work also on 
other EP930x based boards, with the execption of the ether on/off commands,
which are specific to the TS72xx boards.

cctl executes commands given on the command line, then any commands
from any file specified in an -i option (see below).

Command files contain one command per line. Blank lines and lines starting
with a '#' character are ignored.

The output of the cctl program is always in a form that can be saved and 
given back to cctl to execute. So saving a full status output of "cctl"
to a file is a good insurance policy. The values can be reset by 
"cctl -i saved.file" .

Currently cctl can report the settings of

 PwrCnt Register
 ChipId Register

It can report and change the settings of

 clkset1    Register
 clkset2    Register
 refrshtimr Register (alias "refresh")
 
 USB  clock setting 
 IRDA clock setting
 UART max baud rate

 ethernet phy power

Fields within the clkset registers cna be individually specified by
specifying as   

 register.field

The field names are taken from the EP9301 user manual. But just run
"cctl" to get a full output of the exact names used. All names used
are case insensitive.

When frequencies are changed, the refrshtimr register is scaled 
appropriately, so as to keep the SD Ram properly refreshed and working!
The refrshtimr register can be read/set independently, however any 
subsequent frequency changes will cause it to changed in scale with the
frequency change.

Simply specifying the parameter name will cause the current
setting/value to be displayed.

To specify a change in value use the form

 name=newvalue

The name can be a register.field

The new value can be a decimal numeric, or a hex numeric prefixed with 0x,
or "on" or "off" for 1 or 0 when these are the only possible values.


Command line options & Flags:

 -v       verbose output

 -w       commit changes specified in commands - DANGEROUS
 
 -o file  output to file instead of stdout

 -i file  read commands from file 


Examples:

 cctl

  Outputs the current status/values of: ethernet power, USB enable, IRDA
  enable, Max Baud rate of UART, DMA clock status 

 cctl -i

  prompt for commands and executes them. Useful for testing.
  This is safe - no changes will be written, unless the write=on 
  command is given!


 cctl -w -i

  ditto, but commit any changes when exiting - DANGEROUS!
  Remember if you think you have screwed up write=off is your friend


 cctl ether

  output power /on/off status of ethernet


 cctl -w ether=off

  Turn the ethernet power off


 cctl -w ether=on

  Turn the ethernet power on


 cctl clkset1

  Display the value of the syscon register clkset1 and decode and
  display the various fields. A comment section is displayed showing 
  the resultant system clock frequencies that are generated.

 cctl clkset1=0x02b4fa5

  decode and display the fields of this clkset1 value, but do not
  change the value of the system.

 cctl -w clkset1=0x02b4fa5a

  set the clkset1 register to the given value and display the values of 
  the fields - this changes the clock settings. This clkset1 value
  is the default value used with early TS7200 with the EP9301 running
  at a CPU clock of 166MHz and a memory clock of 66MHz

 cctl -w clkset1=0x02a4bb36

  Is I believe the default value for EP9302 cpus running at a CPU clock
  of 200MHz and a memory clock of 100MHz

 cctl -w clkset1=0x0296fa5a

  sets a CPU clock speed, and memory clock of 41.5MHz. I found this the 
  lowest value that the ethernet interface would work at. I'd suggest
  turning off eth0 and the physical interface if reducing the CPU/Mem
  clock lower than this. This gave me a measured reduction in electrical 
  power consumption of 17% on a TS7200 board.

 cctl -w ether=off clkset1=0x0297fa5a

  turns power off to the ether phy, and sets a low CPU & Memory clock 
  of 20.7MHz. This gives a 50% reduction in the boards electrical 
  power requirements, while still having enough processing power
  to do non-intensive jobs etc. It's still useful!

 cctl clkset1.pll1_ps=2

  would show the effect of just changing that field to 2 keeping all
  other values the same. Using the -w flag would implement that change
  on the CPU.
 


BUGS:

Of course! This is beta s/w knocked together in my free time (precious
little).

Let me know if you use this software.  Any bugs, questions,
suggestions or problems, etc. should be sent to

Jim Jackson   <jj@franjam.org.uk>
