1.. 2 Copyright (c) 2017 Linaro Limited 3 Written by Peter Maydell 4 5=================== 6Load and Store APIs 7=================== 8 9QEMU internally has multiple families of functions for performing 10loads and stores. This document attempts to enumerate them all 11and indicate when to use them. It does not provide detailed 12documentation of each API -- for that you should look at the 13documentation comments in the relevant header files. 14 15 16``ld*_p and st*_p`` 17~~~~~~~~~~~~~~~~~~~ 18 19These functions operate on a host pointer, and should be used 20when you already have a pointer into host memory (corresponding 21to guest ram or a local buffer). They deal with doing accesses 22with the desired endianness and with correctly handling 23potentially unaligned pointer values. 24 25Function names follow the pattern: 26 27load: ``ld{type}{sign}{size}_{endian}_p(ptr)`` 28 29store: ``st{type}{size}_{endian}_p(ptr, val)`` 30 31``type`` 32 - (empty) : integer access 33 - ``f`` : float access 34 35``sign`` 36 - (empty) : for 32 or 64 bit sizes (including floats and doubles) 37 - ``u`` : unsigned 38 - ``s`` : signed 39 40``size`` 41 - ``b`` : 8 bits 42 - ``w`` : 16 bits 43 - ``l`` : 32 bits 44 - ``q`` : 64 bits 45 46``endian`` 47 - ``he`` : host endian 48 - ``be`` : big endian 49 - ``le`` : little endian 50 51The ``_{endian}`` infix is omitted for target-endian accesses. 52 53The target endian accessors are only available to source 54files which are built per-target. 55 56Regexes for git grep 57 - ``\<ldf\?[us]\?[bwlq]\(_[hbl]e\)\?_p\>`` 58 - ``\<stf\?[bwlq]\(_[hbl]e\)\?_p\>`` 59 60``cpu_{ld,st}_*`` 61~~~~~~~~~~~~~~~~~ 62 63These functions operate on a guest virtual address. Be aware 64that these functions may cause a guest CPU exception to be 65taken (e.g. for an alignment fault or MMU fault) which will 66result in guest CPU state being updated and control longjumping 67out of the function call. They should therefore only be used 68in code that is implementing emulation of the target CPU. 69 70These functions may throw an exception (longjmp() back out 71to the top level TCG loop). This means they must only be used 72from helper functions where the translator has saved all 73necessary CPU state before generating the helper function call. 74It's usually better to use the ``_ra`` variants described below 75from helper functions, but these functions are the right choice 76for calls made from hooks like the CPU do_interrupt hook or 77when you know for certain that the translator had to save all 78the CPU state that ``cpu_restore_state()`` would restore anyway. 79 80Function names follow the pattern: 81 82load: ``cpu_ld{sign}{size}_{mmusuffix}(env, ptr)`` 83 84store: ``cpu_st{size}_{mmusuffix}(env, ptr, val)`` 85 86``sign`` 87 - (empty) : for 32 or 64 bit sizes 88 - ``u`` : unsigned 89 - ``s`` : signed 90 91``size`` 92 - ``b`` : 8 bits 93 - ``w`` : 16 bits 94 - ``l`` : 32 bits 95 - ``q`` : 64 bits 96 97``mmusuffix`` is one of the generic suffixes ``data`` or ``code``, or 98(for softmmu configs) a target-specific MMU mode suffix as defined 99in the target's ``cpu.h``. 100 101Regexes for git grep 102 - ``\<cpu_ld[us]\?[bwlq]_[a-zA-Z0-9]\+\>`` 103 - ``\<cpu_st[bwlq]_[a-zA-Z0-9]\+\>`` 104 105``cpu_{ld,st}_*_ra`` 106~~~~~~~~~~~~~~~~~~~~ 107 108These functions work like the ``cpu_{ld,st}_*`` functions except 109that they also take a ``retaddr`` argument. This extra argument 110allows for correct unwinding of any exception that is taken, 111and should generally be the result of GETPC() called directly 112from the top level HELPER(foo) function (i.e. the return address 113in the generated code). 114 115These are generally the preferred way to do accesses by guest 116virtual address from helper functions; see the documentation 117of the non-``_ra`` variants for when those would be better. 118 119Calling these functions with a ``retaddr`` argument of 0 is 120equivalent to calling the non-``_ra`` version of the function. 121 122Function names follow the pattern: 123 124load: ``cpu_ld{sign}{size}_{mmusuffix}_ra(env, ptr, retaddr)`` 125 126store: ``cpu_st{sign}{size}_{mmusuffix}_ra(env, ptr, val, retaddr)`` 127 128Regexes for git grep 129 - ``\<cpu_ld[us]\?[bwlq]_[a-zA-Z0-9]\+_ra\>`` 130 - ``\<cpu_st[bwlq]_[a-zA-Z0-9]\+_ra\>`` 131 132``helper_*_{ld,st}*mmu`` 133~~~~~~~~~~~~~~~~~~~~~~~~ 134 135These functions are intended primarily to be called by the code 136generated by the TCG backend. They may also be called by target 137CPU helper function code. Like the ``cpu_{ld,st}_*_ra`` functions 138they perform accesses by guest virtual address; the difference is 139that these functions allow you to specify an ``opindex`` parameter 140which encodes (among other things) the mmu index to use for the 141access. This is necessary if your helper needs to make an access 142via a specific mmu index (for instance, an "always as non-privileged" 143access) rather than using the default mmu index for the current state 144of the guest CPU. 145 146The ``opindex`` parameter should be created by calling ``make_memop_idx()``. 147 148The ``retaddr`` parameter should be the result of GETPC() called directly 149from the top level HELPER(foo) function (or 0 if no guest CPU state 150unwinding is required). 151 152**TODO** The names of these functions are a bit odd for historical 153reasons because they were originally expected to be called only from 154within generated code. We should rename them to bring them 155more in line with the other memory access functions. 156 157load: ``helper_{endian}_ld{sign}{size}_mmu(env, addr, opindex, retaddr)`` 158 159load (code): ``helper_{endian}_ld{sign}{size}_cmmu(env, addr, opindex, retaddr)`` 160 161store: ``helper_{endian}_st{size}_mmu(env, addr, val, opindex, retaddr)`` 162 163``sign`` 164 - (empty) : for 32 or 64 bit sizes 165 - ``u`` : unsigned 166 - ``s`` : signed 167 168``size`` 169 - ``b`` : 8 bits 170 - ``w`` : 16 bits 171 - ``l`` : 32 bits 172 - ``q`` : 64 bits 173 174``endian`` 175 - ``le`` : little endian 176 - ``be`` : big endian 177 - ``ret`` : target endianness 178 179Regexes for git grep 180 - ``\<helper_\(le\|be\|ret\)_ld[us]\?[bwlq]_c\?mmu\>`` 181 - ``\<helper_\(le\|be\|ret\)_st[bwlq]_mmu\>`` 182 183``address_space_*`` 184~~~~~~~~~~~~~~~~~~~ 185 186These functions are the primary ones to use when emulating CPU 187or device memory accesses. They take an AddressSpace, which is the 188way QEMU defines the view of memory that a device or CPU has. 189(They generally correspond to being the "master" end of a hardware bus 190or bus fabric.) 191 192Each CPU has an AddressSpace. Some kinds of CPU have more than 193one AddressSpace (for instance ARM guest CPUs have an AddressSpace 194for the Secure world and one for NonSecure if they implement TrustZone). 195Devices which can do DMA-type operations should generally have an 196AddressSpace. There is also a "system address space" which typically 197has all the devices and memory that all CPUs can see. (Some older 198device models use the "system address space" rather than properly 199modelling that they have an AddressSpace of their own.) 200 201Functions are provided for doing byte-buffer reads and writes, 202and also for doing one-data-item loads and stores. 203 204In all cases the caller provides a MemTxAttrs to specify bus 205transaction attributes, and can check whether the memory transaction 206succeeded using a MemTxResult return code. 207 208``address_space_read(address_space, addr, attrs, buf, len)`` 209 210``address_space_write(address_space, addr, attrs, buf, len)`` 211 212``address_space_rw(address_space, addr, attrs, buf, len, is_write)`` 213 214``address_space_ld{sign}{size}_{endian}(address_space, addr, attrs, txresult)`` 215 216``address_space_st{size}_{endian}(address_space, addr, val, attrs, txresult)`` 217 218``sign`` 219 - (empty) : for 32 or 64 bit sizes 220 - ``u`` : unsigned 221 222(No signed load operations are provided.) 223 224``size`` 225 - ``b`` : 8 bits 226 - ``w`` : 16 bits 227 - ``l`` : 32 bits 228 - ``q`` : 64 bits 229 230``endian`` 231 - ``le`` : little endian 232 - ``be`` : big endian 233 234The ``_{endian}`` suffix is omitted for byte accesses. 235 236Regexes for git grep 237 - ``\<address_space_\(read\|write\|rw\)\>`` 238 - ``\<address_space_ldu\?[bwql]\(_[lb]e\)\?\>`` 239 - ``\<address_space_st[bwql]\(_[lb]e\)\?\>`` 240 241``{ld,st}*_phys`` 242~~~~~~~~~~~~~~~~~ 243 244These are functions which are identical to 245``address_space_{ld,st}*``, except that they always pass 246``MEMTXATTRS_UNSPECIFIED`` for the transaction attributes, and ignore 247whether the transaction succeeded or failed. 248 249The fact that they ignore whether the transaction succeeded means 250they should not be used in new code, unless you know for certain 251that your code will only be used in a context where the CPU or 252device doing the access has no way to report such an error. 253 254``load: ld{sign}{size}_{endian}_phys`` 255 256``store: st{size}_{endian}_phys`` 257 258``sign`` 259 - (empty) : for 32 or 64 bit sizes 260 - ``u`` : unsigned 261 262(No signed load operations are provided.) 263 264``size`` 265 - ``b`` : 8 bits 266 - ``w`` : 16 bits 267 - ``l`` : 32 bits 268 - ``q`` : 64 bits 269 270``endian`` 271 - ``le`` : little endian 272 - ``be`` : big endian 273 274The ``_{endian}_`` infix is omitted for byte accesses. 275 276Regexes for git grep 277 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_phys\>`` 278 - ``\<st[bwlq]\(_[bl]e\)\?_phys\>`` 279 280``cpu_physical_memory_*`` 281~~~~~~~~~~~~~~~~~~~~~~~~~ 282 283These are convenience functions which are identical to 284``address_space_*`` but operate specifically on the system address space, 285always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and 286ignore whether the memory transaction succeeded or failed. 287For new code they are better avoided: 288 289* there is likely to be behaviour you need to model correctly for a 290 failed read or write operation 291* a device should usually perform operations on its own AddressSpace 292 rather than using the system address space 293 294``cpu_physical_memory_read`` 295 296``cpu_physical_memory_write`` 297 298``cpu_physical_memory_rw`` 299 300Regexes for git grep 301 - ``\<cpu_physical_memory_\(read\|write\|rw\)\>`` 302 303``cpu_physical_memory_write_rom`` 304~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 305 306This function performs a write by physical address like 307``address_space_write``, except that if the write is to a ROM then 308the ROM contents will be modified, even though a write by the guest 309CPU to the ROM would be ignored. 310 311Note that unlike ``cpu_physical_memory_write()`` this function takes 312an AddressSpace argument, but unlike ``address_space_write()`` this 313function does not take a ``MemTxAttrs`` or return a ``MemTxResult``. 314 315**TODO**: we should probably clean up this inconsistency and 316turn the function into ``address_space_write_rom`` with an API 317matching ``address_space_write``. 318 319``cpu_physical_memory_write_rom`` 320 321 322``cpu_memory_rw_debug`` 323~~~~~~~~~~~~~~~~~~~~~~~ 324 325Access CPU memory by virtual address for debug purposes. 326 327This function is intended for use by the GDB stub and similar code. 328It takes a virtual address, converts it to a physical address via 329an MMU lookup using the current settings of the specified CPU, 330and then performs the access (using ``address_space_rw`` for 331reads or ``cpu_physical_memory_write_rom`` for writes). 332This means that if the access is a write to a ROM then this 333function will modify the contents (whereas a normal guest CPU access 334would ignore the write attempt). 335 336``cpu_memory_rw_debug`` 337 338``dma_memory_*`` 339~~~~~~~~~~~~~~~~ 340 341These behave like ``address_space_*``, except that they perform a DMA 342barrier operation first. 343 344**TODO**: We should provide guidance on when you need the DMA 345barrier operation and when it's OK to use ``address_space_*``, and 346make sure our existing code is doing things correctly. 347 348``dma_memory_read`` 349 350``dma_memory_write`` 351 352``dma_memory_rw`` 353 354Regexes for git grep 355 - ``\<dma_memory_\(read\|write\|rw\)\>`` 356 357``pci_dma_*`` and ``{ld,st}*_pci_dma`` 358~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 359 360These functions are specifically for PCI device models which need to 361perform accesses where the PCI device is a bus master. You pass them a 362``PCIDevice *`` and they will do ``dma_memory_*`` operations on the 363correct address space for that device. 364 365``pci_dma_read`` 366 367``pci_dma_write`` 368 369``pci_dma_rw`` 370 371``load: ld{sign}{size}_{endian}_pci_dma`` 372 373``store: st{size}_{endian}_pci_dma`` 374 375``sign`` 376 - (empty) : for 32 or 64 bit sizes 377 - ``u`` : unsigned 378 379(No signed load operations are provided.) 380 381``size`` 382 - ``b`` : 8 bits 383 - ``w`` : 16 bits 384 - ``l`` : 32 bits 385 - ``q`` : 64 bits 386 387``endian`` 388 - ``le`` : little endian 389 - ``be`` : big endian 390 391The ``_{endian}_`` infix is omitted for byte accesses. 392 393Regexes for git grep 394 - ``\<pci_dma_\(read\|write\|rw\)\>`` 395 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_pci_dma\>`` 396 - ``\<st[bwlq]\(_[bl]e\)\?_pci_dma\>`` 397