wiki:gsc

Version 66 (modified by Bobby Jones, 2 years ago) (diff)

Shift gsc registers to top of page

  1. Gateworks System Controller (GSC)
    1. GSC versions
    2. GSC Registers
      1. GSC_CTRL_0 (Register R0): Pushbutton Switch, CRC, and Tamper Switch …
      2. GSC_CTRL_1 (Register R1): Sleep Wakeup Timer Control
      3. GSC_SLEEP_WAKE_TIME (Registers R2-R5): Sleep Wakeup Time
      4. GSC_SLEEP_ADD (Registers R6-R9): Sleep Wakeup Time Additive
      5. GSC_INTERRUPT_STATUS (Register R10): Interrupt Source
      6. GSC_INTERRUPT_ENABLE (Register R11): Interrupt Enable (refer to bits above)
      7. GSC_FIRMWARE_CRC (Register R12,R13): GSC Firmware CRC Value
      8. GSC_FIRMWARE_VER (Register R14): GSC Firmware Version
      9. GSC_WRITE_PROTECT (Register R15): Write Protection
      10. GSC_RESET_CAUSE (Register R16): Reset Cause
      11. GSC_INTERRUPT_SOURCE_1 (Register R17): Interrupt Source 1
      12. GSC_INTERRUPT_ENABLE_1 (Register R18): Interrupt Enable 1
      13. GSC_THERMAL_PROTECT (Register R19): Thermal Protection Configuration
      14. GSC_BOOT_OPTIONS (Register R21): Boot Control Options
      15. GSC_MEM_ACCESS_PAGE (Register R22): Direct Memory Access Page Number
      16. GSC_CTRL_2 (Register R23): Pushbutton, Miscellaneous Configuration
      17. GSC_SOFT_POWER_TIME (Register R26): Soft Power Press Time
      18. GSC_REGISTER_BACKUP (Register R31): Register Backup Control
    3. Real Time Clock
    4. System Temperature and Voltage Monitor
      1. GSCv3 (GW6xxx/GW5910/GW5913)
      2. GSC v1/v2 (Laguna/Ventana)
    5. Battery Voltage Reading
    6. Fan Controller
      1. Always-on FAN for a constant voltage source
    7. General Purpose Input and Output (GPIO)
    8. User Pushbutton
      1. Code Examples for software user pushbutton detection
    9. EEPROM storage
      1. EEPROM Secure Key Example
      2. Custom Serial Number Example
    10. Hardware Sleep and Wake
      1. Pushbutton Sleep
      2. Register Timer Sleep
        1. Board sleeping Example
      3. GSC Reboot
    11. Alternate Boot Device
      1. Auto Switch Boot Device
    12. Tamper Detection
    13. GPS Active Antenna short-circuit auto detect and recover
    14. GSC Reset Cause (GSCv3 firmware v53+)
    15. GSC Thermal Protection (GSCv3 firmware v53+)
    16. GSC Interrupts
      1. IRQ_PB interrupt
      2. IRQ_SWITCH_HOLD interrupt
      3. IRQ_SECURE_KEY_ERASED interrupt
      4. IRQ_EEPROM_WP interrupt
      5. IRQ_GPIO_CHANGE interrupt
      6. IRQ_TAMPER_DETECT interrupt
      7. IRQ_WDOG_TIMEOUT interrupt
    17. Hardware Boot Watchdog
    18. Register Save/Load (GSCv3 firmware v57+)
  2. I2C communication with the GSC
    1. Occasional I2C NAK's
  3. GSC Drivers
    1. GSC Core Linux kernel driver
  4. Reset Monitor
  5. GSC Updates
    1. GSC Version History
      1. GSC Version
  6. Battery / Battery Replacement
    1. Battery Replacement
      1. Firmware Reset Default conditions
    2. Board Storage with respect to Battery

Gateworks System Controller (GSC)

The 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):

The GSC communicates with the host CPU over the i2c bus and uses the following 7-bit i2c slave addresses:

  • 0x20 - GSC configuration registers
  • 0x21 - GSC software update registers
  • 0x23 - PCA9555 emulated I/O (common industry standard GPIO port expander)
  • 0x29 - system monitor (similar to industry standard AD7418 but with modified register set - see below)
  • 0x50 - 24c04 emulated EEPROM (256B) (common industry standard EEPROM device)
  • 0x51 - 24c04 emulated 256 byte EEPROM (common industry standard EEPROM device)
  • 0x52 - 24c04 emulated 256 byte EEPROM (common industry standard EEPROM device) (some models only)
  • 0x53 - 24c04 emulated 256 byte EEPROM (common industry standard EEPROM device) (some models only)
  • 0x5e - Direct memory access read register
  • 0x68 - DS1672 emulated RTC (common industry standard device)

GSC versions

The latest Gateworks products use a third generation GSC. The following generations exist:

Family Board GSC version
Venice all v3
Newport all v3
Ventana GW5910/GW5913 v3
Ventana GW51xx/GW52xx/GW53xx/GW54xx/GW55xx v2
Laguna GW2388/GW2391/GW2387 v2
Laguna GW2380/82/83 v1

