19a63ec27SRobert Mustacchi.\" 29a63ec27SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 39a63ec27SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 49a63ec27SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 59a63ec27SRobert Mustacchi.\" 1.0 of the CDDL. 69a63ec27SRobert Mustacchi.\" 79a63ec27SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 89a63ec27SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 99a63ec27SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 109a63ec27SRobert Mustacchi.\" 119a63ec27SRobert Mustacchi.\" 129a63ec27SRobert Mustacchi.\" Copyright 2019 Robert Mustacchi 139a63ec27SRobert Mustacchi.\" 14*11845c32SPeter Tribble.Dd March 10, 2023 159a63ec27SRobert Mustacchi.Dt DDI_DMA_COOKIE_ITER 9F 169a63ec27SRobert Mustacchi.Os 179a63ec27SRobert Mustacchi.Sh NAME 189a63ec27SRobert Mustacchi.Nm ddi_dma_cookie_get , 199a63ec27SRobert Mustacchi.Nm ddi_dma_cookie_iter , 209a63ec27SRobert Mustacchi.Nm ddi_dma_cookie_one , 219a63ec27SRobert Mustacchi.Nm ddi_dma_ncookies , 229a63ec27SRobert Mustacchi.Nm ddi_dma_nextcookie 239a63ec27SRobert Mustacchi.Nd retrieve DMA cookies 249a63ec27SRobert Mustacchi.Sh SYNOPSIS 259a63ec27SRobert Mustacchi.In sys/ddi.h 269a63ec27SRobert Mustacchi.In sys/sunddi.h 279a63ec27SRobert Mustacchi.Ft "const ddi_dma_cookie_t *" 289a63ec27SRobert Mustacchi.Fo ddi_dma_cookie_iter 299a63ec27SRobert Mustacchi.Fa "ddi_dma_handle_t handle" 309a63ec27SRobert Mustacchi.Fa "const ddi_dma_cookie_t *cookiep" 319a63ec27SRobert Mustacchi.Fc 329a63ec27SRobert Mustacchi.Ft "const ddi_dma_cookie_t *" 339a63ec27SRobert Mustacchi.Fo ddi_dma_cookie_get 349a63ec27SRobert Mustacchi.Fa "ddi_dma_handle_t handle" 359a63ec27SRobert Mustacchi.Fa "uint_t index" 369a63ec27SRobert Mustacchi.Fc 379a63ec27SRobert Mustacchi.Ft "const ddi_dma_cookie_t *" 389a63ec27SRobert Mustacchi.Fo ddi_dma_cookie_one 399a63ec27SRobert Mustacchi.Fa "ddi_dma_handle_t handle" 409a63ec27SRobert Mustacchi.Fc 419a63ec27SRobert Mustacchi.Ft "uint_t" 429a63ec27SRobert Mustacchi.Fo ddi_dma_ncookies 439a63ec27SRobert Mustacchi.Fa "ddi_dma_handle_t handle" 449a63ec27SRobert Mustacchi.Fc 459a63ec27SRobert Mustacchi.Ft void 469a63ec27SRobert Mustacchi.Fo ddi_dma_nextcookie 479a63ec27SRobert Mustacchi.Fa "ddi_dma_handle_t handle" 489a63ec27SRobert Mustacchi.Fa "ddi_dma_cookie_t *cookiep" 499a63ec27SRobert Mustacchi.Fc 509a63ec27SRobert Mustacchi.Sh PARAMETERS 519a63ec27SRobert Mustacchi.Bl -tag -width Fa 529a63ec27SRobert Mustacchi.It Fa handle 539a63ec27SRobert MustacchiThe DMA handle obtained by a call to 549a63ec27SRobert Mustacchi.Xr ddi_dma_alloc_handle 9F . 559a63ec27SRobert Mustacchi.It Fa cookie 569a63ec27SRobert MustacchiA pointer to a 579a63ec27SRobert Mustacchi.Xr ddi_dma_cookie 9S 589a63ec27SRobert Mustacchistructure. 599a63ec27SRobert Mustacchi.It Fa index 609a63ec27SRobert MustacchiAn unsigned integer that represents the index of a cookie to obtain. 619a63ec27SRobert MustacchiThe first entry is at index zero. 629a63ec27SRobert Mustacchi.El 639a63ec27SRobert Mustacchi.Sh DESCRIPTION 649a63ec27SRobert MustacchiThe 659a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_iter , 669a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_get , 679a63ec27SRobert Mustacchiand 689a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_one 699a63ec27SRobert Mustacchifunctions obtain information about DMA cookies. 709a63ec27SRobert MustacchiWhen a DMA request, represented by the DMA handle 719a63ec27SRobert Mustacchi.Fa handle , 729a63ec27SRobert Mustacchihas been bound to a series of addresses with the 739a63ec27SRobert Mustacchi.Xr ddi_dma_addr_bind_handle 9F 749a63ec27SRobert Mustacchior 759a63ec27SRobert Mustacchi.Xr ddi_dma_buf_bind_handle 9F 769a63ec27SRobert Mustacchifunctions, the resulting addresses are stored in one or more 779a63ec27SRobert Mustacchi.Xr ddi_dma_cookie 9S 789a63ec27SRobert Mustacchistructures. 799a63ec27SRobert Mustacchithe three different functions provide different ways to obtain cookies 809a63ec27SRobert Mustacchiand are safe alternatives to the unsafe 819a63ec27SRobert Mustacchi.Fn ddi_dma_nextcookie 829a63ec27SRobert Mustacchifunction. 839a63ec27SRobert MustacchiTo see how to use these functions, please see the 849a63ec27SRobert Mustacchi.Sx EXAMPLES 859a63ec27SRobert Mustacchisection. 869a63ec27SRobert Mustacchi.Pp 879a63ec27SRobert MustacchiThe 889a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_iter 899a63ec27SRobert Mustacchifunction provides a way to iterate over all the cookies that are 909a63ec27SRobert Mustacchiassociated with the DMA handle 919a63ec27SRobert Mustacchi.Fa handle . 929a63ec27SRobert MustacchiTo get the first handle, pass 939a63ec27SRobert Mustacchi.Dv NULL 949a63ec27SRobert Mustacchiin 959a63ec27SRobert Mustacchi.Fa cookiep . 969a63ec27SRobert MustacchiDo not use the DMA cookie returned from either of the 979a63ec27SRobert Mustacchi.Xr ddi_dma_addr_bind_handle 9F 989a63ec27SRobert Mustacchior 999a63ec27SRobert Mustacchi.Xr ddi_dma_buf_bind_handle 9F 1009a63ec27SRobert Mustacchifunctions. 1019a63ec27SRobert MustacchiTo get subsequent cookies, pass the returned cookie as the argument 1029a63ec27SRobert Mustacchi.Fa cookiep . 1039a63ec27SRobert MustacchiWhen the function returns 1049a63ec27SRobert Mustacchi.Dv NULL 1059a63ec27SRobert Mustacchithen that indicates that the last handle has been iterated over. 1069a63ec27SRobert Mustacchi.Pp 1079a63ec27SRobert MustacchiThe 1089a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_get 1099a63ec27SRobert Mustacchifunction returns a specific cookie. 1109a63ec27SRobert MustacchiThe 1119a63ec27SRobert Mustacchi.Fa index 1129a63ec27SRobert Mustacchiindicates which of the cookies should be returned. 1139a63ec27SRobert MustacchiThe first cookie is at index 1149a63ec27SRobert Mustacchi.Sy 0 . 1159a63ec27SRobert MustacchiIf an invalid index is specified, the function returns 1169a63ec27SRobert Mustacchi.Dv NULL . 1179a63ec27SRobert Mustacchi.Pp 1189a63ec27SRobert MustacchiThe 1199a63ec27SRobert Mustacchi.Ft ddi_dma_cookie_one 1209a63ec27SRobert Mustacchifunction is a convenience function for DMA requests that have a single 1219a63ec27SRobert Mustacchicookie. 122*11845c32SPeter TribbleThis function always returns the single cookie associated with the DMA 1239a63ec27SRobert Mustacchihandle 1249a63ec27SRobert Mustacchi.Fa handle . 1259a63ec27SRobert MustacchiIf this function is used when there is a DMA request with multiple 1269a63ec27SRobert Mustacchicookies, then it will panic the system. 1279a63ec27SRobert MustacchiIt can never return 1289a63ec27SRobert Mustacchi.Dv NULL . 1299a63ec27SRobert Mustacchi.Pp 1309a63ec27SRobert MustacchiThe 1319a63ec27SRobert Mustacchi.Fn ddi_dma_ncookies 1329a63ec27SRobert Mustacchifunction returns the number of DMA cookies that are associated with the 1339a63ec27SRobert MustacchiDMA handle 1349a63ec27SRobert Mustacchi.Fa handle . 1359a63ec27SRobert MustacchiIf there are no DMA resources bound to the handle, then this will return 1369a63ec27SRobert Mustacchi.Sy 0 . 1379a63ec27SRobert Mustacchi.Pp 1389a63ec27SRobert MustacchiThe 1399a63ec27SRobert Mustacchi.Fn ddi_dma_nextcookie 1409a63ec27SRobert Mustacchifunction was the historical function that was associated with obtaining 1419a63ec27SRobert MustacchiDMA cookies. 1429a63ec27SRobert MustacchiIt should not be used due to several flaws. 1439a63ec27SRobert MustacchiThe 1449a63ec27SRobert Mustacchi.Fn ddi_dma_nextcookie 1459a63ec27SRobert Mustacchifunction mutates the underlying DMA handle meaning that a driver cannot 1469a63ec27SRobert Mustacchiobtain a cookie a second time and thus a device driver using this 1479a63ec27SRobert Mustacchiinterface must either manually keep storage of the cookie around wasting 1489a63ec27SRobert Mustacchispace or rebind the handle, wasting time. 1499a63ec27SRobert MustacchiIn addition, there is no way for the function to indicate that a driver 1509a63ec27SRobert Mustacchihas consumed all of its cookies. 1519a63ec27SRobert MustacchiIf for some reason a device driver calls the 1529a63ec27SRobert Mustacchi.Fn ddi_dma_nextcookie 1539a63ec27SRobert Mustacchifunction more times than there are cookies, the results are undefined. 1549a63ec27SRobert MustacchiIn short, this function should not be used for any purpose. 1559a63ec27SRobert MustacchiUse the 1569a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_iter , 1579a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_get , 1589a63ec27SRobert Mustacchior 1599a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_one 1609a63ec27SRobert Mustacchifunctions instead. 1619a63ec27SRobert Mustacchi.Sh CONTEXT 1629a63ec27SRobert MustacchiThe 1639a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_iter , 1649a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_get , 1659a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_one , 1669a63ec27SRobert Mustacchi.Fn ddi_dma_ncookies , 1679a63ec27SRobert Mustacchiand 1689a63ec27SRobert Mustacchi.Fn ddi_dma_nextcookie 1699a63ec27SRobert Mustacchifunctions may be called from 1709a63ec27SRobert Mustacchi.Sy user , 1719a63ec27SRobert Mustacchi.Sy kernel , 1729a63ec27SRobert Mustacchior 1739a63ec27SRobert Mustacchi.Sy interrupt 1749a63ec27SRobert Mustacchicontext. 1759a63ec27SRobert Mustacchi.Sh RETURN VALUES 1769a63ec27SRobert MustacchiUpon successful completion, the 1779a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_iter , 1789a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_get , 1799a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_one 1809a63ec27SRobert Mustacchifunctions will return the requested DMA cookie. 1819a63ec27SRobert MustacchiIf there are no more cookies, or 182*11845c32SPeter Tribble.Fa cookiep 1839a63ec27SRobert Mustacchiis invalid, the 1849a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_iter 1859a63ec27SRobert Mustacchifunction will return 1869a63ec27SRobert Mustacchi.Dv NULL . 1879a63ec27SRobert MustacchiIf 1889a63ec27SRobert Mustacchi.Fa index 1899a63ec27SRobert Mustacchidoes not correspond to a valid cookie, the 1909a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_get 1919a63ec27SRobert Mustacchifunction will return 1929a63ec27SRobert Mustacchi.Dv NULL . 1939a63ec27SRobert MustacchiIf there is not exactly one DMA cookie, or another issue occurs, then the 1949a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_one 1959a63ec27SRobert Mustacchifunction will panic the system. 1969a63ec27SRobert Mustacchi.Pp 1979a63ec27SRobert MustacchiUpon successful completion, the 1989a63ec27SRobert Mustacchi.Fn ddi_dma_ncookies 1999a63ec27SRobert Mustacchifunction returns the number of cookies associated with 2009a63ec27SRobert Mustacchi.Fa handle . 2019a63ec27SRobert MustacchiIf there are none, then 2029a63ec27SRobert Mustacchi.Sy 0 2039a63ec27SRobert Mustacchiis returned. 2049a63ec27SRobert Mustacchi.Pp 2059a63ec27SRobert MustacchiThe 2069a63ec27SRobert Mustacchi.Fn ddi_dma_nextcookie 2079a63ec27SRobert Mustacchifunction always updates 2089a63ec27SRobert Mustacchi.Fa cookiep 2099a63ec27SRobert Mustacchiregardless of whether it is valid or not. 2109a63ec27SRobert Mustacchi.Sh EXAMPLES 2119a63ec27SRobert Mustacchi.Sy Example 1 2129a63ec27SRobert MustacchiUsing the 2139a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_iter 2149a63ec27SRobert Mustacchifunction to obtain all DMA cookies. 2159a63ec27SRobert Mustacchi.Bd -literal 2169a63ec27SRobert Mustacchi/* 2179a63ec27SRobert Mustacchi * This example assumes that either ddi_dma_addr_bind_handle() or 2189a63ec27SRobert Mustacchi * ddi_dma_buf_bind_handle() has already been successfully called. 2199a63ec27SRobert Mustacchi */ 2209a63ec27SRobert Mustacchivoid 2219a63ec27SRobert Mustacchiprogram_dma(ddi_dma_handle_t handle) 2229a63ec27SRobert Mustacchi{ 2239a63ec27SRobert Mustacchi const ddi_dma_cookie_t *c; 2249a63ec27SRobert Mustacchi 2259a63ec27SRobert Mustacchi for (cookie = ddi_dma_cookie_iter(handle, NULL); c != NULL; 2269a63ec27SRobert Mustacchi c = ddi_dma_cookie_iter(handle, c)) { 2279a63ec27SRobert Mustacchi /* 2289a63ec27SRobert Mustacchi * Use the dmac_laddress and dmac_size members to 2299a63ec27SRobert Mustacchi * properly program the device or descriptor rings. 2309a63ec27SRobert Mustacchi */ 2319a63ec27SRobert Mustacchi } 2329a63ec27SRobert Mustacchi} 2339a63ec27SRobert Mustacchi.Ed 2349a63ec27SRobert Mustacchi.Pp 2359a63ec27SRobert Mustacchi.Sy Example 2 2369a63ec27SRobert MustacchiUsing the 2379a63ec27SRobert Mustacchi.Fn ddi_dma_cookie_get 2389a63ec27SRobert Mustacchifunction. 2399a63ec27SRobert Mustacchi.Bd -literal 2409a63ec27SRobert Mustacchi/* 2419a63ec27SRobert Mustacchi * This example assumes that either ddi_dma_mem_alloc() has already 2429a63ec27SRobert Mustacchi * been successfully called. 2439a63ec27SRobert Mustacchi */ 2449a63ec27SRobert Mustacchiint 2459a63ec27SRobert Mustacchibind_dma(ddi_dma_handle_t handle, void *addr, size_t len) 2469a63ec27SRobert Mustacchi{ 2479a63ec27SRobert Mustacchi int ret; 2489a63ec27SRobert Mustacchi uint_t i, ncookies; 2499a63ec27SRobert Mustacchi ddi_dma_cookie_t first; 2509a63ec27SRobert Mustacchi 2519a63ec27SRobert Mustacchi ret = ddi_dma_addr_bind_handle(handle, NULL, addr, len, 2529a63ec27SRobert Mustacchi DDI_DMA_RDWR | DDI_DMA_CONSISTENT, NULL, NULL, &first, 2539a63ec27SRobert Mustacchi &ncookies); 2549a63ec27SRobert Mustacchi if (ret != DDI_DMA_MAPPED) { 2559a63ec27SRobert Mustacchi return (ret); 2569a63ec27SRobert Mustacchi } 2579a63ec27SRobert Mustacchi 2589a63ec27SRobert Mustacchi /* 2599a63ec27SRobert Mustacchi * A driver doesn't need to store ncookies. It can get it again 2609a63ec27SRobert Mustacchi * by simply calling ddi_dma_ncookies() and using the result in 2619a63ec27SRobert Mustacchi * place of ncookies from ddi_dma_addr_bind_handle(). 2629a63ec27SRobert Mustacchi */ 2639a63ec27SRobert Mustacchi for (i = 0; i < ncookies; i++) { 2649a63ec27SRobert Mustacchi const ddi_dma_cookie_t *cookie; 2659a63ec27SRobert Mustacchi 266*11845c32SPeter Tribble cookie = ddi_dma_cookie_get(handle, i); 2679a63ec27SRobert Mustacchi /* 2689a63ec27SRobert Mustacchi * Use the dmac_laddress and dmac_size members to 2699a63ec27SRobert Mustacchi * properly program the device or descriptor rings. 2709a63ec27SRobert Mustacchi */ 2719a63ec27SRobert Mustacchi } 2729a63ec27SRobert Mustacchi} 2739a63ec27SRobert Mustacchi.Ed 2749a63ec27SRobert Mustacchi.Sh SEE ALSO 2759a63ec27SRobert Mustacchi.Xr ddi_dma_addr_bind_handle 9F , 2769a63ec27SRobert Mustacchi.Xr ddi_dma_alloc_handle 9F , 2779a63ec27SRobert Mustacchi.Xr ddi_dma_buf_bind_handle 9F , 2789a63ec27SRobert Mustacchi.Xr ddi_dma_unbind_handle 9F , 2799a63ec27SRobert Mustacchi.Xr ddi_dma_cookie 9S 2809a63ec27SRobert Mustacchi.Rs 2819a63ec27SRobert Mustacchi.%T Writing Device Drivers 2829a63ec27SRobert Mustacchi.Re 283