Skip to content

Commit 1c87aeb

Browse files
sakumisusakumisu
committed
docs: update rst
1 parent d874bed commit 1c87aeb

File tree

4 files changed

+206
-1
lines changed

4 files changed

+206
-1
lines changed

‎docs/source/demo/usbd_cdc_acm.rst

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,101 @@
11
usbd_cdc_acm
22
===============
3+
4+
本 demo 主要用于演示 cdc acm 功能，包含收发测试，DTR 控制，ZLP 测试，性能测试。
5+
6+
- 开辟读写 buffer，用于收发数据，并且buffer需要用 nocache 修饰，这里我们读写都是用 2048字节，是为了后面的 ZLP 测试和性能测试使用。
7+
8+
.. code-block:: C
9+
10+
USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t read_buffer[2048]; /* 2048 is only for test speed , please use CDC_MAX_MPS for common*/
11+
USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t write_buffer[2048];
12+
13+
14+
- 协议栈回调中，我们需要在枚举完成后启动第一次传输，并清除相关 flag，可以在 reset 事件中清除，也可以在 configured 事件中清除。
15+
16+
.. code-block:: C
17+
18+
static void usbd_event_handler(uint8_t busid, uint8_t event)
19+
{
20+
switch (event) {
21+
case USBD_EVENT_RESET:
22+
break;
23+
case USBD_EVENT_CONNECTED:
24+
break;
25+
case USBD_EVENT_DISCONNECTED:
26+
break;
27+
case USBD_EVENT_RESUME:
28+
break;
29+
case USBD_EVENT_SUSPEND:
30+
break;
31+
case USBD_EVENT_CONFIGURED:
32+
ep_tx_busy_flag = false;
33+
/* setup first out ep read transfer */
34+
usbd_ep_start_read(busid, CDC_OUT_EP, read_buffer, 2048);
35+
break;
36+
case USBD_EVENT_SET_REMOTE_WAKEUP:
37+
break;
38+
case USBD_EVENT_CLR_REMOTE_WAKEUP:
39+
break;
40+
41+
default:
42+
break;
43+
}
44+
}
45+
46+
- 在接收完成中断中继续发起接收；在发送完成中断中判断是否需要发送 ZLP。
47+
48+
.. code-block:: C
49+
50+
void usbd_cdc_acm_bulk_out(uint8_t busid, uint8_t ep, uint32_t nbytes)
51+
{
52+
USB_LOG_RAW("actual out len:%d\r\n", nbytes);
53+
// for (int i = 0; i < 100; i++) {
54+
// printf("%02x ", read_buffer[i]);
55+
// }
56+
// printf("\r\n");
57+
/* setup next out ep read transfer */
58+
usbd_ep_start_read(busid, CDC_OUT_EP, read_buffer, 2048);
59+
}
60+
61+
void usbd_cdc_acm_bulk_in(uint8_t busid, uint8_t ep, uint32_t nbytes)
62+
{
63+
USB_LOG_RAW("actual in len:%d\r\n", nbytes);
64+
65+
if ((nbytes % usbd_get_ep_mps(busid, ep)) == 0 && nbytes) {
66+
/* send zlp */
67+
usbd_ep_start_write(busid, CDC_IN_EP, NULL, 0);
68+
} else {
69+
ep_tx_busy_flag = false;
70+
}
71+
}
72+
73+
- 以下是为了测试 DTR 功能并控制 USB 发送，DTR 和 RTS 只用于搭配 UART 使用，如果是纯 USB，没什么用，这里仅做测试。DTR 开关使用任意串口上位机并勾选 DTR。
74+
75+
.. code-block:: C
76+
77+
void usbd_cdc_acm_set_dtr(uint8_t busid, uint8_t intf, bool dtr)
78+
{
79+
if (dtr) {
80+
dtr_enable = 1;
81+
} else {
82+
dtr_enable = 0;
83+
}
84+
}
85+
86+
- 在主函数中一直调用发送即可
87+
88+
.. code-block:: C
89+
90+
void cdc_acm_data_send_with_dtr_test(uint8_t busid)
91+
{
92+
if (dtr_enable) {
93+
ep_tx_busy_flag = true;
94+
usbd_ep_start_write(busid, CDC_IN_EP, write_buffer, 2048);
95+
while (ep_tx_busy_flag) {
96+
}
97+
}
98+
}
99+
100+
- 上述我们需要注意，长度设置为 2048 是为了测试 ZLP 功能，通常实际使用时，接收长度应该使用 CDC_MAX_MPS 。具体原因参考 :ref:`usb_ext`
101+
- 如果需要做性能测试，使用 tools/test_srcipts/test_cdc_speed.py 进行测试,并在测试之前删除 `usbd_cdc_acm_bulk_out` 和 `usbd_cdc_acm_bulk_in` 中的打印，否则会影响测试结果。

