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

_sources/demo/usbh_net.rst.txt

@@ -3,9 +3,12 @@ usbh_net
 
 本节主要介绍 USB 网卡的使用，USB 网卡推荐采用 AIR780(RNDIS)，EC20(ECM/RNDIS), 手机（RNDIS）,RTL8152 USB 网卡，AX88772 USB 网卡。
 
-USB 网卡传输层面已经对接好了 LWIP 的收发接口，因此，用户只需要包含 **platform/XXX/usbh_lwip.c** 并根据需要开启对应的网卡类的宏即可。
+.. note:: 看完下面内容，你将感受到什么是全自动化的 USB 网卡驱动对接，无需手动调用任何函数。
 
-- 当前支持以下网卡类：
+USB 网卡相关的宏和文件
+------------------------
+
+网卡相关的宏如下，主要用于根据不同的网络组件注册网卡驱动：
 
 .. code-block:: C
 
@@ -14,34 +17,24 @@ USB 网卡传输层面已经对接好了 LWIP 的收发接口，因此，用户
     // #define CONFIG_USBHOST_PLATFORM_CDC_NCM
     // #define CONFIG_USBHOST_PLATFORM_ASIX
     // #define CONFIG_USBHOST_PLATFORM_RTL8152
-    // #define CONFIG_USBHOST_PLATFORM_BL616
 
-- 包含了对接 LWIP 的输入输出接口，举例如下
+.. note:: 如果使用 Kconfig 系统，上述宏自定生成，其他平台请手动定义。
 
-.. code-block:: C
+USB 网卡传输层面已经对接好了相关网络组件，列举如下：
 
-    static err_t usbh_cdc_ecm_linkoutput(struct netif *netif, struct pbuf *p)
-    {
-        int ret;
-        (void)netif;
+- 自定义 OS + LWIP 请使用 **platform/lwip/usbh_lwip.c**，需要自行包含该文件，并使能上述相关的宏
+- RT-THREAD + LWIP 请使用 **platform/rtthread/usbh_lwip.c**，在 Kconfig 中使能对应的网卡驱动后自动勾选该文件
+- ESP-IDF + LWIP 请使用 **platform/freertos/usbh_net.c**，在 Kconfig 中使能对应的网卡驱动后自动勾选该文件
+- NUTTX + NUTTX 网络组件 请使用 **platform/nuttx/usbh_net.c**，在 Kconfig 中使能对应的网卡驱动后自动勾选该文件
 
-        usbh_lwip_eth_output_common(p, usbh_cdc_ecm_get_eth_txbuf());
-        ret = usbh_cdc_ecm_eth_output(p->tot_len);
-        if (ret < 0) {
-            return ERR_BUF;
-        } else {
-            return ERR_OK;
-        }
-    }
+.. note:: 如果是自行添加代码，别忘了添加  USB 网卡驱动相关的源文件，例如 **class/usbh_cdc_ecm.c**。所以我们推荐搭配对应平台使用哦，省去自己添加文件的麻烦
 
-    void usbh_cdc_ecm_eth_input(uint8_t *buf, uint32_t buflen)
-    {
-        usbh_lwip_eth_input_common(&g_cdc_ecm_netif, buf, buflen);
-    }
+USB 网卡对接过程
+-------------------
 
+下面举例对接 LWIP 的对接过程。
 
-- 网卡类枚举完成后，注册 netif，并且创建网卡接收线程（因此使用 RTTHREAD 时不需要使用 RTT 的接收线程模块）。
-- 必须开启 DHCP client 服务，用于从 USB 网卡获取 IP 地址。
+- 在 USB 网卡枚举完成以后，会 **自动** 调用 `usbh_xxx_run` 函数，此时注册 netif 驱动，并且开启 DHCP 客户端和获取 IP 的定时器。
 
 .. code-block:: C
 
@@ -75,17 +68,61 @@ USB 网卡传输层面已经对接好了 LWIP 的收发接口，因此，用户
     #endif
     }
 
-- 获取到 IP 以后，就与 USB 没有关系了，直接使用 LWIP 的接口即可。
+- `usbh_lwip_eth_output_common` 用于将发送 pbuf 组装成 USB 网卡数据包
+- `usbh_lwip_eth_input_common` 用于将 USB 网卡数据组装成 pbuf
+- 实际网卡发送和接收处理
 
