1 /*
2 * SPDX-FileCopyrightText: 2010-2022 Espressif Systems (Shanghai) CO LTD
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #pragma once
8 #include <stddef.h>
9 #include <stdbool.h>
10 #include "sdkconfig.h"
11 #include "esp_rom_lldesc.h"
12
13 //the size field has 12 bits, but 0 not for 4096.
14 //to avoid possible problem when the size is not word-aligned, we only use 4096-4 per desc.
15 /** Maximum size of data in the buffer that a DMA descriptor can hold. */
16 #define LLDESC_MAX_NUM_PER_DESC (4096-4)
17
18 // Some DMA operations might impose certain alignment restrictions on the length
19 #define LLDESC_MAX_NUM_PER_DESC_16B_ALIGNED (4096 - 16)
20 #define LLDESC_MAX_NUM_PER_DESC_32B_ALIGNED (4096 - 32)
21
22 /**
23 * Generate a linked list pointing to a (huge) buffer in an descriptor array.
24 *
25 * The caller should ensure there is enough size to hold the array, by calling
26 * ``lldesc_get_required_num_constrained`` with the same max_desc_size argument.
27 *
28 * @param[out] out_desc_array Output of a descriptor array, the head should be fed to the DMA.
29 * @param buffer Buffer for the descriptors to point to.
30 * @param size Size (or length for TX) of the buffer
31 * @param max_desc_size Maximum length of each descriptor
32 * @param isrx The RX DMA may require the buffer to be word-aligned, set to true for a RX link, otherwise false.
33 */
34 void lldesc_setup_link_constrained(lldesc_t *out_desc_array, const void *buffer, int size, int max_desc_size, bool isrx);
35
36 /**
37 * Generate a linked list pointing to a (huge) buffer in an descriptor array.
38 *
39 * The caller should ensure there is enough size to hold the array, by calling
40 * ``lldesc_get_required_num``.
41 *
42 * @param[out] out_desc_array Output of a descriptor array, the head should be fed to the DMA.
43 * @param buffer Buffer for the descriptors to point to.
44 * @param size Size (or length for TX) of the buffer
45 * @param isrx The RX DMA may require the buffer to be word-aligned, set to true for a RX link, otherwise false.
46 */
47 #define lldesc_setup_link(out_desc_array, buffer, size, isrx) lldesc_setup_link_constrained(out_desc_array, buffer, size, LLDESC_MAX_NUM_PER_DESC, isrx)
48
49 /**
50 * @brief Get the received length of a linked list, until end of the link or eof.
51 *
52 * @param head The head of the linked list.
53 * @param[out] out_next Output of the next descriptor of the EOF descriptor. Return NULL if there's no
54 * EOF. Can be set to NULL if next descriptor is not needed.
55 * @return The accumulation of the `len` field of all descriptors until EOF or the end of the link.
56 */
57 int lldesc_get_received_len(lldesc_t* head, lldesc_t** out_next);
58
59 /**
60 * Get the number of descriptors required for a given buffer size.
61 *
62 * @param data_size Size to check descriptor num.
63 *
64 * @return Numbers required.
65 */
lldesc_get_required_num_constrained(int data_size,int max_desc_size)66 static inline int lldesc_get_required_num_constrained(int data_size, int max_desc_size)
67 {
68 return (data_size + max_desc_size - 1) / max_desc_size;
69 }
70
71 /**
72 * Get the number of descriptors required for a given buffer size.
73 *
74 * @param data_size Size to check descriptor num.
75 * @param max_desc_size Maximum length of each descriptor
76 * @return Numbers required.
77 */
78 #define lldesc_get_required_num(data_size) lldesc_get_required_num_constrained(data_size, LLDESC_MAX_NUM_PER_DESC)
79