The various generations of GSC versions are:

  • v1: MSP430F2132
  • v2: MSP430F2252
    • additional RAM/FLASH space (additional user eeprom regions)
    • additional ADC
    • added FAN controller
    • added Alternate boot device support
  • v3: MSP430FR58471
    • additional RAM/FLASH space
    • additional ADC
    • improved I2C interface (eliminates occasional I2C NAK's)
    • reduced power consumption resulting in longer battery life (3.8Y -> 5Y)
    • resolves 'high power draw state' when inserting a battery while board powered off

GSC Registers

The 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.

GSC Registers:

Reg Number Reg Name Description Supported
0 GSC_CTRL_0 Pushbutton Switch, CRC, Tamper Switch All
1 GSC_CTRL_1 Sleep / Wakeup Control, Alternate Boot Device All
2-5 GSC_SLEEP_WAKE_TIME Sleep Wakeup Timer All
6-9 GSC_SLEEP_ADD Sleep Wakeup Additive Timer All
10 GSC_INTERRUPT_SOURCE Interrupt Source All
11 GSC_INTERRUPT_ENABLE Interrupt Enable All
12-13 GSC_FIRMWARE_CRC Firmware CRC Value All
14 GSC_FIRMWARE_VER Firmware Version All
15 GSC_WRITE_PROTECT Write Protection All
16 GSC_RESET_CAUSE Reset Cause GSCv3
17 GSC_INTERRUPT_SOURCE_1 Interrupt Source 1 GSCv3
18 GSC_INTERRUPT_ENABLE_1 Interrupt Enable 1 GSCv3
19 GSC_THERMAL_PROTECT Thermal Protection GSCv3
20 GSC_CPU_SPEED_CTRL CPU Speed Control GSCv3
21 GSC_BOOT_OPTIONS Boot Control Options GSCv3
22 GSC_MEM_ACCESS_PAGE Direct Memory Access Page Number GSCv3
23 GSC_CTRL_2 Pushbutton Switch, Misc. GSCv3
31 GSC_REGISTER_BACKUP Thermal Protection GSCv3

GSC_CTRL_0 (Register R0): Pushbutton Switch, CRC, and Tamper Switch configuration

Bit Name Description Newport DefaultsVentana Defaults
0 PB_HARD_RESET 0 = Pushbutton Software Interrupt
Generates GSC Interrupt (see R10.0/R11.0)
1 = Push button generates hard system reset to board when the button is
activated and de-activated within 700ms
EnabledEnabled
1 PB_CLEAR_SECURE_KEY 0 = Clear Secure Key EEPROM disabled
1 = Clear GSC EEPROM user space when switch is activated three times with
less than 700ms delay between each activation
Generates GSC Intterupt
DisabledDisabled
2 PB_SOFT_POWER_DOWN 0 = Soft Power Down disabled
1 = Soft Power Down enabled
Hold down >1s to power down
When powered down a momentary press will power up
Generates push button interrupt
DisabledDisabled
3 PB_BOOT_ALTERNATE 0 = Boot Alternate Device disabled.
1 = Boot Alternate Device Enabled
The board will reset and boot from the Alternate Boot Device when the
pushbutton is activated (quick press-and-release) 5 times in quick succession)
EnabledDisabled
4 PERFORM_CRC 1 = Run CRC on GSC and store results in GSC_FIRMWARE_CRC (R12,R13)
resets to 0 on completion of CRC
DisabledDisabled
5 TAMPER_DETECT 0 = Do not activate tamper switch operation
1 = Activate tamper switch operation. When Activated, if the tamper switch
is released, the contents in the EEPROM user space will be erased
Generates tamper switch interrupt.
DisabledDisabled
6 SWITCH_HOLD 0 = Switch hold disabled.
1 = Switch Hold On. When the switch is held down for >700ms an interrupt
will be generated. See interrupt Enable / Status registers. (supported in rev29+)
DisabledDisabled
7 CPU_WDOG_POWERCYCLE 0 = Disabled. CPU WDOG signals only trigger a software reset.
1 = Enabled. Convert CPU WDOG signal into a full board power cycle. (GSCv3 only)
Enabled Not supported

GSC_CTRL_1 (Register R1): Sleep Wakeup Timer Control

Bit Name Description
0 SLEEP_ENABLE 0 = Disable hardware sleep operation
1 = Enable hardware sleep operation
1 ACTIVATE_SLEEP 0 = Do not activate hardware sleep operation
1 = Activate hardware sleep operation (see GSC_SLEEP_WAKE)
2 LATCH_SLEEP_ADD 0 = Reserved
1 = Latch and add GSC_SLEEP_ADD registers to GSC_SLEEP_WAKE
Resets to Zero on Completion
3 SLEEP_NOWAKEPB 0 = Wake from sleep on pushbutton 1 = do not wake on sleep until sleep wakeup time
4 RESERVED
5 RESERVED
6 SWITCH_BOOT_ENABLE 0 = Auto Switch boot disabled
1 = Auto Switch boot enabled
Note this is set and used at powerup by the GSC as a boot watchdog on Ventana boards
7 SWITCH_BOOT_CLEAR Auto Switch boot clear
Set to disable auto switch boot countdown timer
Note this is set and used at bootup by the bootloader as a boot watchdog on Ventana boards

GSC_SLEEP_WAKE_TIME (Registers R2-R5): Sleep Wakeup Time

Bit Description
0-31 RTC Value to wake the board when in sleep
(least significant byte first)

GSC_SLEEP_ADD (Registers R6-R9): Sleep Wakeup Time Additive

Bit Description
0-31 Add to current RTC and store in GSC_SLEEP_WAKE_TIME
latched with R1.2
(least significant byte first)

GSC_INTERRUPT_STATUS (Register R10): Interrupt Source

The 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.

Bit Name Description
0 IRQ_PB When set a pushbutton switch interrupt has occurred
1 IRQ_KEY_ERASED When set a Secure Key erase operation has completed
2 IRQ_EEPROM_WP When set an EEPROM WP violation occurred
(write to EEPROM while GSC_EEPROM_WP_ALL or GSC_EEPROM_WP_BOARDINFO was enabled)
3 Reserved
4 IRQ_GPIO_CHANGE When set a GPIO interrupt has occurred
5 IRQ_TAMPER_DETECT When set a tamper switch interrupt has occurred
6 IRQ_WDOG_TIMEOUT When set a boot watchdog timeout has occurred resulting in the board being reset
7 IRQ_SWITCH_HOLD When set a 'switch hold' interrupt has occurred

For more information see gsc-interrupts

GSC_INTERRUPT_ENABLE (Register R11): Interrupt Enable (refer to bits above)

Bit Name Description
0 IRQ_PB Set to enable pushbutton switch interrupt
1 IRQ_SECURE_KEY_ERASED Set to enable Secure Key erase operation interrupt
2 IRQ_EEPROM_WP Set to enable EEPROM WP violation interrupt
3 Reserved
4 IRQ_GPIO_CHANGE Set to enable GPIO interrupt
5 IRQ_TAMPER_DETECT Set to enable Tamper detect interrupt
6 IRQ_WDOG_TIMEOUT Set to enable Boot Watchdog timeout interrupt
7 IRQ_SWITCH_HOLD Set to enable pushbutton switch 'hold' interrupt

For more information see gsc-interrupts

GSC_FIRMWARE_CRC (Register R12,R13): GSC Firmware CRC Value

Bit Description
0-15 Contains the 16-bit cyclic redundancy check value for the GSP Flash memory (least significant byte first)
The GSC performs a CRC check when R0.4 is set
Once R0.4 is clear, R12 and R13 (16-bit lsb) contain an accurate CRC.

