readme

Sigma SMP8634 Mrua v. 2.8.2.0

XPU RTC Testing
===============

The SMP8634 contains a battery-backed hardware clock register.  The
hardware register is a 32-bit value that rolls seconds since the UNIX
epoch, January 1st 1970.

System and Application engineers can use the xpurtc_timer application and
rmxpurtcapi library to access the hardware clock directly through the
rmxpurtc xtask library.

xpurtc_timer
------------

The xpurtc_timer code exposes the functions of the RTC clock to the CPU 
and shell scripting with this sample application.  The API has 4 main
operations to perform on the clock.

	1. get, retreives the time from the XPU clock register
	2. query, prints the value of the 'valid' bit in the XPU clock register
	3. restore, copies the time from the battery backed register to the XPU
	   exposed register(required after reboot!).
	4. set, writes a time to the XPU clock register

To print out the time from the XPU clock register:

	# ./xpurtc_time --get
	XPU RTC time is: -1

This means the clock is in an unset state.  Either the time has never been
set or the battery backed clock regsiter has not been written to the XPU
clock register after reboot.

To query the clock to see if it has been set in the past:

	# ./xpurtc_time --query
	xpurtc state is: VALID

	or possibly

	xpurtc state is: INVALID

This will return the state of the XPU RTC valid bit from the register.  If
the time has been set in the past and reads -1, but the query returns VALID,
this means the battery backed up register has not been copied to the XPU
register.  See the --restore command.

To restore the clock value from the battery register after a power cycle:

	# ./xpurtc_time --restore

There is no feedback that will indicate if there was valid data in the
battery regeister other than the feedback from the --query command or
simply getting the time again.  If there was no battery backed up time
a restore command will have no effect and the XPU register will still
contain -1.

To simply set the time:

	# ./xpurtc_time --set <timestamp>

Where timestamp is UNIX time retreived from another machine.  One can simply
retreive the time from another machine with:

	# date +%s

Sometimes an OEM may want to sync against some external time source.  
Typically this involves a CPU space program like NTP that sets the Linux
software clock.  To sync the XPU clock against this software clock one 
can exectue:

	# ./xpurtc_time --set -1

This will directly read the time out of the system clock and write it to 
the XPU.

Busybox contains a very minimal version of the date program that is 
slightly different from the date normally found on UNIX system.  To set
the system time via date one uses:

	# date -s <time string>

The time string is a bit unusual, in that it is not anything printed out
by default on normal systems.  It accepts the format that is created by
this date string on a normal UNIX system:

	 # date +%2m%2d%2H%2M%Y
	 050312432000

One can the use this date in the previous date command to set the system
time on the board.  And subsequently use the xpurtc_time program to
write this stamp to the XPU clock.

Security Concerns
-----------------

There is a voluntary challenge-authentication algorithm that DRM's use to
validate secure time stamps.  See the README in teh rmxpurtc SDK for more
information.

The example xpurtc xtask does not perform authentication by default, and
is not required by OEMs to implement.  Other DRM's running on their system
may still obey the system and cause undefined behavior by the xpurtc clock
writing over their timestamps.  OEM's should take care in order respect
the time stamps of other DRMs and implement their challenge-authenticaiton
for the xtask accordingly.