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