GSC_FIRMWARE_VER (Register R14): GSC Firmware Version

Bit Description
0-7 Contains the GSC firmware version number

GSC_WRITE_PROTECT (Register R15): Write Protection

Bit Name Description
0 GSC_EEPROM_WP_ALL 1 = Write Protect all EEPROM regions
1 GSC_EEPROM_WP_BOARDINFO 1 = Write Protect the reserved Gateworks Board Info EEPROM section
2 Reserved -
3-7 GSC_WP_PASSWD Must be 0xB when altering bits[0:2] (ie write 0x59 (0xB<<3|0x1) to enable WP_ALL)

GSC_RESET_CAUSE (Register R16): Reset Cause

Supported on GSCv3 firmware v53+, the GSC_RESET_CAUSE register describes the event that caused the boards power supply to be reset by the GSC. This register is read by up to date Newport and Venice boot firmware and displays an ASCII flag representation. See the reset cause section for more detail.

Value Name ASCII Flag Description
0 RST_CAUSE_VIN VIN Board power was cycled externally; no reset
1 RST_CAUSE_PB PB User pushbutton
2 Reserved - -
3 RST_CAUSE_CPU CPU CPU watchdog
4 RST_CAUSE_TEMP_LOCAL TEMP_L Board Temperature exceeded spec
5 RST_CAUSE_TEMP_REMOTE TEMP_R CPU Temperature exceeded spec
6 RST_CAUSE_SLEEP SLEEP GSC woke board from sleep
7 RST_CAUSE_BOOT_WDT BOOT_WDT1 Boot watchdog
8 RST_CAUSE_BOOT_WDT_MANUAL BOOT_WDT2 User pushbutton 5x to toggle boot device
9 RST_CAUSE_SOFT_PWR SOFT_PWR Button press from soft power control

GSC_INTERRUPT_SOURCE_1 (Register R17): Interrupt Source 1

Value Name Description
0 GSP_IRQ_OVRTMP_LOCAL When set the local temp rose above CRIT_BOARD_TEMP
1 GSP_IRQ_OVRTMP_REMOTE When set the remote temp sensor asserted its ALERTJ signal

GSC_INTERRUPT_ENABLE_1 (Register R18): Interrupt Enable 1

Value Name Description
0 GSP_IRQ_OVRTMP_LOCAL Set to enable the local temp rose above CRIT_BOARD_TEMP interrupt
1 GSP_IRQ_OVRTMP_REMOTE Set to enable the remote temp sensor asserted ALERTJ signal interrupt

GSC_THERMAL_PROTECT (Register R19): Thermal Protection Configuration

Supported on GSCv3 firmware v53+, the GSC_THERMAL_PROTECT register configures the thermal protection feature.

Bit Name Description
0 GSC_TP_ENABLE 1 = Enable Thermal protection

GSC_BOOT_OPTIONS (Register R21): Boot Control Options

Value Name Description
0 GSC_SWITCH_BOOT_SELECT Boot device select. Clear for primary, set for alt device. This bit is also controlled by the user pushbutton 5x press behavior.

GSC_MEM_ACCESS_PAGE (Register R22): Direct Memory Access Page Number

Value Name Description
0-7 GSC_PAGE_NUMBER Page address offset when direct reading the GSC flash

This API which is implemented over I2C on address 0x5f allows a user to do direct memory reads over the entirety of the accessible memory range (0x0000-0xFFFF). It is used by constructing a 16 bit address with the top byte (a.k.a. page) being set by writing to an undocumented register at address 0x20 offset 0x1f. The bottom byte is then added on via standard I2C protocol. Memory writes are not supported with this API. In order to simplify the usage of this API, a bash script was created that will be posted on the wiki and/or given to FAE's to distribute as they see fit. The name of the script is gsc_direct_mem.sh and the contents are included below.

GSC Direct Memory Read Script

#!/bin/bash

[ "$#" -ne 2 ] && {
        echo "This script acts as a wrapper around I2C commands in order to do direct memory reads of the GSC."
        echo "It will output the i2c response in an i2cdump type format."
        echo
        echo "Usage: $0 <offset> <length>"
        echo
        echo "Example usage to read all 2000(0x7d0) peripheral register values:"
        echo "  $0 0x100 0x7d0"
        exit 1
}

# Store inputs
BUS=0
ADDR=0x5e
OFFSET=$1
LENGTH=$2

# Misc variables
COUNT=0
PAGE=0
PRINTVAL=0x0000
REMAINDER=0
HIGH=
RETURN=

# Calculate initial page number based on passed in offset
PAGE=$((OFFSET / 0x100))
OFFSET=$((OFFSET % 0x100))

echo "      0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f     0123456789abcdef"
while [[ $COUNT -ne $LENGTH ]]; do
        # Set the page number accordingly
        i2cset -f -y 0 0x20 0x16 $PAGE

        # Do either a full i2cdump or specify a range if bytes aren't a 0x100 aligned block
        if [[ $(($LENGTH - $COUNT)) -lt 0x100 || $OFFSET -ne 0 ]]; then
                HIGH=$(($LENGTH - $COUNT - 1 + $OFFSET))
                # Record remainder for i2c 0x100 upper range limit
                if [[ $HIGH -gt 0x100 ]]; then
                        REMAINDER=$(($HIGH + 1 - 0x100))
                else
                        REMAINDER=0
                fi

                RETURN=$(i2cdump -f -y -r ${OFFSET}-$(($HIGH - $REMAINDER)) 0 $ADDR b | grep ':')
                COUNT=$(($HIGH - $REMAINDER - $OFFSET + 1 + $COUNT))
                OFFSET=0
        else
                RETURN=$(i2cdump -f -y 0 $ADDR b | grep ':')
                COUNT=$(($COUNT + 0x100))
        fi

        if [[ "$RETURN" ]]; then # Only print reads
                # Format output to be continuous and account for page increase
                echo "$RETURN" | while read x; do
                        printf "%04x" "$((0x$(echo $x | cut -d':' -f1) + $((PAGE * 0x100))))"
                        echo ":${x##*:}"
                done
        fi

        # Increase the page count
        ((++PAGE))
done

GSC_CTRL_2 (Register R23): Pushbutton, Miscellaneous Configuration

Supported in GSCv3 firmware v58+.

Value Name Description
0 GSC_10X_PRESS_DISABLE Disable 10x press for loading FACTORY registers (see register backup)
1 GSC_SOFT_WAKE_PROTECT Disable waking from soft power press if VIN below board preset minimum