‎docs/source/demo/usbd_video.rst

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,83 @@
11
usbd_video
22
===============
3+
4+
本节主要演示 USB UAC 功能，支持 YUYV, MJPEG, H264 格式。为了方便演示，都采用的静态图。
5+
6+
demo 包含 **video_static_yuyv_template**, **video_static_mjpeg_template**, **video_static_h264_template**, 仅描述符和图片数据不同。
7+
8+
- 在高速模式下，默认最大是1024字节，但是如果芯片支持 additional transcations，可以配置为最高 2048字节或者3072字节，这样可以提高传输效率。
9+
10+
.. code-block:: C
11+
12+
#ifdef CONFIG_USB_HS
13+
#define MAX_PAYLOAD_SIZE 1024 // for high speed with one transcations every one micro frame
14+
#define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 1)) | (0x00 << 11))
15+
16+
// #define MAX_PAYLOAD_SIZE 2048 // for high speed with two transcations every one micro frame
17+
// #define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 2)) | (0x01 << 11))
18+
19+
// #define MAX_PAYLOAD_SIZE 3072 // for high speed with three transcations every one micro frame
20+
// #define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 3)) | (0x02 << 11))
21+
22+
#else
23+
#define MAX_PAYLOAD_SIZE 1020
24+
#define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 1)) | (0x00 << 11))
25+
#endif
26+
27+
- 通常只需要修改 WIDTH 和 HEIGHT
28+
29+
.. code-block:: C
30+
31+
#define WIDTH (unsigned int)(640)
32+
#define HEIGHT (unsigned int)(480)
33+
34+
#define CAM_FPS (30)
35+
#define INTERVAL (unsigned long)(10000000 / CAM_FPS)
36+
#define MIN_BIT_RATE (unsigned long)(WIDTH * HEIGHT * 16 * CAM_FPS) //16 bit
37+
#define MAX_BIT_RATE (unsigned long)(WIDTH * HEIGHT * 16 * CAM_FPS)
38+
#define MAX_FRAME_SIZE (unsigned long)(WIDTH * HEIGHT * 2)
39+
40+
- USB 端点配置，默认 interval 为 1，也就是全速模式下 1ms，高速模式下 125us。同步类型使用异步模式。
41+
42+
.. code-block:: C
43+
44+
/* 1.2.2.2 Standard VideoStream Isochronous Video Data Endpoint Descriptor */
45+
USB_ENDPOINT_DESCRIPTOR_INIT(VIDEO_IN_EP, 0x05, VIDEO_PACKET_SIZE, 0x01),
46+
47+
48+
- 使用 `usbd_video_stream_start_write` 传输数据
49+
50+
1，传输采用双缓冲的形式， **MAX_PACKETS_IN_ONE_TRANSFER** 表示一次传输可以携带多少个 **MAX_PAYLOAD_SIZE**，通常 IP 只能为 1。
51+
52+
2，在中断完成中，调用 `usbd_video_stream_split_transfer` 继续下一次传输，直到返回为 true 表示传输完成。这边的分裂传输只是表示将图片数据拆成 **MAX_PACKETS_IN_ONE_TRANSFER * MAX_PAYLOAD_SIZE** 份传输。
53+
54+
3，通常 IP 不支持一次传输非常大的数据，比如传输 1MB，因此需要做分裂传输，但是会增加中断次数。并且一次传输非常大数据也是需要足够的 RAM。
55+
56+
.. code-block:: C
57+
58+
void usbd_video_iso_callback(uint8_t busid, uint8_t ep, uint32_t nbytes)
59+
{
60+
if (usbd_video_stream_split_transfer(busid, ep)) {
61+
/* one frame has done */
62+
iso_tx_busy = false;
63+
}
64+
}
65+
66+
USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t packet_buffer[2][MAX_PACKETS_IN_ONE_TRANSFER * MAX_PAYLOAD_SIZE];
67+
68+
void video_test(uint8_t busid)
69+
{
70+
memset(packet_buffer, 0, sizeof(packet_buffer));
71+
72+
while (1) {
73+
if (tx_flag) {
74+
iso_tx_busy = true;
75+
usbd_video_stream_start_write(busid, VIDEO_IN_EP, &packet_buffer[0][0], &packet_buffer[1][0], MAX_PACKETS_IN_ONE_TRANSFER * MAX_PAYLOAD_SIZE, (uint8_t *)cherryusb_mjpeg, sizeof(cherryusb_mjpeg));
76+
while (iso_tx_busy) {
77+
if (tx_flag == 0) {
78+
break;
79+
}
80+
}
81+
}
82+
}
83+
}

‎docs/source/quick_start/demo.rst

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,32 @@
3333

3434
仓库参考：https://gitee.com/phytium_embedded/phytium-free-rtos-sdk
3535

36-
- 飞腾派支持两个 USB3.0 主机， 两个 USB2.0 主从机
36+
- 飞腾派支持两个 USB3.0 主机（采用 XHCI）， 两个 USB2.0 主从机
3737
- USB 的相关应用位于 `example/peripheral/usb` ，根据官方环境搭建完成后，即可编译使用。
3838

39+
基于 Essemi 系列芯片
40+
---------------------------
41+
42+
仓库参考：https://github.com/CherryUSB/cherryusb_es32
43+
44+
- 支持全速和高速主从机
45+
46+
基于 NXP MCX系列芯片
47+
---------------------------
48+
49+
仓库参考：https://github.com/CherryUSB/cherryusb_mcx 或者 https://github.com/RT-Thread/rt-thread/tree/master/bsp/nxp/mcx
50+
51+
- 支持全速 IP 和高速 IP， 高速 IP 支持主机和从机
52+
53+
- 支持全速和高速主从机
54+
55+
基于 Artinchip 系列芯片
56+
---------------------------
57+
58+
仓库参考：https://gitee.com/artinchip/luban-lite
59+
60+
- 支持全速和高速主从机，主机采用 EHCI + OHCI。
61+
3962
基于 ST 系列芯片
4063
---------------------------
4164

‎docs/source/usb/usb_ext.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _usb_ext:
2+
13
USB 知识点拓展
24
===========================
35

0 commit comments

Comments
 (0)