Deploying to gh-pages from @ cherry-embedded/CherryUSB@015aa774879792d42d8d358a6814585f1f64303d 🚀

_sources/demo/usbd_cdc_acm.rst.txt

@@ -11,7 +11,7 @@ usbd_cdc_acm
     USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t write_buffer[2048];
 
 
-- 协议栈回调中，我们需要在枚举完成后启动第一次传输，并清除相关 flag，可以在 reset 事件中清除，也可以在 configured 事件中清除。
+- 在协议栈事件回调中，我们需要在枚举完成后启动第一次传输，并清除相关 flag，可以在 reset 事件中清除，也可以在 configured 事件中清除。
 
 .. code-block:: C
 
@@ -98,4 +98,7 @@ usbd_cdc_acm
     }
 
 - 上述我们需要注意，长度设置为 2048 是为了测试 ZLP 功能，通常实际使用时，接收长度应该使用 CDC_MAX_MPS 。具体原因参考 :ref:`usb_ext`
-- 如果需要做性能测试，使用 tools/test_srcipts/test_cdc_speed.py 进行测试,并在测试之前删除 `usbd_cdc_acm_bulk_out` 和 `usbd_cdc_acm_bulk_in` 中的打印，否则会影响测试结果。
+- 如果需要做性能测试，使用 tools/test_srcipts/test_cdc_speed.py 进行测试,并在测试之前删除 `usbd_cdc_acm_bulk_out` 和 `usbd_cdc_acm_bulk_in` 中的打印，否则会影响测试结果。
+
+
+此外，对于 CDC ACM 搭配 OS 的情况，通常我们 read 使用异步并将数据存储到 ringbuffer 中，write 使用同步搭配 sem 使用。

_sources/demo/usbd_hid.rst.txt

@@ -1,2 +1,4 @@
 usbd_hid
 ===============
+
+HID 功能比较简单，因此不作赘述，需要注意，使用 hid custom 例程时，需要搭配 `tools/test_srcipts/test_hid_inout.py` 使用。

_sources/demo/usbd_msc.rst.txt

@@ -1,2 +1,39 @@
 usbd_msc
 ===============
+
+本节主要演示 USB 模拟 U 盘功能。默认使用RAM 作为存储介质模拟 U 盘。
+
+- 实现 U 盘的读写和获取容量接口，注意，容量 block_num 为虚拟的，实际没有这么多 block，读写的数据超过 BLOCK_COUNT 会丢弃。
+
+block_size 一般为 512/2048/4096。
+
+.. code-block:: C
+
+    void usbd_msc_get_cap(uint8_t busid, uint8_t lun, uint32_t *block_num, uint32_t *block_size)
+    {
+        *block_num = 1000; //Pretend having so many buffer,not has actually.
+        *block_size = BLOCK_SIZE;
+    }
+    int usbd_msc_sector_read(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length)
+    {
+        if (sector < BLOCK_COUNT)
+            memcpy(buffer, mass_block[sector].BlockSpace, length);
+        return 0;
+    }
+
+    int usbd_msc_sector_write(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length)
+    {
+        if (sector < BLOCK_COUNT)
+            memcpy(mass_block[sector].BlockSpace, buffer, length);
+        return 0;
+    }
+
+- 默认上述 API 在中断中执行，如果需要在非中断中执行，可以选择如下：
+
+1，裸机下开启 `CONFIG_USBDEV_MSC_POLLING` 并在 while1 中调用 `usbd_msc_polling`，则读写函数在 while1 中执行。
+
+2, OS 下开启 `CONFIG_USBDEV_MSC_THREAD`，则读写函数在线程中执行。
+
+- 修改  `CONFIG_USBDEV_MSC_STACKSIZE` 会影响 U 盘的读写速度，必须是 block_size 的整数倍，当然，也会增加 RAM 的占用。
+
+- 如果 RAM 例程可以用，但是介质更换成 SD 或者 FLASH 后不可用，则一定是介质驱动问题。

demo/usbd_cdc_acm.html

@@ -160,7 +160,7 @@
 </pre></div>
 </div>
 <ul class="simple">