GSC_SOFT_POWER_TIME (Register R26): Soft Power Press Time

Supported in GSCv3 firmware v58+. This register controls how long (in seconds) the pushbutton must be depressed before the board turns on/off via soft power control. The register is composed of an upper and lower nibble that control the minimum power on and power off press times respectively. The register defaults to a power on press time of 0 seconds and a power off press time of 1 second (0x01).

Value Name Description
0-3 GSC_SOFT_POWER_TIME_ON Minimum pushbutton press time required to wake, in seconds
4-7 GSC_SOFT_POWER_TIME_OFF Minimum pushbutton press time required to sleep, in seconds

GSC_REGISTER_BACKUP (Register R31): Register Backup Control

This register has an upper nibble password of value 0xA0 that should be bitwise OR'd with an enumerated value in the lower nibble that will be interpreted as the command. This register will self clear when the operation has completed. See the below Register Save/Load section for more information.

Value Name Description
1 GSC_REG_BKP_SAVE Save current register values to USER backup area
2 GSC_REG_BKP_USER_LOAD Load register values from USER backup
3 GSC_REG_BKP_FACTORY_LOAD Load register values from FACTORY backup
4-7 GSC_REG_BKP_PASSWORD Password for upper nibble (0xA0). Bitwise OR this value with lower nibble enumerated values described above

Real Time Clock

The 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 0x68. The RTC is compatible with the standard Linux ds1672 RTC driver and thus works with the standard Linux RTC device API. The RTC device will be /dev/rtc0 and adheres to the standard ioctl and sysfs API's.

The most common Linux RTC commands are (refer to the linux man pages for more info on the commands and the available time/date formats):

Note that typical Linux based systems use a Real Time Clock as such:

System Temperature and Voltage Monitor

The 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. The register mapping differs depending on the version of the GSC:

GSCv3 (GW6xxx/GW5910/GW5913)

The following 16-bit registers (MSB first, LSB second) are available:

system monitor registers:

Name Register Note
Board Temp 0x06 Deg C/10
VBatt 0x08 Volts/1000
FAN0 0x0A Fan setpoint 0 1
FAN1 0x0C Fan setpoint 1 1
FAN2 0x0E Fan setpoint 2 1
FAN3 0x10 Fan setpoint 3 1
FAN4 0x12 Fan setpoint 4 1
FAN5 0x14 Fan setpoint 5 1
FAN_TACH 0x16 FAN TACH pulses per second
ADC A0 0x80 Raw ADC value 2
ADC A1 0x82 Raw ADC value 2
ADC A2 0x84 Raw ADC value 2
ADC A3 0x86 Raw ADC value 2
ADC A4 0x88 Raw ADC value 2
ADC A5 0x8A Raw ADC value 2
ADC A6 0x8C Raw ADC value 2
ADC A7 0x8E Raw ADC value 2
ADC A8 0x90 Raw ADC value 2
ADC A9 0x92 Raw ADC value 2
ADC A10 0x94 Raw ADC value 2
ADC A11 0x96 Raw ADC value 2
ADC A12 0x98 Raw ADC value 2
ADC A13 0x9A Raw ADC value 2
ADC A14 0x9C Raw ADC value 2
ADC A15 0x9E Raw ADC value 2
ADC A30 0xA0 Raw ADC value 2
ADC A31 0xA2 Raw ADC value 2
  1. See fan below
  2. Consult individual board hardware manual or the Linux device-tree for a description of what voltage rail this is and what voltage divider is applied in order to scale it. The Newport Linux kernel and BDK use information from the Linux Device-tree to scale and name these ADC's. Note also that Vin (Board Input voltage) is evaluated at the board's primary power supply input and offset by an estimated diode drop and thus may differ from your actual power supply within a volt or so.

A Linux 'Hardware Monitor' (hwmon) driver is available 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. The hwmon will be found in /sys/class/hwmon/hwmonx where x is a number. Check all hwmonx directories, starting with x=0 and then x=1 until identifying the correct hwmon where the values are contained.

Example ran on a GW62xx using Ubuntu Bionic:

cd /sys/class/hwmon/hwmon1
for F in *;do echo -n $F: ;cat $F;done
in0_input:2762
in0_label:vdd_bat
in10_input:1483
in10_label:vdd_1p5
in11_input:4998
in11_label:vdd_an1
in12_input:3258
in12_label:vdd_gsc
in1_input:491
in1_label:fan_tach
in2_input:15468
in2_label:vdd_vin
in3_input:4943
in3_label:vdd_5p0
in4_input:3398
in4_label:vdd_3p3
in5_input:2456
in5_label:vdd_2p5
in6_input:867
in6_label:vdd_core
in7_input:907
in7_label:vdd_0p9
in8_input:979
in8_label:vdd_1p0
in9_input:1189
in9_label:vdd_1p2
name:gsc_hwmon
pwm1_auto_point1_pwm:127
pwm1_auto_point1_temp:30000
pwm1_auto_point2_pwm:153
pwm1_auto_point2_temp:33000
pwm1_auto_point3_pwm:178
pwm1_auto_point3_temp:36000
pwm1_auto_point4_pwm:204
pwm1_auto_point4_temp:39000
pwm1_auto_point5_pwm:229
pwm1_auto_point5_temp:42000
pwm1_auto_point6_pwm:255
pwm1_auto_point6_temp:45000
temp1_input:46000
temp1_label:temp

Note that the standard sysfs entries for hwmon drivers are such that temperatures are in millidegrees celcius and voltages are in millivolts.

GSC v1/v2 (Laguna/Ventana)

A single temperature sensor provides the board temperature in a 16-bit value (MSB first, LSB second) at register offset 0x00 in degrees Celcius. The voltage based ADC inputs provides a voltage (millivolt) as a 24-bit value (MSB first, LSB last). The ADC measurements are performed once per second (1Hz).

The 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)

system monitor registers:

