New posts: _posts/2024-06-23-Debugging-STM32-USB-Mass-Storage-Class-Device.md

_posts/2024-06-23-Debugging-STM32-USB-Mass-Storage-Class-Device.md

@@ -0,0 +1,338 @@
+---
+title: Debugging STM32 USB Mass Storage Class Device with eMMC
+author: peter
+date: 2024-06-23 22:25:56 +0800
+categories: [Electronics] # Blogging | Electronics | Programming | Mechanical
+tags: [electronics, emmc, embedded] # systems | embedded | rf | microwave | electronics | solidworks | automation
+# image: assets/img/2024-06-23-Debugging-STM32-USB-/preview.png
+---
+
+Summary of my thought process when troubleshooting a board containing eMMC and USB mass storage class device on the STM32L476.
+
+Download Wireshark and the USB pcap plugin.
+
+TLDR: Minimum configuration you should try for troubleshooting is:
+
+- High clock divider (try 4 or 8 or even larger values)
+- 1 bit wide MMC bus
+- Don't initialize MMC peripheral in the USB MSC initialization function.
+
+## 1. USB connects but then disconnects after a few seconds. The device shows momentarily in the tray, but is not assigned a driver letter.
+
+This also shows in wireshark when the response from the device is a `GET MAX LUN Response[Malformed Packet]` packet.
+
+![wireshark packet capture with malformed packet](/assets/img/2024-06-23-Debugging-STM32-USB-/wireshark.png)
+
+Try return `USBD_OK` for the all functions except `STORAGE_GetMaxLun_FS`. It should show up in explorer with a drive letter and should not disconnect.
+
+This means the functions interacting with the storage device are not working.
+
+---
+
+Make sure you are not re-initializing the MMC peripheral in the `STORAGE_Init_FS` function. This is because in the initialization of the MMC peripheral, `HAL_Delay` is called twice. The use of `HAL_Delay` while the USB device is active appears to cause issues with mounting the device.
+
+<!-- ### 1.1 Try disable eMMC or SD card first
+
+In my board I had eMMC, by commenting out code I isolated the issue to the `SDMMC_PowerState_ON` function which is called during the device initialization. When this code was not called the drive showed up with a drive leter, but when the code was called the drive was not mounted.
+
+```c
+(void)SDMMC_PowerState_ON(hmmc->Instance);
+```
+
+From this I concluded that any calls to `HAL_Delay` were causing the USB stack to break.
+
+Commenting out the `HAL_Delay` in the `SDMMC_PowerState_ON` function and the one to wait 74 cycles (`HAL_Delay(1U + (74U * 1000U / (sdmmc_clk)))`) caused it to mount properly. I still have to think about what is happening since obviously the delays appear to have good reasons for existing. -->
+
+## 2. "This request is not supported" when formatting drive, files not readable
+
+Try changing the clock division to something larger like `4` or greater. Once it is stable try decreasing the divider to maximize speed. When I used lower values, the bus was unstable and I could not retrieve files or perform format operations.
+
+```c
+hmmc1.Init.ClockDiv = 4;
+```
+
+## 3. Random files appearing when formatting AND using 4-bit mode
+
+When a drive has already been formatted in 1-bit mode and you try to reformat it, the format fails and there appears to be random files in the apparently formatted drive
+
+The format fails with:
+
+> Windows was unable to complete the format
+
+I guess my board doesn't work in 4-bit mode so I just compromised with 1-bit mode and it worked again.
+
+## 4. DMA not working on STM32L476RET6 STM32L476
+
+Make sure to switch the DMA direction each for RX and TX
+
+Since we are doing bi-directional transfer just use the SDMMC1 DMA request type. Don't use SDMMC1_TX and SDMMC1_RX simulatneously since you need to switch the direction each transfer anyways.
+
+![dma config for sdmmc1](/assets/img/2024-06-23-Debugging-STM32-USB-/dma_settings.png)
+
+Also make sure the preemption priority of the USB is higher than the DMA and SDMMC peripherals and to enable the SDMMC global interrupt.
+
+In my case I am using:
+
+| NVIC interrupt table                                     | Preemption Priority | Sub Priority |
+| -------------------------------------------------------- | ------------------- | ------------ |
+| SDMMC1 global interrupt                                  | 0                   | 0            |
+| DMA2 channel4 global interrupt (Use your DMA controller) | 1                   | 0            |
+| USB OTG FS global interrupt                              | 3                   | 0            |
+
+![nvic priority table](/assets/img/2024-06-23-Debugging-STM32-USB-/nvic_settings.png)
+
+## Performance with DMA
+
+Kind of terrible but I am using 1-bit bus width since 4-bit isn't working for me.
+
+![crystaldiskmark performance](/assets/img/2024-06-23-Debugging-STM32-USB-/crystaldiskmark.png)
+
+## Sample code for eMMC and USB mass storage class device
+
+### `main.c`
+
+```c
+static void MX_SDMMC1_MMC_Init(void)
+{
+
+  /* USER CODE BEGIN SDMMC1_Init 0 */
+
+  /* USER CODE END SDMMC1_Init 0 */
+
+  /* USER CODE BEGIN SDMMC1_Init 1 */
+
+  /* USER CODE END SDMMC1_Init 1 */
+  hmmc1.Instance = SDMMC1;
+  hmmc1.Init.ClockEdge = SDMMC_CLOCK_EDGE_RISING;
+  hmmc1.Init.ClockBypass = SDMMC_CLOCK_BYPASS_DISABLE;
+  hmmc1.Init.ClockPowerSave = SDMMC_CLOCK_POWER_SAVE_DISABLE;
+  hmmc1.Init.BusWide = SDMMC_BUS_WIDE_1B;
+  hmmc1.Init.HardwareFlowControl = SDMMC_HARDWARE_FLOW_CONTROL_DISABLE;
+  hmmc1.Init.ClockDiv = 2; // MODIFY THIS AS APPROPRIATE
+  if (HAL_MMC_Init(&hmmc1) != HAL_OK)
+  {
+    Error_Handler();
+  }
+  if (HAL_MMC_ConfigWideBusOperation(&hmmc1, SDMMC_BUS_WIDE_1B) != HAL_OK)
+  {
+    Error_Handler();
+  }
+  /* USER CODE BEGIN SDMMC1_Init 2 */
+  /* USER CODE END SDMMC1_Init 2 */
+}
+```
+
+### `usbd_storage_if.c`
+
+```c
+int8_t STORAGE_Init_FS(uint8_t lun)
+{
+  /* USER CODE BEGIN 2 */
+  // ALREADY INITIALIZED IN `MX_SDMMC1_MMC_Init` FUNCTION.
+  return USBD_OK;
+  /* USER CODE END 2 */
+}
+
+int8_t STORAGE_GetCapacity_FS(uint8_t lun, uint32_t *block_num, uint16_t *block_size)
+{
+  /* USER CODE BEGIN 3 */
+  HAL_MMC_CardInfoTypeDef card_info;
+  HAL_StatusTypeDef status = HAL_MMC_GetCardInfo(&hmmc1, &card_info);
+  *block_num = card_info.LogBlockNbr - 1;
+  *block_size = card_info.LogBlockSize;
+  return status;
+  /* USER CODE END 3 */
+}
+
+int8_t STORAGE_IsReady_FS(uint8_t lun)
+{
+  /* USER CODE BEGIN 4 */
+  // eMMC IS ALWAYS CONNECTED TO THE BOARD AND IS ALWAYS READY SINCE IT IS
+  // INITIALIZED AT THE START.
+  return USBD_OK;
+  /* USER CODE END 4 */
+}
+
+int8_t STORAGE_IsWriteProtected_FS(uint8_t lun)
+{
+  /* USER CODE BEGIN 5 */
+  // ASSUME eMMC IS NEVER WRITE PROTECTED ON THIS PARTICULAR BOARD
+  // WRITE PROTECT FEATURE IS NOT USED.
+  return USBD_OK;
+  /* USER CODE END 5 */
+}
+
+int8_t STORAGE_Read_FS(uint8_t lun, uint8_t *buf, uint32_t blk_addr, uint16_t blk_len)
+{
+  /* USER CODE BEGIN 6 */
+  // TODO: USE DMA TRANSFER LATER
+  int8_t status = HAL_MMC_ReadBlocks(&hmmc1, buf, blk_addr, (uint32_t)blk_len, TIMEOUT);
+  while (HAL_MMC_GetCardState(&hmmc1) != HAL_MMC_CARD_TRANSFER)
+    ;
+  return status;
+
+  /* USER CODE END 6 */
+}
+
+int8_t STORAGE_Write_FS(uint8_t lun, uint8_t *buf, uint32_t blk_addr, uint16_t blk_len)
+{
+  /* USER CODE BEGIN 7 */
+  // TODO: USE DMA TRANSFER LATER
+  int8_t status = HAL_MMC_WriteBlocks(&hmmc1, buf, blk_addr, (uint32_t)blk_len, TIMEOUT);
+  while (HAL_MMC_GetCardState(&hmmc1) != HAL_MMC_CARD_TRANSFER)
+    ;
+  return status;
+  /* USER CODE END 7 */
+}
+
+```
+
+## Sample code DMA version
+
+### `usbd_storage_if.c`
+
+```c
+volatile uint8_t mmc_rx_done = 1;
+volatile uint8_t mmc_tx_done = 1;
+
+void HAL_MMC_RxCpltCallback(MMC_HandleTypeDef *hmmc)
+{
+  mmc_rx_done = 1;
+}
+
+void HAL_MMC_TxCpltCallback(MMC_HandleTypeDef *hmmc)
+{
+  mmc_tx_done = 1;
+}
+
+// CHANGE DMA DIRECTION
+HAL_StatusTypeDef MMC_DMA_direction(uint32_t direction)
+{
+  HAL_StatusTypeDef status = HAL_OK;
+  hdma_sdmmc1.Init.Direction = direction;
+  HAL_DMA_Abort(&hdma_sdmmc1);
+  HAL_DMA_DeInit(&hdma_sdmmc1);
+  return HAL_DMA_Init(&hdma_sdmmc1);
+}
+
+//
+// [...]
+//
+
+/**
+ * @brief  Initializes over USB FS IP
+ * @param  lun:
+ * @retval USBD_OK if all operations are OK else USBD_FAIL
+ */
+int8_t STORAGE_Init_FS(uint8_t lun)
+{
+  /* USER CODE BEGIN 2 */
+  // ALREADY INITIALIZED IN `MX_SDMMC1_MMC_Init` FUNCTION.
+  return USBD_OK;
+  /* USER CODE END 2 */
+}
+
+/**
+ * @brief  .
+ * @param  lun: .
+ * @param  block_num: .
+ * @param  block_size: .
+ * @retval USBD_OK if all operations are OK else USBD_FAIL
+ */
+int8_t STORAGE_GetCapacity_FS(uint8_t lun, uint32_t *block_num, uint16_t *block_size)
+{
+  /* USER CODE BEGIN 3 */
+  HAL_MMC_CardInfoTypeDef card_info;
+  HAL_StatusTypeDef status = HAL_MMC_GetCardInfo(&hmmc1, &card_info);
+  *block_num = card_info.LogBlockNbr - 1;
+  *block_size = card_info.LogBlockSize;
+  return status;
+  /* USER CODE END 3 */
+}
+
+/**
+ * @brief  .
+ * @param  lun: .
+ * @retval USBD_OK if all operations are OK else USBD_FAIL
+ */
+int8_t STORAGE_IsReady_FS(uint8_t lun)
+{
+  /* USER CODE BEGIN 4 */
+  // if (HAL_MMC_GetState(&hmmc1) == HAL_MMC_STATE_BUSY || HAL_MMC_GetCardState(&hmmc1) != HAL_MMC_CARD_TRANSFER)
+  //   return USBD_FAIL;
+  return USBD_OK;
+  /* USER CODE END 4 */
+}
+
+/**
+ * @brief  .
+ * @param  lun: .
+ * @retval USBD_OK if all operations are OK else USBD_FAIL
+ */
+int8_t STORAGE_IsWriteProtected_FS(uint8_t lun)
+{
+  /* USER CODE BEGIN 5 */
+  // ASSUME eMMC IS NEVER WRITE PROTECTED ON THIS PARTICULAR BOARD
+  // WRITE PROTECT FEATURE IS NOT USED.
+  return USBD_OK;
+  /* USER CODE END 5 */
+}
+
+/**
+ * @brief  .
+ * @param  lun: .
+ * @retval USBD_OK if all operations are OK else USBD_FAIL
+ */
+int8_t STORAGE_Read_FS(uint8_t lun, uint8_t *buf, uint32_t blk_addr, uint16_t blk_len)
+{
+  /* USER CODE BEGIN 6 */
+  mmc_rx_done = 0;
+  if (MMC_DMA_direction(DMA_PERIPH_TO_MEMORY) != HAL_OK)
+    return USBD_FAIL;
+  if (HAL_MMC_ReadBlocks_DMA(&hmmc1, buf, blk_addr, blk_len) != HAL_OK)
+    return USBD_FAIL;
+  while (!mmc_rx_done)
+    ;
+  while (HAL_MMC_GetCardState(&hmmc1) != HAL_MMC_CARD_TRANSFER)
+    ; // FIXME: IMPLEMENT TIMEOUT FAILSAFE
+  return USBD_OK;
+  /* USER CODE END 6 */
+}
+
+/**
+ * @brief  .
+ * @param  lun: .
+ * @retval USBD_OK if all operations are OK else USBD_FAIL
+ */
+int8_t STORAGE_Write_FS(uint8_t lun, uint8_t *buf, uint32_t blk_addr, uint16_t blk_len)
+{
+  /* USER CODE BEGIN 7 */
+  mmc_tx_done = 0;
+  if (MMC_DMA_direction(DMA_MEMORY_TO_PERIPH) != HAL_OK)
+    return USBD_FAIL;
+  if (HAL_MMC_WriteBlocks_DMA(&hmmc1, buf, blk_addr, blk_len) != HAL_OK)
+    return USBD_FAIL;
+  while (!mmc_tx_done)
+    ;
+  while (HAL_MMC_GetCardState(&hmmc1) != HAL_MMC_CARD_TRANSFER)
+    ; // FIXME: IMPLEMENT TIMEOUT FAILSAFE
+  return USBD_OK;
+  /* USER CODE END 7 */
+}
+
+/**
+ * @brief  .
+ * @param  None
+ * @retval .
+ */
+int8_t STORAGE_GetMaxLun_FS(void)
+{
+  /* USER CODE BEGIN 8 */
+  return STORAGE_LUN_NBR - 1;
+  /* USER CODE END 8 */
+}
+```
+
+## Conclusion
+
+I will update this post with more cases as I run into them. Comment on your experiences debugging USB on STM32 and I'll quote them in the article.