[coverage/drivers] Add comments to unreached lines

Add comments explaining why testing of crypto did not reach lines in
drivers.

Signed-off-by: Siemen Dhooghe <sdhooghe@google.com>

Author: siemen11

sw/device/lib/crypto/drivers/aes.c

@@ -276,6 +276,9 @@ static status_t aes_begin(aes_key_t key, const aes_block_t *iv,
   // Check that AES is ready to receive input data.
   uint32_t status = abs_mmio_read32(kBase + AES_STATUS_REG_OFFSET);
   if (!bitfield_bit32_read(status, AES_STATUS_INPUT_READY_BIT)) {
+    // COVERAGE (HW ERR) This line checks whether the AES HW is ready to receive
+    // input but after spin_until(AES_STATUS_IDLE_BIT), hence it will always be
+    // ready unless there is a HW error.
     return OTCRYPTO_RECOV_ERR;
   }
   HARDENED_CHECK_EQ(launder32(bitfield_bit32_read(

sw/device/lib/crypto/drivers/entropy.c

@@ -449,6 +449,8 @@ static status_t csrng_send_app_cmd(uint32_t base_address,
           launder32(cmd_type_used) | kEntropyCsrngSendAppCmdTypeEdnRes;
       break;
     default:
+      // COVERAGE (SW ERR) This is an internal function, the cmd_type given will
+      // always be from these cases.
       return OTCRYPTO_BAD_ARGS;
   }
   // Check if we landed in the correct case statement. Use ORs for this to
@@ -465,6 +467,7 @@ static status_t csrng_send_app_cmd(uint32_t base_address,
     } while (!ready && --timeout);
 
     if (timeout == 0) {
+      // COVERAGE (HW ERR) The timeout should only happen with a HW error.
       return OTCRYPTO_RECOV_ERR;
     }
   }
@@ -519,6 +522,7 @@ static status_t csrng_send_app_cmd(uint32_t base_address,
       } while (!ready && --timeout);
 
       if (timeout == 0) {
+        // COVERAGE (HW ERR) The timeout should only happen with a HW error.
         return OTCRYPTO_RECOV_ERR;
       }
     }
@@ -537,6 +541,7 @@ static status_t csrng_send_app_cmd(uint32_t base_address,
                --timeout);
 
       if (timeout == 0) {
+        // COVERAGE (HW ERR) The timeout should only happen with a HW error.
         return OTCRYPTO_RECOV_ERR;
       }
 
@@ -552,12 +557,14 @@ static status_t csrng_send_app_cmd(uint32_t base_address,
           --timeout);
 
       if (timeout == 0) {
+        // COVERAGE (HW ERR) The timeout should only happen with a HW error.
         return OTCRYPTO_RECOV_ERR;
       }
 
-      // Check the "status" bit, which will be 0 unless there was an error.
       reg = abs_mmio_read32(kBaseCsrng + CSRNG_SW_CMD_STS_REG_OFFSET);
       if (bitfield_field32_read(reg, CSRNG_SW_CMD_STS_CMD_STS_FIELD)) {
+        // COVERAGE (HW ERR) The status bit will be 0 unless there was a HW
+        // error.
         return OTCRYPTO_RECOV_ERR;
       }
     }
@@ -575,11 +582,13 @@ static status_t csrng_send_app_cmd(uint32_t base_address,
                --timeout);
 
       if (timeout == 0) {
+        // COVERAGE (HW ERR) The timeout should only happen with a HW error.
         return OTCRYPTO_RECOV_ERR;
       }
 
-      // Check the "status" bit, which will be 0 unless there was an error.
       if (bitfield_field32_read(reg, CSRNG_SW_CMD_STS_CMD_STS_FIELD)) {
+        // COVERAGE (HW ERR) The status bit will be 0 unless there was a HW
+        // error.
         return OTCRYPTO_RECOV_ERR;
       }
     }
@@ -655,10 +664,12 @@ static status_t edn_ready_block(uint32_t edn_address) {
   } while (!bitfield_bit32_read(reg, EDN_SW_CMD_STS_CMD_RDY_BIT) && --timeout);
 
   if (timeout == 0) {
+    // COVERAGE (HW ERR) The timeout should only happen with a HW error.
     return OTCRYPTO_RECOV_ERR;
   }
 
   if (bitfield_field32_read(reg, CSRNG_SW_CMD_STS_CMD_STS_FIELD)) {
+    // COVERAGE (HW ERR) The status bit will be 0 unless there was a HW error.
     return OTCRYPTO_RECOV_ERR;
   }
   return OTCRYPTO_OK;
