{
  "id": "embedded/spi-dma-transfer-incomplete",
  "signature": "SPI: DMA transfer incomplete, expected 256 bytes but only 128 bytes received on channel 1",
  "signature_zh": "SPI: DMA传输不完整，通道1上预期256字节但仅接收128字节",
  "regex": "SPI: DMA transfer incomplete, expected \\d+ bytes but only \\d+ bytes received on channel \\d+",
  "domain": "embedded",
  "category": "data_error",
  "subcategory": null,
  "root_cause": "The SPI DMA transfer was prematurely terminated due to a timeout, FIFO overflow, or slave device deasserting chip select mid-transfer.",
  "root_cause_type": "generic",
  "root_cause_zh": "SPI DMA传输因超时、FIFO溢出或从设备在传输中途取消片选而过早终止。",
  "versions": [
    {
      "version": "STM32Cube_FW_F7 v1.17.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "STM32Cube_FW_G4 v1.6.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "DMA HAL Driver v2.3.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Increase the SPI clock speed to transfer data faster",
      "why_fails": "Higher clock speed can exacerbate timing issues and cause more FIFO overflows, worsening the problem.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "Disable DMA and use polling SPI transfer instead",
      "why_fails": "Polling transfers can block the CPU for long periods, causing real-time task failures and still not resolving the root cause of incomplete transfers.",
      "fail_rate": 0.75,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Add a DMA transfer complete callback (HAL_SPI_TxRxCpltCallback) to verify the received byte count and re-initiate the transfer if incomplete.",
      "success_rate": 0.85,
      "how": "Add a DMA transfer complete callback (HAL_SPI_TxRxCpltCallback) to verify the received byte count and re-initiate the transfer if incomplete.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Enable SPI CRC checking to detect data corruption and retry the transfer on CRC mismatch.",
      "success_rate": 0.7,
      "how": "Enable SPI CRC checking to detect data corruption and retry the transfer on CRC mismatch.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Add a DMA transfer complete callback (HAL_SPI_TxRxCpltCallback) to verify the received byte count and re-initiate the transfer if incomplete.",
    "Enable SPI CRC checking to detect data corruption and retry the transfer on CRC mismatch."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://www.st.com/resource/en/application_note/an4031-dma-controller-application-examples-stmicroelectronics.pdf",
  "official_doc_section": null,
  "error_code": "SPI_DMA_INCOMPLETE",
  "verification_tier": "ai_generated",
  "confidence": 0.87,
  "fix_success_rate": 0.8,
  "resolvable": "partial",
  "first_seen": "2023-09-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}