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