How do the kill switches work?

[Stevie-O]

So I got my PBPro today, and (like many others) it had all of the kill switches enabled.

I know that pressing the kill-switch combo does something, but I have no idea how it works.  Is it some fancy ACPI magic? A special kernel module?

The most pressing question I have is: how can I tell if a particular kill-switch is currently active or not?

[Arwen]

If this does not answer your questions, please ask more here, so we can add them to the Wiki;

Wiki - Pinebook Pro - Privacy Switches

[Stevie-O]

If this does not answer your questions, please ask more here, so we can add them to the Wiki;

Wiki - Pinebook Pro - Privacy Switches

Well, to restate:

• My most pressing question is: How can I, a human, determine the current state of any given kill switch?
  
  (I suspect that the current answer to the question is "you can't".)
  
  
• How can software running on the main CPU determine the current state of any given kill switch?
  
  (I suspect that the current answer to the question is "you can't".)
  
  
• The wiki states that the "power" (kill switch) state is stored across reboots.  Where is it stored?  
  
  As an example as to why this is relevant, all Chromebooks have a similar feature: a "developer mode" switch that disables the secure boot process, allowing unsigned software to be loaded onto them. In most commercially-available Chromebooks, this switch is virtualized, with the switch state stored in RAM backed by the laptop's primary battery.  Thus, the switch state is persisted across reboots -- unless the laptop's battery is discharged completely.  When that happens, the RAM is cleared, and the virtual devmode switch is effectively cleared with it.
  
  
• (I've pretty much managed to answer this one myself.) The keyboard's main connection is USB. (Incidentally,  AIUI, all USB keyboards are USB 1.1, not USB 2.0.)  Since USB has no facility for privacy switches, it must also have a secondary connection to signal that a kill switch should be enabled/disabled.  Where on the schematics can I find this connection?
  
  I've found, on page 20 of the mainboard schematics, I'm pretty sure U23 (labeled as "SH68F83Q") is involved, because has connections labeled MIC_CUT, WIFI_CUT, and CAM_CUT.  There's also an entry here https://wiki.pine64.org/index.php/Pinebo...eripherals  under "Keyboard Information" to a "Sinowealth SH68F83 [no Q] Datasheet".  This link is dead, it goes to a blank page.
  
  I'm guessing that this might be what the keyboard is physically wired into; I've seen that 'R' and 'C' column before, but on a much smaller scale (3-by-4).  Is that accurate? 
  
  
  
• Where's the source code and build instructions for the keyboard firmware?
  
  
  
• CAM_CUT goes to the "EN" pin on what looks like a voltage regulator; presumably, when this pin is low, no power is supplied to the camera.
  
• MIC_CUT turns on or off a BPJ (Q15) that, when turned on, connects MIC_IN1P to VCC_MICBIAS via a 2.2K resistor.
  
  My analog circuitry isn't very strong, but it seems that this works by saturating the mic input to maximum possible volume, essentially "drowning out" any input from the mic itself.
  
  
• WIFI_CUT appears to work by forcing low WL_REG_ON on U21 (labeled AP6255). From the datasheet:
  
  > WL_REG_ON: Used by the PMU to power up or power down the internal regulators used by the WLAN section. When this pin is high, the regulators are enabled and the WLAN section is out of reset. When this pin is low the WLAN section is in reset.
  
  
• One thing in particular is that if you turn off the kill switch, wlan0 doesn't disappear; however, if the laptop is powered on with the kill switch already inactive, wlan0 never appears in the first place.  I'd like to better understand why this is.

[pfeerick]

My most pressing question is: How can I, a human, determine the current state of any given kill switch?

"you can't", except, by pressing the button to toggle the state, at which point you'll need to do it again. other than, perhaps, in one or two cases, looking at dmesg or poking the right sysfs bits to see if the device is still present or missing.

How can software running on the main CPU determine the current state of any given kill switch?

Generally, "you can't", although wifi and camera would probably appear and disappear, so there is that possibility. The caveat being the wifi driver doesn't like the device disconnect, so may need some poking to get it to properly reflect the device absence/presence.

The wiki states that the "power" (kill switch) state is stored across reboots.  Where is it stored?  

In the EEPROM attached to the keyboard's MCU.

Since USB has no facility for privacy switches, it must also have a secondary connection to signal that a kill switch should be enabled/disabled.  Where on the schematics can I find this connection?

Yup, that would be it. . The SH68F83 is a low speed (i.e. USB 1.1) microcontroller, which being used as the interface between the keyboard matrix and the PBP.

Where's the source code and build instructions for the keyboard firmware?

The source for the keyboard firmware is not available - the manufacturer would not release that, but did give pine64 updated binaries to overcome the initial issues with keyboard responsiveness. There have been efforts to reverse engineer it, and one such is this work by Jack Humbert (check out the firmware/src folder). You'll also find that elusive datasheet in the repo.

One thing in particular is that if you turn off the kill switch, wlan0 doesn't disappear; however, if the laptop is powered on with the kill switch already inactive, wlan0 never appears in the first place.  I'd like to better understand why this is.

Probably related the WiFi driver not understanding how to cope with the WiFi module just suddenly dropping in or out of existence, rather than via some software instruction. That's why these commands are needed to kick it back into life if you turn it on (probably just the unbind command would refresh things if you turn it off, meaning you'd then only have to bind it when turning it back on).