@@ -771,6 +782,7 @@ static status_t entropy_src_configure(const entropy_src_config_t *config) {
   if (config->bypass_conditioner != kMultiBitBool4False) {
     HARDENED_CHECK_NE(config->bypass_conditioner, kMultiBitBool4False);
     // Bypassing the conditioner is not supported.
+    // COVERAGE (SW ERR) The configs provided in the code do not support bypass.
     return OTCRYPTO_BAD_ARGS;
   }
 
@@ -870,6 +882,8 @@ static status_t entropy_src_configure(const entropy_src_config_t *config) {
       return OTCRYPTO_RECOV_ERR;                                       \
     }                                                                  \
   } while (false);
+// COVERAGE (HW ERR) This is only reached if the registers from the RNG were
+// faulted.
 
 /**
  * Check the entropy_src configuration.
@@ -888,13 +902,16 @@ static status_t entropy_src_check(const entropy_src_config_t *config) {
       config->route_to_firmware != kMultiBitBool4False) {
     // This check only supports FIPS-compatible configurations which do not
     // bypass the conditioner or route to firmware.
+    // COVERAGE (SW ERR) This code does not support bypass.
     return OTCRYPTO_BAD_ARGS;
   }
 
   // Check that entropy_src is enabled.
   uint32_t reg =
       abs_mmio_read32(kBaseEntropySrc + ENTROPY_SRC_MODULE_ENABLE_REG_OFFSET);
   if (reg != kMultiBitBool4True) {
+    // COVERAGE (HW ERR) This is only reached when the HW was not enabled before
+    // the check.
     return OTCRYPTO_RECOV_ERR;
   }
 
@@ -912,6 +929,8 @@ static status_t entropy_src_check(const entropy_src_config_t *config) {
       bitfield_field32_read(reg, ENTROPY_SRC_CONF_RNG_BIT_ENABLE_FIELD);
   if (conf_fips_enable != kMultiBitBool4True ||
       conf_rng_bit_enable != kMultiBitBool4False) {
+    // COVERAGE (SW ERR) This is only reached when the RNG was not set in FIPS
+    // mode, but we only support FIPS mode.
     return OTCRYPTO_RECOV_ERR;
   }
   reg =
@@ -922,6 +941,8 @@ static status_t entropy_src_check(const entropy_src_config_t *config) {
       bitfield_field32_read(reg, ENTROPY_SRC_ENTROPY_CONTROL_ES_ROUTE_FIELD);
   if (control_es_type != kMultiBitBool4False ||
       control_es_route != kMultiBitBool4False) {
+    // COVERAGE (SW ERR) We only support configurations which set ES TYPE and
+    // ROUTE to true.
     return OTCRYPTO_RECOV_ERR;
   }
 
@@ -931,6 +952,7 @@ static status_t entropy_src_check(const entropy_src_config_t *config) {
   if (bitfield_field32_read(
           reg, ENTROPY_SRC_HEALTH_TEST_WINDOWS_FIPS_WINDOW_FIELD) !=
       config->fips_test_window_size) {
+    // COVERAGE (SW ERR) We only support a single test window size.
     return OTCRYPTO_RECOV_ERR;
   }
 
@@ -943,6 +965,7 @@ static status_t entropy_src_check(const entropy_src_config_t *config) {
       ~(uint32_t)config->alert_threshold);
   if (exp_reg != abs_mmio_read32(kBaseEntropySrc +
                                  ENTROPY_SRC_ALERT_THRESHOLD_REG_OFFSET)) {
+    // COVERAGE (SW ERR) We only support a single alert threshold.
     return OTCRYPTO_RECOV_ERR;
   }
 
@@ -1013,6 +1036,7 @@ status_t entropy_complex_init(hardened_bool_t fips) {
   if (launder32(config->id) != ((fips == kHardenedBoolFalse)
                                     ? kEntropyComplexConfigIdContinuous
                                     : kEntropyComplexConfigIdFipsContinuous)) {
+    // COVERAGE (SW ERR) We only support FIPS mode.
     return OTCRYPTO_RECOV_ERR;
   }
 
@@ -1034,6 +1058,7 @@ status_t entropy_complex_check(hardened_bool_t fips) {
   if (launder32(config->id) != ((fips == kHardenedBoolFalse)
                                     ? kEntropyComplexConfigIdContinuous
                                     : kEntropyComplexConfigIdFipsContinuous)) {
+    // COVERAGE (SW ERR) We only support FIPS mode.
     return OTCRYPTO_RECOV_ERR;
   }
 
@@ -1068,6 +1093,7 @@ status_t entropy_complex_health_test_config_check(hardened_bool_t fips) {
   // Check recoverable alerts
   if (abs_mmio_read32(kBaseEntropySrc +
                       ENTROPY_SRC_RECOV_ALERT_STS_REG_OFFSET) != 0) {
+    // COVERAGE (HW ERR) This is only reached when we detect a HW alert.
     return OTCRYPTO_RECOV_ERR;
   }
 
@@ -1150,13 +1176,15 @@ status_t entropy_csrng_generate_data_get(uint32_t *buf, size_t len,
              --timeout);
 
     if (timeout == 0) {
+      // COVERAGE (HW ERR) The timeout should only happen with a HW error.
       return OTCRYPTO_RECOV_ERR;
     }
 
     if (fips_check != kHardenedBoolFalse &&
         !bitfield_bit32_read(reg, CSRNG_GENBITS_VLD_GENBITS_FIPS_BIT)) {
       // Entropy isn't FIPS-compatible, so we should return an error when
       // done. However, we still need to read the result to clear CSRNG's FIFO.
+      // COVERAGE (SW ERR) We only support FIPS mode.
       res = OTCRYPTO_RECOV_ERR;
     }
 

sw/device/lib/crypto/drivers/hmac.c

@@ -140,6 +140,7 @@ static status_t hmac_idle_wait(void) {
   uint32_t intr_state =
       abs_mmio_read32(kHmacBaseAddr + HMAC_INTR_STATE_REG_OFFSET);
   if (bitfield_bit32_read(intr_state, HMAC_INTR_STATE_HMAC_DONE_BIT) == 0) {
+    // COVERAGE (HW ERR) Only reached if the HMAC has a HW error.
     return OTCRYPTO_FATAL_ERR;
   }
 

sw/device/lib/crypto/drivers/keymgr.c

@@ -117,6 +117,7 @@ static status_t keymgr_wait_until_done(void) {
   }
 
   // Should be unreachable.
+  // COVERAGE (FI CM) Only reached if there is a fault.
   HARDENED_TRAP();
   return OTCRYPTO_FATAL_ERR;
 }
@@ -235,6 +236,7 @@ status_t keymgr_generate_key_otbn(keymgr_diversification_t diversification,
       WRITE_CTRL(OTBN, GENERATE_HW, true);
       break;
     default:
+      // COVERAGE (FI CM) Only reached if there is a fault.
       HARDENED_TRAP();
       return OTCRYPTO_FATAL_ERR;
   }
@@ -251,6 +253,7 @@ status_t keymgr_generate_key_otbn(keymgr_diversification_t diversification,
       VERIFY_CTRL(OTBN, GENERATE_HW, true);
       break;
     default:
+      // COVERAGE (FI CM) Only reached if there is a fault.
       HARDENED_TRAP();
       return OTCRYPTO_FATAL_ERR;
   }
@@ -280,6 +283,7 @@ static status_t keymgr_sideload_clear(uint32_t slot) {
       abs_mmio_read32(kBaseAddr + KEYMGR_SIDELOAD_CLEAR_REG_OFFSET);
   if (bitfield_field32_read(sideload_clear, KEYMGR_SIDELOAD_CLEAR_VAL_FIELD) !=
       slot) {
+    // COVERAGE (FI CM) Only reached if there is a fault.
     return OTCRYPTO_FATAL_ERR;
   }
 

sw/device/lib/crypto/drivers/kmac.c

@@ -193,6 +193,8 @@ static status_t kmac_get_keccak_rate_words(kmac_security_str_t security_str,
       security_str_set = launder32(security_str_set) | kKmacSecurityStrength512;
       break;
     default:
+      // COVERAGE (SW ERR) This is an internal function, we only provide valid
+      // inputs to it, hence the default case should not be reached.
       return OTCRYPTO_BAD_ARGS;
   }
   // Check if we landed in the correct case statement. Use ORs for this to
@@ -354,15 +356,19 @@ status_t kmac_hwip_default_configure(void) {
 OT_WARN_UNUSED_RESULT
 static status_t wait_status_bit(uint32_t bit_position, bool bit_value) {
   if (bit_position > 31) {
+    // COVERAGE (SW ERR) This is an internal function, we only provide valid
+    // inputs to it, hence the if case should not be reached.
     return OTCRYPTO_BAD_ARGS;
   }
 
   while (true) {
     uint32_t reg = abs_mmio_read32(kKmacBaseAddr + KMAC_STATUS_REG_OFFSET);
     if (bitfield_bit32_read(reg, KMAC_STATUS_ALERT_FATAL_FAULT_BIT)) {
+      // COVERAGE (HW ERR) This is only reached if KMAC raises an alert.
       return OTCRYPTO_FATAL_ERR;
     }
     if (bitfield_bit32_read(reg, KMAC_STATUS_ALERT_RECOV_CTRL_UPDATE_ERR_BIT)) {
+      // COVERAGE (HW ERR) This is only reached if KMAC raises an alert.
       return OTCRYPTO_RECOV_ERR;
     }
     if (bitfield_bit32_read(reg, bit_position) == bit_value) {
@@ -510,6 +516,8 @@ static status_t kmac_init(kmac_operation_t operation,
   } else if (hw_backed == kHardenedBoolFalse) {
     cfg_reg = bitfield_bit32_write(cfg_reg, KMAC_CFG_SHADOWED_SIDELOAD_BIT, 0);
   } else {
+    // COVERAGE (SW ERR) This internal function is only given valid encodings of
+    // hw_backed.
     return OTCRYPTO_BAD_ARGS;
   };
 
@@ -548,6 +556,8 @@ static status_t kmac_write_key_block(kmac_blinded_key_t *key) {
     return OTCRYPTO_OK;
   } else if (launder32(key->hw_backed) != kHardenedBoolFalse) {
     // Invalid value.
+    // COVERAGE (SW ERR) This is only reached with a bad encoding of
+    // key->hw_backed.
     return OTCRYPTO_BAD_ARGS;
   }
   HARDENED_CHECK_EQ(key->hw_backed, kHardenedBoolFalse);
@@ -647,6 +657,8 @@ static status_t kmac_process_msg_blocks(
   if (operation == kKmacOperationKmac) {
     uint32_t digest_len_bits = 8 * sizeof(uint32_t) * digest_len_words;
     if (digest_len_bits / (8 * sizeof(uint32_t)) != digest_len_words) {
+      // COVERAGE (SW ERR) This is an internal function, we only provide it
+      // valid inputs.
       return OTCRYPTO_BAD_ARGS;
     }
 

sw/device/lib/crypto/drivers/otbn.c

@@ -80,11 +80,15 @@ static status_t check_offset_len(uint32_t offset_bytes, size_t num_words,
   uint32_t num_bytes = num_words * sizeof(uint32_t);
 
   if (offset_bytes > UINT32_MAX - num_bytes) {
+    // COVERAGE (SW ERR) This is an internal function, we only provide it valid
+    // inputs.
     return OTCRYPTO_BAD_ARGS;
   }
   uint32_t adjusted_offset_bytes = offset_bytes + num_bytes;
 
   if (adjusted_offset_bytes > mem_size) {
+    // COVERAGE (SW ERR) This is an internal function, we only provide it valid
+    // inputs.
     return OTCRYPTO_BAD_ARGS;
   }
 
@@ -228,11 +232,13 @@ status_t otbn_busy_wait_for_done(void) {
   // If OTBN is idle (not locked), then return a recoverable error.
   if (launder32(status) == kOtbnStatusIdle) {
     HARDENED_CHECK_EQ(status, kOtbnStatusIdle);
+    // COVERAGE (HW ERR) This requires the OTBN to reach an error.
     return OTCRYPTO_RECOV_ERR;
   }
 
   // OTBN is locked; return a fatal error.
   HARDENED_CHECK_EQ(status, kOtbnStatusLocked);
+  // COVERAGE (HW ERR) This is only reached when the OTBN has a HW error.
   return OTCRYPTO_FATAL_ERR;
 }
 
@@ -290,6 +296,8 @@ status_t otbn_set_ctrl_software_errs_fatal(bool enable) {
 static status_t check_app_address_ranges(const otbn_app_t *app) {
   // IMEM must not be backwards or empty.
   if (app->imem_end <= app->imem_start) {
+    // COVERAGE (SW ERR) This is an internal function, we only provide it valid
+    // inputs.
     return OTCRYPTO_BAD_ARGS;
   }
   HARDENED_CHECK_LT(app->imem_start, app->imem_end);