Name Register Parameter Units Description
temp1 0x00 Temperature Deg C/10 SBC Temperature
vin 0x02 Voltage Volts/1000 SBC Input Voltage
3p3 0x05 Voltage Volts/1000 3.3V
bat 0x08 Voltage Volts/1000 GSC Coin Cell Battery
5p0 0x0B Voltage Volts/1000 5.0V
core 0x0E Voltage Volts/1000 Primary Processor Core
cpu1 0x11 Voltage Volts/1000 Primary Processor 1 Operating
cpu2 0x14 Voltage Volts/1000 Primary Processor 2 Operating
dram 0x17 Voltage Volts/1000 System DRAM Memory
ext_bat 0x1A Voltage Volts/1000 GSC External Battery (not in use)
io1 0x1D Voltage Volts/1000 Miscellaneous
io2 0x20 Voltage Volts/1000 Miscellaneous
pcie 0x23 Voltage Volts/1000 PCI Express
io3 0x26 Voltage Volts/1000 Miscellaneous
io4 0x29 Voltage Volts/1000 Miscellaneous
fan0_point0 0x2C Temperature Deg C/10 Fan controller set point 0
fan0_point1 0x2E Temperature Deg C/10 Fan controller set point 1
fan0_point2 0x30 Temperature Deg C/10 Fan controller set point 2
fan0_point3 0x32 Temperature Deg C/10 Fan controller set point 3
fan0_point4 0x34 Temperature Deg C/10 Fan controller set point 4
fan0_point5 0x36 Temperature Deg C/10 Fan controller set point 5

A 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.

For systems without the GSC Hardware Monitor driver, values can be read directly through I2C: Example: Temperature is shown as register 0x00 and 0x01.

i2cget -f -y 0 0x29 1
0x01
i2cget -f -y 0 0x29 0
0xc0

Combining 0x01 and 0xc0, is 0x01c0, which comes out to be 448, which divided by 10, equals 44.8 Deg. C.

For Ventana i.MX6 processor temperature, see here

Battery Voltage Reading

The battery voltage rail (vdd_bat) is only able to be measured when the GSC is actually powered off of the battery.

In some cases you can use the GSC to disable primary board power (referred to as 'GSC Sleep') for a number of seconds in order to refresh the vdd_bat reading. GSCv2 only requires an off time of 3 seconds in order to read the battery. GSCv3 however requires 35 seconds as it's lower power consumption is not guaranteed to consume the VCC capacitance until that time. In other cases some boards have a GSC_Backup regulator which powers the GSC from Vin even when the GSC has disabled the board's primary power to preserve the GSC battery life and those boards require the board's input power to be fully removed in order to read the GSC battery voltage.

Boards with a GSC Backup regulator which require board power to be fully removed to re-fresh the GSC battery voltage reading are:

When a GSC is running from the GSC battery it refreshes the battery voltage reading a second or so after it starts running off the battery (ie after board power is removed) as well as every 18 hours.

Fan Controller

*Note: This feature is only on certain baseboards. Please consult the hardware manual.

A 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 (half on, half off) to 100 percent (fully on). See the below chart for the PWM duty cycle versus temperature set points.

*Note: typically the PWM occurs on the ground pin, and the 5V is constant on the connector. However, consult the hardware manual for the boards specific configuration. For more info on PWM see the following link PWM.

Source Default (°C/10) Description
Fan0_point0 300 Set point 0 = 50% PWM duty cycle
Fan0_point1 330 Set point 1 = 60% PWM duty cycle
Fan0_point2 360 Set point 2 = 70% PWM duty cycle
Fan0_point3 390 Set point 3 = 80% PWM duty cycle
Fan0_point4 420 Set point 4 = 90% PWM duty cycle
fan0_point5 450 Set point 5 = 100% PWM duty cycle

The 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.

The fan controller setpoints are supported via the linux Hardware Monitor (gsc_hwmon) driver.

Examples:

Always-on FAN for a constant voltage source

Occasionally users want to keep the FAN controller always-on in order to provide a constant voltage source.

To 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).

Examples:

General Purpose Input and Output (GPIO)

The 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 PCA9555 Datasheet. The I2C address for the PCA9555 is 0x23.

Each board level product has a unique GPIO configuration. Refer to the specific board hardware user manual for more details.

The most common Linux GPIO commands are:

Note 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.

To 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.

For example to set all P0 and P1 bits as outputs from Linux:

i2cset -f -y 0 0x23 6 0x00 # configure GPIO P0_DIR as outputs
i2cset -f -y 0 0x23 7 0x00 # configure GPIO P1_DIR as outputs

See also:

User Pushbutton

The 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:

The 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 (R0) register. For example:

The gpio-keys kernel driver will produce Linux Input events for the above interrupts.

In 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:

Family Boards gsc gpio linux gpio
Venice All i2c/0-0023 pca9555 gpio2 gpio498
Newport All i2c/0-0023 pca9555 gpio2 gpio450
Ventana GW5xxx i2c/0-0023 pca9555 gpio0 gpio240
Laguna GW2380/GW2382/GW2383 i2c/0-0023 pca9555 gpio8 gpio108
Laguna GW2387/GW2388/GW2391 i2c/0-0023 pca9555 gpio0 gpio100

An 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 because it involves starting a timer on a button-down event and counting the time expired before any button-up event occurs.

The Linux kernel gpio-keys and gpio-keys-polled (and OpenWrt gpio-button-hotplug) drivers can be used to create Linux Input events from GPIO events and interrupt events.

BSP Specific Notes:

In Summary you have a few options for performing actions based on user pushbutton events depending on your needs and BSP.

See also:

gsc-interrupts

Code Examples for software user pushbutton detection

The following example will configure the GSC for SW pushbutton interrupt and read the PB state by polling the GPIO (see above):

# clear R0.1 bit to disable pushbutton hard reset - taking care to not disturb other bits
R0=$(i2cget -f -y 0 0x20 0) && \
  R0=$((R0 & ~0x01)) && \
  i2cset -f -y 0 0x20 0 $R0 || echo i2c error
# export gpio240 to userspace (Note this value is board specific - see above table)
# If using mainline BSP with different GPIO ranges "cat /sys/kernel/gpio" look for pca9555 emulated over i2c, if Ventana use lowest number in range, if Newport use lowest number in range + 2
echo 240 > /sys/class/gpio/export
while [ 1 ]; do
  cat /sys/class/gpio/gpio240/value ;# PB state 0 or 1
done

A 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 Catching a GPIO from Userspace w/o polling for an example of how to do that.

See also:

EEPROM storage

The 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.

