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{type}{sign}{size}_{endian}_p(ptr)``
  28
  29 store: ``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
  51 The ``_{endian}`` infix is omitted for target-endian accesses.
  52
  53 The target endian accessors are only available to source
  54 files which are built per-target.
  55
  56 There are also functions which take the size as an argument:
  57
  58 load: ``ldn{endian}_p(ptr, sz)``
  59
  60 which performs an unsigned load of ``sz`` bytes from ``ptr``
  61 as an ``{endian}`` order value and returns it in a uint64_t.
  62
  63 store: ``stn{endian}_p(ptr, sz, val)``
  64
  65 which stores ``val`` to ``ptr`` as an ``{endian}`` order value
  66 of size ``sz`` bytes.
  67
  68
  69 Regexes 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
  78 These functions operate on a guest virtual address plus a context,
  79 known as a "mmu index" or ``mmuidx``, which controls how that virtual
  80 address is translated.  The meaning of the indexes are target specific,
  81 but specifying a particular index might be necessary if, for instance,
  82 the helper requires an "always as non-privileged" access rather that
  83 the 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.
  97
  98 Function names follow the pattern:
  99
 100 load: ``cpu_ld{sign}{size}{end}_mmuidx_ra(env, ptr, mmuidx, retaddr)``
 101
 102 store: ``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
 120 Regexes 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
 127 These functions work like the ``cpu_{ld,st}_mmuidx_ra`` functions
 128 except that the ``mmuidx`` parameter is taken from the current mode
 129 of the guest CPU, as determined by ``cpu_mmu_index(env, false)``.
 130
 131 These are generally the preferred way to do accesses by guest
 132 virtual address from helper functions, unless the access should
 133 be performed with a context other than the default.
 134
 135 Function names follow the pattern:
 136
 137 load: ``cpu_ld{sign}{size}{end}_data_ra(env, ptr, ra)``
 138
 139 store: ``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
 157 Regexes 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
 164 These functions work like the ``cpu_{ld,st}_data_ra`` functions
 165 except that the ``retaddr`` parameter is 0, and thus does not
 166 unwind guest CPU state.
 167
 168 This means they must only be used from helper functions where the
 169 translator has saved all necessary CPU state.  These functions are
 170 the right choice for calls made from hooks like the CPU ``do_interrupt``
 171 hook or when you know for certain that the translator had to save all
 172 the CPU state anyway.
 173
 174 Function names follow the pattern:
 175
 176 load: ``cpu_ld{sign}{size}{end}_data(env, ptr)``
 177
 178 store: ``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
 196 Regexes 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
 203 These functions perform a read for instruction execution.  The ``mmuidx``
 204 parameter is taken from the current mode of the guest CPU, as determined
 205 by ``cpu_mmu_index(env, true)``.  The ``retaddr`` parameter is 0, and
 206 thus does not unwind guest CPU state, because CPU state is always
 207 synchronized while translating instructions.  Any guest CPU exception
 208 that is raised will indicate an instruction execution fault rather than
 209 a data read fault.
 210
 211 In general these functions should not be used directly during translation.
 212 There are wrapper functions that are to be used which also take care of
 213 plugins for tracing.
 214
 215 Function names follow the pattern:
 216
 217 load: ``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
 230 Regexes for git grep:
 231  - ``\<cpu_ld[us]\?[bwlq]_code\>``
 232
 233 ``translator_ld*``
 234 ~~~~~~~~~~~~~~~~~~
 235
 236 These functions are a wrapper for ``cpu_ld*_code`` which also perform
 237 any actions required by any tracing plugins.  They are only to be
 238 called during the translator callback ``translate_insn``.
 239
 240 There is a set of functions ending in ``_swap`` which, if the parameter
 241 is true, returns the value in the endianness that is the reverse of
 242 the guest native endianness, as determined by ``TARGET_WORDS_BIGENDIAN``.
 243
 244 Function names follow the pattern:
 245
 246 load: ``translator_ld{sign}{size}(env, ptr)``
 247
 248 swap: ``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
 261 Regexes for git grep
 262  - ``\<translator_ld[us]\?[bwlq]\(_swap\)\?\>``
 263
 264 ``helper_*_{ld,st}*_mmu``
 265 ~~~~~~~~~~~~~~~~~~~~~~~~~
 266
 267 These functions are intended primarily to be called by the code
 268 generated by the TCG backend. They may also be called by target
 269 CPU helper function code. Like the ``cpu_{ld,st}_mmuidx_ra`` functions
 270 they perform accesses by guest virtual address, with a given ``mmuidx``.
 271
 272 These functions specify an ``opindex`` parameter which encodes
 273 (among other things) the mmu index to use for the access.  This parameter
 274 should be created by calling ``make_memop_idx()``.
 275
 276 The ``retaddr`` parameter should be the result of GETPC() called directly
 277 from the top level HELPER(foo) function (or 0 if no guest CPU state
 278 unwinding is required).
 279
 280 **TODO** The names of these functions are a bit odd for historical
 281 reasons because they were originally expected to be called only from
 282 within generated code. We should rename them to bring them more in
 283 line with the other memory access functions. The explicit endianness
 284 is the only feature they have beyond ``*_mmuidx_ra``.
 285
 286 load: ``helper_{endian}_ld{sign}{size}_mmu(env, addr, opindex, retaddr)``
 287
 288 store: ``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
 306 Regexes 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
 313 These functions are the primary ones to use when emulating CPU
 314 or device memory accesses. They take an AddressSpace, which is the
 315 way 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
 317 or bus fabric.)
 318
 319 Each CPU has an AddressSpace. Some kinds of CPU have more than
 320 one AddressSpace (for instance Arm guest CPUs have an AddressSpace
 321 for the Secure world and one for NonSecure if they implement TrustZone).
 322 Devices which can do DMA-type operations should generally have an
 323 AddressSpace. There is also a "system address space" which typically
 324 has all the devices and memory that all CPUs can see. (Some older
 325 device models use the "system address space" rather than properly
 326 modelling that they have an AddressSpace of their own.)
 327
 328 Functions are provided for doing byte-buffer reads and writes,
 329 and also for doing one-data-item loads and stores.
 330
 331 In all cases the caller provides a MemTxAttrs to specify bus
 332 transaction attributes, and can check whether the memory transaction
 333 succeeded 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
 361 The ``_{endian}`` suffix is omitted for byte accesses.
 362
 363 Regexes 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
 371 This function performs a write by physical address like
 372 ``address_space_write``, except that if the write is to a ROM then
 373 the ROM contents will be modified, even though a write by the guest
 374 CPU to the ROM would be ignored. This is used for non-guest writes
 375 like writes from the gdb debug stub or initial loading of ROM contents.
 376
 377 Note that portions of the write which attempt to write data to a
 378 device will be silently ignored -- only real RAM and ROM will
 379 be written to.
 380
 381 Regexes for git grep
 382  - ``address_space_write_rom``
 383
 384 ``{ld,st}*_phys``
 385 ~~~~~~~~~~~~~~~~~
 386
 387 These 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
 390 whether the transaction succeeded or failed.
 391
 392 The fact that they ignore whether the transaction succeeded means
 393 they should not be used in new code, unless you know for certain
 394 that your code will only be used in a context where the CPU or
 395 device 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
 417 The ``_{endian}_`` infix is omitted for byte accesses.
 418
 419 Regexes for git grep
 420  - ``\<ldu\?[bwlq]\(_[bl]e\)\?_phys\>``
 421  - ``\<st[bwlq]\(_[bl]e\)\?_phys\>``
 422
 423 ``cpu_physical_memory_*``
 424 ~~~~~~~~~~~~~~~~~~~~~~~~~
 425
 426 These are convenience functions which are identical to
 427 ``address_space_*`` but operate specifically on the system address space,
 428 always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and
 429 ignore whether the memory transaction succeeded or failed.
 430 For 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
 443 Regexes for git grep
 444  - ``\<cpu_physical_memory_\(read\|write\|rw\)\>``
 445
 446 ``cpu_memory_rw_debug``
 447 ~~~~~~~~~~~~~~~~~~~~~~~
 448
 449 Access CPU memory by virtual address for debug purposes.
 450
 451 This function is intended for use by the GDB stub and similar code.
 452 It takes a virtual address, converts it to a physical address via
 453 an MMU lookup using the current settings of the specified CPU,
 454 and then performs the access (using ``address_space_rw`` for
 455 reads or ``cpu_physical_memory_write_rom`` for writes).
 456 This means that if the access is a write to a ROM then this
 457 function will modify the contents (whereas a normal guest CPU access
 458 would ignore the write attempt).
 459
 460 ``cpu_memory_rw_debug``
 461
 462 ``dma_memory_*``
 463 ~~~~~~~~~~~~~~~~
 464
 465 These behave like ``address_space_*``, except that they perform a DMA
 466 barrier operation first.
 467
 468 **TODO**: We should provide guidance on when you need the DMA
 469 barrier operation and when it's OK to use ``address_space_*``, and
 470 make sure our existing code is doing things correctly.
 471
 472 ``dma_memory_read``
 473
 474 ``dma_memory_write``
 475
 476 ``dma_memory_rw``
 477
 478 Regexes for git grep
 479  - ``\<dma_memory_\(read\|write\|rw\)\>``
 480
 481 ``pci_dma_*`` and ``{ld,st}*_pci_dma``
 482 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 483
 484 These functions are specifically for PCI device models which need to
 485 perform accesses where the PCI device is a bus master. You pass them a
 486 ``PCIDevice *`` and they will do ``dma_memory_*`` operations on the
 487 correct 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
 515 The ``_{endian}_`` infix is omitted for byte accesses.
 516
 517 Regexes for git grep
 518  - ``\<pci_dma_\(read\|write\|rw\)\>``
 519  - ``\<ldu\?[bwlq]\(_[bl]e\)\?_pci_dma\>``
 520  - ``\<st[bwlq]\(_[bl]e\)\?_pci_dma\>``