meta-dts/docs/error-paths.md

Error paths

Possible error paths in DTS and how to trigger them

UI/User Experience

• UI refresh loop

  • press Enter multiple times (or keep it pressed) in main UI
  • relevant code: dts.sh#L44

• multiple UI refreshes per one key

  • press arrow key in main UI
  • relevant code: dts.sh#L44

• strings don't fit in UI border

  • check on platform/firmware with very long dmidecode strings

  • or enter DTS shell and use these commands:

    export DTS_TESTING=true
    export TEST_SYSTEM_VENDOR="very long system vendor string that won't fit"
    dts-boot
    

  • relevant code: show_hardsoft_inf

• RAM hardware information has different indentation

  • start DTS and compare HARDWARE INFORMATION entries
  • relevant code: show_ram_inf

• wrong answer for user choice

  • enter value outside of allowed ones
  • enter value with spaces and other special characters
  • enter non-numeric value if choice expects number
  • press enter without writing anything (if there's no default value used)
  • relevant code: Check all read command usages

• stop workflow

  • Answer negatively when asked if everything is ok/you want to continue
  • relevant code:
    • force_me_update
    • display_warning specification
    • display_warning deploy
    • ask_for_confirmation
    • HCL report
    • restore

• CTRL+C

  • press CTRL+C. Shouldn't break anything no matter when it's used.
  • If it's used during workflow then user should see relevant information that workflow was stopped.
  • If CTRL+C is used during flashing user should be informed that their platform is in unknown state, and they shouldn't reboot.
  • alternatively - CTRL+C should be trapped and do nothing (at least when flashing to not brick user platform)

Credentials

• empty e-mail
  • press Enter without writing anything when prompted for e-mail
  • relevant code: get_dpp_creds e-mail
• empty password
  • press Enter without writing anything when prompted for password
  • relevant code: get_dpp_creds password
• non-existent credentials
  • enter random, non-existent e-mail and password when prompted
• no internet access
  • disconnect Ethernet cable or set network interface down before trying to load credentials
• no access to MinIO server - e.g. server is down
  • modify DPP_SERVER_ADDRESS
  • relevant code: dts-environment.sh
• e-mail or password with space
  • use space in e-mail or password

Generic workflow (update, deployment, transition)

• missing remote files - any combination of missing files downloaded by DTS so firmware binaries, hashes, signatures, additional binaries used by some platforms
  • remove files on remote server
  • change path to file to point to non-existent file (in dts-configs or by modifying scripts)
• no access to remote server
  • FTP/minio/GitHub is down or blocked
  • modify address of remote server to some non-existent one
  • block server/IP via e.g. firewall
• no internet access
  • disconnect Ethernet cable or disable network interface before starting workflow
  • disable network before starting workflow and during
  • all places where we connect to the remote should be tested (all usages of curl, wget, mc, e.t.c.). All file downloads should possibly be merged into one function to simplify testing
• BIOS region in flash is write-protected
  • enable BIOS boot medium lock or Enable SMM BIOS write protection in BIOS on Dasharo UEFI firmware
  • mock on non-Dasharo firmware
  • test all workflows that use flashrom to write to flash
• no firmware available
  • try to run workflow on unsupported platform or platform by emulating unsupported platform (TEST_SYSTEM_* and TEST_BOARD_MODEL variables).
  • modify DTS_CONFIG_REF to use dts-configs branch with removed support for your platform
• firmware to be deployed doesn't support platform hardware e.g.
  • firmware doesn't support 13th gen CPU
• wrong hash
  • modify .sha256 file used during workflow
  • use custom file server with wrong hash files
• wrong signature
  • serve malformed .sig file
  • serve .sig file signed with different, untrusted, key
• flashing fails
  • mock flashing failure
  • There are multiple possible failure points in deploy_firmware function, all need to be tested.
  • inform user what to do in this case (especially if it was partially flashed).
• flashrom (internal) failures
  • multiple failure points
  • to test: mock
  • complete flashrom failure (can't access flash at all)
  • flash region read failures
• flashrom (ec) failures
  • to test: mock
  • complete flashrom failure (can't access flash at all)
  • flash region read failures
  • flash write failure (initial deployment)
• capsule workflow with Intel ME enabled
  • run capsule workflow (e.g. update/fuse) with Intel ME enabled or Soft disabled
• failed capsule loading
  • run capsule update on firmware that doesn't support capsule updates
  • run capsule update with enabled ME

Variables

Wrong values in DTS variables in dts-scripts or dts-configs

• Variables related to paths e.g.:

  • bios_path_comm
  • heads_link_dpp
  • and others. Same results as in Missing remote files point.

• Unsupported version format in dasharo_rel_ver*

  • set version in format unsupported by compare_version

• Variables related to binary preparation i.e. *_MIGRATION. Those variables decide whether we need to run workflow related to this migration. If they have wrong value then final workflow result might be different from expected e.g. in case of NEED_SMMSTORE_MIGRATION we might end up without migrated config (so we lose all BIOS configuration after update)

• Variables related to flashing firmware e.g. HAVE_EC, FLASHROM_ADD_OPT_UPDATE_OVERRIDE, PROGRAMMER_BIOS, PROGRAMMER_EC. Mistakes here might result in:

  • flashrom command failing
  • flashrom flashing wrong/unexpected regions
  • EC not being flashed (if platform has EC) or error when trying to flash non-existent EC