Deploying to gh-pages from @ cherry-embedded/CherryUSB@11b91a028309a16068dc91ae882ce694a1472c25 🚀

_sources/api/api_host.rst.txt

@@ -198,7 +198,7 @@ usbh_serial_control
 usbh_serial_write
 """"""""""""""""""""""""""""""""""""
 
-``usbh_serial_write`` 向串口写数据。 **串口设备如果是 USB2TTL 类型，必须按照波特率发送，否则会丢包**
+``usbh_serial_write`` 向串口写数据。
 
 .. code-block:: C
 
@@ -214,7 +214,7 @@ usbh_serial_write
 usbh_serial_read
 """"""""""""""""""""""""""""""""""""
 
-``usbh_serial_read`` 从串口读数据。 **如果没有设置波特率，不允许使用该 API**。
+``usbh_serial_read`` 从串口读数据。 **如果没有设置波特率，不允许使用该 API，设置波特率后，内部会开启 rx 接收并将数据写入 ringbuf **。
 
 .. code-block:: C
 
@@ -244,7 +244,7 @@ usbh_serial_cdc_write_async
 usbh_serial_cdc_read_async
 """"""""""""""""""""""""""""""""""""
 
-``usbh_serial_cdc_read_async`` 异步从串口读数据。 **如果设置了波特率，不允许使用该 API**。
+``usbh_serial_cdc_read_async`` 异步从串口读数据。 **如果设置了波特率，不允许使用该 API，设置波特率后，内部会开启 rx 接收并将数据写入 ringbuf **。
 
 .. code-block:: C
 

_sources/demo/usbh_serial.rst.txt

