docs/devel/loads-stores.rst

   1 ..
   2    Copyright (c) 2017 Linaro Limited
   3    Written by Peter Maydell
   4
   5 ===================
   6 Load and Store APIs
   7 ===================
   8
   9 QEMU internally has multiple families of functions for performing
  10 loads and stores. This document attempts to enumerate them all
  11 and indicate when to use them. It does not provide detailed
  12 documentation of each API -- for that you should look at the
  13 documentation comments in the relevant header files.
  14
  15
  16 ``ld*_p and st*_p``
  17 ~~~~~~~~~~~~~~~~~~~
  18
  19 These functions operate on a host pointer, and should be used
  20 when you already have a pointer into host memory (corresponding
  21 to guest ram or a local buffer). They deal with doing accesses
  22 with the desired endianness and with correctly handling
  23 potentially unaligned pointer values.
  24
  25 Function names follow the pattern:
  26
  27 load: ``ld{sign}{size}_{endian}_p(ptr)``
  28
  29 store: ``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
  48 The ``_{endian}`` infix is omitted for target-endian accesses.
  49
  50 The target endian accessors are only available to source
  51 files which are built per-target.
  52
  53 There are also functions which take the size as an argument:
  54
  55 load: ``ldn{endian}_p(ptr, sz)``
  56
  57 which performs an unsigned load of ``sz`` bytes from ``ptr``
  58 as an ``{endian}`` order value and returns it in a uint64_t.
  59
  60 store: ``stn{endian}_p(ptr, sz, val)``
  61
  62 which stores ``val`` to ``ptr`` as an ``{endian}`` order value
  63 of size ``sz`` bytes.
  64
  65
  66 Regexes 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
  76 These functions operate on a guest virtual address, plus a context
  77 known as a "mmu index" which controls how that virtual address is
  78 translated, plus a ``MemOp`` which contains alignment requirements
  79 among other things.  The ``MemOp`` and mmu index are combined into
  80 a single argument of type ``MemOpIdx``.
  81
  82 The meaning of the indexes are target specific, but specifying a
  83 particular index might be necessary if, for instance, the helper
  84 requires a "always as non-privileged" access rather than the
  85 default access for the current state of the guest CPU.
  86
  87 These functions may cause a guest CPU exception to be taken
  88 (e.g. for an alignment fault or MMU fault) which will result in
  89 guest CPU state being updated and control longjmp'ing out of the
  90 function call.  They should therefore only be used in code that is
  91 implementing emulation of the guest CPU.
  92
  93 The ``retaddr`` parameter is used to control unwinding of the
  94 guest CPU state in case of a guest CPU exception.  This is passed
  95 to ``cpu_restore_state()``.  Therefore the value should either be 0,
  96 to indicate that the guest CPU state is already synchronized, or
  97 the result of ``GETPC()`` from the top level ``HELPER(foo)``
  98 function, 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
 106 Function names follow the pattern:
 107
 108 load: ``cpu_ld{size}{end}_mmu(env, ptr, oi, retaddr)``
 109
 110 store: ``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
 123 Regexes 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
 131 These functions work like the ``cpu_{ld,st}_mmu`` functions except
 132 that the ``mmuidx`` parameter is not combined with a ``MemOp``,
 133 and therefore there is no required alignment supplied or enforced.
 134
 135 Function names follow the pattern:
 136
 137 load: ``cpu_ld{sign}{size}{end}_mmuidx_ra(env, ptr, mmuidx, retaddr)``
 138
 139 store: ``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
 157 Regexes 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
 164 These functions work like the ``cpu_{ld,st}_mmuidx_ra`` functions
 165 except that the ``mmuidx`` parameter is taken from the current mode
 166 of the guest CPU, as determined by ``cpu_mmu_index(env, false)``.
 167
 168 These are generally the preferred way to do accesses by guest
 169 virtual address from helper functions, unless the access should
 170 be performed with a context other than the default, or alignment
 171 should be enforced for the access.
 172
 173 Function names follow the pattern:
 174
 175 load: ``cpu_ld{sign}{size}{end}_data_ra(env, ptr, ra)``
 176
 177 store: ``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
 195 Regexes 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
 202 These functions work like the ``cpu_{ld,st}_data_ra`` functions
 203 except that the ``retaddr`` parameter is 0, and thus does not
 204 unwind guest CPU state.
 205
 206 This means they must only be used from helper functions where the
 207 translator has saved all necessary CPU state.  These functions are
 208 the right choice for calls made from hooks like the CPU ``do_interrupt``
 209 hook or when you know for certain that the translator had to save all
 210 the CPU state anyway.
 211
 212 Function names follow the pattern:
 213
 214 load: ``cpu_ld{sign}{size}{end}_data(env, ptr)``
 215
 216 store: ``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
 234 Regexes 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
 241 These functions perform a read for instruction execution.  The ``mmuidx``
 242 parameter is taken from the current mode of the guest CPU, as determined
 243 by ``cpu_mmu_index(env, true)``.  The ``retaddr`` parameter is 0, and
 244 thus does not unwind guest CPU state, because CPU state is always
 245 synchronized while translating instructions.  Any guest CPU exception
 246 that is raised will indicate an instruction execution fault rather than
 247 a data read fault.
 248
 249 In general these functions should not be used directly during translation.
 250 There are wrapper functions that are to be used which also take care of
 251 plugins for tracing.
 252
 253 Function names follow the pattern:
 254
 255 load: ``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
 268 Regexes for git grep:
 269  - ``\<cpu_ld[us]\?[bwlq]_code\>``
 270
 271 ``translator_ld*``
 272 ~~~~~~~~~~~~~~~~~~
 273
 274 These functions are a wrapper for ``cpu_ld*_code`` which also perform
 275 any actions required by any tracing plugins.  They are only to be
 276 called during the translator callback ``translate_insn``.
 277
 278 There is a set of functions ending in ``_swap`` which, if the parameter
 279 is true, returns the value in the endianness that is the reverse of
 280 the guest native endianness, as determined by ``TARGET_BIG_ENDIAN``.
 281
 282 Function names follow the pattern:
 283
 284 load: ``translator_ld{sign}{size}(env, ptr)``
 285
 286 swap: ``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
 299 Regexes for git grep:
 300  - ``\<translator_ld[us]\?[bwlq]\(_swap\)\?\>``
 301
 302 ``helper_{ld,st}*_mmu``
 303 ~~~~~~~~~~~~~~~~~~~~~~~~~
 304
 305 These functions are intended primarily to be called by the code
 306 generated by the TCG backend.  Like the ``cpu_{ld,st}_mmu`` functions
 307 they perform accesses by guest virtual address, with a given ``MemOpIdx``.
 308
 309 They differ from ``cpu_{ld,st}_mmu`` in that they take the endianness
 310 of the operation only from the MemOpIdx, and loads extend the return
 311 value to the size of a host general register (``tcg_target_ulong``).
 312
 313 load: ``helper_ld{sign}{size}_mmu(env, addr, opindex, retaddr)``
 314
 315 store: ``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
 328 Regexes for git grep:
 329  - ``\<helper_ld[us]\?[bwlq]_mmu\>``
 330  - ``\<helper_st[bwlq]_mmu\>``
 331
 332 ``address_space_*``
 333 ~~~~~~~~~~~~~~~~~~~
 334
 335 These functions are the primary ones to use when emulating CPU
 336 or device memory accesses. They take an AddressSpace, which is the
 337 way 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
 339 or bus fabric.)
 340
 341 Each CPU has an AddressSpace. Some kinds of CPU have more than
 342 one AddressSpace (for instance Arm guest CPUs have an AddressSpace
 343 for the Secure world and one for NonSecure if they implement TrustZone).
 344 Devices which can do DMA-type operations should generally have an
 345 AddressSpace. There is also a "system address space" which typically
 346 has all the devices and memory that all CPUs can see. (Some older
 347 device models use the "system address space" rather than properly
 348 modelling that they have an AddressSpace of their own.)
 349
 350 Functions are provided for doing byte-buffer reads and writes,
 351 and also for doing one-data-item loads and stores.
 352
 353 In all cases the caller provides a MemTxAttrs to specify bus
 354 transaction attributes, and can check whether the memory transaction
 355 succeeded 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
 383 The ``_{endian}`` suffix is omitted for byte accesses.
 384
 385 Regexes 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
 393 This function performs a write by physical address like
 394 ``address_space_write``, except that if the write is to a ROM then
 395 the ROM contents will be modified, even though a write by the guest
 396 CPU to the ROM would be ignored. This is used for non-guest writes
 397 like writes from the gdb debug stub or initial loading of ROM contents.
 398
 399 Note that portions of the write which attempt to write data to a
 400 device will be silently ignored -- only real RAM and ROM will
 401 be written to.
 402
 403 Regexes for git grep:
 404  - ``address_space_write_rom``
 405
 406 ``{ld,st}*_phys``
 407 ~~~~~~~~~~~~~~~~~
 408
 409 These 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
 412 whether the transaction succeeded or failed.
 413
 414 The fact that they ignore whether the transaction succeeded means
 415 they should not be used in new code, unless you know for certain
 416 that your code will only be used in a context where the CPU or
 417 device 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
 439 The ``_{endian}_`` infix is omitted for byte accesses.
 440
 441 Regexes for git grep:
 442  - ``\<ldu\?[bwlq]\(_[bl]e\)\?_phys\>``
 443  - ``\<st[bwlq]\(_[bl]e\)\?_phys\>``
 444
 445 ``cpu_physical_memory_*``
 446 ~~~~~~~~~~~~~~~~~~~~~~~~~
 447
 448 These are convenience functions which are identical to
 449 ``address_space_*`` but operate specifically on the system address space,
 450 always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and
 451 ignore whether the memory transaction succeeded or failed.
 452 For 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
 465 Regexes for git grep:
 466  - ``\<cpu_physical_memory_\(read\|write\|rw\)\>``
 467
 468 ``cpu_memory_rw_debug``
 469 ~~~~~~~~~~~~~~~~~~~~~~~
 470
 471 Access CPU memory by virtual address for debug purposes.
 472
 473 This function is intended for use by the GDB stub and similar code.
 474 It takes a virtual address, converts it to a physical address via
 475 an MMU lookup using the current settings of the specified CPU,
 476 and then performs the access (using ``address_space_rw`` for
 477 reads or ``cpu_physical_memory_write_rom`` for writes).
 478 This means that if the access is a write to a ROM then this
 479 function will modify the contents (whereas a normal guest CPU access
 480 would ignore the write attempt).
 481
 482 ``cpu_memory_rw_debug``
 483
 484 ``dma_memory_*``
 485 ~~~~~~~~~~~~~~~~
 486
 487 These behave like ``address_space_*``, except that they perform a DMA
 488 barrier operation first.
 489
 490 **TODO**: We should provide guidance on when you need the DMA
 491 barrier operation and when it's OK to use ``address_space_*``, and
 492 make sure our existing code is doing things correctly.
 493
 494 ``dma_memory_read``
 495
 496 ``dma_memory_write``
 497
 498 ``dma_memory_rw``
 499
 500 Regexes 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
 508 These functions are specifically for PCI device models which need to
 509 perform accesses where the PCI device is a bus master. You pass them a
 510 ``PCIDevice *`` and they will do ``dma_memory_*`` operations on the
 511 correct 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
 539 The ``_{endian}_`` infix is omitted for byte accesses.
 540
 541 Regexes for git grep:
 542  - ``\<pci_dma_\(read\|write\|rw\)\>``
 543  - ``\<ldu\?[bwlq]\(_[bl]e\)\?_pci_dma\>``
 544  - ``\<st[bwlq]\(_[bl]e\)\?_pci_dma\>``