-- 需要注意以下参数
+.. code-block:: C
 
-LWIP_TCPIP_CORE_LOCKING_INPUT 用于不使用 lwip 内置的 tcpip 线程，而使用 USB 自己的处理线程。
+    static err_t usbh_cdc_ecm_linkoutput(struct netif *netif, struct pbuf *p)
+    {
+        int ret;
+        (void)netif;
 
-LWIP_TCPIP_CORE_LOCKING 在现在 lwip 版本中默认是打开的，也推荐必须打开。
+        usbh_lwip_eth_output_common(p, usbh_cdc_ecm_get_eth_txbuf());
+        ret = usbh_cdc_ecm_eth_output(p->tot_len);
+        if (ret < 0) {
+            return ERR_BUF;
+        } else {
+            return ERR_OK;
+        }
+    }
 
-PBUF_POOL_BUFSIZE 推荐大于1600，搭配 LWIP_TCPIP_CORE_LOCKING_INPUT 使用，因为我们提供了使用 zero mempy 的方式，使用静态 pbuf，而不是把数据 copy 到 pbuf 中。
+    void usbh_cdc_ecm_eth_input(uint8_t *buf, uint32_t buflen)
+    {
+        usbh_lwip_eth_input_common(&g_cdc_ecm_netif, buf, buflen);
+    }
 
-TCPIP_THREAD_STACKSIZE 推荐大于 1K，防止栈溢出。
+- USB 网卡 拔出以后会 **自动** 调用 `usbh_xxx_stop` 函数，此时需要停止 DHCP 客户端，删除定时器，并且移除 netif。
+
+.. code-block:: C
+
+    void usbh_cdc_ecm_stop(struct usbh_cdc_ecm *cdc_ecm_class)
+    {
+        struct netif *netif = &g_cdc_ecm_netif;
+        (void)cdc_ecm_class;
+
+    #if LWIP_DHCP
+        dhcp_stop(netif);
+        dhcp_cleanup(netif);
+        usb_osal_timer_delete(dhcp_handle);
+    #endif
+        netif_set_down(netif);
+        netif_remove(netif);
+    }
+
+- 因为 USB 网卡内部已经对接了LWIP，因此用户可以直接使用 LWIP 的 API，无需关心 USB 的实现。
+
+USB 网卡 LWIP 配置宏相关注意事项
+------------------------------------
+
+**LWIP_TCPIP_CORE_LOCKING_INPUT** 用于不使用 lwip 内置的 tcpip 线程，而使用 USB 自己的接收处理线程。
+
+**LWIP_TCPIP_CORE_LOCKING** 在现在 lwip 版本中默认是打开的，也推荐必须打开。
+
+**PBUF_POOL_BUFSIZE** 推荐大于1600，搭配 LWIP_TCPIP_CORE_LOCKING_INPUT 使用，因为我们提供了使用 zero mempy 的方式，使用静态 pbuf，而不是把数据 copy 到 pbuf 中。
+
+**TCPIP_THREAD_STACKSIZE** 推荐大于 1K，防止栈溢出。
 
 .. code-block:: C
 

demo/usbh_net.html

@@ -93,7 +93,12 @@
 <li class="toctree-l1"><a class="reference internal" href="usbh_serial.html">usbh_serial</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usbh_hid.html">usbh_hid</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usbh_msc.html">usbh_msc</a></li>
-<li class="toctree-l1 current"><a class="current reference internal" href="#">usbh_net</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">usbh_net</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#usb">USB 网卡相关的宏和文件</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#id1">USB 网卡对接过程</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#usb-lwip">USB 网卡 LWIP 配置宏相关注意事项</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="usbh_bluetooth.html">usbh_bluetooth</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usbh_wifi.html">usbh_wifi</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usbd_vendor.html">vendor device 驱动编写</a></li>
@@ -160,44 +165,41 @@
   <section id="usbh-net">
 <h1>usbh_net<a class="headerlink" href="#usbh-net" title="Link to this heading"></a></h1>
 <p>本节主要介绍 USB 网卡的使用，USB 网卡推荐采用 AIR780(RNDIS)，EC20(ECM/RNDIS), 手机（RNDIS）,RTL8152 USB 网卡，AX88772 USB 网卡。</p>