Address Device Address Size (bytes) Function
0x000-0x0FF 0x50: 0x00-0xFF 256 User EEPROM space
0x100-0x17f 0x51: 0x00-0x7F 128 Board Info EEPROM 1
0x180-0x1DF 0x51: 0x80-0xDF 96 5 Secure Key EEPROM 2
0x1E0-0x1FF 0x51: 0xE0-0xFF 32 Reserved
0x200-0x2FF 0x52: 0x00-0xFF 256 User EEPROM space 3
0x300-0x3FF 0x53: 0x00-0xFF 256 User EEPROM space 3
  1. Board Info EEPROM is reserved for Gateworks
    • Can be write protected by enabling EEPROM_WP_BOARDINFO (R15.1)
    • Information about board serialnum, model, manufacturing date, etc can be found in the EEPROM - see here for details
  2. Secure Key EEPROM is erased if:
    • Pushbutton is activated 3 times in quick succession (press-and-released <700ms delay between each activation). This function is enabled with R0.1
    • Tamper circuit has been activated (for boards supporting a tamper switch/header)
    • The GSC battery is depleted or is removed for more than ~35 seconds
    • Note that these cases will always erase the secure key EEPROM region regardless of the Write Protect bits
  3. Additional 4Kbits (512bytes) available on GW2387/GW2388/GW2391)
  4. There are 2 bits in GSC_CTRL_1 (R1) which act as a Write Protect for EEPROM regions:
  5. GSCv3 provides 128 bytes of secure key area instead of 96

GSC firmware update Notes:

EEPROM Secure Key Example

The secure key area starts at 0x51 offset 0x80 and extends for 96 bytes for GSC v1/v2 and for 128 bytes for GSCv3.

To see the secure key, you can use the command i2cdump from the command line: (starts at offset 0x80 and ends with 0xdf in below example)

> i2cdump -f -y 0 0x51
No size specified (using byte-data access)

<<--------------- HEX GRID --------------------->>     << ASCII VALUE>>
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f    0123456789abcdef
00: 00 d0 12 a9 ef f8 00 d0 12 a9 ef f9 ff ff ff ff    .?????.?????....
10: ff ff ff ff ff ff ff ff cb 5b 09 00 ff ff ff ff    ........?[?.....
20: 11 27 20 13 ff ff ff ff ff ff ff 05 0c 02 18 08    ?' ?.......?????
30: 47 57 35 32 30 30 2d 53 50 32 38 33 2d 41 00 00    GW5200-SP283-A..
40: 06 00 b5 4d 33 f0 01 00 c9 00 00 00 00 00 25 d0    ?.?M3??.?.....%?
50: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
60: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
70: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
80: 44 33 ff ff ff ff ff ff ff ff ff ff ff ff ff ff    D3..............
90: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
a0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
b0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
c0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
d0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff 77    ...............w
e0: XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX    XXXXXXXXXXXXXXXX
f0: XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX    XXXXXXXXXXXXXXXX

To 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.

i2cset -f -y 0 0x51 0x80 0x3344 w

To Write a single byte:

i2cset -f -y 0 0x51 0x80 0x33

Custom Serial Number Example

For 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.

Here, a customer specific serial number is created in the userspace EEPROM. For example using the first 6 bytes of userspace EEPROM to store a 6 digit serial number in ASCII representation:

i2cset -f -y 0 0x50 0x0 0x3535 w
i2cset -f -y 0 0x50 0x2 0x3737 w
i2cset -f -y 0 0x50 0x4 0x3939 w

Then, a i2cdump will show the serial number stored:

> i2cdump -f -y 0 0x50
No size specified (using byte-data access)
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f    0123456789abcdef
00: 35 35 37 37 39 39 ff ff ff ff ff ff ff ff ff ff    557799..........
10: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
20: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
30: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
40: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
50: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
60: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
70: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
80: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
90: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
a0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
b0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
c0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
d0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
e0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................
f0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff    ................

To retrieve it, use the i2cget command:

> i2cget -f -y 0 0x50 0x0 w
0x3535

Hardware Sleep and Wake

The GSC 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 or similar power source). There are two ways the GSC can engage a board sleep event, via register timers or pushbutton hold.

Pushbutton Sleep

Setting PB_SOFT_POWER_DOWN R0.2 configures the GSC to do an indefinite hardware sleep if the pushbutton is held for more than 1 second. In order to wake from a sleep started via pushbutton, the pushbutton must be pressed again. This should not be confused with SWITCH_HOLD R0.6 which will enable a software interrupt when the pushbutton is held for more than 700ms. Both can be set, but typically one is opted for over the other.

As of GSCv3 firmware v58, GSC_SOFT_POWER_TIME (R26) can be used to configure the required press times for both the sleep and wake events. By default the value is 0x01 which retains the old behavior of 1 second press to sleep and immediate press to wake.

An example of setting the wake press time to 4 seconds and the sleep press time to 3 seconds:

# Set R26 to 0x43 for 4 second wake and 3 second sleep times
i2cset -f -y 0 0x20 26 0x43

Register Timer Sleep

Registers GSC_CTRL_1 (R1) and either GSC_SLEEP_WAKE_TIME (R2-R5) or GSC_SLEEP_ADD (R6-R9) can be used to put the board to sleep via i2c. In this situation 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_TIME (R2-R5) registers. The wakeup time can either be set to an absolute RTC time by writing directly to GSC_SLEEP_WAKE_TIME (R2-R5) or be set relative to the current RTC value by writing to GSC_SLEEP_ADD (R6-R9) and then latching it by setting LATCH_SLEEP_ADD (R1.2). After GSC_SLEEP_WAKE_TIME (R2-R5) has been set using either of the aforementioned methods, setting ACTIVATE_SLEEP (R1.1) will put the board to sleep.

Once asleep, the GSC will automatically wake the board after the RTC time has reached the GSC_SLEEP_WAKE_TIME (R2-R5) value. Alternatively, a pushbutton press will also wake the board unless the SLEEP_NOWAKEPB (R1.3) bit is set.

Board sleeping Example

The preferred method is to use the sysfs powerdown hook from the GSC driver as this takes care of the math and retries for you:

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.

SECS=300 ;# 5 mins
i2cset -f -y 0 0x20 6 $((SECS % 256)); SECS=$((SECS >> 8))
i2cset -f -y 0 0x20 7 $((SECS % 256)); SECS=$((SECS >> 8))
i2cset -f -y 0 0x20 8 $((SECS % 256)); SECS=$((SECS >> 8))
i2cset -f -y 0 0x20 9 $((SECS % 256))
# set add time bit - taking care to not disturb other bits
R1=$(i2cget -f -y 0 0x20 1) && \
  R1=$((R1 | 0x04)) && \
  i2cset -f -y 0 0x20 1 $R1 || echo i2c error
