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{sign}{size}_{endian}_p(ptr)`` 28 29store: ``st{size}_{endian}_p(ptr, val)`` 30 31``sign`` 32 - (empty) : for 32 or 64 bit sizes 33 - ``u`` : unsigned 34 - ``s`` : signed 35 36``size`` 37 - ``b`` : 8 bits 38 - ``w`` : 16 bits 39 - ``24`` : 24 bits 40 - ``l`` : 32 bits 41 - ``q`` : 64 bits 42 43``endian`` 44 - ``he`` : host endian 45 - ``be`` : big endian 46 - ``le`` : little endian 47 48The ``_{endian}`` infix is omitted for target-endian accesses. 49 50The target endian accessors are only available to source 51files which are built per-target. 52 53There are also functions which take the size as an argument: 54 55load: ``ldn{endian}_p(ptr, sz)`` 56 57which performs an unsigned load of ``sz`` bytes from ``ptr`` 58as an ``{endian}`` order value and returns it in a uint64_t. 59 60store: ``stn{endian}_p(ptr, sz, val)`` 61 62which stores ``val`` to ``ptr`` as an ``{endian}`` order value 63of size ``sz`` bytes. 64 65 66Regexes for git grep: 67 - ``\<ld[us]\?[bwlq]\(_[hbl]e\)\?_p\>`` 68 - ``\<st[bwlq]\(_[hbl]e\)\?_p\>`` 69 - ``\<st24\(_[hbl]e\)\?_p\>`` 70 - ``\<ldn_\([hbl]e\)\?_p\>`` 71 - ``\<stn_\([hbl]e\)\?_p\>`` 72 73``cpu_{ld,st}*_mmu`` 74~~~~~~~~~~~~~~~~~~~~ 75 76These functions operate on a guest virtual address, plus a context 77known as a "mmu index" which controls how that virtual address is 78translated, plus a ``MemOp`` which contains alignment requirements 79among other things. The ``MemOp`` and mmu index are combined into 80a single argument of type ``MemOpIdx``. 81 82The meaning of the indexes are target specific, but specifying a 83particular index might be necessary if, for instance, the helper 84requires a "always as non-privileged" access rather than the 85default access for the current state of the guest CPU. 86 87These functions may cause a guest CPU exception to be taken 88(e.g. for an alignment fault or MMU fault) which will result in 89guest CPU state being updated and control longjmp'ing out of the 90function call. They should therefore only be used in code that is 91implementing emulation of the guest CPU. 92 93The ``retaddr`` parameter is used to control unwinding of the 94guest CPU state in case of a guest CPU exception. This is passed 95to ``cpu_restore_state()``. Therefore the value should either be 0, 96to indicate that the guest CPU state is already synchronized, or 97the result of ``GETPC()`` from the top level ``HELPER(foo)`` 98function, which is a return address into the generated code\ [#gpc]_. 99 100.. [#gpc] Note that ``GETPC()`` should be used with great care: calling 101 it in other functions that are *not* the top level 102 ``HELPER(foo)`` will cause unexpected behavior. Instead, the 103 value of ``GETPC()`` should be read from the helper and passed 104 if needed to the functions that the helper calls. 105 106Function names follow the pattern: 107 108load: ``cpu_ld{size}{end}_mmu(env, ptr, oi, retaddr)`` 109 110store: ``cpu_st{size}{end}_mmu(env, ptr, val, oi, retaddr)`` 111 112``size`` 113 - ``b`` : 8 bits 114 - ``w`` : 16 bits 115 - ``l`` : 32 bits 116 - ``q`` : 64 bits 117 118``end`` 119 - (empty) : for target endian, or 8 bit sizes 120 - ``_be`` : big endian 121 - ``_le`` : little endian 122 123Regexes for git grep: 124 - ``\<cpu_ld[bwlq]\(_[bl]e\)\?_mmu\>`` 125 - ``\<cpu_st[bwlq]\(_[bl]e\)\?_mmu\>`` 126 127 128``cpu_{ld,st}*_mmuidx_ra`` 129~~~~~~~~~~~~~~~~~~~~~~~~~~ 130 131These functions work like the ``cpu_{ld,st}_mmu`` functions except 132that the ``mmuidx`` parameter is not combined with a ``MemOp``, 133and therefore there is no required alignment supplied or enforced. 134 135Function names follow the pattern: 136 137load: ``cpu_ld{sign}{size}{end}_mmuidx_ra(env, ptr, mmuidx, retaddr)`` 138 139store: ``cpu_st{size}{end}_mmuidx_ra(env, ptr, val, mmuidx, retaddr)`` 140 141``sign`` 142 - (empty) : for 32 or 64 bit sizes 143 - ``u`` : unsigned 144 - ``s`` : signed 145 146``size`` 147 - ``b`` : 8 bits 148 - ``w`` : 16 bits 149 - ``l`` : 32 bits 150 - ``q`` : 64 bits 151 152``end`` 153 - (empty) : for target endian, or 8 bit sizes 154 - ``_be`` : big endian 155 - ``_le`` : little endian 156 157Regexes for git grep: 158 - ``\<cpu_ld[us]\?[bwlq]\(_[bl]e\)\?_mmuidx_ra\>`` 159 - ``\<cpu_st[bwlq]\(_[bl]e\)\?_mmuidx_ra\>`` 160 161``cpu_{ld,st}*_data_ra`` 162~~~~~~~~~~~~~~~~~~~~~~~~ 163 164These functions work like the ``cpu_{ld,st}_mmuidx_ra`` functions 165except that the ``mmuidx`` parameter is taken from the current mode 166of the guest CPU, as determined by ``cpu_mmu_index(env, false)``. 167 168These are generally the preferred way to do accesses by guest 169virtual address from helper functions, unless the access should 170be performed with a context other than the default, or alignment 171should be enforced for the access. 172 173Function names follow the pattern: 174 175load: ``cpu_ld{sign}{size}{end}_data_ra(env, ptr, ra)`` 176 177store: ``cpu_st{size}{end}_data_ra(env, ptr, val, ra)`` 178 179``sign`` 180 - (empty) : for 32 or 64 bit sizes 181 - ``u`` : unsigned 182 - ``s`` : signed 183 184``size`` 185 - ``b`` : 8 bits 186 - ``w`` : 16 bits 187 - ``l`` : 32 bits 188 - ``q`` : 64 bits 189 190``end`` 191 - (empty) : for target endian, or 8 bit sizes 192 - ``_be`` : big endian 193 - ``_le`` : little endian 194 195Regexes for git grep: 196 - ``\<cpu_ld[us]\?[bwlq]\(_[bl]e\)\?_data_ra\>`` 197 - ``\<cpu_st[bwlq]\(_[bl]e\)\?_data_ra\>`` 198 199``cpu_{ld,st}*_data`` 200~~~~~~~~~~~~~~~~~~~~~ 201 202These functions work like the ``cpu_{ld,st}_data_ra`` functions 203except that the ``retaddr`` parameter is 0, and thus does not 204unwind guest CPU state. 205 206This means they must only be used from helper functions where the 207translator has saved all necessary CPU state. These functions are 208the right choice for calls made from hooks like the CPU ``do_interrupt`` 209hook or when you know for certain that the translator had to save all 210the CPU state anyway. 211 212Function names follow the pattern: 213 214load: ``cpu_ld{sign}{size}{end}_data(env, ptr)`` 215 216store: ``cpu_st{size}{end}_data(env, ptr, val)`` 217 218``sign`` 219 - (empty) : for 32 or 64 bit sizes 220 - ``u`` : unsigned 221 - ``s`` : signed 222 223``size`` 224 - ``b`` : 8 bits 225 - ``w`` : 16 bits 226 - ``l`` : 32 bits 227 - ``q`` : 64 bits 228 229``end`` 230 - (empty) : for target endian, or 8 bit sizes 231 - ``_be`` : big endian 232 - ``_le`` : little endian 233 234Regexes for git grep: 235 - ``\<cpu_ld[us]\?[bwlq]\(_[bl]e\)\?_data\>`` 236 - ``\<cpu_st[bwlq]\(_[bl]e\)\?_data\+\>`` 237 238``cpu_ld*_code`` 239~~~~~~~~~~~~~~~~ 240 241These functions perform a read for instruction execution. The ``mmuidx`` 242parameter is taken from the current mode of the guest CPU, as determined 243by ``cpu_mmu_index(env, true)``. The ``retaddr`` parameter is 0, and 244thus does not unwind guest CPU state, because CPU state is always 245synchronized while translating instructions. Any guest CPU exception 246that is raised will indicate an instruction execution fault rather than 247a data read fault. 248 249In general these functions should not be used directly during translation. 250There are wrapper functions that are to be used which also take care of 251plugins for tracing. 252 253Function names follow the pattern: 254 255load: ``cpu_ld{sign}{size}_code(env, ptr)`` 256 257``sign`` 258 - (empty) : for 32 or 64 bit sizes 259 - ``u`` : unsigned 260 - ``s`` : signed 261 262``size`` 263 - ``b`` : 8 bits 264 - ``w`` : 16 bits 265 - ``l`` : 32 bits 266 - ``q`` : 64 bits 267 268Regexes for git grep: 269 - ``\<cpu_ld[us]\?[bwlq]_code\>`` 270 271``translator_ld*`` 272~~~~~~~~~~~~~~~~~~ 273 274These functions are a wrapper for ``cpu_ld*_code`` which also perform 275any actions required by any tracing plugins. They are only to be 276called during the translator callback ``translate_insn``. 277 278There is a set of functions ending in ``_swap`` which, if the parameter 279is true, returns the value in the endianness that is the reverse of 280the guest native endianness, as determined by ``TARGET_BIG_ENDIAN``. 281 282Function names follow the pattern: 283 284load: ``translator_ld{sign}{size}(env, ptr)`` 285 286swap: ``translator_ld{sign}{size}_swap(env, ptr, swap)`` 287 288``sign`` 289 - (empty) : for 32 or 64 bit sizes 290 - ``u`` : unsigned 291 - ``s`` : signed 292 293``size`` 294 - ``b`` : 8 bits 295 - ``w`` : 16 bits 296 - ``l`` : 32 bits 297 - ``q`` : 64 bits 298 299Regexes for git grep: 300 - ``\<translator_ld[us]\?[bwlq]\(_swap\)\?\>`` 301 302``helper_{ld,st}*_mmu`` 303~~~~~~~~~~~~~~~~~~~~~~~~~ 304 305These functions are intended primarily to be called by the code 306generated by the TCG backend. Like the ``cpu_{ld,st}_mmu`` functions 307they perform accesses by guest virtual address, with a given ``MemOpIdx``. 308 309They differ from ``cpu_{ld,st}_mmu`` in that they take the endianness 310of the operation only from the MemOpIdx, and loads extend the return 311value to the size of a host general register (``tcg_target_ulong``). 312 313load: ``helper_ld{sign}{size}_mmu(env, addr, opindex, retaddr)`` 314 315store: ``helper_{size}_mmu(env, addr, val, opindex, retaddr)`` 316 317``sign`` 318 - (empty) : for 32 or 64 bit sizes 319 - ``u`` : unsigned 320 - ``s`` : signed 321 322``size`` 323 - ``b`` : 8 bits 324 - ``w`` : 16 bits 325 - ``l`` : 32 bits 326 - ``q`` : 64 bits 327 328Regexes for git grep: 329 - ``\<helper_ld[us]\?[bwlq]_mmu\>`` 330 - ``\<helper_st[bwlq]_mmu\>`` 331 332``address_space_*`` 333~~~~~~~~~~~~~~~~~~~ 334 335These functions are the primary ones to use when emulating CPU 336or device memory accesses. They take an AddressSpace, which is the 337way QEMU defines the view of memory that a device or CPU has. 338(They generally correspond to being the "master" end of a hardware bus 339or bus fabric.) 340 341Each CPU has an AddressSpace. Some kinds of CPU have more than 342one AddressSpace (for instance Arm guest CPUs have an AddressSpace 343for the Secure world and one for NonSecure if they implement TrustZone). 344Devices which can do DMA-type operations should generally have an 345AddressSpace. There is also a "system address space" which typically 346has all the devices and memory that all CPUs can see. (Some older 347device models use the "system address space" rather than properly 348modelling that they have an AddressSpace of their own.) 349 350Functions are provided for doing byte-buffer reads and writes, 351and also for doing one-data-item loads and stores. 352 353In all cases the caller provides a MemTxAttrs to specify bus 354transaction attributes, and can check whether the memory transaction 355succeeded using a MemTxResult return code. 356 357``address_space_read(address_space, addr, attrs, buf, len)`` 358 359``address_space_write(address_space, addr, attrs, buf, len)`` 360 361``address_space_rw(address_space, addr, attrs, buf, len, is_write)`` 362 363``address_space_ld{sign}{size}_{endian}(address_space, addr, attrs, txresult)`` 364 365``address_space_st{size}_{endian}(address_space, addr, val, attrs, txresult)`` 366 367``sign`` 368 - (empty) : for 32 or 64 bit sizes 369 - ``u`` : unsigned 370 371(No signed load operations are provided.) 372 373``size`` 374 - ``b`` : 8 bits 375 - ``w`` : 16 bits 376 - ``l`` : 32 bits 377 - ``q`` : 64 bits 378 379``endian`` 380 - ``le`` : little endian 381 - ``be`` : big endian 382 383The ``_{endian}`` suffix is omitted for byte accesses. 384 385Regexes for git grep: 386 - ``\<address_space_\(read\|write\|rw\)\>`` 387 - ``\<address_space_ldu\?[bwql]\(_[lb]e\)\?\>`` 388 - ``\<address_space_st[bwql]\(_[lb]e\)\?\>`` 389 390``address_space_write_rom`` 391~~~~~~~~~~~~~~~~~~~~~~~~~~~ 392 393This function performs a write by physical address like 394``address_space_write``, except that if the write is to a ROM then 395the ROM contents will be modified, even though a write by the guest 396CPU to the ROM would be ignored. This is used for non-guest writes 397like writes from the gdb debug stub or initial loading of ROM contents. 398 399Note that portions of the write which attempt to write data to a 400device will be silently ignored -- only real RAM and ROM will 401be written to. 402 403Regexes for git grep: 404 - ``address_space_write_rom`` 405 406``{ld,st}*_phys`` 407~~~~~~~~~~~~~~~~~ 408 409These are functions which are identical to 410``address_space_{ld,st}*``, except that they always pass 411``MEMTXATTRS_UNSPECIFIED`` for the transaction attributes, and ignore 412whether the transaction succeeded or failed. 413 414The fact that they ignore whether the transaction succeeded means 415they should not be used in new code, unless you know for certain 416that your code will only be used in a context where the CPU or 417device doing the access has no way to report such an error. 418 419``load: ld{sign}{size}_{endian}_phys`` 420 421``store: st{size}_{endian}_phys`` 422 423``sign`` 424 - (empty) : for 32 or 64 bit sizes 425 - ``u`` : unsigned 426 427(No signed load operations are provided.) 428 429``size`` 430 - ``b`` : 8 bits 431 - ``w`` : 16 bits 432 - ``l`` : 32 bits 433 - ``q`` : 64 bits 434 435``endian`` 436 - ``le`` : little endian 437 - ``be`` : big endian 438 439The ``_{endian}_`` infix is omitted for byte accesses. 440 441Regexes for git grep: 442 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_phys\>`` 443 - ``\<st[bwlq]\(_[bl]e\)\?_phys\>`` 444 445``cpu_physical_memory_*`` 446~~~~~~~~~~~~~~~~~~~~~~~~~ 447 448These are convenience functions which are identical to 449``address_space_*`` but operate specifically on the system address space, 450always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and 451ignore whether the memory transaction succeeded or failed. 452For new code they are better avoided: 453 454* there is likely to be behaviour you need to model correctly for a 455 failed read or write operation 456* a device should usually perform operations on its own AddressSpace 457 rather than using the system address space 458 459``cpu_physical_memory_read`` 460 461``cpu_physical_memory_write`` 462 463``cpu_physical_memory_rw`` 464 465Regexes for git grep: 466 - ``\<cpu_physical_memory_\(read\|write\|rw\)\>`` 467 468``cpu_memory_rw_debug`` 469~~~~~~~~~~~~~~~~~~~~~~~ 470 471Access CPU memory by virtual address for debug purposes. 472 473This function is intended for use by the GDB stub and similar code. 474It takes a virtual address, converts it to a physical address via 475an MMU lookup using the current settings of the specified CPU, 476and then performs the access (using ``address_space_rw`` for 477reads or ``cpu_physical_memory_write_rom`` for writes). 478This means that if the access is a write to a ROM then this 479function will modify the contents (whereas a normal guest CPU access 480would ignore the write attempt). 481 482``cpu_memory_rw_debug`` 483 484``dma_memory_*`` 485~~~~~~~~~~~~~~~~ 486 487These behave like ``address_space_*``, except that they perform a DMA 488barrier operation first. 489 490**TODO**: We should provide guidance on when you need the DMA 491barrier operation and when it's OK to use ``address_space_*``, and 492make sure our existing code is doing things correctly. 493 494``dma_memory_read`` 495 496``dma_memory_write`` 497 498``dma_memory_rw`` 499 500Regexes for git grep: 501 - ``\<dma_memory_\(read\|write\|rw\)\>`` 502 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_dma\>`` 503 - ``\<st[bwlq]\(_[bl]e\)\?_dma\>`` 504 505``pci_dma_*`` and ``{ld,st}*_pci_dma`` 506~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 507 508These functions are specifically for PCI device models which need to 509perform accesses where the PCI device is a bus master. You pass them a 510``PCIDevice *`` and they will do ``dma_memory_*`` operations on the 511correct address space for that device. 512 513``pci_dma_read`` 514 515``pci_dma_write`` 516 517``pci_dma_rw`` 518 519``load: ld{sign}{size}_{endian}_pci_dma`` 520 521``store: st{size}_{endian}_pci_dma`` 522 523``sign`` 524 - (empty) : for 32 or 64 bit sizes 525 - ``u`` : unsigned 526 527(No signed load operations are provided.) 528 529``size`` 530 - ``b`` : 8 bits 531 - ``w`` : 16 bits 532 - ``l`` : 32 bits 533 - ``q`` : 64 bits 534 535``endian`` 536 - ``le`` : little endian 537 - ``be`` : big endian 538 539The ``_{endian}_`` infix is omitted for byte accesses. 540 541Regexes for git grep: 542 - ``\<pci_dma_\(read\|write\|rw\)\>`` 543 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_pci_dma\>`` 544 - ``\<st[bwlq]\(_[bl]e\)\?_pci_dma\>`` 545