hdctools: Chrome OS Hardware Debug & Control Tools

Servo v4

Servo v4 is a debug device in the Servo family.

Servo v4 functions as a configurable USB hub to support developer and lab recovery features. However, it doesn‘t have any hardware debug features on its own. It must be paired with CCD (GSC’s on-board servo implementation) or Servo Micro.

What is Servo v4?

Servo v4 combines the functionality of the following devices into one:

  • Ethernet-USB dongle
  • Muxable USB port
  • microSD to USB3.0 dongle
  • Keyboard emulator
  • Pass through charger
  • Case-Closed Debug (CCD) interface (SuzyQ debug cable)

Details:

Servo v4 with Accessories

Getting Servo v4

Sorry, Servo v4 is not publicly available for purchase.
IMPORTANT: You will need to update the firmware before using, as the factory firmware is quite old.

Partners

Your contact at Google should be able to provide you with Servo v4.

Googlers

Stop by your local Chromestop, or use http://go/hwrequest and enter Servo V4 for the Google Code Name.

How to Use Servo v4

The plastic case has labels HOST, DUT POWER, and uSERVO.

  • HOST: Servo v4 can be plugged into a host machine using a micro-B USB cable via the micro-B USB port marked HOST. This will power Servo v4 while allowing the user to control Servo v4 using servod.

  • DUT POWER: USB-C port labeled DUT POWER is for powering the DUT through the Servo. Servo v4 can be used to power the DUT which becomes useful for devices that use USB-C as their only charge port (tablets, phones etc.). The Type-C port can be used to plug in any Type-C charger to provide full charging capabilities as a charge through hub. If no charger is plugged, Servo v4 will act as a passive hub.

  • uSERVO: On the side labeled uSERVO there are two connectors.

    • The DUT connector (which is a captive cable: servo side is permanently connected) can be plugged into a DUT, providing the DUT access to the ethernet and blue USB port. The Type-C captive cable enables debugging of devices that have a GSC (recent Chromebooks) through CCD.

    • The “uServo” USB port can be used to plug a servo micro to debug DUT over the Yoshi debug header.

  • The following ports on the unlabeled side can be used to download data to a device:

    • Ethernet
    • microSD card
    • USB stick

Servo v4 has an embedded keyboard so keystrokes can be emulated on the DUT.

The servod server must be running for Servo v4 to work. Details can be found on the Servo page.

Type-A vs Type-C Variants

There are two variants of Servo V4: Type-A and Type-C.

Both versions use the same board and case, but have a different captive cable stuffed.

Type-C Version

The Type-C version acts as both a USB hub and PD charger. Servo v4 can also control both CC terminations which allows it to act as a debug accessory. It should be used on systems with CCD.

NOTE: Type-C Servo v4 is a charge-through hub and is NOT functionally equivalent to a Type-A servo with an A-to-C adapter. DO NOT use a Type-C Servo v4 just because you want to plug into a Type-C port. Older Chromebooks (Eve, Samus, etc.) have EC bugs that prevent charge through hubs from working correctly.

Servo v4 Type-C

Type-A Version

The Type-A version is used with a uServo and serves as the DUT USB hub, with the uServo providing SPI and UART support.

Servo v4 Type-A

Servo v4 Revisions

Servo v4 had several revisions, indicated by board color. The mass production (MP) version is available from Chromestop.

Green (MP)

Final version, has full functionality.

Blue (DVT)

The DVT version is completely functional except for the one bug affecting only Type-C variant. There are about one thousand of these, so you may encounter them.

  • PD Charge-through only works on chargers up to 10V.
  • Firmware identifies this by board revision and will not negotiate any voltages above 10V.

Red (EVT)

The EVT version is a mostly functioning version with a few bugs. There are around three hundred of these total.

  • The ethernet IC has a bug in it that makes the device fall out of GigE/USB3.0 speeds under certain circumstances and it falls down to USB1.1 / 2 speeds and never properly recovers until reset.
  • Type-C variant doesn't function, Type-A works OK.

Software

Servo v4 runs more or less equivalently to Servo v2, through servod. It's intended to be mostly transparent, but there are some differences.

Most functionality is exported through dut-control.

$  start-servod -b <board> -s <serial>

To use with a specific board, you can connect a servo_micro to the “uServo” labeled port (or use the Type-C cable to connect to CCD) and run servod, which will load the board config and control both Servo v4 and Servo Micro (or GSC).

$ start-servod -b [board] -s [serialno printed on servo v4 sticker]

Recipes

Connect to Servo console without servod

Connect to Servo v4 Console:

(chroot) $ usb_console -d 18d1:501b

Connect to Servo Micro Console:

(chroot) $ usb_console -d 18d1:501a -i 3

Connect to GSC Console:

#H1/Cr50
(chroot) $ usb_console -d 18d1:5014
# D2/Ti50
(chroot) $ watch -n 1 "lsusb | grep 18d1:504A"

Switch SD to Host