-<li><p>协议栈回调中，我们需要在枚举完成后启动第一次传输，并清除相关 flag，可以在 reset 事件中清除，也可以在 configured 事件中清除。</p></li>
+<li><p>在协议栈事件回调中，我们需要在枚举完成后启动第一次传输，并清除相关 flag，可以在 reset 事件中清除，也可以在 configured 事件中清除。</p></li>
 </ul>
 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">usbd_event_handler</span><span class="p">(</span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">busid</span><span class="p">,</span><span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">event</span><span class="p">)</span>
 <span class="p">{</span>
@@ -249,6 +249,7 @@
 <li><p>上述我们需要注意，长度设置为 2048 是为了测试 ZLP 功能，通常实际使用时，接收长度应该使用 CDC_MAX_MPS 。具体原因参考 <a class="reference internal" href="../usb/usb_ext.html#usb-ext"><span class="std std-ref">USB 知识点拓展</span></a></p></li>
 <li><p>如果需要做性能测试，使用 tools/test_srcipts/test_cdc_speed.py 进行测试,并在测试之前删除 <cite>usbd_cdc_acm_bulk_out</cite> 和 <cite>usbd_cdc_acm_bulk_in</cite> 中的打印，否则会影响测试结果。</p></li>
 </ul>
+<p>此外，对于 CDC ACM 搭配 OS 的情况，通常我们 read 使用异步并将数据存储到 ringbuffer 中，write 使用同步搭配 sem 使用。</p>
 </section>
 
 

demo/usbd_hid.html

@@ -151,6 +151,7 @@
              
   <section id="usbd-hid">
 <h1>usbd_hid<a class="headerlink" href="#usbd-hid" title="Link to this heading"></a></h1>
+<p>HID 功能比较简单，因此不作赘述，需要注意，使用 hid custom 例程时，需要搭配 <cite>tools/test_srcipts/test_hid_inout.py</cite> 使用。</p>
 </section>
 
 

demo/usbd_msc.html

@@ -151,6 +151,40 @@
              
   <section id="usbd-msc">
 <h1>usbd_msc<a class="headerlink" href="#usbd-msc" title="Link to this heading"></a></h1>
+<p>本节主要演示 USB 模拟 U 盘功能。默认使用RAM 作为存储介质模拟 U 盘。</p>
+<ul class="simple">
+<li><p>实现 U 盘的读写和获取容量接口，注意，容量 block_num 为虚拟的，实际没有这么多 block，读写的数据超过 BLOCK_COUNT 会丢弃。</p></li>
+</ul>
+<p>block_size 一般为 512/2048/4096。</p>
+<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span><span class="w"> </span><span class="nf">usbd_msc_get_cap</span><span class="p">(</span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">busid</span><span class="p">,</span><span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">lun</span><span class="p">,</span><span class="w"> </span><span class="kt">uint32_t</span><span class="w"> </span><span class="o">*</span><span class="n">block_num</span><span class="p">,</span><span class="w"> </span><span class="kt">uint32_t</span><span class="w"> </span><span class="o">*</span><span class="n">block_size</span><span class="p">)</span>
+<span class="p">{</span>
+<span class="w">    </span><span class="o">*</span><span class="n">block_num</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1000</span><span class="p">;</span><span class="w"> </span><span class="c1">//Pretend having so many buffer,not has actually.</span>
+<span class="w">    </span><span class="o">*</span><span class="n">block_size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">BLOCK_SIZE</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="kt">int</span><span class="w"> </span><span class="nf">usbd_msc_sector_read</span><span class="p">(</span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">busid</span><span class="p">,</span><span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">lun</span><span class="p">,</span><span class="w"> </span><span class="kt">uint32_t</span><span class="w"> </span><span class="n">sector</span><span class="p">,</span><span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="o">*</span><span class="n">buffer</span><span class="p">,</span><span class="w"> </span><span class="kt">uint32_t</span><span class="w"> </span><span class="n">length</span><span class="p">)</span>
+<span class="p">{</span>
+<span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">sector</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">BLOCK_COUNT</span><span class="p">)</span>
+<span class="w">        </span><span class="n">memcpy</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span><span class="w"> </span><span class="n">mass_block</span><span class="p">[</span><span class="n">sector</span><span class="p">].</span><span class="n">BlockSpace</span><span class="p">,</span><span class="w"> </span><span class="n">length</span><span class="p">);</span>
+<span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">int</span><span class="w"> </span><span class="nf">usbd_msc_sector_write</span><span class="p">(</span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">busid</span><span class="p">,</span><span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">lun</span><span class="p">,</span><span class="w"> </span><span class="kt">uint32_t</span><span class="w"> </span><span class="n">sector</span><span class="p">,</span><span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="o">*</span><span class="n">buffer</span><span class="p">,</span><span class="w"> </span><span class="kt">uint32_t</span><span class="w"> </span><span class="n">length</span><span class="p">)</span>
+<span class="p">{</span>
+<span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">sector</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">BLOCK_COUNT</span><span class="p">)</span>
+<span class="w">        </span><span class="n">memcpy</span><span class="p">(</span><span class="n">mass_block</span><span class="p">[</span><span class="n">sector</span><span class="p">].</span><span class="n">BlockSpace</span><span class="p">,</span><span class="w"> </span><span class="n">buffer</span><span class="p">,</span><span class="w"> </span><span class="n">length</span><span class="p">);</span>
+<span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><p>默认上述 API 在中断中执行，如果需要在非中断中执行，可以选择如下：</p></li>
+</ul>
+<p>1，裸机下开启 <cite>CONFIG_USBDEV_MSC_POLLING</cite> 并在 while1 中调用 <cite>usbd_msc_polling</cite>，则读写函数在 while1 中执行。</p>
+<p>2, OS 下开启 <cite>CONFIG_USBDEV_MSC_THREAD</cite>，则读写函数在线程中执行。</p>
+<ul class="simple">
+<li><p>修改  <cite>CONFIG_USBDEV_MSC_STACKSIZE</cite> 会影响 U 盘的读写速度，必须是 block_size 的整数倍，当然，也会增加 RAM 的占用。</p></li>
+<li><p>如果 RAM 例程可以用，但是介质更换成 SD 或者 FLASH 后不可用，则一定是介质驱动问题。</p></li>
+</ul>
 </section>