@@ -43,7 +43,6 @@ Serial 框架当前支持 cdc acm, ftdi, cp210x, ch34x, pl2303，gsm 驱动。
             goto delete_with_close;
         } else {
             serial_tx_bytes += ret;
-            usb_osal_msleep(10); // 11.52 Byte/ms at 115200bps --> 64Byte/5.5ms
 
             if (serial_tx_bytes == SERIAL_TEST_LEN) {
                 USB_LOG_RAW("send over\r\n");
@@ -55,7 +54,7 @@ Serial 框架当前支持 cdc acm, ftdi, cp210x, ch34x, pl2303，gsm 驱动。
     volatile uint32_t wait_timeout = 0;
     serial_rx_bytes = 0;
     while (1) {
-        ret = usbh_serial_read(serial, &serial_rx_data[serial_rx_bytes], SERIAL_TEST_LEN);
+        ret = usbh_serial_read(serial, &serial_rx_data[serial_rx_bytes], SERIAL_TEST_LEN - serial_rx_bytes);
         if (ret < 0) {
             USB_LOG_RAW("serial read error, ret:%d\r\n", ret);
             goto delete_with_close;
@@ -86,11 +85,12 @@ Serial 框架当前支持 cdc acm, ftdi, cp210x, ch34x, pl2303，gsm 驱动。
 
     usbh_serial_close(serial);
 
+.. note:: 需要注意，例程中使用的是比较简单的先发送后读取的方式，因此发送的总长度不可以超过 CONFIG_USBHOST_SERIAL_RX_SIZE，正常使用 TX/RX 请分开进行。
 
 用户需要考虑以下三种场景：
 
-- USB2TTL 设备 + 启用了波特率，这种情况下需要使用 `usbh_serial_write` 和 `usbh_serial_read` 进行收发数据， **并且需要根据波特率控制发送频率，防止对端丢包**；
+- USB2TTL 设备 + 启用了波特率，这种情况下需要使用 `usbh_serial_write` 和 `usbh_serial_read` 进行收发数据， **并且 read 操作需要及时，防止 ringbuf 数据溢出而丢包**；
 
-- 纯 USB 设备 + 未启动波特率，这种情况下可以使用 `usbh_serial_cdc_write_async` 和 `usbh_serial_cdc_read_async` 进行异步收发数据，阻塞则用 `usbh_serial_write` 并且不需要控制发送频率。不可以使用 `usbh_serial_read`。
+- 纯 USB 设备 + 未启动波特率，这种情况下可以使用 `usbh_serial_cdc_write_async` 和 `usbh_serial_cdc_read_async` 进行异步收发数据。阻塞则可以用 `usbh_serial_write` ，不可以使用 `usbh_serial_read`。
 
-- 纯 USB 设备 + 启动波特率，同 1，但是速率打折扣。不可以使用 `usbh_serial_cdc_write_async` 和 `usbh_serial_cdc_read_async`。如果是 GSM 设备需要使用第一种。
+- 纯 USB 设备 + 启动波特率，同 1，但是速率打折扣（因为多了一层 ringbuf）。此时也不可以使用 `usbh_serial_cdc_write_async` 和 `usbh_serial_cdc_read_async`。 **如果是 GSM 设备请使用第一种场景**。

api/api_host.html

@@ -370,7 +370,7 @@
 </section>
 <section id="usbh-serial-write">
 <h3>usbh_serial_write<a class="headerlink" href="#usbh-serial-write" title="Link to this heading"></a></h3>
-<p><code class="docutils literal notranslate"><span class="pre">usbh_serial_write</span></code> 向串口写数据。 <strong>串口设备如果是 USB2TTL 类型，必须按照波特率发送，否则会丢包</strong></p>
+<p><code class="docutils literal notranslate"><span class="pre">usbh_serial_write</span></code> 向串口写数据。</p>
 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="nf">usbh_serial_write</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">usbh_serial</span><span class="w"> </span><span class="o">*</span><span class="n">serial</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">void</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">buflen</span><span class="p">);</span>
 </pre></div>
 </div>
@@ -387,7 +387,7 @@
 </section>
 <section id="usbh-serial-read">
 <h3>usbh_serial_read<a class="headerlink" href="#usbh-serial-read" title="Link to this heading"></a></h3>
-<p><code class="docutils literal notranslate"><span class="pre">usbh_serial_read</span></code> 从串口读数据。 <strong>如果没有设置波特率，不允许使用该 API</strong>。</p>
+<p><code class="docutils literal notranslate"><span class="pre">usbh_serial_read</span></code> 从串口读数据。 <a href="#id6"><span class="problematic" id="id7">**</span></a>如果没有设置波特率，不允许使用该 API，设置波特率后，内部会开启 rx 接收并将数据写入 ringbuf <a href="#id8"><span class="problematic" id="id9">**</span></a>。</p>
 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="nf">usbh_serial_read</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">usbh_serial</span><span class="w"> </span><span class="o">*</span><span class="n">serial</span><span class="p">,</span><span class="w"> </span><span class="kt">void</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">buflen</span><span class="p">);</span>
 </pre></div>
 </div>
@@ -415,7 +415,7 @@
 </section>
 <section id="usbh-serial-cdc-read-async">
 <h3>usbh_serial_cdc_read_async<a class="headerlink" href="#usbh-serial-cdc-read-async" title="Link to this heading"></a></h3>
-<p><code class="docutils literal notranslate"><span class="pre">usbh_serial_cdc_read_async</span></code> 异步从串口读数据。 <strong>如果设置了波特率，不允许使用该 API</strong>。</p>
+<p><code class="docutils literal notranslate"><span class="pre">usbh_serial_cdc_read_async</span></code> 异步从串口读数据。 <a href="#id10"><span class="problematic" id="id11">**</span></a>如果设置了波特率，不允许使用该 API，设置波特率后，内部会开启 rx 接收并将数据写入 ringbuf <a href="#id12"><span class="problematic" id="id13">**</span></a>。</p>
 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="nf">usbh_serial_cdc_read_async</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">usbh_serial</span><span class="w"> </span><span class="o">*</span><span class="n">serial</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">buflen</span><span class="p">,</span><span class="w"> </span><span class="n">usbh_complete_callback_t</span><span class="w"> </span><span class="n">complete</span><span class="p">,</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">arg</span><span class="p">);</span>
 </pre></div>
 </div>

demo/usbh_serial.html

@@ -197,7 +197,6 @@
 <span class="w">        </span><span class="k">goto</span><span class="w"> </span><span class="n">delete_with_close</span><span class="p">;</span>
 <span class="w">    </span><span class="p">}</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="p">{</span>
 <span class="w">        </span><span class="n">serial_tx_bytes</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">ret</span><span class="p">;</span>
-<span class="w">        </span><span class="n">usb_osal_msleep</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span><span class="w"> </span><span class="c1">// 11.52 Byte/ms at 115200bps --&gt; 64Byte/5.5ms</span>
 
 <span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">serial_tx_bytes</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">SERIAL_TEST_LEN</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
 <span class="w">            </span><span class="n">USB_LOG_RAW</span><span class="p">(</span><span class="s">&quot;send over</span><span class="se">\r\n</span><span class="s">&quot;</span><span class="p">);</span>
@@ -209,7 +208,7 @@
 <span class="k">volatile</span><span class="w"> </span><span class="kt">uint32_t</span><span class="w"> </span><span class="n">wait_timeout</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
 <span class="n">serial_rx_bytes</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
 <span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
-<span class="w">    </span><span class="n">ret</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">usbh_serial_read</span><span class="p">(</span><span class="n">serial</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">serial_rx_data</span><span class="p">[</span><span class="n">serial_rx_bytes</span><span class="p">],</span><span class="w"> </span><span class="n">SERIAL_TEST_LEN</span><span class="p">);</span>
+<span class="w">    </span><span class="n">ret</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">usbh_serial_read</span><span class="p">(</span><span class="n">serial</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">serial_rx_data</span><span class="p">[</span><span class="n">serial_rx_bytes</span><span class="p">],</span><span class="w"> </span><span class="n">SERIAL_TEST_LEN</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">serial_rx_bytes</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">ret</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="mi">0</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
 <span class="w">        </span><span class="n">USB_LOG_RAW</span><span class="p">(</span><span class="s">&quot;serial read error, ret:%d</span><span class="se">\r\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">ret</span><span class="p">);</span>
 <span class="w">        </span><span class="k">goto</span><span class="w"> </span><span class="n">delete_with_close</span><span class="p">;</span>
@@ -241,11 +240,15 @@
 <span class="n">usbh_serial_close</span><span class="p">(</span><span class="n">serial</span><span class="p">);</span>
 </pre></div>
 </div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>需要注意，例程中使用的是比较简单的先发送后读取的方式，因此发送的总长度不可以超过 CONFIG_USBHOST_SERIAL_RX_SIZE，正常使用 TX/RX 请分开进行。</p>
+</div>
 <p>用户需要考虑以下三种场景：</p>
 <ul class="simple">
-<li><p>USB2TTL 设备 + 启用了波特率，这种情况下需要使用 <cite>usbh_serial_write</cite> 和 <cite>usbh_serial_read</cite> 进行收发数据， <strong>并且需要根据波特率控制发送频率，防止对端丢包</strong>；</p></li>
-<li><p>纯 USB 设备 + 未启动波特率，这种情况下可以使用 <cite>usbh_serial_cdc_write_async</cite> 和 <cite>usbh_serial_cdc_read_async</cite> 进行异步收发数据，阻塞则用 <cite>usbh_serial_write</cite> 并且不需要控制发送频率。不可以使用 <cite>usbh_serial_read</cite>。</p></li>
-<li><p>纯 USB 设备 + 启动波特率，同 1，但是速率打折扣。不可以使用 <cite>usbh_serial_cdc_write_async</cite> 和 <cite>usbh_serial_cdc_read_async</cite>。如果是 GSM 设备需要使用第一种。</p></li>
+<li><p>USB2TTL 设备 + 启用了波特率，这种情况下需要使用 <cite>usbh_serial_write</cite> 和 <cite>usbh_serial_read</cite> 进行收发数据， <strong>并且 read 操作需要及时，防止 ringbuf 数据溢出而丢包</strong>；</p></li>
+<li><p>纯 USB 设备 + 未启动波特率，这种情况下可以使用 <cite>usbh_serial_cdc_write_async</cite> 和 <cite>usbh_serial_cdc_read_async</cite> 进行异步收发数据。阻塞则可以用 <cite>usbh_serial_write</cite> ，不可以使用 <cite>usbh_serial_read</cite>。</p></li>
+<li><p>纯 USB 设备 + 启动波特率，同 1，但是速率打折扣（因为多了一层 ringbuf）。此时也不可以使用 <cite>usbh_serial_cdc_write_async</cite> 和 <cite>usbh_serial_cdc_read_async</cite>。 <strong>如果是 GSM 设备请使用第一种场景</strong>。</p></li>
 </ul>
 </section>