$ dut-control -- sd_en:on sd_pwr_en:on sd_mux_sel:servo_sees_usbkey host_sd_usb_mux_en:on host_sd_usb_mux_sel:sd

Switch SD to DUT

$ dut-control -- sd_en:on sd_pwr_en:on sd_mux_sel:dut_sees_usbkey

Disable SD

$ dut-control -- sd_en:off sd_pwr_en:off

Switch USB3 to Host

$ dut-control -- usb3_mux_en:on usb3_mux_sel:servo_sees_usbkey usb3_pwr_en:on host_sd_usb_mux_en:on host_sd_usb_mux_sel:usb

Switch USB3 to DUT

$ dut-control -- usb3_mux_en:on usb3_mux_sel:dut_sees_usbkey usb3_pwr_en:on

Disable/Enable SuzyQ wiring (debug accessory mode)

Type-C Servo v4 only
$ dut-control -- servo_v4_dts_mode:off [on]

Connect remotely

$ dut-control -- --host XXX --port YYY

Disable/Enable Chargethrough

Type-C Servo v4 only
$ dut-control -- servo_v4_role:snk [src]

Firmware flashing and reading

When flashing the BIOS or EC with CCD, you need to make sure the FlashAP capability is enabled in GSC.

Read and flash AP firmware (BIOS) with CCD or any other servo debug connection:

(chroot) $ sudo futility read --servo -v "$OUTFILE"
(chroot) $ sudo futility update --servo -v -i "$INFILE"

Updating Firmware

The latest firmware is available via the servod docker image. You need to have go/servod configured. That would also add servo_updater CLI to your host shell.

NOTE: servod must not be running. You should have recent versions of start-servod and servo_updater scripts that are in hdctools repo (repo sync)

Update to latest stable firmware:

$ servo_updater -- -b servo_v4

Rollback to previous stable version if needed:

$ servo_updater -- -b servo_v4 -c prev --allow-rollback

Advanced usage below:

  • Update to specific binary file
$ servo_updater -f <file_path> -- -b servo_v4
  • Update to specific FW channel
$ servo_updater -- -b servo_v4 -c [alpha|dev|prev|stable]
  • If you need to update FW, before it reaches monthly released servod image specify channel for servod docker distribution (“release” is default)
$ servo_updater --updater_channel [local|latest|beta|release] -- -b servo_v4 [...]

Enabling Case Closed Debug (CCD)

See CCD for complete details.

If using a Type-C Servo v4, these commands will only work if the USB-C cable is plugged into the correct USB port. Generally, this is the USB port on the left side of the device. If the command doesn't work, try the other ports.

Connect to GSC console:

(chroot) $ usb_console -d 18d1:5014

Check the GSC FW version in the GSC console:

> version
Build:   0.4.10/cr50_v1.9308_B.269-754117a

CCD requires Cr50 version 0.3.9+ / 0.4.9+

  • 0.4.x is the “pre-pvt” version, for pre-production devices.
  • 0.3.x is the “mp” version, for production devices. This requires the device to be in developer mode before “ccd open”.
  • 0.0.22 is the factory preflash from GUC. It needs an update.

Open CCD in the GSC console:

> ccd open

Press power button when prompted. It should take around 5 minutes.

If you get an access denied error when attempting ccd open, you likely do not have developer mode enabled.
GSC loses the developer mode state after “opening CCD”. If your device boots into recovery mode, try re-entering developer mode.

Enable testlab mode in the GSC console:

> ccd testlab enable

Press power button some more. CTRL+C to exit.

Run servod as normal, CCD should be enabled now.

Known issues

  • Displayport - not supported
  • Type-A/Type-C: Servo V4 comes in two variants on the captive cable, both can be obtained from Chromestop.
  • Type-C Servo is not interchangeable with Type-A. Type-C must be paired with CCD, Type-A must be paired with Servo Micro.
  • DFU: To use util/flash_ec you must enable DFU by connecting servo with an A-A cable plugged into an OTG cable. USB ID is tied to BOOT0 indicator on the STM32 part.

Interop Problems with Some Switches

See http://b/112187276.

Your network switch port will get hosed (some TX buffer fills up and starts dropping things) if you have Servo v4 connected to most switches and unplug the servo‘s USB connection, or power off the DUT fully, after the servo’s NIC has an IP. This behavior is not reproducible with a GS108Tv2, so the workaround is to use a GS108Tv2.

Bugs

File bug or feature requests here.

Programming

You don‘t need to do this unless you’re developing Servo v4 firmware.

Servo v4 code lives in the EC and hdctools codebase. It can be built as follows:

(chroot) $ cd ~/chromiumos/src/platform/ec
(chroot) $ make BOARD=servo_v4 -j8

To raw flash a Servo v4, BOOT0 select pin is indicated by the OTG cable:

(chroot) $ ./util/flash_ec --board=servo_v4

To set the Servo v4 serial number on the Servo console:

> serialno set 012345