# set sleep enable and sleep activate bits - taking care not to disturb other bits
R1=$(i2cget -f -y 0 0x20 1) && \
  R1=$((R1 | 0x03)) && \
  i2cset -f -y 0 0x20 1 $R1 || echo i2c error

The 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 GSC_SLEEP_WAKE_TIME (R2-R5) to the number of seconds since the epoch (date +%s will show current system time in seconds).

GSC Reboot

The GSC can also be used to reboot the board. See the following link for more info:

Alternate Boot Device

Some Gateworks family products have an Alternate boot device that can be used for multiple firmware images, such as a flash recovery image. There are a number of ways that you can instruct the GSC to boot to the alternate boot device vs the primary boot device:

  1. Press-and-release the user pushbutton 5 times in quick succession (see PB_BOOT_ALTERNATE (R0.3))
  2. Use the Auto Switch Boot feature
  3. Use the GSC_BOOT_OPTIONS (R21) register and power cycle (GSCv3 firmware v57+)

More details on using the Alternate Boot Device can be found here.

Auto Switch Boot Device

If the board is equipped with an alternate boot device such as a micro SD, you can enable the GSC's Auto Switch Boot feature by setting SWITCH_BOOT_ENABLE (R1.6).

GSCv2: When a board powers on with this bit set, a 30 second boot watchdog timer begins counting down. If this timer expires before SWITCH_BOOT_CLEAR (R1.7) is set, the GSC will toggle the boot device* and power-cycle the board. Most up to date bootloader firmware provided by Gateworks will set this boot check bit automatically, but you can manually disable the timer by setting SWITCH_BOOT_CLEAR (R1.7) via i2c. Either way it will be re-armed on the next power cycle unless SWITCH_BOOT_ENABLE (R1.6) has been cleared.

GSCv3 (firmware v57+): The boot watchdog is forced on and SWITCH_BOOT_ENABLE (R1.6) only controls whether or not the next boot attempt will toggle the boot device.

For example, if you a supporting firmware updates in your product but want a mechanism to ensure a failed firmware update does not render your device unrecoverable 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 SWITCH_BOOT_CLEAR (R1.7) within 30 seconds of bootup if that firmware image is desirable. If either image fails to set this bit within the 30 seconds, the board will automatically power cycle and boot to the other device.

More details on using the Auto Switch Boot Device can be found here.

Tamper Detection

Some 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).

For these boards you can enable the GSC's Tamper Detect feature by setting TAMPER_DETECT (R0.5) and the accompanying interrupt enable register bit IRQ_TAMPER_DETECT (R11.5). Once these bits are set any tamper event produced by a switch closing and the signal conducting to board ground will do the following:

  1. Set IRQ_TAMPER_DETECT (R10.5) interrupt status bit
  2. Erase the Secure Key EEPROM section
  3. Produce a GSC interrupt if board is powered (see gsc-interrupts)

GPS Active Antenna short-circuit auto detect and recover

On 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:

  1. Over-current protection keeps board power available if an antenna short/fault has occurred
  2. A shorted/faulty antenna can be replaced without having to power down the board

Products with GPS antenna protection (GPS is not loaded on all model variants, contact sales@… for details):

Family Board Overcurrent Protection Recovery
Newport GW640X Current Limit No
GW630X Current Limit No
GW620X Current Limit No
GW610X Current Limit No
Ventana GW51XX Current Limit No
GW52XX Current Limit No
GW53XX Yes Yes
GW54XX Yes Yes
GW553X Yes No
Laguna GW2387 Yes Yes
GW2388 Yes No
GW2391 Yes Yes

GSC Reset Cause (GSCv3 firmware v53+)

On most boards, the Gateworks System Controller has the ability to disable primary board power. This is used as a form of 'hard reset' in many cases. You can determine if and why the board was hard reset by looking at the value of the GSC_RESET_CAUSE (R16) register.

Note that the current Venice and Newport boot firmware will display the reason on bootup. Note that the value of 0, reported as 'VIN' indicates the GSC did not reset the board power supply and the board reset because of Vin being externally cycled.

Example:

The value provided in the GSC banner above after "RST:" will be a short ASCII string.

Consult the associated register table for numerical value and ASCII flag string definitions.

GSC Thermal Protection (GSCv3 firmware v53+)

The Gateworks System Controller has the ability to monitor board temperature and CPU temperature and disable board primary power when either of those exceeds specified values.

If either the GSC 'board temperature' exceeds 85C or the 'external thermal sensor' exceeds its threshold (100C for Newport CPU Junction Temperature (Tj)) the GSC will disable the primary power supply for a 'cooldown period'. The cooldown period has a range of 5-300 seconds, and will increase from 5 by 30 seconds each time a thermal threshold event occurs. If no thermal threshold event occurs within 300 seconds of power-up the cooldown period will be reset to the minimum of 5 seconds.

This feature is present on:

Thermal protection is controlled by GSC_THERMAL_PROTECT (R19).

Note: Thermal protection is enabled automatically by current Gateworks boot firmware. This is indicated by "Thermal Protection Enabled" as seen in the SPL output below:

GSC     : v53 0x0e68 RST:VIN Thermal Protection Enabled

GSC Interrupts

The 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_0 (R11) register defines what events can trigger an interrupt and an interrupt service routine can query the GSC_INTERRUPT_STATUS_0 (R10) 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_0 (R10) register.

GSCv3 has an additional pair of interrupt registers represented by GSC_INTERRUPT_STATUS_1 (R17) and GSC_INTERRUPT_ENABLE_1 (R18).

IRQ_PB interrupt

The 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 (R0) register for this to occur otherwise a pushbutton will cause a hard board reset.

See also:

IRQ_SWITCH_HOLD interrupt

The IRQ_SWITCH_HOLD interrupt occurs if SWITCH_HOLD is enabled in the GSC_CTRL_0 (R0) register and the user pushbutton was held for over 1 second.

See also:

IRQ_SECURE_KEY_ERASED interrupt

The 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 (R0.5)) or because 3x quick button press-and-release events have occurred (see PB_CLEAR_SECURE_KEY (R0.1)).

See also:

IRQ_EEPROM_WP interrupt

The IRQ_EEPROM_WP interrupt occurs if the GSC_EEPROM_WP_ALL or GSC_EEPROM_BOARDINFO bits are set in the GSC_WRITE_PROTECT (R15) register and a write protect violation has occurred.

