#############
Memory Bundle
#############

.. Symbol access is provided by the :py:attr:`SymbolService<lauterbach.trace32.rcl.SymbolService>` class. Each debugger has its own instance, which can be used through its :py:attr:`symbol<lauterbach.trace32.rcl.Debugger.symbol>` attribute.


Memory bundles can be used to speed up consecutive read/write accesses, for example when reading/writing multiple memory-mapped registers. The speedup depends on the size of the individual memory accesses. Larger block accesses will result in no speedup compared to the normal read/write accesses.


********************
Create Memory Bundle
********************

First a bundle needs to be created and read, write and/or read-write operation added to it: 

.. code-block:: pycon

	>>> bundle = pyrcl.MemoryAccessBundle()
	>>> bundle.add_write(addr, data)
	>>> bundle.add_read(addr, length=length)
	>>> bundle.add_readwrite(addr, data, mask)

Read-write operations will first read the value, and then write :code:`value = (read_value & ~mask) | (write_value & mask)`


*********************
Execute Memory Bundle
*********************

Memory bundles can be executed using :code:`dbg.memory.execute_bundle(bundle)`.

.. code-block:: pycon

	>>> try:
	>>> 	results = dbg.memory.execute_bundle(bundle)
	>>> except pyrcl.MemoryAccessError as e:
	>>> 	print(f"{type(e).__name__}: {e}")

A list of :code:`pyrcl.MemoryAccessResult` for each access added to the bundle is returned.

.. code-block:: pycon

	>>> for i, result in enumerate(results):
	>>> 	print(i, type(result), result.error, result.data)

Each result must checked for :code:`result.error`, the data can be accessed by :code:`result.data`.