1 /** 2 * @file 3 * @brief DMA Devicetree macro public API header file. 4 */ 5 6 /* 7 * Copyright (c) 2020, Linaro Ltd. 8 * 9 * SPDX-License-Identifier: Apache-2.0 10 */ 11 12 #ifndef ZEPHYR_INCLUDE_DEVICETREE_DMAS_H_ 13 #define ZEPHYR_INCLUDE_DEVICETREE_DMAS_H_ 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** 20 * @defgroup devicetree-dmas Devicetree DMA API 21 * @ingroup devicetree 22 * @{ 23 */ 24 25 /** 26 * @brief Get a label property from the node referenced by a dmas 27 * property at an index 28 * 29 * It's an error if the DMA controller node referenced by the phandle 30 * in node_id's dmas property at index "idx" has no label property. 31 * 32 * Example devicetree fragment: 33 * 34 * dma1: dma@... { 35 * label = "DMA_1"; 36 * }; 37 * 38 * dma2: dma@... { 39 * label = "DMA_2"; 40 * }; 41 * 42 * n: node { 43 * dmas = <&dma1 1 2 0x400 0x3>, 44 * <&dma2 6 3 0x404 0x5>; 45 * }; 46 * 47 * Example usage: 48 * 49 * DT_DMAS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "DMA_2" 50 * 51 * @param node_id node identifier for a node with a dmas property 52 * @param idx logical index into dmas property 53 * @return the label property of the node referenced at index "idx" 54 */ 55 #define DT_DMAS_LABEL_BY_IDX(node_id, idx) \ 56 __DEPRECATED_MACRO \ 57 DT_PROP_BY_PHANDLE_IDX(node_id, dmas, idx, label) 58 59 /** 60 * @brief Get a label property from a DT_DRV_COMPAT instance's dmas 61 * property at an index 62 * @param inst DT_DRV_COMPAT instance number 63 * @param idx logical index into dmas property 64 * @return the label property of the node referenced at index "idx" 65 * @see DT_DMAS_LABEL_BY_IDX() 66 */ 67 #define DT_INST_DMAS_LABEL_BY_IDX(inst, idx) \ 68 __DEPRECATED_MACRO \ 69 DT_DMAS_LABEL_BY_IDX(DT_DRV_INST(inst), idx) 70 71 /** 72 * @brief Get a label property from a dmas property by name 73 * 74 * It's an error if the DMA controller node referenced by the phandle 75 * in node_id's dmas property at the element named "name" has no label 76 * property. 77 * 78 * Example devicetree fragment: 79 * 80 * dma1: dma@... { 81 * label = "DMA_1"; 82 * }; 83 * 84 * dma2: dma@... { 85 * label = "DMA_2"; 86 * }; 87 * 88 * n: node { 89 * dmas = <&dma1 1 2 0x400 0x3>, 90 * <&dma2 6 3 0x404 0x5>; 91 * dma-names = "tx", "rx"; 92 * }; 93 * 94 * Example usage: 95 * 96 * DT_DMAS_LABEL_BY_NAME(DT_NODELABEL(n), rx) // "DMA_2" 97 * 98 * @param node_id node identifier for a node with a dmas property 99 * @param name lowercase-and-underscores name of a dmas element 100 * as defined by the node's dma-names property 101 * @return the label property of the node referenced at the named element 102 */ 103 #define DT_DMAS_LABEL_BY_NAME(node_id, name) \ 104 __DEPRECATED_MACRO \ 105 DT_PROP(DT_PHANDLE_BY_NAME(node_id, dmas, name), label) 106 107 /** 108 * @brief Get the node identifier for the DMA controller from a 109 * dmas property at an index 110 * 111 * Example devicetree fragment: 112 * 113 * dma1: dma@... { ... }; 114 * 115 * dma2: dma@... { ... }; 116 * 117 * n: node { 118 * dmas = <&dma1 1 2 0x400 0x3>, 119 * <&dma2 6 3 0x404 0x5>; 120 * }; 121 * 122 * Example usage: 123 * 124 * DT_DMAS_CTLR_BY_IDX(DT_NODELABEL(n), 0) // DT_NODELABEL(dma1) 125 * DT_DMAS_CTLR_BY_IDX(DT_NODELABEL(n), 1) // DT_NODELABEL(dma2) 126 * 127 * @param node_id node identifier for a node with a dmas property 128 * @param idx logical index into dmas property 129 * @return the node identifier for the DMA controller referenced at 130 * index "idx" 131 * @see DT_PROP_BY_PHANDLE_IDX() 132 */ 133 #define DT_DMAS_CTLR_BY_IDX(node_id, idx) DT_PHANDLE_BY_IDX(node_id, dmas, idx) 134 135 /** 136 * @brief Get the node identifier for the DMA controller from a 137 * dmas property by name 138 * 139 * Example devicetree fragment: 140 * 141 * dma1: dma@... { ... }; 142 * 143 * dma2: dma@... { ... }; 144 * 145 * n: node { 146 * dmas = <&dma1 1 2 0x400 0x3>, 147 * <&dma2 6 3 0x404 0x5>; 148 * dma-names = "tx", "rx"; 149 * }; 150 * 151 * Example usage: 152 * 153 * DT_DMAS_CTLR_BY_NAME(DT_NODELABEL(n), tx) // DT_NODELABEL(dma1) 154 * DT_DMAS_CTLR_BY_NAME(DT_NODELABEL(n), rx) // DT_NODELABEL(dma2) 155 * 156 * @param node_id node identifier for a node with a dmas property 157 * @param name lowercase-and-underscores name of a dmas element 158 * as defined by the node's dma-names property 159 * @return the node identifier for the DMA controller in the named element 160 * @see DT_PHANDLE_BY_NAME() 161 */ 162 #define DT_DMAS_CTLR_BY_NAME(node_id, name) \ 163 DT_PHANDLE_BY_NAME(node_id, dmas, name) 164 165 /** 166 * @brief Equivalent to DT_DMAS_CTLR_BY_IDX(node_id, 0) 167 * @param node_id node identifier for a node with a dmas property 168 * @return the node identifier for the DMA controller at index 0 169 * in the node's "dmas" property 170 * @see DT_DMAS_CTLR_BY_IDX() 171 */ 172 #define DT_DMAS_CTLR(node_id) DT_DMAS_CTLR_BY_IDX(node_id, 0) 173 174 /** 175 * @brief Get a label property from a DT_DRV_COMPAT instance's dmas 176 * property by name 177 * @param inst DT_DRV_COMPAT instance number 178 * @param name lowercase-and-underscores name of a dmas element 179 * as defined by the node's dma-names property 180 * @return the label property of the node referenced at the named element 181 * @see DT_DMAS_LABEL_BY_NAME() 182 */ 183 #define DT_INST_DMAS_LABEL_BY_NAME(inst, name) \ 184 __DEPRECATED_MACRO \ 185 DT_DMAS_LABEL_BY_NAME(DT_DRV_INST(inst), name) 186 187 /** 188 * @brief Get the node identifier for the DMA controller from a 189 * DT_DRV_COMPAT instance's dmas property at an index 190 * 191 * @param inst DT_DRV_COMPAT instance number 192 * @param idx logical index into dmas property 193 * @return the node identifier for the DMA controller referenced at 194 * index "idx" 195 * @see DT_DMAS_CTLR_BY_IDX() 196 */ 197 #define DT_INST_DMAS_CTLR_BY_IDX(inst, idx) \ 198 DT_DMAS_CTLR_BY_IDX(DT_DRV_INST(inst), idx) 199 200 /** 201 * @brief Get the node identifier for the DMA controller from a 202 * DT_DRV_COMPAT instance's dmas property by name 203 * @param inst DT_DRV_COMPAT instance number 204 * @param name lowercase-and-underscores name of a dmas element 205 * as defined by the node's dma-names property 206 * @return the node identifier for the DMA controller in the named element 207 * @see DT_DMAS_CTLR_BY_NAME() 208 */ 209 #define DT_INST_DMAS_CTLR_BY_NAME(inst, name) \ 210 DT_DMAS_CTLR_BY_NAME(DT_DRV_INST(inst), name) 211 212 /** 213 * @brief Equivalent to DT_INST_DMAS_CTLR_BY_IDX(inst, 0) 214 * @param inst DT_DRV_COMPAT instance number 215 * @return the node identifier for the DMA controller at index 0 216 * in the instance's "dmas" property 217 * @see DT_DMAS_CTLR_BY_IDX() 218 */ 219 #define DT_INST_DMAS_CTLR(inst) DT_INST_DMAS_CTLR_BY_IDX(inst, 0) 220 221 /** 222 * @brief Get a DMA specifier's cell value at an index 223 * 224 * Example devicetree fragment: 225 * 226 * dma1: dma@... { 227 * compatible = "vnd,dma"; 228 * #dma-cells = <2>; 229 * }; 230 * 231 * dma2: dma@... { 232 * compatible = "vnd,dma"; 233 * #dma-cells = <2>; 234 * }; 235 * 236 * n: node { 237 * dmas = <&dma1 1 0x400>, 238 * <&dma2 6 0x404>; 239 * }; 240 * 241 * Bindings fragment for the vnd,dma compatible: 242 * 243 * dma-cells: 244 * - channel 245 * - config 246 * 247 * Example usage: 248 * 249 * DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 0, channel) // 1 250 * DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 1, channel) // 6 251 * DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 0, config) // 0x400 252 * DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 1, config) // 0x404 253 * 254 * @param node_id node identifier for a node with a dmas property 255 * @param idx logical index into dmas property 256 * @param cell lowercase-and-underscores cell name 257 * @return the cell value at index "idx" 258 * @see DT_PHA_BY_IDX() 259 */ 260 #define DT_DMAS_CELL_BY_IDX(node_id, idx, cell) \ 261 DT_PHA_BY_IDX(node_id, dmas, idx, cell) 262 263 /** 264 * @brief Get a DT_DRV_COMPAT instance's DMA specifier's cell value at an index 265 * @param inst DT_DRV_COMPAT instance number 266 * @param idx logical index into dmas property 267 * @param cell lowercase-and-underscores cell name 268 * @return the cell value at index "idx" 269 * @see DT_DMAS_CELL_BY_IDX() 270 */ 271 #define DT_INST_DMAS_CELL_BY_IDX(inst, idx, cell) \ 272 DT_PHA_BY_IDX(DT_DRV_INST(inst), dmas, idx, cell) 273 274 /** 275 * @brief Get a DMA specifier's cell value by name 276 * 277 * Example devicetree fragment: 278 * 279 * dma1: dma@... { 280 * compatible = "vnd,dma"; 281 * #dma-cells = <2>; 282 * }; 283 * 284 * dma2: dma@... { 285 * compatible = "vnd,dma"; 286 * #dma-cells = <2>; 287 * }; 288 * 289 * n: node { 290 * dmas = <&dma1 1 0x400>, 291 * <&dma2 6 0x404>; 292 * dma-names = "tx", "rx"; 293 * }; 294 * 295 * Bindings fragment for the vnd,dma compatible: 296 * 297 * dma-cells: 298 * - channel 299 * - config 300 * 301 * Example usage: 302 * 303 * DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), tx, channel) // 1 304 * DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), rx, channel) // 6 305 * DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), tx, config) // 0x400 306 * DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), rx, config) // 0x404 307 * 308 * @param node_id node identifier for a node with a dmas property 309 * @param name lowercase-and-underscores name of a dmas element 310 * as defined by the node's dma-names property 311 * @param cell lowercase-and-underscores cell name 312 * @return the cell value in the specifier at the named element 313 * @see DT_PHA_BY_NAME() 314 */ 315 #define DT_DMAS_CELL_BY_NAME(node_id, name, cell) \ 316 DT_PHA_BY_NAME(node_id, dmas, name, cell) 317 318 /** 319 * @brief Get a DT_DRV_COMPAT instance's DMA specifier's cell value by name 320 * @param inst DT_DRV_COMPAT instance number 321 * @param name lowercase-and-underscores name of a dmas element 322 * as defined by the node's dma-names property 323 * @param cell lowercase-and-underscores cell name 324 * @return the cell value in the specifier at the named element 325 * @see DT_DMAS_CELL_BY_NAME() 326 */ 327 #define DT_INST_DMAS_CELL_BY_NAME(inst, name, cell) \ 328 DT_DMAS_CELL_BY_NAME(DT_DRV_INST(inst), name, cell) 329 330 /** 331 * @brief Is index "idx" valid for a dmas property? 332 * @param node_id node identifier for a node with a dmas property 333 * @param idx logical index into dmas property 334 * @return 1 if the "dmas" property has index "idx", 0 otherwise 335 */ 336 #define DT_DMAS_HAS_IDX(node_id, idx) \ 337 IS_ENABLED(DT_CAT(node_id, _P_dmas_IDX_##idx##_EXISTS)) 338 339 /** 340 * @brief Is index "idx" valid for a DT_DRV_COMPAT instance's dmas property? 341 * @param inst DT_DRV_COMPAT instance number 342 * @param idx logical index into dmas property 343 * @return 1 if the "dmas" property has a specifier at index "idx", 0 otherwise 344 */ 345 #define DT_INST_DMAS_HAS_IDX(inst, idx) \ 346 DT_DMAS_HAS_IDX(DT_DRV_INST(inst), idx) 347 348 /** 349 * @brief Does a dmas property have a named element? 350 * @param node_id node identifier for a node with a dmas property 351 * @param name lowercase-and-underscores name of a dmas element 352 * as defined by the node's dma-names property 353 * @return 1 if the dmas property has the named element, 0 otherwise 354 */ 355 #define DT_DMAS_HAS_NAME(node_id, name) \ 356 IS_ENABLED(DT_CAT(node_id, _P_dmas_NAME_##name##_EXISTS)) 357 358 /** 359 * @brief Does a DT_DRV_COMPAT instance's dmas property have a named element? 360 * @param inst DT_DRV_COMPAT instance number 361 * @param name lowercase-and-underscores name of a dmas element 362 * as defined by the node's dma-names property 363 * @return 1 if the dmas property has the named element, 0 otherwise 364 */ 365 #define DT_INST_DMAS_HAS_NAME(inst, name) \ 366 DT_DMAS_HAS_NAME(DT_DRV_INST(inst), name) 367 368 /** 369 * @} 370 */ 371 372 #ifdef __cplusplus 373 } 374 #endif 375 376 #endif /* ZEPHYR_INCLUDE_DEVICETREE_DMAS_H_ */ 377
