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 ``{ld,st}*_phys``
 257 ~~~~~~~~~~~~~~~~~
 258
 259 These are functions which are identical to
 260 ``address_space_{ld,st}*``, except that they always pass
 261 ``MEMTXATTRS_UNSPECIFIED`` for the transaction attributes, and ignore
 262 whether the transaction succeeded or failed.
 263
 264 The fact that they ignore whether the transaction succeeded means
 265 they should not be used in new code, unless you know for certain
 266 that your code will only be used in a context where the CPU or
 267 device doing the access has no way to report such an error.
 268
 269 ``load: ld{sign}{size}_{endian}_phys``
 270
 271 ``store: st{size}_{endian}_phys``
 272
 273 ``sign``
 274  - (empty) : for 32 or 64 bit sizes
 275  - ``u`` : unsigned
 276
 277 (No signed load operations are provided.)
 278
 279 ``size``
 280  - ``b`` : 8 bits
 281  - ``w`` : 16 bits
 282  - ``l`` : 32 bits
 283  - ``q`` : 64 bits
 284
 285 ``endian``
 286  - ``le`` : little endian
 287  - ``be`` : big endian
 288
 289 The ``_{endian}_`` infix is omitted for byte accesses.
 290
 291 Regexes for git grep
 292  - ``\<ldu\?[bwlq]\(_[bl]e\)\?_phys\>``
 293  - ``\<st[bwlq]\(_[bl]e\)\?_phys\>``
 294
 295 ``cpu_physical_memory_*``
 296 ~~~~~~~~~~~~~~~~~~~~~~~~~
 297
 298 These are convenience functions which are identical to
 299 ``address_space_*`` but operate specifically on the system address space,
 300 always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and
 301 ignore whether the memory transaction succeeded or failed.
 302 For new code they are better avoided:
 303
 304 * there is likely to be behaviour you need to model correctly for a
 305   failed read or write operation
 306 * a device should usually perform operations on its own AddressSpace
 307   rather than using the system address space
 308
 309 ``cpu_physical_memory_read``
 310
 311 ``cpu_physical_memory_write``
 312
 313 ``cpu_physical_memory_rw``
 314
 315 Regexes for git grep
 316  - ``\<cpu_physical_memory_\(read\|write\|rw\)\>``
 317
 318 ``cpu_physical_memory_write_rom``
 319 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 320
 321 This function performs a write by physical address like
 322 ``address_space_write``, except that if the write is to a ROM then
 323 the ROM contents will be modified, even though a write by the guest
 324 CPU to the ROM would be ignored.
 325
 326 Note that unlike ``cpu_physical_memory_write()`` this function takes
 327 an AddressSpace argument, but unlike ``address_space_write()`` this
 328 function does not take a ``MemTxAttrs`` or return a ``MemTxResult``.
 329
 330 **TODO**: we should probably clean up this inconsistency and
 331 turn the function into ``address_space_write_rom`` with an API
 332 matching ``address_space_write``.
 333
 334 ``cpu_physical_memory_write_rom``
 335
 336
 337 ``cpu_memory_rw_debug``
 338 ~~~~~~~~~~~~~~~~~~~~~~~
 339
 340 Access CPU memory by virtual address for debug purposes.
 341
 342 This function is intended for use by the GDB stub and similar code.
 343 It takes a virtual address, converts it to a physical address via
 344 an MMU lookup using the current settings of the specified CPU,
 345 and then performs the access (using ``address_space_rw`` for
 346 reads or ``cpu_physical_memory_write_rom`` for writes).
 347 This means that if the access is a write to a ROM then this
 348 function will modify the contents (whereas a normal guest CPU access
 349 would ignore the write attempt).
 350
 351 ``cpu_memory_rw_debug``
 352
 353 ``dma_memory_*``
 354 ~~~~~~~~~~~~~~~~
 355
 356 These behave like ``address_space_*``, except that they perform a DMA
 357 barrier operation first.
 358
 359 **TODO**: We should provide guidance on when you need the DMA
 360 barrier operation and when it's OK to use ``address_space_*``, and
 361 make sure our existing code is doing things correctly.
 362
 363 ``dma_memory_read``
 364
 365 ``dma_memory_write``
 366
 367 ``dma_memory_rw``
 368
 369 Regexes for git grep
 370  - ``\<dma_memory_\(read\|write\|rw\)\>``
 371
 372 ``pci_dma_*`` and ``{ld,st}*_pci_dma``
 373 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 374
 375 These functions are specifically for PCI device models which need to
 376 perform accesses where the PCI device is a bus master. You pass them a
 377 ``PCIDevice *`` and they will do ``dma_memory_*`` operations on the
 378 correct address space for that device.
 379
 380 ``pci_dma_read``
 381
 382 ``pci_dma_write``
 383
 384 ``pci_dma_rw``
 385
 386 ``load: ld{sign}{size}_{endian}_pci_dma``
 387
 388 ``store: st{size}_{endian}_pci_dma``
 389
 390 ``sign``
 391  - (empty) : for 32 or 64 bit sizes
 392  - ``u`` : unsigned
 393
 394 (No signed load operations are provided.)
 395
 396 ``size``
 397  - ``b`` : 8 bits
 398  - ``w`` : 16 bits
 399  - ``l`` : 32 bits
 400  - ``q`` : 64 bits
 401
 402 ``endian``
 403  - ``le`` : little endian
 404  - ``be`` : big endian
 405
 406 The ``_{endian}_`` infix is omitted for byte accesses.
 407
 408 Regexes for git grep
 409  - ``\<pci_dma_\(read\|write\|rw\)\>``
 410  - ``\<ldu\?[bwlq]\(_[bl]e\)\?_pci_dma\>``
 411  - ``\<st[bwlq]\(_[bl]e\)\?_pci_dma\>``