Changes between Version 52 and Version 53 of gsc


Ignore:
Timestamp:
07/02/2020 07:51:26 PM (7 months ago)
Author:
Tim Harvey
Comment:

update the GSC driver section

Legend:

Unmodified
Added
Removed
Modified
  • gsc

    v52 v53  
    10901090[=#drivers]
    10911091= GSC Drivers =
    1092 A set of Linux drivers exists in the Gateworks BSP's that exposes some very useful GSC functionality:
     1092Linux drivers exists in the Gateworks BSP's that exposes some very useful GSC functionality:
    10931093 * gsc-core driver
    1094  * gsc-watchdog driver
    1095  * gsc-input driver
     1094 * gsc-hwmon driver
    10961095
    10971096== GSC Core Linux kernel driver ==
     
    11131112}}}
    11141113
    1115 
    1116 [=#wdtdriver]
    1117 == GSC Watchdog kernel driver ==
    1118 Note that Newport boards do not need or use the GSC Watchdog (see [#watchdog above]).
    1119 
    1120 The 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.
    1121 
    1122 Note that the GSC watchdog function is available in GSC firmware v44 and beyond.
    1123 
    1124 In 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.
    1125 
    1126 The 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.
    1127 
    1128 To enable the GSC watchdog:
    1129  * in linux:
    1130 {{{
    1131 #!bash
    1132 i2cset -f -y 0 0x20 1 0x20 ;# enable for 30 second timeout
    1133 # or
    1134 i2cset -f -y 0 0x20 1 0x30 ;# enable for 60 second timeout
    1135 }}}
    1136  * in Ventana bootloader:
    1137 {{{
    1138 #!bash
    1139 gsc wd enable 30 # enable watchdog for 30s timeout
    1140 # or
    1141 gsc wd enable 60 # enable watchdog for 60s timeout
    1142 }}}
    1143  * in Laguna bootloader:
    1144 {{{
    1145 #!bash
    1146 i2c dev 0 && i2c mw 0x20 1 0x20 1 # set R1=0x20 to enable watchdog for 30s timeout
    1147 # or
    1148 i2c dev 0 && i2c mw 0x20 1 0x30 1 # set R1=0x30 to enable watchdog for 60s timeout
    1149 }}}
    1150 
    1151 The following requirements exist for using the GSC watchdog with the GSC watchdog driver:
    1152  1. user manually enables the watchdog by setting GSC CTRL_1 bit 6 (see above)
    1153  2. GSC has v44 or newer firmware
    1154  3. GSC driver is enabled in the kernel (latest OpenWrt 14.08 BSP, Yocto v1.6+ BSP, Android Kitkat BSP)
    1155  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)
    1156 
    1157 BSP specific notes:
    1158  * OpenWrt 14.08+:
    1159   * 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)
    1160   * 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}}}
    1161   * you can tell procd to stop tickling the watchdog to test the affect:
    1162 {{{
    1163 #!bash
    1164 ubus call system watchdog '{ "stop": true }'  # system will reset when wd timeout occurs
    1165 }}}
    1166  * Yocto v1.6+:
    1167   * 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):
    1168 {{{
    1169 #!bash
    1170 # create conf file
    1171 cat << EOF > /etc/watchdog.conf
    1172 watchdog-device = /dev/watchdog
    1173 realtime = yes
    1174 priority = 1
    1175 interval = 5
    1176 watchdog-timeout = 30
    1177 EOF
    1178 
    1179 # create an init service script
    1180 cat << EOF > /etc/init.d/watchdog
    1181 #!/bin/sh
    1182 
    1183 watchdog
    1184 EOF
    1185 
    1186 # make it executable
    1187 chmod +x /etc/init.d/watchdog
    1188 
    1189 # configure as a system service to start on boot, priority 1
    1190 update-rc.d watchdog defaults 1
    1191 sync
    1192 }}}
    1193  * Android kk+:
    1194   * 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
    1195 
    1196 Notes:
    1197  * see [wiki:watchdog] for more info
    1198 
    1199 [=#inputdriver]
    1200 == GSC Input kernel driver ==
    1201 The 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.
    1202 
    1203 All 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.
    1204 
    1205 The following table shows what linux input EV_KEY event is sent for each interruptable configuration:
     1114Device-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.
     1115
     1116These actions depend on the manual user configuration of the [#gsc_ctrl_0 GSC CTRL_0] 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.
     1117
     1118The following table shows what linux input EV_KEY event is sent for each event:
    12061119||= interrupt =||= key =||= event                                                 =||= requirements                                           =||= notes =||
    1207 || 0           || BTN_0 || user button press/release within 700ms                  || R0.0=0 (hard reset disabled)                             || event fires appx 1s after the press ||
    1208 || 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 ||
    1209 || 2           || BTN_2 || user eeprom write-protect violation                     || || ||
    1210 || 4           || BTN_3 || gpio change                                             || R0.0=0 (hard reset disabled)                            || ||
     1120|| N/A (gpio)  || BTN_0 || user button state change                                || R0.0=0 (hard reset disabled)
     1121|| 0           || BTN_1 || user button press/release within 700ms                  || R0.0=0 (hard reset disabled)                             || event fires appx 1s after the press ||
     1122|| 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 ||
     1123|| 2           || BTN_3 || user eeprom write-protect violation                     || || ||
    12111124|| 5           || BTN_4 || tamper event                                            || R0.5=1 (tamper detect enabled)                           || ||
    12121125|| 7           || BTN_5 || user button held >700ms                                 || R0.6=1 (switch hold enabled)                             || event fires 700ms after press ||
     
    12221135  * please see [#IRQ_GPIO_CHANGE here] regarding un-terminated inputs causing spurious GPIO_CHANGE events
    12231136
    1224 BSP Specific notes:
    1225  * OpenWrt (14.08 and below only):
    1226   - OpenWrt does not typically do anything with Linux input events. If you are interested in user pushbutton press-release events see [#pushbutton pushbutton]
    1227   - you can use the event_test application to show Linux Input events:
    1228 {{{
    1229 #!bash
    1230 > event_test /dev/input/event0
     1137Example:
     1138 - use the {{{evtest}}} application to show Linux Input events:
     1139{{{
     1140#!bash
     1141# evtest /dev/input/event0
    12311142Input driver version is 1.0.1
    1232 Input device ID: bus 0x0 vendor 0x0 product 0x0 version 0x0
    1233 Input device name: "gsc_input"
    1234 Supported events:
    1235   Event type 0 (Reset)
    1236     Event code 0 (Reset)
    1237     Event code 1 (Key)
    1238   Event type 1 (Key)
    1239     Event code 256 (Btn0)
    1240     Event code 257 (Btn1)
    1241     Event code 258 (Btn2)
    1242     Event code 259 (Btn3)
    1243     Event code 260 (Btn4)
    1244     Event code 261 (Btn5)
    1245 Testing ... (interrupt to exit)
    1246 Event: time 1435938985.047196, type 1 (Key), code 259 (Btn3), value 1
    1247 Event: time 1435938985.047196, type 1 (Key), code 259 (Btn3), value 0
    1248 Event: time 1435938985.047196, type 0 (Reset), code 0 (Reset), value 0
    1249 Event: time 1435938985.047217, type 1 (Key), code 256 (Btn0), value 1
    1250 Event: time 1435938985.047217, type 1 (Key), code 256 (Btn0), value 0
    1251 Event: time 1435938985.047217, type 0 (Reset), code 0 (Reset), value 0
    1252 }}}
    1253   * 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)
    1254  * Yocto:
    1255   - you can use the evtest application to show Linux Input events:
    1256 {{{
    1257 #!bash
    1258 > evtest /dev/input/event0
    1259 Input driver version is 1.0.1
    1260 Input device ID: bus 0x0 vendor 0x0 product 0x0 version 0x0
    1261 Input device name: "gsc_input"
     1143Input device ID: bus 0x19 vendor 0x1 product 0x1 version 0x100
     1144Input device name: "gpio_keys"
    12621145Supported events:
    12631146  Event type 0 (EV_SYN)
     
    12711154Properties:
    12721155Testing ... (interrupt to exit)
    1273 Event: time 1435939364.644274, type 1 (EV_KEY), code 259 (BTN_3), value 1
    1274 Event: time 1435939364.644274, type 1 (EV_KEY), code 259 (BTN_3), value 0
    1275 Event: time 1435939364.644274, -------------- EV_SYN ------------
    1276 Event: time 1435939364.644283, type 1 (EV_KEY), code 256 (BTN_0), value 1
    1277 Event: time 1435939364.644283, type 1 (EV_KEY), code 256 (BTN_0), value 0
    1278 Event: time 1435939364.644283, -------------- EV_SYN ------------
    1279 }}}
    1280   * 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)
    1281  * Android:
    1282   - 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:
    1283 {{{
    1284 #!bash
    1285 > cat /system/usr/keylayout/gsc_input.kl
    1286 # quick press-and-release (held <700ms) of front-panel pushbutton
    1287 key 256   POWER                 WAKE
    1288 
    1289 # front panel pushbutton held >700ms (long-press)
    1290 key 257   HOME                  WAKE
    1291 
    1292 # user-eeprom section erased after 3 quick presses
    1293 key 258   SEARCH                WAKE
    1294 
    1295 # tamper event
    1296 key 259   POWER                 WAKE
    1297 }}}
    1298   - you can use the getevent application to show Linux Input events:
    1299 {{{
    1300 #!bash
    1301 > getevent /dev/input/event0
    1302 0001 0103 00000001
    1303 0001 0103 00000000
    1304 0000 0000 00000000
    1305 0001 0100 00000001
    1306 0001 0100 00000000
    1307 0000 0000 00000000
    1308 }}}
    1309   * 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)
     1156Event: time 1585777533.062878, type 1 (EV_KEY), code 256 (BTN_0), value 1
     1157Event: time 1585777533.062878, -------------- SYN_REPORT ------------
     1158Event: time 1585777533.222969, type 1 (EV_KEY), code 256 (BTN_0), value 0
     1159Event: time 1585777533.222969, -------------- SYN_REPORT ------------
     1160Event: time 1585777534.274156, type 1 (EV_KEY), code 257 (BTN_1), value 1
     1161Event: time 1585777534.274156, -------------- SYN_REPORT ------------
     1162Event: time 1585777534.291347, type 1 (EV_KEY), code 257 (BTN_1), value 0
     1163Event: time 1585777534.291347, -------------- SYN_REPORT ------------
     1164}}}
     1165  * the above events occur when the user pushbutton is pressed and quickly released. The 4 events above are:
     1166   1. the user pushbutton is pressed (BTN_0 value 1)
     1167   2. the user pushbutton is released (BTN_0 value 0)
     1168   3. the IRQ_PB interrupt is asserted (BTN_1 value 1) indicating a 1x quick button press/release occured
     1169   4. the IRQ_PB interrupt is de-asserted (BTN_1 value 0) indicating the interrupt was handled and cleared
    13101170
    13111171User Pushbutton Notes: