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