Documentation URL

https://docs.micropython.org/en/latest/library/rp2.DMA.html#chaining-and-trigger-register-access

Description

Port, board and/or hardware

rp2, Pico RP2040

MicroPython version

MicroPython v1.23.0 on 2024-06-02; Raspberry Pi Pico with RP2040

Reproduction

import rp2

test_dma = rp2.DMA()

test_dma.active(1)

print("R",hex(test_dma.registers[0]))
print("W",hex(test_dma.registers[1]))
print("T",hex(test_dma.registers[2]))
print("C",hex(test_dma.registers[3]))
print("C",hex(test_dma.registers[4]))
print("R",hex(test_dma.registers[5]))
print("W",hex(test_dma.registers[6]))
print("T",hex(test_dma.registers[7]))
print("C",hex(test_dma.registers[8]))
print("T",hex(test_dma.registers[9]))
print("R",hex(test_dma.registers[10]))
print("W",hex(test_dma.registers[11]))
print("C",hex(test_dma.registers[12]))
print("W",hex(test_dma.registers[13]))
print("T",hex(test_dma.registers[14]))
print("R",hex(test_dma.registers[15]))

Expected behaviour

Base on the DMA chain example, I expected a result with the address of a DMA register.

Observed behaviour

I received this result, which shows the value within the DMA register.

Additional Information

With regard to DMA.config(), this documentation states:

write: The address to which the DMA controller will start writing or an object into which data will be written.

This example, shows:

gather_dma.config(
        read=gather_list, write=buffer_dma.registers[14:16],
        count=2, ctrl=gather_ctrl
    )

where DMA.registers is used to obtain the address of the register.

Because of how DMA.registers is used in the example, I expected DMA.registers to provide DMA register address, but the result shows DMA.registers provides values within the register.

Therefore, the example is showing incorrect use of DMA.registers, which has caused confusion as shown here.

Recommendation:

1. Update DMA.registers with additional language to explain how to use DMA.registers and the expected result.

2. Update the chain example to include two common chain use cases:
   a) "ping-pong" when changes in DMA config are not needed
   b) when one DMA is used to change the config of another DMA
   i) provide a way to write to a DMA register. possibly uctypes.addressof(DMA.register) + offset ?

Code of Conduct

Yes, I agree