From 41ffa44a3fc0187e8edd7ba07c576a2a73220b82 Mon Sep 17 00:00:00 2001 From: sakumisu <1203593632@qq.com> Date: Mon, 1 Dec 2025 12:28:55 +0800 Subject: docs: update rst Signed-off-by: sakumisu <1203593632@qq.com> --- docs/source/demo/usbd_audiov1.rst | 4 +- docs/source/demo/usbd_audiov2.rst | 7 +- docs/source/index.rst | 7 +- docs/source/opensource.rst | 62 --------------- docs/source/q&a.rst | 98 ----------------------- docs/source/quick_start/demo.rst | 15 ++++ docs/source/quick_start/esp.rst | 17 ---- docs/source/quick_start/img/question1.png | Bin 0 -> 12295 bytes docs/source/quick_start/img/question2.png | Bin 0 -> 40757 bytes docs/source/quick_start/opensource.rst | 62 +++++++++++++++ docs/source/quick_start/q&a.rst | 124 ++++++++++++++++++++++++++++++ docs/source/quick_start/share.rst | 27 +++++++ docs/source/share.rst | 27 ------- 13 files changed, 239 insertions(+), 211 deletions(-) delete mode 100644 docs/source/opensource.rst delete mode 100644 docs/source/q&a.rst delete mode 100644 docs/source/quick_start/esp.rst create mode 100644 docs/source/quick_start/img/question1.png create mode 100644 docs/source/quick_start/img/question2.png create mode 100644 docs/source/quick_start/opensource.rst create mode 100644 docs/source/quick_start/q&a.rst create mode 100644 docs/source/quick_start/share.rst delete mode 100644 docs/source/share.rst (limited to 'docs/source') diff --git a/docs/source/demo/usbd_audiov1.rst b/docs/source/demo/usbd_audiov1.rst index 9d2e3051..794ac8f6 100644 --- a/docs/source/demo/usbd_audiov1.rst +++ b/docs/source/demo/usbd_audiov1.rst @@ -1,5 +1,7 @@ usbd_audiov1 =============== -.. note:: 在使用windows 时,当修改描述符任意参数时,必须同步修改字符串描述符,并且卸载驱动,否则windows会认为设备未更改,继续使用旧的驱动,导致无法识别设备。Linux 不受此限制。 +在使用 UAC1.0 时,需要注意以下几点: +- 在使用windows 时,当修改描述符任意参数时,必须同步修改字符串描述符,并且卸载驱动,否则windows会认为设备未更改,继续使用旧的驱动,导致无法识别设备。Linux 不受此限制。 +- QQ 群文件中下载 RemoveGhostDev64.exe 可以自动删除所有 USB 注册的驱动信息,无需第一步 \ No newline at end of file diff --git a/docs/source/demo/usbd_audiov2.rst b/docs/source/demo/usbd_audiov2.rst index 816532c9..0390f17d 100644 --- a/docs/source/demo/usbd_audiov2.rst +++ b/docs/source/demo/usbd_audiov2.rst @@ -1,6 +1,9 @@ usbd_audiov2 =============== -.. note:: 在使用windows 时,当修改描述符任意参数时,必须同步修改字符串描述符,并且卸载驱动,否则windows会认为设备未更改,继续使用旧的驱动,导致无法识别设备。Linux 不受此限制。 +在使用 UAC2.0 时,需要注意以下几点: -.. note:: windows 10 uac2.0 功能不完善,请使用 windows 11 测试uac2.0 功能。Linux 不受此限制。 \ No newline at end of file +- 在使用windows 时,当修改描述符任意参数时,必须同步修改字符串描述符,并且卸载驱动,否则windows会认为设备未更改,继续使用旧的驱动,导致无法识别设备。Linux 不受此限制。 +- QQ 群文件中下载 RemoveGhostDev64.exe 可以自动删除所有 USB 注册的驱动信息,无需第一步 +- windows 10 uac2.0 功能不完善,请使用 windows 11 测试uac2.0 功能。Linux 不受此限制 +- windows 中设置的采样率表范围在多通道时(通道数大于2)计算有误,比如设置 8K~96K,那么实际是大于等于8K 小于96K,而非小于等于96K。Linux 不受此限制 diff --git a/docs/source/index.rst b/docs/source/index.rst index a6dc3d8a..8cdb78cd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -56,10 +56,9 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 quick_start/demo quick_start/transplant quick_start/rtthread - quick_start/esp - q&a - opensource - share + quick_start/q&a + quick_start/share + quick_start/opensource .. toctree:: :maxdepth: 1 diff --git a/docs/source/opensource.rst b/docs/source/opensource.rst deleted file mode 100644 index 7990538e..00000000 --- a/docs/source/opensource.rst +++ /dev/null @@ -1,62 +0,0 @@ -官方开源项目分享 -==================== - -除了基本的厂家 SDK 支持以外,我们还对一些火热的开源项目进行了支持,以便于开发者更好的使用这些项目。下面列举适配的 demo 工程链接,具体适配层参考 https://github.com/cherry-embedded/CherryUSB/tree/master/platform 。 - -DAPLINK --------------- - -适配链接:https://github.com/cherry-embedded/CherryDAP - -Blackmagic --------------- - -适配链接:https://github.com/zhangjiance/bmp-hpm-port - -RT-Thread --------------- - -适配链接:https://github.com/RT-Thread/rt-thread - -NUTTX/VELA --------------- - -适配链接:https://github.com/CherryUSB/cherryusb_nuttx - -Zephyr --------------- - -适配链接:https://github.com/hpmicro/zephyr_sdk_glue - -Cangaroo --------------- - -Cangaroo is an open source can bus analyzer software. We provide four-channel CANFD analyzer based on hpmicro hpm5361 - -适配上位机链接:https://github.com/RCSN/cangaroo_hpmicro_canfd_analyzer -适配下位机链接:https://github.com/RCSN/hpm_sdk_extra/tree/main/demos/cangaroo_hpmicro - -LVGL --------------- - -适配链接:https://github.com/cherry-embedded/CherryUSB/tree/master/platform/lvgl - -QMK --------------- - -QMK is an open-source keyboard firmware for Atmel AVR and Arm USB families. - -适配链接:待开放 - -Klipper --------------- - -Klipper is a 3d-printer firmware. - -适配链接:待开放 - - -MAKCU/KMBOX --------------- - -懂的都懂,不开放 \ No newline at end of file diff --git a/docs/source/q&a.rst b/docs/source/q&a.rst deleted file mode 100644 index 59b9dc7d..00000000 --- a/docs/source/q&a.rst +++ /dev/null @@ -1,98 +0,0 @@ -Q & A -============================== - -移植提问模板 ----------------- - -请在下列途径提交问题: -- RT-Thread 官方论坛: https://club.rt-thread.org/ask/tag/5f5f851966917b14.html -- Github issue: https://github.com/cherry-embedded/CherryUSB/issues/new/choose - -提问中请包含以下信息: - -- 使用的版本 -- 使用的板子,引脚,USB IP -- 是否配置 USB 中断,USB 时钟,USB 引脚,USB phy 配置,以及 USB 寄存器地址是否正确,截图 -- 是否能进 USB 中断 -- 芯片是否带有 cache功能,是否做了 no cache 处理,截图 -- USB 电路是否画正确,是否使用杜邦线连接,是否直连,如果正常,请说明正常原因 -- 如果能进中断,配置 **#define CONFIG_USB_DBG_LEVEL USB_DBG_LOG** 并提供 log,仅限商业 IP, 其余 IP 禁止开启 log,否则无法枚举 -- 是否流片并销售 - -其余问题提问模板 ------------------- - -具体说明现象,复现方式,使用我提供的 demo 再测试,以及提供完整 log - -CherryUSB 性能能到多少 ----------------------------------------------------------------- - -参考 :ref:`performace_show` - -ST IP 命名问题 ------------------- - -ST 命名为 USB_OTG_FS, USB_OTG_HS,并不是说明本身是高速或者全速,只是代表可以支持到高速,但是本身都是全速,需要外挂高速phy。因此,提问禁止说这两个词,请使用 USB0(PA11/PA12),USB1(PB14/PB15) 代替。其余国产厂家同理。 - -GD IP 问题 ------------------- - -GD IP 采用 DWC2,但是读取的硬件参数都是 0(我也不懂为什么不给人知道),因此需要用户自行知道硬件信息,从 1.5.0 开始由于需要读取硬件信息,因此无法直接使用。 - -其次 GD 复位以后无法使用 EPDIS 功能关闭端点,需要用户删除 reset 中断中的以下代码: - -.. code-block:: C - - USB_OTG_INEP(i)->DIEPCTL = (USB_OTG_DIEPCTL_EPDIS | USB_OTG_DIEPCTL_SNAK); - USB_OTG_OUTEP(i)->DOEPCTL = (USB_OTG_DOEPCTL_EPDIS | USB_OTG_DOEPCTL_SNAK); - -Ep addr XXX overflow ------------------------------- - -该 IP 硬件上没有这么多端点, 请更换 IP or 减少端点使用。并且默认 demo 不做双向功能,考虑到不是所有的 IP 都支持,因此默认是 81 02 这样的而不是 81 01, -如果支持,自行修改。某些 IP 双向端点可能会占用相同的硬件信息,不一定能同时使用,自行检查。 - -This dwc2 version does not support dma mode, so stop working ----------------------------------------------------------------- - -该 DWC2 版本不支持 dma 模式,禁止使用。 - -__has_include 报错 ------------------------------------------------------------------- -如果报错,需要编译器支持 c99 语法,如果是 keil,请用 ac6 编译器 - -CONFIG_USB_HS 何时使用 ----------------------------------------------------------------- - -当你的芯片硬件支持高速,并想初始化成高速模式时开启,相关 IP 会根据该宏配置内部或者外部 高速 PHY。 - -Failed to enable port ----------------------------------------------------------------- - -供电不足或者硬件 USB 电路问题 - -移植 usb host 出现 urb 返回 -12/-14 ----------------------------------------------------------------- - -检查 phy 配置,cache 配置(如果有),电源供电(建议自供电) - -USB_ERR_NAK 说明 ----------------------------------------------------------------- -USB_ERR_NAK 只存在于 DWC2 buffer dma 模式,DWC2 在 buffer dma模式下对于中断传输不支持硬件处理 NAK 中断,因此需要软件处理,导致 NAK 中断非常多,建议搭配定时器使用。 -DWC2 scatter/gather dma 模式下全部由硬件处理,但是不支持 split 传输。总结, **半斤 IP**。 - -USB host 连接 USB 网卡问题 ----------------------------------------------------------------- - -表现为能识别网卡并且分配到 IP 地址,但是无法 ping 通,这是因为网卡自身需要开启自动拨号,通常需要使用 AT 口设置。具体为 EC20/ML307 等模块。 - -PC 识别的 COM 口如何更改名称 ----------------------------------------------------------------- - -这是微软对 CDC ACM 的驱动问题,无法修改,如需修改,请联系微软并缴纳费用即可更改。 - -connect 和 disconnect event 不触发 ----------------------------------------------------------------- - -当前仅 hpm 芯片支持 connect 和 disconnect 事件,其他芯片请使用 USB 检测 vbus 电路。DWC2 IP 支持,但是由于需要占用引脚,并且大多是log 口, -然后不同使能的配置也不一样,因此不做支持。 \ No newline at end of file diff --git a/docs/source/quick_start/demo.rst b/docs/source/quick_start/demo.rst index ebb211a9..e51a2e3e 100644 --- a/docs/source/quick_start/demo.rst +++ b/docs/source/quick_start/demo.rst @@ -29,6 +29,21 @@ - esp32p4:一个 USB2.0 内置全速 PHY 芯片,一个 USB2.0 内置高速 PHY 芯片,支持主从机。 - 默认 demo 采用组件库安装的形式,在 https://components.espressif.com/ 中搜索 cherryusb 即可 +ESP-Registry 可以参考官方文档,推荐使用 vscode + esp-idf 的开发环境。 + +- ctrl + shift + p 选择 ESP-IDF 欢迎界面,然后选择 Component mananger + +.. figure:: img/esp1.png + +- 找到 cherryusb 并安装 + +.. figure:: img/esp2.png + +- 打开 menuconfig,并打开 cherryusb 的配置,根据实际情况选择主机或者从机模式 + +.. figure:: img/esp3.png +.. figure:: img/esp4.png + 基于飞腾派系列芯片(官方 SDK 支持) ----------------------------------- diff --git a/docs/source/quick_start/esp.rst b/docs/source/quick_start/esp.rst deleted file mode 100644 index 29639e05..00000000 --- a/docs/source/quick_start/esp.rst +++ /dev/null @@ -1,17 +0,0 @@ -基于 ESP-Registry 开发指南 -=========================== - -ESP-Registry 可以参考官方文档,推荐使用 vscode + esp-idf 的开发环境。 - -- ctrl + shift + p 选择 ESP-IDF 欢迎界面,然后选择 Component mananger - -.. figure:: img/esp1.png - -- 找到 cherryusb 并安装 - -.. figure:: img/esp2.png - -- 打开 menuconfig,并打开 cherryusb 的配置,根据实际情况选择主机或者从机模式 - -.. figure:: img/esp3.png -.. figure:: img/esp4.png \ No newline at end of file diff --git a/docs/source/quick_start/img/question1.png b/docs/source/quick_start/img/question1.png new file mode 100644 index 00000000..a852e6aa Binary files /dev/null and b/docs/source/quick_start/img/question1.png differ diff --git a/docs/source/quick_start/img/question2.png b/docs/source/quick_start/img/question2.png new file mode 100644 index 00000000..e00b3bfa Binary files /dev/null and b/docs/source/quick_start/img/question2.png differ diff --git a/docs/source/quick_start/opensource.rst b/docs/source/quick_start/opensource.rst new file mode 100644 index 00000000..7990538e --- /dev/null +++ b/docs/source/quick_start/opensource.rst @@ -0,0 +1,62 @@ +官方开源项目分享 +==================== + +除了基本的厂家 SDK 支持以外,我们还对一些火热的开源项目进行了支持,以便于开发者更好的使用这些项目。下面列举适配的 demo 工程链接,具体适配层参考 https://github.com/cherry-embedded/CherryUSB/tree/master/platform 。 + +DAPLINK +-------------- + +适配链接:https://github.com/cherry-embedded/CherryDAP + +Blackmagic +-------------- + +适配链接:https://github.com/zhangjiance/bmp-hpm-port + +RT-Thread +-------------- + +适配链接:https://github.com/RT-Thread/rt-thread + +NUTTX/VELA +-------------- + +适配链接:https://github.com/CherryUSB/cherryusb_nuttx + +Zephyr +-------------- + +适配链接:https://github.com/hpmicro/zephyr_sdk_glue + +Cangaroo +-------------- + +Cangaroo is an open source can bus analyzer software. We provide four-channel CANFD analyzer based on hpmicro hpm5361 + +适配上位机链接:https://github.com/RCSN/cangaroo_hpmicro_canfd_analyzer +适配下位机链接:https://github.com/RCSN/hpm_sdk_extra/tree/main/demos/cangaroo_hpmicro + +LVGL +-------------- + +适配链接:https://github.com/cherry-embedded/CherryUSB/tree/master/platform/lvgl + +QMK +-------------- + +QMK is an open-source keyboard firmware for Atmel AVR and Arm USB families. + +适配链接:待开放 + +Klipper +-------------- + +Klipper is a 3d-printer firmware. + +适配链接:待开放 + + +MAKCU/KMBOX +-------------- + +懂的都懂,不开放 \ No newline at end of file diff --git a/docs/source/quick_start/q&a.rst b/docs/source/quick_start/q&a.rst new file mode 100644 index 00000000..dfdbac85 --- /dev/null +++ b/docs/source/quick_start/q&a.rst @@ -0,0 +1,124 @@ +Q & A +============================== + +移植提问模板 +---------------- + +请在下列途径提交问题: +- RT-Thread 官方论坛: https://club.rt-thread.org/ask/tag/5f5f851966917b14.html +- Github issue: https://github.com/cherry-embedded/CherryUSB/issues/new/choose + +提问中请包含以下信息: + +- 使用的版本 +- 使用的板子,引脚,USB IP +- 是否配置 USB 中断,USB 时钟,USB 引脚,USB phy 配置,以及 USB 寄存器地址是否正确,截图 +- 是否能进 USB 中断 +- 芯片是否带有 cache功能,是否做了 no cache 处理,截图 +- USB 电路是否画正确,是否使用杜邦线连接,是否直连,如果正常,请说明正常原因 +- 如果能进中断,配置 **#define CONFIG_USB_DBG_LEVEL USB_DBG_LOG** 并提供 log,仅限商业 IP, 其余 IP 禁止开启 log,否则无法枚举 +- 是否流片并销售 + +其余问题提问模板 +------------------ + +具体说明现象,复现方式,使用我提供的 demo 再测试,以及提供完整 log + +CherryUSB 性能能到多少 +---------------------------------------------------------------- + +参考 :ref:`performace_show` + +ST IP 命名问题 +------------------ + +ST 命名为 USB_OTG_FS, USB_OTG_HS,并不是说明本身是高速或者全速,只是代表可以支持到高速,但是本身都是全速,需要外挂高速phy。因此,提问禁止说这两个词,请使用 USB0(PA11/PA12),USB1(PB14/PB15) 代替。其余国产厂家同理。 + +GD IP 问题 +------------------ + +GD IP 采用 DWC2,但是读取的硬件参数都是 0(我也不懂为什么不给人知道),因此需要用户自行知道硬件信息,从 1.5.0 开始由于需要读取硬件信息,因此无法直接使用。 + +其次 GD 复位以后无法使用 EPDIS 功能关闭端点,需要用户删除 reset 中断中的以下代码: + +.. code-block:: C + + USB_OTG_INEP(i)->DIEPCTL = (USB_OTG_DIEPCTL_EPDIS | USB_OTG_DIEPCTL_SNAK); + USB_OTG_OUTEP(i)->DOEPCTL = (USB_OTG_DOEPCTL_EPDIS | USB_OTG_DOEPCTL_SNAK); + +除此之外可能存在其他未知 BUG,请自行测试。 + +开启 USB_LOG_DBG 后无法枚举 +---------------------------------------------------------------- + +有且仅有商业性 IP 开启后可以枚举,其余 IP 禁止开启,否则无法枚举。懂得都懂。 + +USB3 CV测试用哪个版本 +------------------------------ + +1.4.3 版本及以上 + +Ep addr XXX fifo overflow +------------------------------ + +.. figure:: img/question1.png + +该错误表示该端点默认设置的 fifo 空间不够用,需要增大 fifo 空间,通常见于 DWC2/MUSB IP。FIFO 设置参考相关的 glue 文件。 + +Ep addr XXX overflow +------------------------------ + +.. figure:: img/question2.png + +该错误表示该 IP 硬件上没有这么多端点, 请更换 IP or 减少端点使用。 +当然也可以修改为双向端点,考虑到不是所有的 IP 都支持双向端点,因此默认 demo 不做双向功能,举例默认是 81 02 这样的而不是 81 01,如果支持,自行修改。某些 IP 双向端点可能会占用相同的硬件信息,不一定能同时使用,自行检查。 + +This dwc2 version does not support dma mode, so stop working +---------------------------------------------------------------- + +该 DWC2 版本不支持 dma 模式,禁止使用。不使用 DMA 模式会频繁触发 NAK 中断(大概几十us一次),CPU 占用率过高。 + +OTG 有哪些芯片支持 +------------------------------ + +当前主线仅 HPM 芯片支持 OTG 功能,通过 ID 引脚自动切换主从模式,其他芯片请使用手动切换模式 OR 自行实现添加 ID 识别的驱动。 + +PC 识别的 COM 口如何更改名称 +---------------------------------------------------------------- + +这是微软对 CDC ACM 的驱动问题,无法修改,如需修改,请联系微软并缴纳费用+编写驱动后即可更改。 + +connect 和 disconnect event 不触发 +---------------------------------------------------------------- + +当前仅 hpm 芯片支持 connect 和 disconnect 事件,其他芯片请使用 USB 检测 vbus 电路。DWC2 IP 支持,但是由于需要占用引脚,并且大多是log 口,然后不同使能的配置也不一样,因此不做支持。 + +__has_include 报错 +------------------------------------------------------------------ +如果报错,需要编译器支持 c99 语法,如果是 keil,请用 ac6 编译器 + +CONFIG_USB_HS 何时使用 +---------------------------------------------------------------- + +当你的芯片硬件支持高速,并想初始化成高速模式时开启,相关 IP 会根据该宏配置内部或者外部 高速 PHY。 + +Failed to enable port +---------------------------------------------------------------- + +供电不足或者硬件 USB 电路问题 + +移植 usb host 出现 urb 返回 -12/-14 +---------------------------------------------------------------- + +检查 phy 配置,cache 配置(如果有),电源供电(建议自供电) + +USB_ERR_NAK 说明 +---------------------------------------------------------------- + +USB_ERR_NAK 只存在于 DWC2 buffer dma 模式,DWC2 在 buffer dma模式下对于中断传输不支持硬件处理 NAK 中断,因此需要软件处理,导致 NAK 中断非常多,建议搭配定时器使用。 +DWC2 scatter/gather dma 模式下全部由硬件处理,但是不支持 split 传输。总结, **半斤 IP**。 + +USB host 连接 USB 网卡问题 +---------------------------------------------------------------- + +表现为能识别网卡并且分配到 IP 地址,但是无法 ping 通,这是因为网卡自身需要开启自动拨号,通常需要使用 AT 口设置。具体为 EC20/ML307 等模块。 diff --git a/docs/source/quick_start/share.rst b/docs/source/quick_start/share.rst new file mode 100644 index 00000000..a57a8e1e --- /dev/null +++ b/docs/source/quick_start/share.rst @@ -0,0 +1,27 @@ +开发者经验/开源项目分享 +======================== + +- `RT-Thread-CherryUSB - RT-Thread `_ + +- `[HPM-DIY]hpm6750 USB开源协议栈性能对比-cherryusb or tinyusb? `_ + +- `RT-Thread-CherryUSB移植笔记(一):APM32F407VGT6 DWC2移植 Port.A Full-Speed + Por.B High-SpeedRT-Thread问答社区 - RT-Thread `_ + +- `华大HC32F460XXX移植cherryusb协议栈,实现USB CDC ACM_cherryusb移植教程-CSDN博客 `_ + +- `rt-thread使用cherryusb实现虚拟串口-CSDN博客 `_ + +- `F1C100S+rtt+CherryUSB的USB HOST成功读到U盘 / 全志 SOC / WhyCan Forum(哇酷开发者社区) `_ + +- `模仿stm32标准库风格写的库文件(f1c100s/f1c200s),且已移植了rt-thread、lvgl、fatfs、cherryusb / 全志 SOC / WhyCan Forum(哇酷开发者社区) `_ + +- `printalyzer-timer: F-Stop enlarging timer and print exposure meter `_ + +- `MiSTeryNano: Atari STE MiSTery core for the Tang Nano 20k FPGA `_ + +- `Cherryuf2 `_ + +- `PicoPiFi: Driverless RNDIS USB WIFI Dongle `_ + +- `phobia: Phobia Motor Controller `_ + diff --git a/docs/source/share.rst b/docs/source/share.rst deleted file mode 100644 index a57a8e1e..00000000 --- a/docs/source/share.rst +++ /dev/null @@ -1,27 +0,0 @@ -开发者经验/开源项目分享 -======================== - -- `RT-Thread-CherryUSB - RT-Thread `_ - -- `[HPM-DIY]hpm6750 USB开源协议栈性能对比-cherryusb or tinyusb? `_ - -- `RT-Thread-CherryUSB移植笔记(一):APM32F407VGT6 DWC2移植 Port.A Full-Speed + Por.B High-SpeedRT-Thread问答社区 - RT-Thread `_ - -- `华大HC32F460XXX移植cherryusb协议栈,实现USB CDC ACM_cherryusb移植教程-CSDN博客 `_ - -- `rt-thread使用cherryusb实现虚拟串口-CSDN博客 `_ - -- `F1C100S+rtt+CherryUSB的USB HOST成功读到U盘 / 全志 SOC / WhyCan Forum(哇酷开发者社区) `_ - -- `模仿stm32标准库风格写的库文件(f1c100s/f1c200s),且已移植了rt-thread、lvgl、fatfs、cherryusb / 全志 SOC / WhyCan Forum(哇酷开发者社区) `_ - -- `printalyzer-timer: F-Stop enlarging timer and print exposure meter `_ - -- `MiSTeryNano: Atari STE MiSTery core for the Tang Nano 20k FPGA `_ - -- `Cherryuf2 `_ - -- `PicoPiFi: Driverless RNDIS USB WIFI Dongle `_ - -- `phobia: Phobia Motor Controller `_ - -- cgit v1.3.1