-<p>USB 网卡传输层面已经对接好了 LWIP 的收发接口，因此，用户只需要包含 <strong>platform/XXX/usbh_lwip.c</strong> 并根据需要开启对应的网卡类的宏即可。</p>
-<ul class="simple">
-<li><p>当前支持以下网卡类：</p></li>
-</ul>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>看完下面内容，你将感受到什么是全自动化的 USB 网卡驱动对接，无需手动调用任何函数。</p>
+</div>
+<section id="usb">
+<h2>USB 网卡相关的宏和文件<a class="headerlink" href="#usb" title="Link to this heading"></a></h2>
+<p>网卡相关的宏如下，主要用于根据不同的网络组件注册网卡驱动：</p>
 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="c1">// #define CONFIG_USBHOST_PLATFORM_CDC_ECM</span>
 <span class="c1">// #define CONFIG_USBHOST_PLATFORM_CDC_RNDIS</span>
 <span class="c1">// #define CONFIG_USBHOST_PLATFORM_CDC_NCM</span>
 <span class="c1">// #define CONFIG_USBHOST_PLATFORM_ASIX</span>
 <span class="c1">// #define CONFIG_USBHOST_PLATFORM_RTL8152</span>
-<span class="c1">// #define CONFIG_USBHOST_PLATFORM_BL616</span>
 </pre></div>
 </div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>如果使用 Kconfig 系统，上述宏自定生成，其他平台请手动定义。</p>
+</div>
+<p>USB 网卡传输层面已经对接好了相关网络组件，列举如下：</p>
 <ul class="simple">
