feat(driver_twai): add prioritized TX queue support

docs/en/api-reference/peripherals/twai.rst

@@ -134,6 +134,7 @@ The :cpp:type:`twai_frame_t` message structure also includes other configuration
 - :cpp:member:`twai_frame_t::header::fdf`: Marks the frame as an FD format frame, supporting up to 64 bytes of data.
 - :cpp:member:`twai_frame_t::header::brs`: Enables use of a separate data-phase baud rate when transmitting.
 - :cpp:member:`twai_frame_t::header::esi`: For received frames, indicates the error state of the transmitting node.
+- :cpp:member:`twai_frame_t::tx_queue_priority`: Local transmit queue priority. See `Transmit Queue Priority`_ for details.
 
 Receiving Messages
 ------------------
@@ -214,6 +215,13 @@ The TWAI driver supports transmitting messages from an Interrupt Service Routine
 .. note::
     When calling :cpp:func:`twai_node_transmit` from an ISR, the ``timeout`` parameter is ignored, and the function will not block. If the transmit queue is full, the function will return immediately with an error. It is the application's responsibility to handle cases where the queue is full. Similarly, the ``twai_frame_t`` structure and the memory pointed to by ``buffer`` must remain valid until the transmission is complete. You can get the completed frame by the :cpp:member:`twai_tx_done_event_data_t::done_tx_frame` pointer.
 
+Transmit Queue Priority
+-----------------------
+
+The TWAI driver supports local transmit queue prioritization through :cpp:member:`twai_frame_t::tx_queue_priority`. When multiple frames are pending in the driver's transmit queue, frames with a higher ``tx_queue_priority`` value are dequeued and started transmitting first. Frames with the same priority keep their enqueue order.
+
+This priority only affects the driver's local transmit queue. It is not transmitted on the TWAI bus and does not replace TWAI bus arbitration. If the controller has multiple hardware transmit buffers (for example, 4 hardware transmit buffers for esp32c5), the already cached frames will not be preempted by newly queued higher-priority frames. Once a frame reaches the bus, arbitration is still determined by the frame ID, where lower IDs have higher bus priority.
+
 Bit Timing Customization
 ------------------------
 

docs/zh_CN/api-reference/peripherals/twai.rst

@@ -134,6 +134,7 @@ TWAI 报文有多种类型，由报头指定。一个典型的数据帧报文主
 - :cpp:member:`twai_frame_t::header::fdf` 报文为 FD 格式，支持最大数据长度 64 字节。
 - :cpp:member:`twai_frame_t::header::brs` 发送报文时在数据段使用独立的波特率。
 - :cpp:member:`twai_frame_t::header::esi` 对于收到的报文，指示发送节点的错误状态。
+- :cpp:member:`twai_frame_t::tx_queue_priority` 本地发送队列优先级，详情请参阅 `发送队列优先级`_。
 
 接收报文
 --------
@@ -214,6 +215,13 @@ TWAI 驱动支持在中断服务程序 (ISR) 中发送报文。这对于需要
 .. note::
     在 ISR 中调用 :cpp:func:`twai_node_transmit` 时，``timeout`` 参数将被忽略，函数不会阻塞。如果发送队列已满，函数将立即返回错误。应用程序需要自行处理队列已满的情况。同样，``twai_frame_t`` 及其 ``buffer`` 指向的内存必须在 **该传输** 完成之前保持有效。通过 :cpp:member:`twai_tx_done_event_data_t::done_tx_frame` 指针可得知该次完成的报文。
 
+发送队列优先级
+--------------
+
+TWAI 驱动支持通过 :cpp:member:`twai_frame_t::tx_queue_priority` 设置本地发送队列优先级。当驱动发送队列中有多个待发送报文时，``tx_queue_priority`` 值更高的报文会优先出队开始发送。优先级相同的报文保持入队顺序发送。
+
+该优先级只影响驱动的本地发送队列，不会被发送到 TWAI 总线上，也不会替代 TWAI 总线仲裁。若控制器有多个硬件发送缓存（例如 esp32c5 的 4 个硬件发送缓存），已经缓存的报文也不会被新入队的高优先级报文抢占。报文到达总线后，仲裁仍由帧 ID 决定，ID 越小，总线优先级越高。控制器已经开始发送的报文不会被新入队的高优先级报文抢占。
+
 位时序自定义
 -------------