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}_*``
  76 ~~~~~~~~~~~~~~~~~
  77
  78 These functions operate on a guest virtual address. Be aware
  79 that these functions may cause a guest CPU exception to be
  80 taken (e.g. for an alignment fault or MMU fault) which will
  81 result in guest CPU state being updated and control longjumping
  82 out of the function call. They should therefore only be used
  83 in code that is implementing emulation of the target CPU.
  84
  85 These functions may throw an exception (longjmp() back out
  86 to the top level TCG loop). This means they must only be used
  87 from helper functions where the translator has saved all
  88 necessary CPU state before generating the helper function call.
  89 It's usually better to use the ``_ra`` variants described below
  90 from helper functions, but these functions are the right choice
  91 for calls made from hooks like the CPU do_interrupt hook or
  92 when you know for certain that the translator had to save all
  93 the CPU state that ``cpu_restore_state()`` would restore anyway.
  94
  95 Function names follow the pattern:
  96
  97 load: ``cpu_ld{sign}{size}_{mmusuffix}(env, ptr)``
  98
  99 store: ``cpu_st{size}_{mmusuffix}(env, ptr, val)``
 100
 101 ``sign``
 102  - (empty) : for 32 or 64 bit sizes
 103  - ``u`` : unsigned
 104  - ``s`` : signed
 105
 106 ``size``
 107  - ``b`` : 8 bits
 108  - ``w`` : 16 bits
 109  - ``l`` : 32 bits
 110  - ``q`` : 64 bits
 111
 112 ``mmusuffix`` is one of the generic suffixes ``data`` or ``code``, or
 113 (for softmmu configs) a target-specific MMU mode suffix as defined
 114 in the target's ``cpu.h``.
 115
 116 Regexes for git grep
 117  - ``\<cpu_ld[us]\?[bwlq]_[a-zA-Z0-9]\+\>``
 118  - ``\<cpu_st[bwlq]_[a-zA-Z0-9]\+\>``
 119
 120 ``cpu_{ld,st}_*_ra``
 121 ~~~~~~~~~~~~~~~~~~~~
 122
 123 These functions work like the ``cpu_{ld,st}_*`` functions except
 124 that they also take a ``retaddr`` argument. This extra argument
 125 allows for correct unwinding of any exception that is taken,
 126 and should generally be the result of GETPC() called directly
 127 from the top level HELPER(foo) function (i.e. the return address
 128 in the generated code).
 129
 130 These are generally the preferred way to do accesses by guest
 131 virtual address from helper functions; see the documentation
 132 of the non-``_ra`` variants for when those would be better.
 133
 134 Calling these functions with a ``retaddr`` argument of 0 is
 135 equivalent to calling the non-``_ra`` version of the function.
 136
 137 Function names follow the pattern:
 138
 139 load: ``cpu_ld{sign}{size}_{mmusuffix}_ra(env, ptr, retaddr)``
 140
 141 store: ``cpu_st{sign}{size}_{mmusuffix}_ra(env, ptr, val, retaddr)``
 142
 143 Regexes for git grep
 144  - ``\<cpu_ld[us]\?[bwlq]_[a-zA-Z0-9]\+_ra\>``
 145  - ``\<cpu_st[bwlq]_[a-zA-Z0-9]\+_ra\>``
 146
 147 ``helper_*_{ld,st}*mmu``
 148 ~~~~~~~~~~~~~~~~~~~~~~~~
 149
 150 These functions are intended primarily to be called by the code
 151 generated by the TCG backend. They may also be called by target
 152 CPU helper function code. Like the ``cpu_{ld,st}_*_ra`` functions
 153 they perform accesses by guest virtual address; the difference is
 154 that these functions allow you to specify an ``opindex`` parameter
 155 which encodes (among other things) the mmu index to use for the
 156 access. This is necessary if your helper needs to make an access
 157 via a specific mmu index (for instance, an "always as non-privileged"
 158 access) rather than using the default mmu index for the current state
 159 of the guest CPU.
 160
 161 The ``opindex`` parameter should be created by calling ``make_memop_idx()``.
 162
 163 The ``retaddr`` parameter should be the result of GETPC() called directly
 164 from the top level HELPER(foo) function (or 0 if no guest CPU state
 165 unwinding is required).
 166
 167 **TODO** The names of these functions are a bit odd for historical
 168 reasons because they were originally expected to be called only from
 169 within generated code. We should rename them to bring them
 170 more in line with the other memory access functions.
 171
 172 load: ``helper_{endian}_ld{sign}{size}_mmu(env, addr, opindex, retaddr)``
 173
 174 load (code): ``helper_{endian}_ld{sign}{size}_cmmu(env, addr, opindex, retaddr)``
 175
 176 store: ``helper_{endian}_st{size}_mmu(env, addr, val, opindex, retaddr)``
 177
 178 ``sign``
 179  - (empty) : for 32 or 64 bit sizes
 180  - ``u`` : unsigned
 181  - ``s`` : signed
 182
 183 ``size``
 184  - ``b`` : 8 bits
 185  - ``w`` : 16 bits
 186  - ``l`` : 32 bits
 187  - ``q`` : 64 bits
 188
 189 ``endian``
 190  - ``le`` : little endian
 191  - ``be`` : big endian
 192  - ``ret`` : target endianness
 193
 194 Regexes for git grep
 195  - ``\<helper_\(le\|be\|ret\)_ld[us]\?[bwlq]_c\?mmu\>``
 196  - ``\<helper_\(le\|be\|ret\)_st[bwlq]_mmu\>``
 197
 198 ``address_space_*``
 199 ~~~~~~~~~~~~~~~~~~~
 200
 201 These functions are the primary ones to use when emulating CPU
 202 or device memory accesses. They take an AddressSpace, which is the
 203 way QEMU defines the view of memory that a device or CPU has.
 204 (They generally correspond to being the "master" end of a hardware bus
 205 or bus fabric.)
 206
 207 Each CPU has an AddressSpace. Some kinds of CPU have more than
 208 one AddressSpace (for instance ARM guest CPUs have an AddressSpace
 209 for the Secure world and one for NonSecure if they implement TrustZone).
 210 Devices which can do DMA-type operations should generally have an
 211 AddressSpace. There is also a "system address space" which typically
 212 has all the devices and memory that all CPUs can see. (Some older
 213 device models use the "system address space" rather than properly
 214 modelling that they have an AddressSpace of their own.)
 215
 216 Functions are provided for doing byte-buffer reads and writes,
 217 and also for doing one-data-item loads and stores.
 218
 219 In all cases the caller provides a MemTxAttrs to specify bus
 220 transaction attributes, and can check whether the memory transaction
 221 succeeded using a MemTxResult return code.
 222
 223 ``address_space_read(address_space, addr, attrs, buf, len)``
 224
 225 ``address_space_write(address_space, addr, attrs, buf, len)``
 226
 227 ``address_space_rw(address_space, addr, attrs, buf, len, is_write)``
 228
 229 ``address_space_ld{sign}{size}_{endian}(address_space, addr, attrs, txresult)``
 230
 231 ``address_space_st{size}_{endian}(address_space, addr, val, attrs, txresult)``
 232
 233 ``sign``
 234  - (empty) : for 32 or 64 bit sizes
 235  - ``u`` : unsigned
 236
 237 (No signed load operations are provided.)
 238
 239 ``size``
 240  - ``b`` : 8 bits
 241  - ``w`` : 16 bits
 242  - ``l`` : 32 bits
 243  - ``q`` : 64 bits
 244
 245 ``endian``
 246  - ``le`` : little endian
 247  - ``be`` : big endian
 248
 249 The ``_{endian}`` suffix is omitted for byte accesses.
 250
 251 Regexes for git grep
 252  - ``\<address_space_\(read\|write\|rw\)\>``
 253  - ``\<address_space_ldu\?[bwql]\(_[lb]e\)\?\>``
 254  - ``\<address_space_st[bwql]\(_[lb]e\)\?\>``
 255
 256 ``address_space_write_rom``
 257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 258
 259 This function performs a write by physical address like
 260 ``address_space_write``, except that if the write is to a ROM then
 261 the ROM contents will be modified, even though a write by the guest
 262 CPU to the ROM would be ignored. This is used for non-guest writes
 263 like writes from the gdb debug stub or initial loading of ROM contents.
 264
 265 Note that portions of the write which attempt to write data to a
 266 device will be silently ignored -- only real RAM and ROM will
 267 be written to.
 268
 269 Regexes for git grep
 270  - ``address_space_write_rom``
 271
 272 ``{ld,st}*_phys``
 273 ~~~~~~~~~~~~~~~~~
 274
 275 These are functions which are identical to
 276 ``address_space_{ld,st}*``, except that they always pass
 277 ``MEMTXATTRS_UNSPECIFIED`` for the transaction attributes, and ignore
 278 whether the transaction succeeded or failed.
 279
 280 The fact that they ignore whether the transaction succeeded means
 281 they should not be used in new code, unless you know for certain
 282 that your code will only be used in a context where the CPU or
 283 device doing the access has no way to report such an error.
 284
 285 ``load: ld{sign}{size}_{endian}_phys``
 286
 287 ``store: st{size}_{endian}_phys``
 288
 289 ``sign``
 290  - (empty) : for 32 or 64 bit sizes
 291  - ``u`` : unsigned
 292
 293 (No signed load operations are provided.)
 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
 305 The ``_{endian}_`` infix is omitted for byte accesses.
 306
 307 Regexes for git grep
 308  - ``\<ldu\?[bwlq]\(_[bl]e\)\?_phys\>``
 309  - ``\<st[bwlq]\(_[bl]e\)\?_phys\>``
 310
 311 ``cpu_physical_memory_*``
 312 ~~~~~~~~~~~~~~~~~~~~~~~~~
 313
 314 These are convenience functions which are identical to
 315 ``address_space_*`` but operate specifically on the system address space,
 316 always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and
 317 ignore whether the memory transaction succeeded or failed.
 318 For new code they are better avoided:
 319
 320 * there is likely to be behaviour you need to model correctly for a
 321   failed read or write operation
 322 * a device should usually perform operations on its own AddressSpace
 323   rather than using the system address space
 324
 325 ``cpu_physical_memory_read``
 326
 327 ``cpu_physical_memory_write``
 328
 329 ``cpu_physical_memory_rw``
 330
 331 Regexes for git grep
 332  - ``\<cpu_physical_memory_\(read\|write\|rw\)\>``
 333
 334 ``cpu_memory_rw_debug``
 335 ~~~~~~~~~~~~~~~~~~~~~~~
 336
 337 Access CPU memory by virtual address for debug purposes.
 338
 339 This function is intended for use by the GDB stub and similar code.
 340 It takes a virtual address, converts it to a physical address via
 341 an MMU lookup using the current settings of the specified CPU,
 342 and then performs the access (using ``address_space_rw`` for
 343 reads or ``cpu_physical_memory_write_rom`` for writes).
 344 This means that if the access is a write to a ROM then this
 345 function will modify the contents (whereas a normal guest CPU access
 346 would ignore the write attempt).
 347
 348 ``cpu_memory_rw_debug``
 349
 350 ``dma_memory_*``
 351 ~~~~~~~~~~~~~~~~
 352
 353 These behave like ``address_space_*``, except that they perform a DMA
 354 barrier operation first.
 355
 356 **TODO**: We should provide guidance on when you need the DMA
 357 barrier operation and when it's OK to use ``address_space_*``, and
 358 make sure our existing code is doing things correctly.
 359
 360 ``dma_memory_read``
 361
 362 ``dma_memory_write``
 363
 364 ``dma_memory_rw``
 365
 366 Regexes for git grep
 367  - ``\<dma_memory_\(read\|write\|rw\)\>``
 368
 369 ``pci_dma_*`` and ``{ld,st}*_pci_dma``
 370 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 371
 372 These functions are specifically for PCI device models which need to
 373 perform accesses where the PCI device is a bus master. You pass them a
 374 ``PCIDevice *`` and they will do ``dma_memory_*`` operations on the
 375 correct address space for that device.
 376
 377 ``pci_dma_read``
 378
 379 ``pci_dma_write``
 380
 381 ``pci_dma_rw``
 382
 383 ``load: ld{sign}{size}_{endian}_pci_dma``
 384
 385 ``store: st{size}_{endian}_pci_dma``
 386
 387 ``sign``
 388  - (empty) : for 32 or 64 bit sizes
 389  - ``u`` : unsigned
 390
 391 (No signed load operations are provided.)
 392
 393 ``size``
 394  - ``b`` : 8 bits
 395  - ``w`` : 16 bits
 396  - ``l`` : 32 bits
 397  - ``q`` : 64 bits
 398
 399 ``endian``
 400  - ``le`` : little endian
 401  - ``be`` : big endian
 402
 403 The ``_{endian}_`` infix is omitted for byte accesses.
 404
 405 Regexes for git grep
 406  - ``\<pci_dma_\(read\|write\|rw\)\>``
 407  - ``\<ldu\?[bwlq]\(_[bl]e\)\?_pci_dma\>``
 408  - ``\<st[bwlq]\(_[bl]e\)\?_pci_dma\>``