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