Skip to content

Commit 1f80205

Browse files
committed
README_BUILD: Document DMA path environment var
Describe the LIBIIO_DMA_HEAP_PATH environment variable and provide an usage example. Signed-off-by: Dan Nechita <[email protected]>
1 parent cc84d3c commit 1f80205

File tree

1 file changed

+40
-0
lines changed

1 file changed

+40
-0
lines changed

README_BUILD.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,46 @@ It will try to link against the `call_function` symbol even though it's clearly
164164

165165
For this reason, when building with MSVC, please build in `RelWithDebInfo` mode. If you try to build in `Debug` mode, it will error.
166166

167+
## Environment Variable Configuration
168+
169+
### DMA Heap Path Configuration
170+
171+
libiio supports configuring the DMA heap path globally through the `LIBIIO_DMA_HEAP_PATH` environment variable. This overrides the default `/dev/dma_heap/system` path for all IIO devices.
172+
173+
#### Supported Format (Global Only)
174+
```bash
175+
export LIBIIO_DMA_HEAP_PATH=heap_name
176+
```
177+
This will use `/dev/dma_heap/<heap_name>` for every device.
178+
179+
#### Accepted Values
180+
181+
The environment variable accepts only the following predefined heap names:
182+
- `system` (default when unset or empty)
183+
- `default_cma_region`
184+
- `reserved`
185+
- `linux,cma`
186+
- `default-pool`
187+
188+
**Examples:**
189+
```bash
190+
export LIBIIO_DMA_HEAP_PATH=default_cma_region
191+
./an_iio_application
192+
193+
export LIBIIO_DMA_HEAP_PATH=reserved
194+
./an_iio_application
195+
```
196+
197+
#### Behavior and Error Handling
198+
199+
- **Unset or empty**: Defaults to `system` heap (`/dev/dma_heap/system`)
200+
- **Valid value**: Uses the specified heap (`/dev/dma_heap/<heap_name>`)
201+
- **Invalid value**: **Operation fails with error** - no fallback occurs
202+
203+
Setting an invalid heap name will cause DMABUF operations to fail immediately with an error message listing the accepted values. This ensures users are aware when their configuration is incorrect rather than silently using a fallback.
204+
205+
This feature is intended for users who need to select an alternative DMA heap present under `/dev/dma_heap/` (for example a reserved or CMA heap).
206+
167207
## Instructions applicable to Microcontroller configurations
168208

169209
### Install Prerequisites/Dependencies

0 commit comments

Comments
 (0)