-<li><p>包含了对接 LWIP 的输入输出接口，举例如下</p></li>
+<li><p>自定义 OS + LWIP 请使用 <strong>platform/lwip/usbh_lwip.c</strong>，需要自行包含该文件，并使能上述相关的宏</p></li>
+<li><p>RT-THREAD + LWIP 请使用 <strong>platform/rtthread/usbh_lwip.c</strong>，在 Kconfig 中使能对应的网卡驱动后自动勾选该文件</p></li>
+<li><p>ESP-IDF + LWIP 请使用 <strong>platform/freertos/usbh_net.c</strong>，在 Kconfig 中使能对应的网卡驱动后自动勾选该文件</p></li>
+<li><p>NUTTX + NUTTX 网络组件 请使用 <strong>platform/nuttx/usbh_net.c</strong>，在 Kconfig 中使能对应的网卡驱动后自动勾选该文件</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="n">err_t</span><span class="w"> </span><span class="nf">usbh_cdc_ecm_linkoutput</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">netif</span><span class="w"> </span><span class="o">*</span><span class="n">netif</span><span class="p">,</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">pbuf</span><span class="w"> </span><span class="o">*</span><span class="n">p</span><span class="p">)</span>
-<span class="p">{</span>
-<span class="w">    </span><span class="kt">int</span><span class="w"> </span><span class="n">ret</span><span class="p">;</span>
-<span class="w">    </span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="n">netif</span><span class="p">;</span>
-
-<span class="w">    </span><span class="n">usbh_lwip_eth_output_common</span><span class="p">(</span><span class="n">p</span><span class="p">,</span><span class="w"> </span><span class="n">usbh_cdc_ecm_get_eth_txbuf</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_cdc_ecm_eth_output</span><span class="p">(</span><span class="n">p</span><span class="o">-&gt;</span><span class="n">tot_len</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="k">return</span><span class="w"> </span><span class="n">ERR_BUF</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="k">return</span><span class="w"> </span><span class="n">ERR_OK</span><span class="p">;</span>
-<span class="w">    </span><span class="p">}</span>
-<span class="p">}</span>
-
-<span class="kt">void</span><span class="w"> </span><span class="nf">usbh_cdc_ecm_eth_input</span><span class="p">(</span><span class="kt">uint8_t</span><span class="w"> </span><span class="o">*</span><span class="n">buf</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="p">{</span>
-<span class="w">    </span><span class="n">usbh_lwip_eth_input_common</span><span class="p">(</span><span class="o">&amp;</span><span class="n">g_cdc_ecm_netif</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="n">buflen</span><span class="p">);</span>
-<span class="p">}</span>
-</pre></div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>如果是自行添加代码，别忘了添加  USB 网卡驱动相关的源文件，例如 <strong>class/usbh_cdc_ecm.c</strong>。所以我们推荐搭配对应平台使用哦，省去自己添加文件的麻烦</p>
 </div>
+</section>
+<section id="id1">
+<h2>USB 网卡对接过程<a class="headerlink" href="#id1" title="Link to this heading"></a></h2>
+<p>下面举例对接 LWIP 的对接过程。</p>
 <ul class="simple">
-<li><p>网卡类枚举完成后，注册 netif，并且创建网卡接收线程（因此使用 RTTHREAD 时不需要使用 RTT 的接收线程模块）。</p></li>
-<li><p>必须开启 DHCP client 服务，用于从 USB 网卡获取 IP 地址。</p></li>
+<li><p>在 USB 网卡枚举完成以后，会 <strong>自动</strong> 调用 <cite>usbh_xxx_run</cite> 函数，此时注册 netif 驱动，并且开启 DHCP 客户端和获取 IP 的定时器。</p></li>
 </ul>
 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span><span class="w"> </span><span class="nf">usbh_cdc_ecm_run</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">usbh_cdc_ecm</span><span class="w"> </span><span class="o">*</span><span class="n">cdc_ecm_class</span><span class="p">)</span>
 <span class="p">{</span>
@@ -231,13 +233,58 @@
 </pre></div>
 </div>
 <ul class="simple">
-<li><p>获取到 IP 以后，就与 USB 没有关系了，直接使用 LWIP 的接口即可。</p></li>
-<li><p>需要注意以下参数</p></li>
+<li><p><cite>usbh_lwip_eth_output_common</cite> 用于将发送 pbuf 组装成 USB 网卡数据包</p></li>
+<li><p><cite>usbh_lwip_eth_input_common</cite> 用于将 USB 网卡数据组装成 pbuf</p></li>
+<li><p>实际网卡发送和接收处理</p></li>
 </ul>
-<p>LWIP_TCPIP_CORE_LOCKING_INPUT 用于不使用 lwip 内置的 tcpip 线程，而使用 USB 自己的处理线程。</p>
-<p>LWIP_TCPIP_CORE_LOCKING 在现在 lwip 版本中默认是打开的，也推荐必须打开。</p>
-<p>PBUF_POOL_BUFSIZE 推荐大于1600，搭配 LWIP_TCPIP_CORE_LOCKING_INPUT 使用，因为我们提供了使用 zero mempy 的方式，使用静态 pbuf，而不是把数据 copy 到 pbuf 中。</p>
-<p>TCPIP_THREAD_STACKSIZE 推荐大于 1K，防止栈溢出。</p>
+<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="n">err_t</span><span class="w"> </span><span class="nf">usbh_cdc_ecm_linkoutput</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">netif</span><span class="w"> </span><span class="o">*</span><span class="n">netif</span><span class="p">,</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">pbuf</span><span class="w"> </span><span class="o">*</span><span class="n">p</span><span class="p">)</span>
+<span class="p">{</span>
+<span class="w">    </span><span class="kt">int</span><span class="w"> </span><span class="n">ret</span><span class="p">;</span>
+<span class="w">    </span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="n">netif</span><span class="p">;</span>
+
+<span class="w">    </span><span class="n">usbh_lwip_eth_output_common</span><span class="p">(</span><span class="n">p</span><span class="p">,</span><span class="w"> </span><span class="n">usbh_cdc_ecm_get_eth_txbuf</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_cdc_ecm_eth_output</span><span class="p">(</span><span class="n">p</span><span class="o">-&gt;</span><span class="n">tot_len</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="k">return</span><span class="w"> </span><span class="n">ERR_BUF</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="k">return</span><span class="w"> </span><span class="n">ERR_OK</span><span class="p">;</span>
+<span class="w">    </span><span class="p">}</span>
+<span class="p">}</span>
+
+<span class="kt">void</span><span class="w"> </span><span class="nf">usbh_cdc_ecm_eth_input</span><span class="p">(</span><span class="kt">uint8_t</span><span class="w"> </span><span class="o">*</span><span class="n">buf</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="p">{</span>
+<span class="w">    </span><span class="n">usbh_lwip_eth_input_common</span><span class="p">(</span><span class="o">&amp;</span><span class="n">g_cdc_ecm_netif</span><span class="p">,</span><span class="w"> </span><span class="n">buf</span><span class="p">,</span><span class="w"> </span><span class="n">buflen</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><p>USB 网卡 拔出以后会 <strong>自动</strong> 调用 <cite>usbh_xxx_stop</cite> 函数，此时需要停止 DHCP 客户端，删除定时器，并且移除 netif。</p></li>
+</ul>
+<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span><span class="w"> </span><span class="nf">usbh_cdc_ecm_stop</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">usbh_cdc_ecm</span><span class="w"> </span><span class="o">*</span><span class="n">cdc_ecm_class</span><span class="p">)</span>
+<span class="p">{</span>
+<span class="w">    </span><span class="k">struct</span><span class="w"> </span><span class="nc">netif</span><span class="w"> </span><span class="o">*</span><span class="n">netif</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">&amp;</span><span class="n">g_cdc_ecm_netif</span><span class="p">;</span>
+<span class="w">    </span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="n">cdc_ecm_class</span><span class="p">;</span>
+
+<span class="cp">#if LWIP_DHCP</span>
+<span class="w">    </span><span class="n">dhcp_stop</span><span class="p">(</span><span class="n">netif</span><span class="p">);</span>
+<span class="w">    </span><span class="n">dhcp_cleanup</span><span class="p">(</span><span class="n">netif</span><span class="p">);</span>
+<span class="w">    </span><span class="n">usb_osal_timer_delete</span><span class="p">(</span><span class="n">dhcp_handle</span><span class="p">);</span>
+<span class="cp">#endif</span>
+<span class="w">    </span><span class="n">netif_set_down</span><span class="p">(</span><span class="n">netif</span><span class="p">);</span>
+<span class="w">    </span><span class="n">netif_remove</span><span class="p">(</span><span class="n">netif</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><p>因为 USB 网卡内部已经对接了LWIP，因此用户可以直接使用 LWIP 的 API，无需关心 USB 的实现。</p></li>
+</ul>
+</section>
+<section id="usb-lwip">
+<h2>USB 网卡 LWIP 配置宏相关注意事项<a class="headerlink" href="#usb-lwip" title="Link to this heading"></a></h2>
+<p><strong>LWIP_TCPIP_CORE_LOCKING_INPUT</strong> 用于不使用 lwip 内置的 tcpip 线程，而使用 USB 自己的接收处理线程。</p>
+<p><strong>LWIP_TCPIP_CORE_LOCKING</strong> 在现在 lwip 版本中默认是打开的，也推荐必须打开。</p>
+<p><strong>PBUF_POOL_BUFSIZE</strong> 推荐大于1600，搭配 LWIP_TCPIP_CORE_LOCKING_INPUT 使用，因为我们提供了使用 zero mempy 的方式，使用静态 pbuf，而不是把数据 copy 到 pbuf 中。</p>
+<p><strong>TCPIP_THREAD_STACKSIZE</strong> 推荐大于 1K，防止栈溢出。</p>
 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="cp">#if LWIP_TCPIP_CORE_LOCKING_INPUT != 1</span>
 <span class="cp">#warning suggest you to set LWIP_TCPIP_CORE_LOCKING_INPUT to 1, usb handles eth input with own thread</span>
 <span class="cp">#endif</span>
@@ -258,6 +305,7 @@
 <ul class="simple">
 <li><p>具体移植文章可以参考开发者的一些笔记 <a class="reference external" href="https://club.rt-thread.org/ask/article/5cf3e9e0b2d95800.html">https://club.rt-thread.org/ask/article/5cf3e9e0b2d95800.html</a></p></li>
 </ul>
+</section>
 </section>