Changes between Initial Version and Version 1 of gsc


Ignore:
Timestamp:
10/22/2017 05:28:45 AM (5 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • gsc

    v1 v1  
     1[[PageOutline]]
     2
     3
     4= Gateworks System Controller (GSC) =
     5The '''Gateworks System Controller''' (GSC) is a device present across various Gateworks product families that provides a set of system related feature such as the following (refer to the board hardware user manuals to see what features below are present):
     6 * [wiki:gsc#RealTimeClock Real Time Clock (RTC)]
     7 * [wiki:gsc#SystemTemperatureandVoltageMonitor System voltage/temperature monitoring]
     8 * [wiki:gsc#FanController Software controllable Fan controller (6 temperature setpoints)]
     9 * [wiki:gsc#GeneralPurposeInputandOutputGPIO General Purpose Input / Output (GPIO) expansion]
     10 * [wiki:gsc#UserPushbutton Software Configurable User Push-Button]
     11 * [wiki:gsc#EEPROMstorage EEPROM storage]
     12 * [wiki:gsc#HardwareSleepandWake Software Configurable Deep Sleep with RTC Wakeup]
     13 * [wiki:gsc#AlternateBootDevice Alternate Boot device selection and auto-selection]
     14 * [wiki:gsc#TamperDetection Tamper detection]
     15 * [wiki:gsc#GPSActiveAntennashort-circuitauto-detectandrecover GPS Active Antenna short-circuit auto-detect and recover]
     16 * [wiki:gsc#HardwareWatchdog Hardware Watchdog]
     17 * [wiki:gsc#GSCUpdates Software field-upgradable firmware]
     18
     19
     20The GSC communicates with the host CPU over the i2c bus and uses the following 7-bit i2c slave addresses:
     21 * 0x20 - GSC configuration registers
     22 * 0x21 - GSC software update registers
     23 * 0x23 - PCA9555 emulated I/O (common industry standard GPIO port expander)
     24 * 0x29 - system monitor (similar to industry standard AD7418 but with modified register set - see below)
     25 * 0x50 - 24c04 emulated EEPROM (256B) (common industry standard EEPROM device)
     26 * 0x51 - 24c04 emulated 256 byte EEPROM (common industry standard EEPROM device)
     27 * 0x52 - 24c04 emulated 256 byte EEPROM (common industry standard EEPROM device) (some models only)
     28 * 0x53 - 24c04 emulated 256 byte EEPROM (common industry standard EEPROM device) (some models only)
     29 * 0x68 - DS1672 emulated RTC (common industry standard device)
     30
     31[[Image(gateworksgsc.png,400px)]]
     32
     33
     34[=#rtc]
     35== Real Time Clock ==
     36The GSC contains a Real Time Clock (RTC) which emulates a Dallas Semiconductor DS1672, or equivalent. The RTC is battery backed to retain time information when SBC power is removed. The I2C address for the RTC is 0x68h. The RTC is compatible with the standard Linux ds1672 RTC driver and thus works with the standard Linux RTC device API documented [http://www.kernel.org/doc/Documentation/rtc.txt here]. The RTC device will be {{{/dev/rtc0}}} and adheres to the standard ioctl and sysfs API's.
     37
     38The most common Linux RTC commands are (refer to the linux man pages for more info on the commands and the available time/date formats):
     39 * Write System Time and Date from Console:
     40{{{
     41#!bash
     42date #time and date you would like to write
     43}}}
     44 * Write Real Time Clock Time and Date from System Time:
     45{{{
     46#!bash
     47hwclock -w
     48}}}
     49 * Read Time and Date from System Time:
     50{{{
     51#!bash
     52date
     53}}}
     54 * Read Time and Date from Real Time Clock:
     55{{{
     56#!bash
     57hwclock -r
     58}}}
     59
     60 * '''Example: Set the system time to a specific date, then set the RTC from that date, then read the RTC:'''
     61{{{
     62#!bash
     63> date -s 201303041744.42
     64Mon Mar  4 17:44:42 UTC 2013
     65> hwclock -w
     66> hwclock -r
     67Mon Mar  4 17:44:47 2013  0.000000 seconds
     68}}}
     69
     70Note that typical Linux based systems use a Real Time Clock as such:
     71 * on system boot, the hardware clock (RTC) sets the time of the system clock (the system clock ticks based on the CPU's timer). This is typically done in an init script using {{{hwclock}}} but sometimes can be done from an RTC kernel driver (which is the case for the GSC RTC supported by the ds1672 driver - upon driver init, the system time will be set from the GSC RTC)
     72 * a Network Time Protocol (NTP) client runs in the background and periodically updates the system clock (not the hardware RTC) based on the time of an Internet Time Server
     73 * on system shutdown (ie, a 'clean' or 'user prompted' shutdown) the system will set the RTC value from the system clock (because it is assumed that a system clock sync'd with an Internet Time Server is more accurate than an RTC). This is typically done in a shutdown init script.
     74 * Note that none of the above may be typical of an Embedded Linux OS
     75
     76[=#hwmon]
     77== System Temperature and Voltage Monitor ==
     78The GSC implements system voltage and temperature monitoring (similar to industry standard AD7418) at i2c slave address 0x29. For each analog to digital converter (ADC) input, the value can be read at a register offset. A single temperature sensor provides the board temperature in a 16-bit value (LSB first, MSB second) at register offset 0x00 in degrees Celcius. The voltage based ADC inputs provides a voltage (millivolt) as a 24-bit value (LSB first, MSB last). The ADC measurements are performed once per second (1Hz).
     79
     80The following table shows the set of registers supported (Note each board supports a subset of these - an unsupported {source} will return a full-scale reading of 16,777,215)
     81
     82system monitor registers:
     83||= Name =||= Register =||= Parameter =||= Units =||= Description =||
     84|| temp1       || 0x00           || Temperature   || Deg C/10    || SBC Temperature   ||
     85|| vin         || 0x02           || Voltage       || Volts/1000  || SBC Input Voltage ||
     86|| 3p3         || 0x05           || Voltage       || Volts/1000  || 3.3V                            ||
     87|| bat         || 0x08           || Voltage       || Volts/1000  || GSC Coin Cell Battery           ||
     88|| 5p0         || 0x0B           || Voltage       || Volts/1000  || 5.0V                            ||
     89|| core        || 0x0E           || Voltage       || Volts/1000  || Primary Processor Core          ||
     90|| cpu1        || 0x11           || Voltage       || Volts/1000  || Primary Processor 1 Operating   ||
     91|| cpu2        || 0x14           || Voltage       || Volts/1000  || Primary Processor 2 Operating   ||
     92|| dram        || 0x17           || Voltage       || Volts/1000  || System DRAM Memory              ||
     93|| ext_bat     || 0x1A           || Voltage       || Volts/1000  || GSC External Battery (not in use) ||
     94|| io1         || 0x1D           || Voltage       || Volts/1000  || Miscellaneous                   ||
     95|| io2         || 0x20           || Voltage       || Volts/1000  || Miscellaneous                   ||
     96|| pcie        || 0x23           || Voltage       || Volts/1000  || PCI Express                     ||
     97|| io3         || 0x26           || Voltage       || Volts/1000  || Miscellaneous                   ||
     98|| io4         || 0x29           || Voltage       || Volts/1000  || Miscellaneous                   ||
     99|| fan0_point0 || 0x2C           || Temperature   || Deg C/10    || Fan controller set point 0      ||
     100|| fan0_point1 || 0x2E           || Temperature   || Deg C/10    || Fan controller set point 1      ||
     101|| fan0_point2 || 0x30           || Temperature   || Deg C/10    || Fan controller set point 2      ||
     102|| fan0_point3 || 0x32           || Temperature   || Deg C/10    || Fan controller set point 3      ||
     103|| fan0_point4 || 0x34           || Temperature   || Deg C/10    || Fan controller set point 4      ||
     104|| fan0_point5 || 0x36           || Temperature   || Deg C/10    || Fan controller set point 5      ||
     105
     106 * Note that bat rail cannot be measured until board power is turned off for one second or more. When power is off, we monitor the bat voltage every 9 hours. When the board is fully powered on and booted into Linux, the bat reading cannot be continually updated and reports the last read voltage when the board was powered off.
     107 * Note that the above descriptions are board-specific. Please see the board [http://www.gateworks.com/usermanuals Hardware User Manual] 'System Temperature and Voltage Monitor' section for details.
     108
     109A Linux 'Hardware Monitor' ({{{hwmon}}}) driver is available in OpenWrt which provides simple standard access to the above temperature/voltage registers via sysfs.  The arguments have been given labels which define the source. The user can “cat” the label to determine the source. See the following examples listed below.
     110
     111* Read board Input Voltage:
     112{{{#!bash
     113DIR=$(find /sys/bus/i2c/devices/0-0029/ -name in0_input)
     114DIR=${DIR%/*}
     115cat $DIR/in0_label
     116cat $DIR/in0_input
     117}}}
     118
     119* Output a list of all sources and their values:
     120{{{#!bash
     121# DIR=$(find /sys/bus/i2c/devices/0-0029/ -name in0_input)
     122# DIR=${DIR%/*}
     123# cd $DIR
     124# for F in *;do echo -n “$F: “;cat $F;done
     125 fan0_point0: 300
     126 fan0_point1: 330
     127 fan0_point2: 360
     128 fan0_point3: 390
     129 fan0_point4: 420
     130 fan0_point5: 450
     131 in0_input: 23569
     132 in0_label: vin
     133 in10_input: 16777215
     134 in10_label: io2
     135 in11_input: 1505
     136 in11_label: pci2
     137 in12_input: 16777215
     138 in12_label: current
     139 in1_input: 3395
     140 in1_label: 3p3
     141 in2_input: 3403
     142 in2_label: bat //coincell battery
     143 in3_input: 4836
     144 in3_label: 5p0
     145 in4_input: 1237
     146 in4_label: core
     147 in5_input: 16777215
     148 in5_label: cpu1
     149 in6_input: 16777215
     150 in6_label: cpu2
     151 in7_input: 1802
     152 in7_label: dram
     153 in8_input: 16777215
     154 in8_label: ext_bat //not currently in use
     155 in9_input: 2466
     156 in9_label: io1
     157 temp0_input: 442
     158 temp0_label: temp
     159}}}
     160 - Note 16777215 indicates a default value and item is not connected.
     161
     162
     163For Ventana i.MX6 processor temperature, see [wiki:ventana/thermal here]
     164
     165[=#fan]
     166== Fan Controller ==
     167'''*Note: This feature is only on certain baseboards. Please consult the hardware manual.'''
     168
     169A pulse width modulated (PWM) fan controller is supported by some boards. The GSC controller allows the fan speed to be varied based upon temperature to help reduce bearing wear and extend fan lifetime. The fan controller contains six temperature set points which correspond to duty cycles ranging from 50 to 100 percent (fully on). See the below chart for the PWM duty cycle versus temperature set points.
     170
     171'''*Note: typically the PWM occurs on the ground pin, and the 5V is constant. However, consult the hardware manual to determine if your board uses that configuration.'''
     172
     173||= Source =||= Default (°C/10) =||= Description =||
     174|| Fan0_point0  || 300                   || Set point 0 = 50% PWM duty cycle  ||
     175|| Fan0_point1  || 330                   || Set point 1 = 60% PWM duty cycle  ||
     176|| Fan0_point2  || 360                   || Set point 2 = 70% PWM duty cycle  ||
     177|| Fan0_point3  || 390                   || Set point 3 = 80% PWM duty cycle  ||
     178|| Fan0_point4  || 420                   || Set point 4 = 90% PWM duty cycle  ||
     179|| fan0_point5  || 450                   || Set point 5 = 100% PWM duty cycle ||
     180
     181* Note - The set point value represents temperature in °C/10 (only positive values allowed).
     182
     183The fan controller temperature set points can be found in the {{{/sys/class/hwmon}}} directory along with the temperature and voltage monitor information (see previous section). The following examples show reading and writing to the fan set point register.
     184
     185
     186The fan controller setpoints are supported via the standard linux Hardware Monitor ({{{hwmon}}}) driver in the OpenWrt BSP.  Some examples of configuration are:
     187 * Read temperature set-point 0:
     188{{{#!bash
     189DIR=$(find /sys/bus/i2c/devices/0-0029/ -name in0_input)
     190DIR=${DIR%/*}
     191# cat $DIR/fan0_point0 # read set point - default 30C
     192300
     193}}}
     194 * Set temperature set-point 0:
     195{{{#!bash
     196DIR=$(find /sys/bus/i2c/devices/0-0029/ -name in0_input)
     197DIR=${DIR%/*}
     198echo 350 > $DIR/fan0_point0 # set to 35C
     199}}}
     200
     201=== Always-on FAN for a constant voltage source ===
     202Occasionally users want to keep the FAN controller always-on in order to provide a constant voltage source.
     203
     204To achieve a constant 5 volts for general use, it is possible to set the 100% PWM duty cycle fan point (fan0_point5) to 0. Because the fan controller does not accept negative temperatures, this means it will always be on while the temperature is greater than 0C (or negative as the fan controller does not accept negative temperatures).
     205
     206Examples:
     207 * FAN output always on 100% duty cycle (constant 5V):
     208{{{#!bash
     209DIR=$(find /sys/bus/i2c/devices/0-0029/ -name in0_input)
     210DIR=${DIR%/*}
     211echo 0 > $DIR/fan0_point5; set to 0C
     212}}}
     213
     214
     215[=#gpio]
     216== General Purpose Input and Output (GPIO) ==
     217The GSC contains a General Purpose Input and Output (GPIO) port expander which emulates a Texas Instruments PCA9555, or equivalent. The Gateworks board support package maps the PCA9555 GPIO base number to 100 by default (Though this may vary). The functionality supports setting each GPIO signal as an input or output with read-back. For more information on the PCA9555 see the [http://dev.gateworks.com/datasheets/PCA9555.pdf PCA9555 Datasheet]. The I2C address for the PCA9555 is 0x23h.
     218
     219Each board level product has a unique GPIO configuration. Refer to the specific board hardware user manual for more details.
     220
     221The most common Linux GPIO commands are:
     222 * Determine GPIO configuration and settings:
     223{{{
     224#!bash
     225cat /sys/kernel/debug/gpio
     226}}}
     227 * Configure GPIO 'n' as Input:
     228{{{
     229#!bash
     230echo in > /sys/class/gpio/gpio<n>/direction
     231}}}
     232 * Configure GPIO 'n' as Output:
     233{{{
     234#!bash
     235echo out > /sys/class/gpio/gpio<n>/direction
     236}}}
     237 * Read Input GPIO 'n':
     238{{{
     239#!bash
     240cat /sys/class/gpio/gpio<n>/value
     241}}}
     242 * Write Output GPIO 'n' to Logical 1:
     243{{{
     244#!bash
     245echo 1 > /sys/class/gpio/gpio<n>/value
     246}}}
     247 * Write Output GPIO 'n' to Logical 0:
     248{{{
     249#!bash
     250echo 0 > /sys/class/gpio/gpio<n>/value
     251}}}
     252
     253Note that some boards route several GSC based GPIO's to various off-board connectors for use as general purpose digital I/O (DIO) or tamper switch circuits. As such, these ports are configured as inputs by default and if unconnected (un-terminated electrically) can cause spurious IRQ_GPIO_CHANGE interrupt events when enabled. This is typically the case with an unused tamper circuit.
     254
     255To avoid spurious interrupts if you have un-terminated GPIO's configure them as outputs. Note that the GSC will not allow a dedicated input GPIO to be set as an output so there is no harm in just setting all to outputs as long as you don't have one of them connected to a circuit off-board that will cause undesired effects if driven high or low.
     256
     257For example to set all P0 and P1 bits as outputs from Linux:
     258{{{
     259#!bash
     260i2cset -f -y 0 0x23 6 0x00 # configure GPIO P0_DIR as outputs
     261i2cset -f -y 0 0x23 7 0x00 # configure GPIO P1_DIR as outputs
     262}}}
     263
     264See also:
     265 * [wiki:OpenWrt/gpio OpenWrt GPIO]
     266 * [wiki:gpio GPIO]
     267
     268[=#pushbutton]
     269== User Pushbutton ==
     270The GSC offers software controllable user pushbutton configuration. The GSC can be configured to perform a hardware function or raise a host CPU interrupt on certain configurations:
     271 * hardware reset (1x quick press-and-release) - '''default configuration'''
     272 * software interrupt on state change (!r30 firmware and above)
     273 * software interrupt on long (>700ms) press-and-hold
     274 * erase security key EEPROM on 3x quick press-and-release
     275 * reset board and boot from alternate boot device on 5x quick press-and-release (for boards that have an alternate boot device)
     276
     277The default configuration of the GSC is to perform a hard reset on a quick press-and-release. To change this you need to set the [#gsc_ctrl_0 CTRL_0] register. For example:
     278 * enable all button events
     279{{{
     280#!bash
     281i2cset -f -y 0 0x20 0 0x00 # disable pushbutton hard reset
     282i2cset -f -y 0 0x20 11 0xff # enable all interrupts
     283}}}
     284  * please see [#IRQ_GPIO_CHANGE here] regarding un-terminated inputs causing spurious GPIO_CHANGE events
     285
     286The [#inputdriver gsc-input kernel driver] will produce Linux Input events for the above interrupts.
     287
     288In addition, the user pushbutton state is available on a GPIO in case you need to do anything more flexible than the above built-in interrupt functionality:
     289||= Family =||= Boards             =||= gsc gpio =||= linux gpio =||
     290|| Ventana  || GW5xxx               || i2c/0-0023 pca9555 gpio0 || gpio240 ||
     291|| Laguna   || GW2380/GW2382/GW2383 || i2c/0-0023 pca9555 gpio8 || gpio108 ||
     292|| Laguna   || GW2387/GW2388/GW2391 || i2c/0-0023 pca9555 gpio0 || gpio100 ||
     293
     294An example of when you would want to use the pushbutton gpio is if you want to do something like determine if the user pushbutton has been held for a certain amount of time. This type of event is not available via the GSC interrupts and thus the [#inputdriver gsc-input kernel driver] because it involves starting a timer on a button-down event and counting the time expired before any button-up event occurs.
     295
     296The Linux kernel gpio-keys and gpio-keys-polled (and OpenWrt [wiki:OpenWrt/gpio#button-hotplug-gw gpio-button-hotplug]) drivers can be used to create Linux Input events from pushbuttons connected to GPIO's however if you want this functionality, you can use the gsc-input driver which is already enabled in the Gateworks BSP's. Note that the gpio-keys/gpio-keys-polled/gpio-button-hotplug drivers use the pushbutton gpio in a kernel driver therefore you can not export the gpio to userspace, where-as the gsc-input driver uses GSC interrupts for its information and therefore does not take control over the gpio.
     297
     298BSP Specific Notes:
     299 * OpenWrt:
     300  - the [#inputdriver gsc-input kernel driver] can be used to catch the built-in interrupts which can be produced by various pushbutton events
     301  - the [wiki:OpenWrt/gpio#button-hotplug-gw gpio-button-hotplug] driver is enabled uses the pushbutton GPIO therefore it must be disabled if you want to export it for userspace access. Most likely you can get the functionality you need by using the [=#button-hotplug-gw OpenWrt button-hotplug-gw] package.
     302   - The [wiki:OpenWrt/gpio#button-hotplug-gw gpio-button-hotplug] out-of-tree driver is an OpenWrt custom driver that takes the place of the in-kernel gpio-keys (KEYBOARD_GPIO) and gpio_keys_polled (KEYBOARD_GPIO_POLLED) drivers and instead of emiting linux input events it emits uevent messages to the button subsystem which tie into the OpenWrt hotplug daemon.
     303   - Note that for Ventana this uses the gpio_keys device-tree node to map gpio-240 to the 'user_pb' button event.
     304   - to disable this driver to be able to export the pushbutton gpio either by removing the device-tree node (Ventana only) or by disabling KEYBOARD_GPIO/KEYBOARD_GPIO_POLLED drivers in the OpenWrt kernel config.
     305   - The only real benefit of using your own program to monitor the pushbutton gpio over the OpenWrt hotplug method is that you can catch 'held' events without waiting for a button release because the [wiki:OpenWrt/gpio#button-hotplug-gw gpio-button-hotplug] OpenWrt driver only catchings button down and up events (it does not fire off a timer on a button down event and periodically emit hotplug events as the button is still held down)
     306  - see [wiki:OpenWrt/gpio OpenWrt GPIO] for more info on how to use GPIO's as buttons in OpenWrt
     307  - see also http://wiki.openwrt.org/doc/howto/hardware.button
     308 * Yocto:
     309  - the [#inputdriver gsc-input kernel driver] can be used to catch the built-in interrupts which can be produced by various pushbutton events
     310 * Android:
     311  - the [#inputdriver gsc-input kernel driver] can be used to catch the built-in interrupts which can be produced by various pushbutton events. There is also a key-layout file that maps these events to Android keys.
     312
     313In Summary you have a few options for performing actions based on user pushbutton events depending on your needs and BSP.
     314
     315See also:
     316 [#gsc-interrupts gsc-interrupts]
     317
     318
     319=== Code Examples for software user pushbutton detection ===
     320The following example will configure the GSC for SW pushbutton interrupt and read the PB state by polling the GPIO (see above):
     321{{{
     322#!bash
     323# clear R0.1 bit to disable pushbutton hard reset - taking care to not disturb other bits
     324R0=$(i2cget -f -y 0 0x20 0) && \
     325  R0=$((R0 & ~0x01)) && \
     326  i2cset -f -y 0 0x20 0 $R0 || echo i2c error
     327# export gpio240 to userspace (Note this value is board specific - see above table)
     328echo 240 > /sys/class/gpio/export
     329while [ 1 ]; do
     330  cat /sys/class/gpio/gpio240/value ;# PB state 0 or 1
     331done
     332}}}
     333
     334A more appropriate method of detection may be to use the fact that the GSC has interrupt support and use the libc {{{poll(2)}}} function to block on the GPIO until it changes state. See [wiki:gpio#catchingagpiochangefromuserspacewithoutpolling Catching a GPIO from Userspace w/o polling] for an example of how to do that.
     335
     336See also:
     337 * [wiki:gpio#catchingagpiochangefromuserspacewithoutpolling Catching a GPIO from Userspace w/o polling]
     338 * [wiki:ventana/DigitalIO]
     339
     340[=#eeprom]
     341== EEPROM storage ==
     342The GSC emulates Atmel 24C04 EEPROM storage devices, or equivalent. The EEPROM functionality supports 4Kbits (512bytes) partitioned as shown below. The EEPROM is supported in Linux. The 7-bit I2C base address is 0x50.
     343
     344||= Address    =||= Device Address =||= Size (bytes) =||= Function                  =||
     345|| 0x000-0x0FF  || 0x50: 0x00-0xFF  || 256            || User EEPROM space           ||
     346|| 0x100-0x17f  || 0x51: 0x00-0x7F  || 128            || '''Board Info''' EEPROM ^1^ ||
     347|| 0x180-0x1DF  || 0x51: 0x80-0xDF  || 96             || '''Secure Key''' EEPROM ^2^ ||
     348|| 0x1E0-0x1FF  || 0x51: 0xE0-0xFF  || 32             || Reserved                    ||
     349|| 0x200-0x2FF  || 0x52: 0x00-0xFF  || 256            || User EEPROM space ^3^       ||
     350|| 0x300-0x3FF  || 0x53: 0x00-0xFF  || 256            || User EEPROM space ^3^       ||
     351 1. ''Board Info'' EEPROM is reserved for Gateworks
     352  * can be ''write protected'' by enabling EEPROM_WP_BOARD_INFO (R1.4)
     353  * Information about board serialnum, model, manufacturing date, etc can be found in the EEPROM - see [wiki:modelserialnumber here] for details
     354 2. ''Secure Key'' EEPROM is erased if:
     355  * pushbutton is activated 3 times in quick succession (press-and-released <700ms delay between each activation). This function is enabled with R0.1
     356  * Tamper circuit has been activated (for boards supporting a tamper switch/header)
     357  * The GSC battery is depleted or is removed for more than 10 seconds
     358  * Note that these cases will always erase the ''Secure Key'' EEPROM region regardless of the ''Write Protect'' bits
     359 3. additional 4Kbits (512bytes) available on GW2387/GW2388/GW2391)
     360 4. There are 2 bits in R1 (GSC_CTRL_1) which act as a ''Write Protect'' for EEPROM regions:
     361  * EEPROM_WP_ALL (R1.3) will dissalow user i2c writes to all EEPROM regions (does not affect ''secure key'' erasure cases)
     362  * EEPROM_WP_BOARDINFO (R1.4) will dissallow user i2c writes to the ''Board Info'' EEPROM region
     363
     364=== EEPROM Secure Key Example ===
     365The secure key is stored between 0x80 and 0xDF. This is 96 bytes long.
     366
     367To see the secure key, you can use the command i2cdump from the command line: (starts with the ASCII values of D3 and ends with w in below example)
     368{{{
     369#!bash
     370> i2cdump -f -y 0 0x51
     371No size specified (using byte-data access)
     372
     373<<--------------- HEX GRID --------------------->>     << ASCII VALUE>>
     374     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f    0123456789abcdef
     37500: 00 d0 12 a9 ef f8 00 d0 12 a9 ef f9 ff ff ff ff    .?????.?????....
     37610: ff ff ff ff ff ff ff ff cb 5b 09 00 ff ff ff ff    ........?[?.....
     37720: 11 27 20 13 ff ff ff ff ff ff ff 05 0c 02 18 08    ?' ?.......?????
     37830: 47 57 35 32 30 30 2d 53 50 32 38 33 2d 41 00 00    GW5200-SP283-A..
     37940: 06 00 b5 4d 33 f0 01 00 c9 00 00 00 00 00 25 d0    ?.?M3??.?.....%?
     38050: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     38160: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     38270: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     38380: 44 33 ff ff ff ff ff ff ff ff ff ff ff ff ff ff    D3..............
     38490: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     385a0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     386b0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     387c0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     388d0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff 77    ...............w
     389e0: XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX    XXXXXXXXXXXXXXXX
     390f0: XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX    XXXXXXXXXXXXXXXX
     391}}}
     392
     393To set the bytes from the command line, use a i2cset command. This example shows us writing a 0x3344 of size w (word, 2 bytes) at the beginning of the Secure Key storage at 0x80. The 0x51 is the i2c device address which will remain the same as according to the above information.
     394{{{
     395#!bash
     396i2cset -f -y 0 0x51 0x80 0x3344 w
     397}}}
     398
     399To Write a single byte:
     400{{{
     401#!bash
     402i2cset -f -y 0 0x51 0x80 0x33
     403}}}
     404
     405=== Custom Serial Number Example ===
     406For customers who need to add their own serial number, they can write it in the userspace EEPROM space at address 0x50 as shown in the table above.
     407
     408Here, a customer specific serial number is created in the userspace EEPROM. For example using the first 6 bytes of userspace EEPROM to store a 6digit serial number in ascii representation:
     409{{{
     410#!bash
     411i2cset -f -y 0 0x50 0x0 0x3535 w
     412i2cset -f -y 0 0x50 0x2 0x3737 w
     413i2cset -f -y 0 0x50 0x4 0x3939 w
     414}}}
     415
     416Then, a {{{i2cdump}}} will show the serial number stored:
     417{{{
     418#!bash
     419> i2cdump -f -y 0 0x50
     420No size specified (using byte-data access)
     421     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f    0123456789abcdef
     42200: 35 35 37 37 39 39 ff ff ff ff ff ff ff ff ff ff    557799..........
     42310: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     42420: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     42530: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     42640: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     42750: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     42860: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     42970: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     43080: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     43190: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     432a0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     433b0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     434c0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     435d0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     436e0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     437f0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
     438}}}
     439
     440To retrieve it, use the {{{i2cget}}} command:
     441{{{
     442#!bash
     443> i2cget -f -y 0 0x50 0x0 w
     4440x3535
     445}}}
     446
     447
     448[=#powercontrol]
     449== Hardware Sleep and Wake ==
     450The GSC has the ability (on the Laguna & Ventana product family) has the ability to put the board into a 'Hardware Sleep' mode by disabling the primary power supply. This is very useful in many applications that do not require 24 hour operation and need to save power. In this mode the only item drawing power is the GSC itself (powered by a coin-cell battery). The GSC will 'wake' the board again by enabling the primary power supply when the RTC reaches the time defined in the GSC_SLEEP_WAKE register. The wakeup time can be set to an absolute RTC time by writing to GSC_SLEEP_WAKE or be set relative to the current RTC value by setting the GSC_SLEEP_ADD register and latching it via setting R1.2.
     451
     452A pushbutton press will also wake the board unless the SLEEP_NOWAKEPB (R1.3) is enabled.
     453
     454 * '''NOTE''' : If performing sleep without a coin cell battery, a maximum of 4 seconds should be used for resetting the board. Anything longer may put the board to 'sleep' and not allow it to wake up without pressing the pushbutton or unplugging and plugging in the main power supply.
     455
     456==== Board sleeping Example ====
     457The preferred method is to use the sysfs powerdown hook from the GSC driver as this takes care of the math and retries for you:
     458 * Using the gsc-driver:
     459{{{
     460#!bash
     461echo 300 > /sys/bus/i2c/devices/0-0020/powerdown # sleep for 5 mins
     462}}}
     463* Manually writing to GSC (if you don't have the GSC driver)
     464The following example will sleep the board for 10 seconds by setting the “add timer” to 10 seconds (from the current time) and then putting the board to sleep. This example uses the Linux I2C utilities.
     465{{{
     466#!bash
     467SECS=300 ;# 5 mins
     468i2cset -f -y 0 0x20 6 $((SECS % 256)); SECS=$((SECS >> 8))
     469i2cset -f -y 0 0x20 7 $((SECS % 256)); SECS=$((SECS >> 8))
     470i2cset -f -y 0 0x20 8 $((SECS % 256)); SECS=$((SECS >> 8))
     471i2cset -f -y 0 0x20 9 $((SECS % 256))
     472# set add time bit - taking care to not disturb other bits
     473R1=$(i2cget -f -y 0 0x20 1) && \
     474  R1=$((R1 | 0x04)) && \
     475  i2cset -f -y 0 0x20 1 $R1 || echo i2c error
     476# set sleep enable and sleep activate bits - taking care not to disturb other bits
     477R1=$(i2cget -f -y 0 0x20 1) && \
     478  R1=$((R1 | 0x03)) && \
     479  i2cset -f -y 0 0x20 1 $R1 || echo i2c error
     480}}}
     481
     482The board will go to sleep and then wake up after 5 minutes (300secs). If you wanted the board to wakeup at a specific date/time regardless of the current RTC date/time you could set R2-5 to the number of seconds since the epoch (date +%s will show current system time in seconds) instead of using the R6-R9 'relative time' registers.
     483
     484=== GSC Reboot ===
     485The GSC can also be used to reboot the board. See the following link for more info:
     486 * [wiki:gscreboot Safe GSCReboot Script]
     487
     488[=#altbootdevice]
     489== Alternate Boot Device ==
     490Some Gateworks Laguna family products (GW2388) have an ''Alternate boot device'' that can be used for alternate firmware images, such as a flash recovery image. There are 2 ways that you can instruct the GSC to boot to the alternate boot device vs the primary boot device:
     491 1. Press-and-release the user pushbutton 5 times in quick succession (see R0.3 (PB_BOOT_ALTERNATE) below)
     492 2. Use the 'Auto Switch Boot' feature
     493
     494More details on using the Alternate Boot Device can be found [wiki:gsc/alternate_boot_device here].
     495
     496=== Auto Switch Boot Device ===
     497If the board is equipped with an ''Alternate Boot Device'' you can enable the GSC's ''Auto Switch Boot'' feature by setting R1.6 (SWITCH_BOOT_ENABLE). When a board powers on with this bit set, the watchdog timer will be set for a 30 second timeout when the board is powered on. If this timer expires the GSC will toggle the boot device and power-cycle the board. You can disable the timer for the current boot by setting R1.7 (SWITCH_BOOT_CLEAR) (it will be re-armed on the next power cycle in SWITCH_BOOT_ENABLE has not been cleared).
     498
     499For example, if you a supporting firmware updates in your product but want a mechanism to ensure a power loss or other event during a firmware update does not render your device recoverable you can enable this feature and put a 'recovery image' on the alternate boot device.  In this example both firmware images (the primary and the alternate) should set R1.7 within 30 seconds of bootup if that firmware image is desirable.  If either image fails to set R1.7 within the 30 seconds, the board will automatically boot to the other device.
     500
     501More details on using the Auto Switch Boot Device can be found [wiki:gsc/alternate_boot_device here].
     502
     503[=#tamper]
     504== Tamper Detection ==
     505Some boards have a ''Tamper Detect'' circuit implemented either as a physical pushbutton on the board and/or a header that can have an external switch wired to it. The circuit implemented is a ''normally open'' switch to board ground (GND).
     506
     507For these boards you can enable the GSC's ''Tamper Detect'' feature by setting bit R0.5 (TAMPER_DETECT) and the accompanying interrupt register bit R11.5 (IRQ_TAMPER_DETECT). Once these bits are set any tamper event produced by a switch closing and the signal conducting to board ground will do the following:
     508 1. set IRQ_TAMPER_DETECT interrupt source bit
     509 2. erase the '''secure key''' EEPROM section
     510 3. produce a GSC interrupt (if board is powered)
     511
     512* ''' Note: Ventana models may require a modification for this feature, please contact factory at support@gateworks.com'''
     513
     514See also:
     515 [#gsc-interrupts gsc-interrupts]
     516
     517[=#activegpsantenna]
     518== GPS Active Antenna short-circuit auto-detect and recover ==
     519On some Gateworks products, the Active GPS Antenna has a short-circuit detection circuit that will disable the antenna power if an excessive current draw is detected (ie a short). On some of these products, the GSC will re-enable the antenna power every second in case the short has been removed or replaced. The reason for this protection is two-fold:
     520 1. over-current protection keeps board power available if an antenna short/fault has occurred
     521 2. a shorted/faulty antenna can be replaced without having to power down the board
     522
     523Products with GPS antenna protection (GPS is not loaded on all model variants, contact sales@gateworks.com for details):
     524||= Family =||= Board =||= Overcurrent Protection =||= Recovery =||
     525|| Ventana  || GW51XX  || Current Limit            || No         ||
     526|| Ventana  || GW52XX  || Current Limit            || No         ||
     527|| Ventana  || GW53XX  || Yes                      || Yes        ||
     528|| Ventana  || GW54XX  || Yes                      || Yes        ||
     529|| Laguna   || GW2387  || Yes                      || Yes        ||
     530|| Laguna   || GW2391  || Yes                      || Yes        ||
     531
     532[=#gsc-interrupts]
     533== GSC Interrupts ==
     534The Gateworks System Controller has an interrupt signal to the host processor which it asserts when an event has occurred worth notifying the host about. The GSC_INTERRUPT_ENABLE register defines what events can trigger an interrupt and an interrupt service routine can query the GSC_INTERRUPT_STATUS register to see what events are present. The interrupt remains asserted until all status bits are cleared by writing 0's to those bits in the GSC_INTERRUPT_STATUS register.
     535
     536See also:
     537 * [#gsc_interrupt_status GSC_INTERRUPT_STATUS register]
     538 * [#gsc_interrupt_enable GSC_INTERRUPT_ENABLE register]
     539
     540[=#IRQ_PB]
     541=== IRQ_PB interrupt ===
     542The IRQ_PB interrupt occurs if the user pushbutton has been pressed then released within 700ms thus signifying a quick 'press-and-release' event. Note that the PB_HARD_RESET bit must be cleared in the GSC_CTRL_0 register for this to occur otherwise a pushbutton will cause a hard board reset.
     543
     544See also:
     545 * [#pushbutton pushbutton]
     546
     547[=#IRQ_SWITCH_HOLD]
     548=== IRQ_SWITCH_HOLD interrupt ===
     549The IRQ_SWITCH_HOLD interrupt occurs if SWITCH_HOLD is enabled in the GSC_CTRL_0 register and the user pushbutton was held for over 1 second.
     550
     551See also:
     552 * [#pushbutton pushbutton]
     553
     554[=#IRQ_SECURE_KEY_ERASED]
     555=== IRQ_SECURE_KEY_ERASED interrupt ===
     556The IRQ_SECURE_KEY_ERASED interrupt occurs after the user key EEPROM area has been erased. This can occur because of either a tamper event (see TAMPER_DETECT) or because 3x quick button press-and-release events have occurred (see PB_CLEAR_SECURE_KEY).
     557
     558See also:
     559 * [#pushbutton pushbutton]
     560 * [#eeprom EEPROM]
     561
     562[=#IRQ_EEPROM_WP]
     563=== IRQ_EEPROM_WP interrupt ===
     564The IRQ_EEPROM_WP interrupt occurs if the GSC_EEPROM_WP_ALL or GSC_EEPROM_BOARDINFO bits are set in the GSC_WRITE_PROTECT register and a write protect violation has occurred.
     565
     566See also:
     567 * [#eeprom EEPROM]
     568
     569[=#IRQ_GPIO_CHANGE]
     570=== IRQ_GPIO_CHANGE interrupt ===
     571The IRQ_GPIO_CHANGE interrupt occurs if a GSC GPIO which is configured as an input has changed state. Note that the GSC GPIO controller emulates a PCA9555 chip.
     572
     573Note that this interrupt needs to be enabled if you wish to sense user pushbutton press and release events independently (for example, you are trying to implement your own timing, or using the Linux {{{gpio-keys}}} driver which creates Linux input events from GPIO based buttons).
     574
     575Note that some boards route one or more GSC based GPIO's to various off-board connectors for use as general purpose digital I/O (DIO) or tamper switch circuits. As such, these ports are configured as inputs by default and if unconnected (un-terminated electrically) can cause spurious IRQ_GPIO_CHANGE interrupt events when enabled.
     576
     577To avoid this make sure you configure unused inputs as outputs. Note that the GSC will not allow a dedicated input GPIO to be set as an output so there is no harm in just defaulting all to outputs as long as there are no GPIO's connected to off-board circuits that will cause undesirable affects if drive high or low.
     578
     579For example to set all P0 and P1 bits as outputs from Linux:
     580{{{
     581#!bash
     582i2cset -f -y 0 0x23 6 0x00 # configure GPIO P0_DIR as outputs
     583i2cset -f -y 0 0x23 7 0x00 # configure GPIO P1_DIR as outputs
     584}}}
     585
     586See also:
     587 * [#gpio GPIO]
     588
     589[=#IRQ_TAMPER_DETECT]
     590=== IRQ_TAMPER_DETECT interrupt ===
     591The IRQ_TAMPER_DETECT interrupt occurs if TAMPER_DETECT has been enabled in the GSC_CTRL_0 register and the tamper circuit is broken. Only certain products have one or more tamper circuits. If supported the tamper signals are connected to a normally closed to ground button.
     592
     593See also:
     594 * [#tamper Tamper Detection]
     595
     596[=#IRQ_WDOG_TIMEOUT]
     597=== IRQ_WDOG_TIMEOUT interrupt ===
     598The IRQ_WDOG_TIMEOUT interrupt indicates that the GSC watchdog caused a board level power cycle and as such can't be caught via software (as the board was power cycled) but can be detected at power-on as the reason for reset.
     599
     600Note that the Ventana bootloader reads and clears this status register but displays the result.
     601
     602See also:
     603 * [#watchdog Hardware Watchdog]
     604
     605[=#watchdog]
     606== Hardware Watchdog ==
     607* ''' NOTE: REQUIRES V44 or later of GSC FIRMWARE '''
     608A watchdog is a common feature which allows a timer to be configured such that a reset occurs if that timer expires. A software component will typically enable the watchdog timer and restart it periodically before the timer expires based on some conditions. Usually there is no specific condition so the timer gets restarted (avoiding a system reset) unless the CPU running that software hangs.
     609
     610Systems that want to place more criteria on the condition of restarting the watchdog can do so, such as checking various statistics or states. For example, you may wish to reset the board if the network connection ever goes away.
     611
     612Most modern CPU's have built-in watchdog elements, which will reset the CPU and sometimes drive an external signal which can reset various components on the board. For example, our Laguna products with NOR flash will reset the NOR flash when a watchdog reset occurs because we have found that without doing so the processor can hang on a CPU reset. The linux kernel supports CPU watchdogs with a driver and a well known userspace API, but in this scenario the watchdog is not enabled (and thus not protecting against hangs etc) until userspace init is reached.
     613
     614Sometimes, however, a CPU watchdog isn't adequate because there may be an issue which you are trying to protect against such as a hang before the watchdog is even enabled or perhaps an issue where a peripheral isn't reset on a watchdog event (because the hardware doesn't have a reset pin for example, or the board design did not connect it).
     615
     616Because the Gateworks System Controller has the ability to disable a board's primary power supply its the perfect place to implement a hardware watchdog. When the GSC's watchdog trips, it will power cycle the board vs a 'reset'. Furthermore, because the GSC watchdog re-arms on power-up when enabled you can protect against hangs over the full power-up of the board: primary program loader (ie CPU boot ROM), secondary program loader (oe uboot), kernel (ie Linux kernel), and userspace.
     617
     618Example usage:
     619 * Enable watchdog (with '''latest Ventana u-boot'''):
     620{{{
     621#!bash
     622gsc wd enable 30 # enable watchdog for 30s timeout
     623gsc wd enable 60 # enable watchdog for 60s timeout
     624}}}
     625 * Enable watchdog (from older Ventana u-boot)
     626{{{
     627#!bash
     628i2c dev 0 # GSC is on the first of several i2c busses
     629i2c mw 0x20 1 0x20 1 # set R1=0x20 to enable watchdog for 30s timeout
     630}}}
     631 * Enable watchdog (from Laguna u-boot)
     632{{{
     633#!bash
     634imw 0x20 1 0x20 1 # set R1=0x20 to enable watchdog for 30s timeout
     635imw 0x20 1 0x30 1 # set R1=0x30 to enable watchdog for 60s timeout
     636}}}
     637 * Enable watchdog (from Linux)
     638{{{
     639#!bash
     640i2cset -f -y 0 0x20 1 0x20 # set R1=0x20 to enable watchdog for 30s timeout
     641i2cset -f -y 0 0x20 1 0x30 # set R1=0x30 to enable watchdog for 60s timeout
     642}}}
     643 * Disable watchdog (from '''latest Ventana u-boot''')
     644{{{
     645#!bash
     646gsc wd disable
     647}}}
     648 * Disable watchdog (from older Ventana u-boot)
     649{{{
     650#!bash
     651i2c dev 0 # GSC is on the first of several i2c busses
     652i2c mw 0x20 1 0 1 # disable watchdog
     653}}}
     654 * disable watchdog (from Laguna u-boot-2008)
     655{{{
     656#!bash
     657imw 0x20 1 0 1 # disable watchdog
     658}}}
     659 * disable watchdog (from Linux)
     660{{{
     661#!bash
     662i2cset -f -y 0 0x20 1 0x00 # clear R1 to disable watchdog
     663}}}
     664
     665In the above examples, notice that you are overwriting other bits that you may care about in R1 such as sleep enable. If you want a more foolproof way of adjusting just the bit you care about mask out the bits you want to set then OR in the value you want to set them to. For example, if you wish to set R1.4=0 and R1.5=1 you could to the following in shell:
     666{{{
     667#!bash
     668R1=$(i2cget -f -y 0 0x20 1) && \
     669  R1=$((R1 & ~0x30)) && \
     670  R1=$((R1 |  0x20)) && \
     671  i2cset -f -y 0 0x20 1 $R1 || echo i2c error
     672}}}
     673
     674Notes:
     675 * Once enabled, the GSC watchdog will re-arm on a power-up event (so that the board is protected from power-up onward). Because of this feature, if you have enabled the GSC watchdog:
     676  * if you break out of the bootloader you will need to disable the watchdog manually (see above)
     677  * if you use jtag_usb to program firmware you will need to be sure to use the most recent version which knows to disable the GSC watchdog
     678 * The Ventana GSC always uses the watchdog on power-up to cover some IMX6 errata which can cause the board to fail to boot from NAND. The bootloader disables the watchdog unless you have enabled it manually.
     679 * If you encounter difficulties once you have enabled the watchdog (ie your software is not resetting or disabling the watchdog, or your can't program the board via uboot or jtag) you can simply remove the GSC battery for 10seconds to reset the GSC to the default state where the watchdog is not enabled (this will of course reset all other registers you may have changed including the RTC).
     680 * see [wiki:gsc#GSCWatchdogkerneldriver below] for details on using the GSC watchdog via the Linux kernel driver and making sure you have a userspace application that tickles it
     681 * see [wiki:watchdog] for more info on watchdogs in general
     682
     683[=#registers]
     684== GSC Registers ==
     685The System Specialized Functions described above are configured via a set of GSC registers in an i2c slave device at the 7-bit address of 0x20.
     686
     687GSC Registers:
     688||= Reg Number =||= Reg Name           =||= Description                                 =||
     689|| 0            || GSC_CTRL_0           || Pushbutton Switch, CRC, Tamper Switch         ||
     690|| 1            || GSC_CTRL_1           || Sleep / Wakeup Control, Alternate Boot Device ||
     691|| 2-5          || GSC_SLEEP_WAKE_TIME  || Sleep Wakeup Timer                            ||
     692|| 6-9          || GSC_SLEEP_ADD        || Sleep Wakeup Additive Timer                   ||
     693|| 10           || GSC_INTERRUPT_SOURCE || Interrupt Source                              ||
     694|| 11           || GSC_INTERRUPT_ENABLE || Interrupt Enable                              ||
     695|| 12-13        || GSC_FIRMWARE_CRC     || Firmware CRC Value                            ||
     696|| 14           || GSC_FIRMWARE_VER     || Firmware Version                              ||
     697|| 15           || GSC_WRITE_PROTECT    || Write Protection                              ||
     698
     699[=#gsc_ctrl_0]
     700=== GSC_CTRL_0 (Register R0): Pushbutton Switch, CRC, and Tamper Switch configuration ===
     701||= Bit =||= Name              =||= Description =||
     702|| 0     || PB_HARD_RESET       || 0 = Pushbutton Software Interrupt[[BR]] Generates GSC Interrupt (see R10.0/R11.0)[[BR]] 1 = Push button generates hard system reset to board when the button is[[BR]] activated and de-activated within 700ms ||
     703|| 1     || PB_CLEAR_SECURE_KEY || 0 = Clear '''Secure Key''' EEPROM disabled[[BR]] 1 = Clear GSC EEPROM user space when switch is activated three times with[[BR]] less than 700ms delay between each activation[[BR]] Generates GSC Intterupt ||
     704|| 2     || PB_SOFT_POWER_DOWN  || 0 = Soft Power Down disabled[[BR]] 1 = Soft Power Down enabled[[BR]]Hold down >1s to power down[[BR]]When powered down a momentary press will power up[[BR]] Generates push button interrupt ||
     705|| 3     || PB_BOOT_ALTERNATE   || 0 = Boot Alternate Device disabled.[[BR]] 1 = Boot Alternate Device Enabled[[BR]] The board will reset and boot from the Alternate Boot Device when the[[BR]] pushbutton is activated (quick press-and-release) 5 times in quick succession) ||
     706|| 4     || PERFORM_CRC         || 1 = Run CRC on GSC and store results in GSC_FIRMWARE_CRC (R12,R13)[[BR]] resets to 0 on completion of CRC ||
     707|| 5     || TAMPER_DETECT       || 0 = Do not activate tamper switch operation[[BR]] 1 = Activate tamper switch operation. When Activated, if the tamper switch[[BR]] is released, the contents in the EEPROM user space will be erased[[BR]] Generates tamper switch interrupt. ||
     708|| 6     || SWITCH_HOLD         || 0 = Switch hold disabled.[[BR]] 1 = Switch Hold On. When the switch is held down for >700ms an interrupt[[BR]] will be generated. See interrupt Enable / Status registers. (supported in rev29+) ||
     709|| 7     ||                     || Reserved ||
     710
     711[=#gsc_ctrl_1]
     712=== GSC_CTRL_1 (Register R1): Sleep Wakeup Timer Control ===
     713||= Bit =||= Name              =||= Description =||
     714|| 0     || SLEEP_ENABLE        || 0 = Disable hardware sleep operation[[BR]] 1 = Enable hardware sleep operation ||
     715|| 1     || ACTIVATE_SLEEP      || 0 = Do not activate hardware sleep operation[[BR]] 1 = Activate hardware sleep operation (see GSC_SLEEP_WAKE) ||
     716|| 2     || LATCH_SLEEP_ADD     || 0 = Reserved[[BR]] 1 = Latch and add GSC_SLEEP_ADD registers to GSC_SLEEP_WAKE[[BR]]Resets to Zero on Completion ||
     717|| 3     || SLEEP_NOWAKEPB      || 0 = Wake from sleep on pushbutton 1 = do not wake on sleep until sleep wakeup time ||
     718|| 4     || WATCHDOG_TIME       || 0 = 30 second timeout[[BR]] 1 = 60 second timeout ||
     719|| 5     || WATCHDOG_ENABLE     || 0 = disable watchdog[[BR]] 1 = Enable / Reset watchdog timer ||
     720|| 6     || SWITCH_BOOT_ENABLE  || 0 = Auto Switch boot disabled[[BR]] 1 = Auto Switch boot enabled[[BR]]Note this is set and used at powerup by the GSC as a '''boot watchdog''' on Ventana boards ||
     721|| 7     || SWITCH_BOOT_CLEAR   || Auto Switch boot clear[[BR]]Set to disable auto switch boot countdown timer[[BR]]Note this is set and used at bootup by the bootloader as a '''boot watchdog''' on Ventana boards ||
     722
     723[=#gsc_sleep_wake_time]
     724=== GSC_SLEEP_WAKE_TIME (Registers R2-R5): Sleep Wakeup Time ===
     725||= Bit =||= Description =||
     726|| 0-31  || RTC Value to wake the board when in sleep[[BR]] (least significant byte first) ||
     727
     728[=#gsc_sleep_add]
     729=== GSC_SLEEP_ADD (Registers R6-R9): Sleep Wakeup Time Additive ===
     730||= Bit =||= Description =||
     731|| 0-31  || Add to current RTC and store in GSC_SLEEP_WAKE_TIME[[BR]] latched with R1.2[[BR]] (least significant byte first) ||
     732
     733[=#gsc_interrupt_status]
     734=== GSC_INTERRUPT_STATUS (Register R10): Interrupt Source ===
     735The GSC includes a single active-low level-triggered interrupt connected to an interrupt input on the ARM host processor. The GSC includes several possible interrupt sources with a control register to enable the desired interrupts and a status register to determine which are active. The following bits will indicate the cause of the host interrupt assertion which will remain asserted until all enabled bits are clear.
     736
     737||= Bit =||= Name =||= Description =||
     738|| 0     || IRQ_PB            || When set a pushbutton switch interrupt has occurred ||
     739|| 1     || IRQ_KEY_ERASED    || When set a '''Secure Key''' erase operation has completed ||
     740|| 2     || IRQ_EEPROM_WP     || When set an EEPROM WP violation occurred[[BR]] (write to EEPROM while GSC_EEPROM_WP_ALL or GSC_EEPROM_WP_BOARDINFO was enabled) ||
     741|| 3     ||                   || Reserved ||
     742|| 4     || IRQ_GPIO_CHANGE   || When set a GPIO interrupt has occurred ||
     743|| 5     || IRQ_TAMPER_DETECT || When set a tamper switch interrupt has occurred ||
     744|| 6     || IRQ_WDOG_TIMEOUT  || When set a watchdog timeout has occurred resulting in the board being reset ||
     745|| 7     || IRQ_SWITCH_HOLD   || When set a 'switch hold' interrupt has occurred ||
     746
     747For more information see [#gsc-interrupts gsc-interrupts]
     748
     749[=#gsc_interrupt_enable]
     750=== GSC_INTERRUPT_ENABLE (Register R11): Interrupt Enable (refer to bits above) ===
     751||= Bit =||= Name =||= Description =||
     752|| 0     || IRQ_PB                || Set to enable pushbutton switch interrupt ||
     753|| 1     || IRQ_SECURE_KEY_ERASED || Set to enable '''Secure Key''' erase operation interrupt ||
     754|| 2     || IRQ_EEPROM_WP         || Set to enable EEPROM WP violation interrupt ||
     755|| 3     ||                       || Reserved ||
     756|| 4     || IRQ_GPIO_CHANGE       || Set to enable GPIO interrupt ||
     757|| 5     || IRQ_TAMPER_DETECT     || Set to enable Tamer detect interrupt ||
     758|| 6     || IRQ_WDOG_TIMEOUT      || Set to enable Watchdog timeout interrupt ||
     759|| 7     || IRQ_SWITCH_HOLD       || Set to enable pushbutton switch 'hold' interrupt ||
     760
     761For more information see [#gsc-interrupts gsc-interrupts]
     762
     763[=#gsc_firmware_crc]
     764=== GSC_FIRMWARE_CRC (Register R12,R13): GSC Firmware CRC Value ===
     765||= Bit  =||= Description =||
     766||  0-15  || Contains the 16-bit cyclic redundancy check value for the GSP Flash memory (least significant byte first)[[BR]] The GSC performs a CRC check when R0.4 is set[[BR]] Once R0.4 is clear, R12 and R13 (16-bit lsb) contain an accurate CRC. ||
     767
     768
     769[=#gsc_firmware_ver]
     770=== GSC_FIRMWARE_VER (Register R14): GSC Firmware Version ===
     771||= Bit =||= Description                            =||
     772|| 0-7   || Contains the GSC firmware version number ||
     773
     774
     775[=#gsc_write_protect]
     776=== GSC_WRITE_PROTECT (Register R15): Write Protection ===
     777||= Bit =||= Name =||= Description                                                                                      =||
     778|| 0     || GSC_EEPROM_WP_ALL       || 1 = Write Protect all EEPROM regions                                              ||
     779|| 1     || GSC_EEPROM_WP_BOARDINFO || 1 = Write Protect the reserved Gateworks '''Board Info''' EEPROM section          ||
     780|| 2     ||                         || Reserved                                                                          ||
     781|| 3-7   || GSC_WP_PASSWD           || Must be 0xB when altering bits[0:2] (ie write 0x59 (0xB<<3|0x1) to enable WP_ALL) ||
     782
     783== Code Examples ==
     784
     785The following examples show how to utilize some of the GSC features and functions.
     786
     787* Reading the GSC Registers
     788 * Use {{{i2cget}}} to read the GSC registers
     789  * {{{i2cget -f -y BUS# DEVICE-ADDRESS# REGISTER#}}}
     790  * For example, to read register 14:
     791   * {{{i2cget -f -y 0 0x20 14}}}
     792   * For the GSC, always use 0 and 0x20 for the BUS and DEVICE
     793
     794* Board sleeping for 10 seconds
     795 * The following example will sleep the board for 10 seconds by setting the “add timer” to 10 seconds (from the current time) and then putting the board to sleep. This example uses the Linux I2C utilities.
     796{{{
     797#!bash
     798i2cset -f -y 0 0x20 6 10        ;# write add timer to 10sec
     799i2cset -f -y 0 0x20 7 0
     800i2cset -f -y 0 0x20 8 0
     801i2cset -f -y 0 0x20 9 0
     802i2cset -f -y 0 0x20 1 0x4       ;# set add time bit
     803i2cset -f -y 0 0x20 1 0x3       ;# enable (put board to sleep)
     804}}}
     805
     806The board will go to sleep and then wake up after 10 seconds. If you wanted the board to wakeup at a specific date/time regardless of the current RTC date/time you could set R2-5 to the number of seconds since the epoch ({{{date +%s}}} will show current system time in seconds) instead of using the R6-R9 'relative time' registers but note that if you set a value that has already passed you will have to activate the boards user pushbutton (if present) or remove the GSC battery for 10 seconds to reset the GSC/RTC to be able to wakeup the board.
     807
     808* Reading GSC version
     809 * The following example will print out the GSC code revision. This example uses the Linux I2C utilities.
     810{{{
     811i2cget -f -y 0 0x20 14          ;# read GSC revision from register 14
     8120x16                            ;# hex revision value = v22
     813}}}
     814
     815[=#i2c]
     816= I2C communication with the GSC =
     817The GSC communicates with the SoC via i2c at a maximum clock rate of 100KHz. The GSC may occasionally be busy and fail to ACK an i2c master transaction within the bit timing. This is because every second the GSC performs a round of ADC conversions for its hardware monitoring function. At worst, you should never fail an ACK more than 2 times in a row based on the amount of time needed for the ADC conversions.
     818
     819For this reason, you should retry and i2c read/write calls up to 3 times if the failure is a NAK (failure to ACK).
     820
     821Note that the GSC registers are 8bit values where each bit has a different meaning. To read/modify/write you should do the following:
     822 1. read register value
     823 2. mask out the bits your going to clear (or set) (&= ~(mask))
     824 3. set the bits your going to set
     825
     826An example of how you can do this as well as check for i2c read/write errors using shell is the following:
     827{{{
     828#!bash
     829R0=$(i2cget -f -y 0 0x20 0) && \
     830  R0=$((R0 & ~0x05)) && \
     831  R0=$((R0 |  0x04)) && \
     832  i2cset -f -y 0 0x20 0 $R0 || echo i2c error
     833}}}
     834 * clear R0.0 (PB_HARD_RESET) to disable pushbutton hard reset
     835 * set R0.2 (PB_SOFT_POWER) to enable soft power control
     836 * Note that we are clearing bits 0 and 2 with R0 = R0 & ~0x05 and setting bits 2 with R0 = R0 | 0x04
     837
     838[=#drivers]
     839= GSC Drivers =
     840A set of Linux drivers exists in the Gateworks BSP's that exposes some very useful GSC functionality:
     841 * gsc-core driver
     842 * gsc-watchdog driver
     843 * gsc-input driver
     844
     845== GSC Core Linux kernel driver ==
     846The gsc-core driver provides the following:
     847 * manages shared resources for the other GSC drivers
     848 * interrupt controller to provide distinct interrupts for the various GSC status register bits (which other drivers can use)
     849 * sysfs API for powering down the board (using the 'GSC sleep' function. Using a sleep time of 2 seconds guarantees a 1 to 2 second power-off)
     850
     851Examples:
     852 * power-cycle (2 seconds guarantees between 1 and 2 seconds power-off)
     853{{{
     854#!bash
     855sync && echo 2 > /sys/bus/i2c/devices/0-0020/powerdown
     856}}}
     857  * power-down for 30 seconds:
     858{{{
     859#!bash
     860sync && echo 30 > /sys/bus/i2c/devices/0-0020/powerdown
     861}}}
     862
     863
     864[=#wdtdriver]
     865== GSC Watchdog kernel driver ==
     866The gsc-wdt driver implements the Linux watchdog API for the hardware watchdog inside the GSC. When using this watchdog as opposed to the in-chip watchdog (ie mpcore for Laguna or imx for Ventana) the board will be fully power-cycled when/if the watchdog expires. This can be more reliable that SoC level resets which are done by the SoC watchdogs.
     867
     868Note that the GSC watchdog function is available in GSC firmware v44 and beyond.
     869
     870In order to use the GSC watchdog function and driver, the GSC watchdog must be manually enabled by the user - it is not enabled by default by the GSC firmware, and the GSC driver does not enable it.
     871
     872The GSC watchdog driver init/probe function will fail if the GSC watchdog is not enabled. This allows the SoC watchdog driver to become {{{/dev/watchdog0}}} if the GSC watchdog is not enabled.
     873
     874To enable the GSC watchdog:
     875 * in linux:
     876{{{
     877#!bash
     878i2cset -f -y 0 0x20 1 0x20 ;# enable for 30 second timeout
     879# or
     880i2cset -f -y 0 0x20 1 0x30 ;# enable for 60 second timeout
     881}}}
     882 * in Ventana bootloader:
     883{{{
     884#!bash
     885gsc wd enable 30 # enable watchdog for 30s timeout
     886# or
     887gsc wd enable 60 # enable watchdog for 60s timeout
     888}}}
     889 * in Laguna bootloader:
     890{{{
     891#!bash
     892i2c dev 0 && i2c mw 0x20 1 0x20 1 # set R1=0x20 to enable watchdog for 30s timeout
     893# or
     894i2c dev 0 && i2c mw 0x20 1 0x30 1 # set R1=0x30 to enable watchdog for 60s timeout
     895}}}
     896
     897The following requirements exist for using the GSC watchdog with the GSC watchdog driver:
     898 1. user manually enables the watchdog by setting GSC CTRL_1 bit 6 (see above)
     899 2. GSC has v44 or newer firmware
     900 3. GSC driver is enabled in the kernel (latest OpenWrt 14.08 BSP, Yocto v1.6+ BSP, Android Kitkat BSP)
     901 4. a userspace app is tickling the proper watchdog (Note that if you have both in-chip cpu watchdog enabled and GSC watchdog enabled you will have two {{{/dev/watchdog*}}} devices - the SoC watchdog will be {{{/dev/watchdog0}}} and the GSC watchdog will be {{{/dev/watchdog1}}} in this case) (see below for BSP specific details)
     902
     903BSP specific notes:
     904 * OpenWrt 14.08+:
     905  * procd (PID1) takes on the responsibility of tickling the watchdog and does so at {{{/dev/watchdog}}} (not configurable without changing procd's {{{watchdog.c}}} code)
     906  * the GSC watchdog driver initializes before the SoC watchdog driver, so if you have met requirements 1-4 above, then the GSC watchdog device becomes {{{/dev/watchdog}}} (as opposed to the SoC watchdog). Failure to meet 1-4 above will result in the SoC watchdog becoming {{{/dev/watchdog}}}
     907  * you can tell procd to stop tickling the watchdog to test the affect:
     908{{{
     909#!bash
     910ubus call system watchdog '{ "stop": true }'  # system will reset when wd timeout occurs
     911}}}
     912 * Yocto v1.6+:
     913  * The watchdog util is installed on the Gateworks BSP but not enabled. Therefore to meet requirement 4 above you must give it a conf file and configure it to start on boot (prior to enabling it):
     914{{{
     915#!bash
     916# create conf file
     917cat << EOF > /etc/watchdog.conf
     918watchdog-device = /dev/watchdog
     919realtime = yes
     920priority = 1
     921interval = 5
     922watchdog-timeout = 30
     923EOF
     924
     925# create an init service script
     926cat << EOF > /etc/init.d/watchdog
     927#!/bin/sh
     928
     929watchdog
     930EOF
     931
     932# make it executable
     933chmod +x /etc/init.d/watchdog
     934
     935# configure as a system service to start on boot, priority 1
     936update-rc.d watchdog defaults 1
     937sync
     938}}}
     939 * Android kk+:
     940  * The {{{/dev/watchdog}}} is enabled and tickled by {{{/sbin/watchdogd}}} which is kicked off from Android's init process and part of the Android init tool
     941
     942Notes:
     943 * see [wiki:watchdog] for more info
     944
     945[=#inputdriver]
     946== GSC Input kernel driver ==
     947The gsc-input driver registers itself as a handler for the interrupts that the gsc-core driver provides for the various interrupt sources of the GSC and dispatches Linux input events for each specific event.
     948
     949All of these actions depend on the manual user configuration of the [#gsc_ctrl_0 GSC CTRL_0] and [#gsc_interrupt_enable GSC_IRQ_ENABLE] registers. The driver does 'not' force a configuration upon the user. Note that all Gateworks Laguna and Ventana products ship with GSC_CTRL_0=0x01 configuring the pushbutton as a hard-reset and that this register is non-volatile as long as the GSC battery is powering the GSC. In such a default configuration a quick press/release of the user pushbutton will result in a hard reset instead of an interrupt that can be caught by software.
     950
     951The following table shows what linux input EV_KEY event is sent for each interruptable configuration:
     952||= interrupt =||= key =||= event                                                 =||= requirements                                           =||= notes =||
     953|| 0           || BTN_0 || user button press/release within 700ms                  || R0.0=0 (hard reset disabled)                             || event fires appx 1s after the press ||
     954|| 1           || BTN_1 || user eeprom section erased after 3x quick press/release || R0.0=0 (hard reset disabled) R0.1=1 (secure key enabled) || takes a couple of secs from first press to trigger as secure key is erased ||
     955|| 2           || BTN_2 || user eeprom write-protect violation                     || || ||
     956|| 4           || BTN_3 || gpio change                                             || R0.0=0 (hard reset disabled)                             || ||
     957|| 5           || BTN_4 || tamper event                                            || R0.5=1 (tamper detect enabled)                           || ||
     958|| 7           || BTN_5 || user button held >700ms                                 || R0.6=1 (switch hold enabled)                             || event fires 700ms after press ||
     959 * In addition to the requirements for GSC_CTRL_0 listed above, the associated bit in R11 corresponding to the interrupt number also must be enabled.
     960
     961The driver does not alter the configuration of CTRL_0 so the user must do so manually depending on their interests. Some example configurations are:
     962 * enable all events (allows catching individual button press and button release events):
     963{{{
     964#!bash
     965i2cset -f -y 0 0x20 0 0x00 # disable pushbutton hard reset
     966i2cset -f -y 0 0x20 11 0xff # enable all interrupts
     967}}}
     968  * please see [#IRQ_GPIO_CHANGE here] regarding un-terminated inputs causing spurious GPIO_CHANGE events
     969
     970BSP Specific notes:
     971 * OpenWrt (14.08 and below only):
     972  - OpenWrt does not typically do anything with Linux input events. If you are interested in user pushbutton press-release events see [#pushbutton pushbutton]
     973  - you can use the event_test application to show Linux Input events:
     974{{{
     975#!bash
     976> event_test /dev/input/event0
     977Input driver version is 1.0.1
     978Input device ID: bus 0x0 vendor 0x0 product 0x0 version 0x0
     979Input device name: "gsc_input"
     980Supported events:
     981  Event type 0 (Reset)
     982    Event code 0 (Reset)
     983    Event code 1 (Key)
     984  Event type 1 (Key)
     985    Event code 256 (Btn0)
     986    Event code 257 (Btn1)
     987    Event code 258 (Btn2)
     988    Event code 259 (Btn3)
     989    Event code 260 (Btn4)
     990    Event code 261 (Btn5)
     991Testing ... (interrupt to exit)
     992Event: time 1435938985.047196, type 1 (Key), code 259 (Btn3), value 1
     993Event: time 1435938985.047196, type 1 (Key), code 259 (Btn3), value 0
     994Event: time 1435938985.047196, type 0 (Reset), code 0 (Reset), value 0
     995Event: time 1435938985.047217, type 1 (Key), code 256 (Btn0), value 1
     996Event: time 1435938985.047217, type 1 (Key), code 256 (Btn0), value 0
     997Event: time 1435938985.047217, type 0 (Reset), code 0 (Reset), value 0
     998}}}
     999  * the above events occur when the user pushbutton is pressed and quickly released: Btn3 reflects the gpio change (IRQ_GPIO_CHANGE) event, and Btn0 reflects the pushbutton quick press-and-release event (IRQ_PB)
     1000 * Yocto:
     1001  - you can use the evtest application to show Linux Input events:
     1002{{{
     1003#!bash
     1004> evtest /dev/input/event0
     1005Input driver version is 1.0.1
     1006Input device ID: bus 0x0 vendor 0x0 product 0x0 version 0x0
     1007Input device name: "gsc_input"
     1008Supported events:
     1009  Event type 0 (EV_SYN)
     1010  Event type 1 (EV_KEY)
     1011    Event code 256 (BTN_0)
     1012    Event code 257 (BTN_1)
     1013    Event code 258 (BTN_2)
     1014    Event code 259 (BTN_3)
     1015    Event code 260 (BTN_4)
     1016    Event code 261 (BTN_5)
     1017Properties:
     1018Testing ... (interrupt to exit)
     1019Event: time 1435939364.644274, type 1 (EV_KEY), code 259 (BTN_3), value 1
     1020Event: time 1435939364.644274, type 1 (EV_KEY), code 259 (BTN_3), value 0
     1021Event: time 1435939364.644274, -------------- EV_SYN ------------
     1022Event: time 1435939364.644283, type 1 (EV_KEY), code 256 (BTN_0), value 1
     1023Event: time 1435939364.644283, type 1 (EV_KEY), code 256 (BTN_0), value 0
     1024Event: time 1435939364.644283, -------------- EV_SYN ------------
     1025}}}
     1026  * the above events occur when the user pushbutton is pressed and quickly released: Btn3 reflects the gpio change (IRQ_GPIO_CHANGE) event, and Btn0 reflects the pushbutton quick press-and-release event (IRQ_PB)
     1027 * Android:
     1028  - a keymap file is present in {{{/system/usr/keylayout/gsc_input.kl}}} which maps the keys above to android key events. For example, the BTN_0 key (256 in Linux) is mapped to the POWER key for Android so that it acts like a power button toggle on a phone or tablet:
     1029{{{
     1030#!bash
     1031> cat /system/usr/keylayout/gsc_input.kl
     1032# quick press-and-release (held <700ms) of front-panel pushbutton
     1033key 256   POWER                 WAKE
     1034
     1035# front panel pushbutton held >700ms (long-press)
     1036key 257   HOME                  WAKE
     1037
     1038# user-eeprom section erased after 3 quick presses
     1039key 258   SEARCH                WAKE
     1040
     1041# tamper event
     1042key 259   POWER                 WAKE
     1043}}}
     1044  - you can use the getevent application to show Linux Input events:
     1045{{{
     1046#!bash
     1047> getevent /dev/input/event0
     10480001 0103 00000001
     10490001 0103 00000000
     10500000 0000 00000000
     10510001 0100 00000001
     10520001 0100 00000000
     10530000 0000 00000000
     1054}}}
     1055  * the above events occur when the user pushbutton is pressed and quickly released: Btn3 (hex 103) reflects the gpio change (IRQ_GPIO_CHANGE) event, and Btn0 (hex 100) reflects the pushbutton quick press-and-release event (IRQ_PB)
     1056
     1057User Pushbutton Notes:
     1058 * If you need more flexibility in monitoring the GSC pushbutton (ie you want to determine if the button has been pressed and held down for 10 seconds) you need to monitor its GPIO manually. See [#pushbutton pushbutton] for more details on how to do this.
     1059
     1060[=#firmware]
     1061= GSC Updates =
     1062From time to time, there may be updates to this firmware in order to provide new features. There are two options for updating the GSC firmware:
     1063 * JTAG from a host Linux PC via the Linux jtag_usb application found [http://svn.gateworks.com/bsp/jtag here]:
     1064{{{
     1065#!bash
     1066jtag_usbv4 -m <firmware.txt>  ;# update GSC firmware image
     1067jtag_usbv4 -x <firmware.txt>  ;# verify GSC firmware image
     1068}}}
     1069 * linux running on the target board using the {{{gsc_update}}} application which is present in the latest firmware images (OpenWRT package and source available [[http://trac.gateworks.com/browser/openwrt/trunk/packages/gateworks/gsc-update here]]):
     1070{{{
     1071#!bash
     1072gsc_update -f <firmware.txt>
     1073}}}
     1074
     1075Notes:
     1076 * GSC firmware images can be found with the pre-built firmware images for the various product families
     1077 * using the {{{gsc_update}}} method, there is no validity checking of the firmware file (for transfer errors or for product ID) - updating an invalid image will require you to use the linux jtag_usbv4 application and a JTAG dongle to re-program (via {{{./jtag_usbv4 -m gsp_firmware.txt}}}). Care should be taken to make sure you are updating a valid image meant for your target board. To verify the firmware update completed properly you can query the GSC firmware version register:
     1078{{{
     1079#!bash
     1080i2cget -f -y 0 0x20 14
     1081}}}
     1082 * after re-programming the GSC will revert some of its configuration just as if the coin-cell battery had been removed and replaced (see Battery Replacement info for details)
     1083
     1084GSC Firmware Downloads:
     1085 * [http://svn.gateworks.com/ventana/images Ventana Product Family]
     1086 * [http://svn.gateworks.com/laguna/images Laguna Product Family]
     1087 * [http://svn.gateworks.com/cambria/images Cambria Product Family]
     1088 * [http://svn.gateworks.com/rincon/images Rincon Product Family]
     1089
     1090[=#revisions]
     1091== GSC Version History ==
     1092
     1093The following represents the revision history for externally released GSC firmware revisions:
     1094 * v49:
     1095  - fix temperature accuracy between -40C and 0C
     1096  - added Ventana GW553X support
     1097 * v48:
     1098  - fix Ventana wake by pushbutton for GW5400
     1099  - add ability to program 'firmware reset default' for R0 and R1 (see [#firmware-reset below])
     1100 * v47:
     1101  - fix Ventana wake by pushbutton (boot_mode0 disabled if power control or wake)
     1102 * v46:
     1103  - fix Ventana soft power control (boot_mode0 disabled when soft power control is enabled)
     1104  - change: do a hard power cycle of board instead of reset on push-button press when
     1105    hard reset enabled. This resolves some reset issues when using push-button reset on Ventana
     1106 * v45 - bugfix: fix occasional GSC reset during flash EEPROM write
     1107 * v44 - added GSC hardware watchdog
     1108 * v43 - Ventana bugfix:
     1109  - fix Ventana [http://trac.gateworks.com/wiki/ventana/serial_downloader boot recovery mode]
     1110  - fix hwmon readings at low temperatures
     1111 * v42 - added Ventana GW52XX/GW53XX support
     1112 * v41 - added Ventana GW51XX support
     1113 * v40 - added Ventana GW54XX support
     1114 * v39 - bugfix: fix possible race condition for missing i2c interrupts
     1115 * v38 - bugfix: fix race condition which can cause occasional boot failure
     1116 * v36 - add write protect capability and bugfix for missed bits if a start condition occurs during an ISR
     1117 * v35 - bugfix: resolve issue keeping board powered down if pushbutton pressed while board is off
     1118 * v34 - bugfix: wakeup board immediately if Wake time has already occurred in the past
     1119 * v33 - add support for GW2391
     1120 * v32 - pushbutton bugfix and change board power enable drive
     1121 * v30 - added mapping of pushbutton state in GPIO
     1122 * v29 - add support for PB_HOLD interrupt
     1123 * v28 - bugfix: resolve issue with detecting Tamper event while board powered on
     1124 * v27 - and 'Auto Switch' alternate boot device
     1125 * v23-26 - add support for new boards
     1126
     1127Latest GSC revisions per baseboard:
     1128||= family =||= board =||= revision                                                     =||
     1129|| Ventana  || GW553x  || [http://svn.gateworks.com/ventana/images/gsc_553x_v49.txt v49] ||
     1130|| Ventana  || GW552x  || [http://svn.gateworks.com/ventana/images/gsc_552x_v49.txt v49] ||
     1131|| Ventana  || GW551x  || [http://svn.gateworks.com/ventana/images/gsc_551x_v49.txt v49] ||
     1132|| Ventana  || GW54xx  || [http://svn.gateworks.com/ventana/images/gsc_54xx_v49.txt v49] ||
     1133|| Ventana  || GW53xx  || [http://svn.gateworks.com/ventana/images/gsc_53xx_v49.txt v49] ||
     1134|| Ventana  || GW52xx  || [http://svn.gateworks.com/ventana/images/gsc_52xx_v49.txt v49] ||
     1135|| Ventana  || GW51xx  || [http://svn.gateworks.com/ventana/images/gsc_51xx_v49.txt v49] ||
     1136||||
     1137|| Laguna   || GW2391  || [http://svn.gateworks.com/laguna/images/gsc_2391_v49.txt v49]  ||
     1138|| Laguna   || GW2388  || [http://svn.gateworks.com/laguna/images/gsc_2388_v49.txt v49]  ||
     1139|| Laguna   || GW2387  || [http://svn.gateworks.com/laguna/images/gsc_2387_v49.txt v49]  ||
     1140|| Laguna   || GW2383  || [http://svn.gateworks.com/laguna/images/gsc_2383_v49.txt v49]  ||
     1141|| Laguna   || GW2382  || [http://svn.gateworks.com/laguna/images/gsc_2382_v49.txt v49]  ||
     1142|| Laguna   || GW2380  || [http://svn.gateworks.com/laguna/images/gsc_2380_v49.txt v49]  ||
     1143
     1144=== GSC Version ===
     1145Type the following command from the command prompt on the board. This will return a hex value:
     1146{{{
     1147#!bash
     1148i2cget -f -y 0 0x20 14
     1149}}}
     1150
     1151[=#battery]
     1152= Battery / Battery Replacement =
     1153The coin cell battery used provides for approximately '''3.8 years''' of battery-backed powered-off shelf life (see [#battstorage below]). When primary board power is applied to the board (regardless of if the board is in 'sleep' mode) the battery source is not drained - this value is the worst-case life for an unpowered board.
     1154
     1155== Battery Replacement ==
     1156Battery Replacement Details:
     1157 * A BR1225 coin cell battery is used.
     1158 * While primary board power is removed, the GSC battery can be removed for about 10 seconds before power is lost to the GSC.  This gives you a small window of time to replace the battery without losing data such as RTC values. If longer then 10 seconds then the GSC will be reset.
     1159 * If battery is replaced while board power is off, '''you must apply board power momentarily afterwards to reset the GSC into the proper operational state. If power is not applied the drain on the battery will be fairly large and will deplete the battery within about 3-4 weeks.'''
     1160  * To verify the GSC current consumption, you can measure the voltage across a diode (+ probe on anode, - probe on cathode). The voltage across the diode with no power applied to the board should be approximately 300mV. If you see something in the 400mV range that means the GSC is not reset properly or there is some type of contamination causing excessive current draw. Contact support with your serial number for specifics on which diode ( support@gateworks.com ).
     1161 * Note that bat rail voltage cannot be measured via Linux software as shown above until board power is turned off for one second or more (a second time when battery is replaced/GSC reset). When power is off, we monitor the bat voltage every 9 hours. When the board is fully powered on and booted into Linux, the bat reading cannot be continually updated and reports the last read voltage when the board was last powered off.
     1162 * The GSC can operate down to a battery voltage of 2.2V. If the battery goes below this erratic behavior can result and the battery should be either removed (operate without battery) or replaced.
     1163 * A fresh battery typically has a voltage ranging from 2.8 to 3.1V (also depends on temperature). The battery discharge rate is fairly flat but once it is discharged it can decay rapidly. Note that when the board is powered, the 3.3V power supply supplies power to the GSC and the battery will not be drained. This should be factored in when determining battery lifetime.
     1164 * The BR1225 coin cell is rated at 50mA/hours. The GSC's typical drain when in low power mode is 1.5uA. Battery lifetime can be calculated by taking the battery rating divided by the current drain. Example: (50mA/hour)/(1.5uA) = 33.33K hours.
     1165
     1166[=#firmware-reset]
     1167=== Firmware Reset Default conditions ===
     1168The following items are reset if the battery is removed for more than 10 seconds or if the GSC firmware has been updated:
     1169 * RTC value (reset to 0 seconds since midnight Jan 1 1970)
     1170 * GSC configuration registers (R0's reset value varies from board to board, the others default to 0). Note that if using firmware v48 or later, you can program the 'firmware reset value' of R0 and R1 by writing to i2c eeprom slave 0x51 offset 0x50 and 0x51:
     1171{{{
     1172#!bash
     1173# to set the default value of R0 to 0x04 (soft interrupt / soft power control)
     1174i2c dev 0 && i2c mw 0x51 0x50 0x04 1 # write 0x04 to 0x51:0x50
     1175# to set the default value of R1 to 0x30 to enable 60s watchdog
     1176i2c dev 0 && i2c mw 0x51 0x51 0x30 1 # write 0x30 to 0x51:0x51
     1177}}}
     1178 * Fan controller registers default to the temperature setpoints shown in the Fan Controller section above
     1179 * '''Secure Key''' EEPROM area is set to 0xff's (see EEPROM section above)
     1180 * GPIO Port configuration is reset depending on particular board:
     1181  * All general purpose I/O's are set to 'inverted inputs' (with pullup enabled)
     1182  * All dedicated outputs are set to output high
     1183  * All dedicated inputs are configured as inputs*
     1184
     1185[=#battstorage]
     1186== Board Storage with respect to Battery ==
     1187When a board is powered on, the GSC will draw power from the primary power supply and not it's coincell battery.
     1188
     1189However, when the board sits on a shelf with no Vin applied, the GSC is still running its application and consuming very little power such that the battery should last approximately 3.8 years. This approximation will vary based on environmental conditions such as temperature. (see [http://dev.gateworks.com/datasheets/AAA4000CE25.pdf datasheet]).
     1190
     1191Care should be taken that the board is stored in a way that the battery case (which is the + side of the battery) does not come in contact with a conductive path to ground on the board as doing so would not only drain the battery but if this conduction path persists for ~8 seconds or more it would put the GSC into 'reset' where its current path (even after the battery short is removed) is higher than normal. This is the same scenario described above in the Battery replacement section and can be resolved by powering the board on at least once to get the GSC out of reset.