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