See also:

IRQ_GPIO_CHANGE interrupt

The 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.

Note 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).

Note 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.

To 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.

For example to set all P0 and P1 bits as outputs from Linux:

i2cset -f -y 0 0x23 6 0x00 # configure GPIO P0_DIR as outputs
i2cset -f -y 0 0x23 7 0x00 # configure GPIO P1_DIR as outputs

See also:

IRQ_TAMPER_DETECT interrupt

The IRQ_TAMPER_DETECT interrupt occurs if TAMPER_DETECT has been enabled in the GSC_CTRL_0 (R0) 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.

See also:

IRQ_WDOG_TIMEOUT interrupt

The IRQ_WDOG_TIMEOUT interrupt indicates that the GSC boot 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.

Note that the Ventana bootloader reads and clears this status register but displays the result.

Hardware Boot Watchdog

Gateworks boards benefit from a GSC Boot Watchdog which will cause a primary board power supply reset if the bootloader fails to load and disable it within 30 seconds. This protects against occasional chip errata that our hardware has no control over.

Register Save/Load (GSCv3 firmware v57+)

With the release of GSCv3 firmware version v57 the GSC now has the ability to save and load the control register set. The registers affected are all registers available from the 0x20 chip address, with the exception of non control registers such as the status, CRC, and firmware version registers.

The register saves are stored in a non volatile section of memory, allowing them to persist across power loss events. When the the GSC resets for whatever reason, it will first attempt to load the register values from the USER_DEFAULTS section if values previously saved by the user exist. Otherwise the FACTORY_DEFAULTS values will be loaded instead.

There are currently two places registers are saved, a non user accessible FACTORY_DEFAULTS section that is populated with the factory programmed register values, and a USER_DEFAULTS section that contains the current control register values when the user executes a GSC_REG_BKP_SAVE command via register GSC_REGISTER_BACKUP (R31) described above. From this register, a user can remotely load register defaults from either location. As an additional recovery measure, a 10x press of the pushbutton will load the values stored in the FACTORY_DEFAULTS location and reset the GSC as well as powercycle the board.

I2C communication with the GSC

The GSC communicates with the SoC via i2c at a maximum clock rate of 100KHz.

GSC v1 and v2 (see above) may occasionally be busy and fail to ACK an i2c master transaction within the bit timing. The GSCv3 used in the Newport and newer product families is not susceptible to this.

Reading the GSC registers example using i2cget:

# i2cget -f -y <BUS> <DEVICE-ADDRESS> <REGISTER>
# For the GSC, always use 0 and 0x20 for the BUS and DEVICE
# Read the GSC version from R14:
i2cget -f -y 0 0x20 14

Occasional I2C NAK's

I2C NAK's can occur on GSC v1 and v2. 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.

For this reason, you should retry and i2c read/write calls up to 3 times if the failure is a NAK (failure to ACK).

Note that the GSC registers are 8bit values where each bit has a different meaning. To read/modify/write you should do the following:

  1. read register value
  2. mask out the bits your going to clear (or set) (&= ~(mask))
  3. set the bits your going to set

An example of how you can do this as well as check for i2c read/write errors using shell is the following:

R0=$(i2cget -f -y 0 0x20 0) && \
  R0=$((R0 & ~0x05)) && \
  R0=$((R0 |  0x04)) && \
  i2cset -f -y 0 0x20 0 $R0 || echo i2c error

GSC Drivers

Linux drivers exists in the Gateworks BSP's that exposes some very useful GSC functionality:

GSC Core Linux kernel driver

The gsc-core driver provides the following:

Examples:

Device-tree bindings for the KEYBOARD_GPIO (gpio-keys) driver are used to map the user pushbutton gpio as well as the other GSC status interrupt events to Linux input events.

These actions depend on the manual user configuration of the GSC_CTRL_0 (R0) register. The driver does 'not' force a configuration upon the user. Note that all Gateworks boards ship with pushbutton configured as a hard-reset (R0.0=1) 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.

The following table shows what linux input EV_KEY event is sent for each event:

interrupt key event requirements notes
N/A (gpio) BTN_0 user button state change R0.0=0 (hard reset disabled)
0 BTN_1 user button press/release within 700ms R0.0=0 (hard reset disabled) event fires appx 1s after the press
1 BTN_2 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
2 BTN_3 user eeprom write-protect violation
5 BTN_4 tamper event R0.5=1 (tamper detect enabled)
7 BTN_5 user button held >700ms R0.6=1 (switch hold enabled) event fires 700ms after press

The driver does not alter the configuration of GSC_CTRL_0 (R0) so the user must do so manually depending on their interests. Some example configurations are:

Example:

User Pushbutton Notes:

Reset Monitor

The third generation GSC used on the Newport product family acts as a hardware reset monitor for the board. For this feature the GSC monitors board-specific voltage rails before letting the CPU come out of reset.

GSC Updates

From 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:

Notes:

GSC Firmware Downloads:

GSC Version History

Latest GSC revisions per baseboard:

family board revision
Venice GW7000 v58
Newport GW640x v58
GW630x v58
GW620x v58
GW610x v58
Ventana GW553x v50
GW552x v50
GW551x v50
GW54xx v50
GW53xx v50
GW52xx v50
GW51xx v50
GW5910 v58
GW5913 v58
Laguna GW2391 v50
GW2388 v50
GW2387 v50
GW2383 v50
GW2382 v50
GW2380 v50

The following represents the revision history for externally released GSC firmware revisions:

GSC Version

Type the following command from the command prompt on the board. This will return a hex value:

i2cget -f -y 0 0x20 14

Battery / Battery Replacement

The coin cell battery used provides power for the GSC to run while board power is removed (or in some cases when the GSC has removed the board's primary power via GSC sleep).

The shelf life of the battery defines how long the GSC retains power and thus its settings such as the RTC when board power is removed and depends on the version of the GSC:

Battery Replacement

Battery Replacement Details:

Firmware Reset Default conditions

The following items are reset if the battery is removed for more than 10 seconds or if the GSC firmware has been updated:

Board Storage with respect to Battery

When a board is powered on, the GSC will draw power from the primary power supply and not it's coincell battery.

However, 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 for years. Battery life will vary based on environmental conditions such as temperature. (see datasheet).

Care 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.

Attachments (2)

Download all attachments as: .zip