Code:

$ echo 'fe310000.dwmmc' | sudo tee /sys/bus/platform/drivers/dwmmc_rockchip/unbind
$ echo 'fe310000.dwmmc' | sudo tee /sys/bus/platform/drivers/dwmmc_rockchip/bind

[Arwen]

If this does not answer your questions, please ask more here, so we can add them to the Wiki;

Wiki - Pinebook Pro - Privacy Switches

Well, to restate:

...

• The wiki states that the "power" (kill switch) state is stored across reboots.  Where is it stored?  
  
  As an example as to why this is relevant, all Chromebooks have a similar feature: a "developer mode" switch that disables the secure boot process, allowing unsigned software to be loaded onto them. In most commercially-available Chromebooks, this switch is virtualized, with the switch state stored in RAM backed by the laptop's primary battery.  Thus, the switch state is persisted across reboots -- unless the laptop's battery is discharged completely.  When that happens, the RAM is cleared, and the virtual devmode switch is effectively cleared with it.
  
  
• (I've pretty much managed to answer this one myself.) The keyboard's main connection is USB. (Incidentally,  AIUI, all USB keyboards are USB 1.1, not USB 2.0.)  Since USB has no facility for privacy switches, it must also have a secondary connection to signal that a kill switch should be enabled/disabled.  Where on the schematics can I find this connection?
  
  I've found, on page 20 of the mainboard schematics, I'm pretty sure U23 (labeled as "SH68F83Q") is involved, because has connections labeled MIC_CUT, WIFI_CUT, and CAM_CUT.  There's also an entry here https://wiki.pine64.org/index.php/Pinebo...eripherals  under "Keyboard Information" to a "Sinowealth SH68F83 [no Q] Datasheet".  This link is dead, it goes to a blank page.
  
  I'm guessing that this might be what the keyboard is physically wired into; I've seen that 'R' and 'C' column before, but on a much smaller scale (3-by-4).  Is that accurate?
  

...

For the first, I've updated the Wiki to indicate it's stored in the keyboard's flash memory.

On the second, @pfeerick added the PDF to our Wiki and corrected the link.

So, 2 things improved.

One note, Jack's keyboard firmware can send a special key sequence on disable and enable of the kill switches. This is to allow future OS level detection of change, like re-enabling WiFi chip. It's still early days, so we will have to see if Jack's firmware becomes the "new" default firmware. Already we have seen a change in the default OS from Debian to Manjaro.

[Stevie-O]

My most pressing question is: How can I, a human, determine the current state of any given kill switch?

"you can't", except, by pressing the button to toggle the state, at which point you'll need to do it again. other than, perhaps, in one or two cases, looking at dmesg or poking the right sysfs bits to see if the device is still present or missing.

Which, of course, is not quite the same. (Especially since, for Wifi, you now have to reboot the machine. Or type an arcane sequence in.)

How can software running on the main CPU determine the current state of any given kill switch?

Generally, "you can't", although wifi and camera would probably appear and disappear, so there is that possibility. The caveat being the wifi driver doesn't like the device disconnect, so may need some poking to get it to properly reflect the device absence/presence.

Point of clarification:  That only holds for the camera.  

The microphone is a simple analog device.  The microphone kill switch turns on/off a circuit that's parallel to the microphone input; there is no device, or absence thereof, to be detected.

Likewise, the Wifi circuitry is not disconnected. The WIFI_CUT trace goes to a pin that (according to the AP6256 datasheet) internally "powers down the internal regulators used by the WLAN section. When this pin is low the WLAN section is in reset." What that means, exactly, is not elaborated upon further.  (more on that below.)

Yup, that would be it. . The SH68F83 is a low speed (i.e. USB 1.1) microcontroller, which being used as the interface between the keyboard matrix and the PBP.

I pointed this out because the wiki page says "The keyboard and trackpad both use the USB 2.0 protocol".  I'm betting the trackpad is 1.1 as well.

Where's the source code and build instructions for the keyboard firmware?

The source for the keyboard firmware is not available - the manufacturer would not release that, but did give pine64 updated binaries to overcome the initial issues with keyboard responsiveness.

Now that is not an answer I expected, given the nature of everything else in a Pinebook!

There have been efforts to reverse engineer it, and one such is this work by Jack Humbert (check out the firmware/src folder). You'll also find that elusive datasheet in the repo.

I'm not even convinced that what's needed counts as "reverse engineering".  We just need to write our own (open) firmware.

Based on the pinout laid out on the schematics, it's probably a basic switch grid design.  (As I said, I've worked on them before, though that one was a numeric keypad, it only had 12 keys.)  The principle is pretty simple:

1. Enable internal pullup on column pins, set to input mode.  They will float high.
2. Write an active 0 to all row pins.
3. Register to be interrupted when any column pins goes to 0
4. When IRQ is signaled, disable interrupt and start timer
5. When timer goes off, put all rows but R0 into high-impedance mode.  Note which columns read 0.  Then repeat this for all other rows.
   Now you know exactly which keys are currently being pressed.
6. As soon as no keys are pressed, disable timer and reenable interrupt

(Depending on MCU limitations, you might have to have the timer on all the time; doing so still works, but consumes more power.)

Anyway, thanks for pointing me to that; I think I'll talk to @jackhumbert about the possibilities here.

One thing in particular is that if you turn off the kill switch, wlan0 doesn't disappear; however, if the laptop is powered on with the kill switch already inactive, wlan0 never appears in the first place.  I'd like to better understand why this is.

Probably related the WiFi driver not understanding how to cope with the WiFi module just suddenly dropping in or out of existence, rather than via some software instruction. That's why these commands are needed to kick it back into life if you turn it on (probably just the unbind command would refresh things if you turn it off, meaning you'd then only have to bind it when turning it back on).

Code:

$ echo 'fe310000.dwmmc' | sudo tee /sys/bus/platform/drivers/dwmmc_rockchip/unbind
$ echo 'fe310000.dwmmc' | sudo tee /sys/bus/platform/drivers/dwmmc_rockchip/bind

As I pointed out above, I don't think that's exactly what's happening.  This is what I suspect happens: (of course, I could be wrong.  That's why I said I want to better understand this.)

== Process when starting up with kill switch active ==

1. Something causes the kernel driver for the wifi chip to be loaded
2. The driver starts by initializing the wifi circuitry
3. If the kill switch is off, the wifi circuitry does not respond to the driver's commands, and it aborts without creating wlan0

== Process when toggling kill switch while power is on ==

1. Key sequence entered, disabling wifi ("putting into reset")
   This has the effect that the initialization done by the driver at boot time is undone.
2. Key sequence entered, re-enabling wifi ("out of reset")
3. At this point, the wifi chip is now enabled, but no longer initialized.  Because of this, it does not properly respond to commands from the driver.
    (And the driver has no way of knowing this has happened.)

My understanding is that the "unbind/bind" thing has the effect of
1. unbind => tell kernel to have the current driver stop being in charge of that device
2. bind => tell kernel to use the specified driver to be in charge of that device

That has the effect of forcing the driver to be reloaded -- and since the first thing it does is (re)initialize the wifi chip, it works again!

For the first, I've updated the Wiki to indicate it's stored in the keyboard's flash memory.

Just to be clear: @pfeerick says it's in EEPROM storage, and I suspect he's right.  (The relevant difference is whether or not the kill switches are preserved when the flash memory is rewritten during a firmware update.)

One note, Jack's keyboard firmware can send a special key sequence on disable and enable of the kill switches. This is to allow future OS level detection of change, like re-enabling WiFi chip. It's still early days, so we will have to see if Jack's firmware becomes the "new" default firmware. Already we have seen a change in the default OS from Debian to Manjaro.

I can't imagine that it wouldn't be; it's keyboard controller firmware.  It either does its job or it doesn't.  The only distinguishing factor here is closed-source vs open-source, and I find it difficult to believe that the kind of people who are interested in Pinebooks wouldn't embrace the latter.

[Arwen]

...

For the first, I've updated the Wiki to indicate it's stored in the keyboard's flash memory.

Just to be clear: @pfeerick says it's in EEPROM storage, and I suspect he's right.  (The relevant difference is whether or not the kill switches are preserved when the flash memory is rewritten during a firmware update.)

One note, Jack's keyboard firmware can send a special key sequence on disable and enable of the kill switches. This is to allow future OS level detection of change, like re-enabling WiFi chip. It's still early days, so we will have to see if Jack's firmware becomes the "new" default firmware. Already we have seen a change in the default OS from Debian to Manjaro.

I can't imagine that it wouldn't be; it's keyboard controller firmware.  It either does its job or it doesn't.  The only distinguishing factor here is closed-source vs open-source, and I find it difficult to believe that the kind of people who are interested in Pinebooks wouldn't embrace the latter.

The difference on what device the kill switch status is stored on the keyboard is not really clear. We do not have the schematics of the keyboard to determine if it has just 1 re-writable flash memory. Or 2. So I went with the more generic wording. But, I did clarify that it's stored on the keyboard. Even works before the OS is booted. (Jack or examination of what Jack has done, may clarify it. But, I don't have the skill to determine it.)

As for open source keyboard firmware, if you look at Pine64, they encourage others to do the work. Pine64 supplies the hardware, the hard part, (no pun intended). Thus, it's much easier for others to do the software, like OS distro and firmware for U-Boot on SPI.

One note, the trackpad is connected to the keyboard. So their is 1 USB interface for both.

[Phillip Bell]

I view the WiFi as an emergency-off, only.

You can press Pine-F11, and WiFi is immediately disabled. A reboot at this point will ensure it stays off. But you cannot press Pine-F11 and expect WiFi to come back on. For that, you need to Press Pine-F11, then reboot, then it should be back on.

I have had no luck with he camera or mic yet, so I can't comment on those.