1.. 2 Copyright (c) 2017 Linaro Limited 3 Written by Peter Maydell 4 5=================== 6Load and Store APIs 7=================== 8 9QEMU internally has multiple families of functions for performing 10loads and stores. This document attempts to enumerate them all 11and indicate when to use them. It does not provide detailed 12documentation of each API -- for that you should look at the 13documentation comments in the relevant header files. 14 15 16``ld*_p and st*_p`` 17~~~~~~~~~~~~~~~~~~~ 18 19These functions operate on a host pointer, and should be used 20when you already have a pointer into host memory (corresponding 21to guest ram or a local buffer). They deal with doing accesses 22with the desired endianness and with correctly handling 23potentially unaligned pointer values. 24 25Function names follow the pattern: 26 27load: ``ld{sign}{size}_{endian}_p(ptr)`` 28 29store: ``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 47The ``_{endian}`` infix is omitted for target-endian accesses. 48 49The target endian accessors are only available to source 50files which are built per-target. 51 52There are also functions which take the size as an argument: 53 54load: ``ldn{endian}_p(ptr, sz)`` 55 56which performs an unsigned load of ``sz`` bytes from ``ptr`` 57as an ``{endian}`` order value and returns it in a uint64_t. 58 59store: ``stn{endian}_p(ptr, sz, val)`` 60 61which stores ``val`` to ``ptr`` as an ``{endian}`` order value 62of size ``sz`` bytes. 63 64 65Regexes 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 74These functions operate on a guest virtual address, plus a context 75known as a "mmu index" which controls how that virtual address is 76translated, plus a ``MemOp`` which contains alignment requirements 77among other things. The ``MemOp`` and mmu index are combined into 78a single argument of type ``MemOpIdx``. 79 80The meaning of the indexes are target specific, but specifying a 81particular index might be necessary if, for instance, the helper 82requires a "always as non-privileged" access rather than the 83default access for the current state of the guest CPU. 84 85These functions may cause a guest CPU exception to be taken 86(e.g. for an alignment fault or MMU fault) which will result in 87guest CPU state being updated and control longjmp'ing out of the 88function call. They should therefore only be used in code that is 89implementing emulation of the guest CPU. 90 91The ``retaddr`` parameter is used to control unwinding of the 92guest CPU state in case of a guest CPU exception. This is passed 93to ``cpu_restore_state()``. Therefore the value should either be 0, 94to indicate that the guest CPU state is already synchronized, or 95the result of ``GETPC()`` from the top level ``HELPER(foo)`` 96function, 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 104Function names follow the pattern: 105 106load: ``cpu_ld{size}{end}_mmu(env, ptr, oi, retaddr)`` 107 108store: ``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 121Regexes 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 129These functions work like the ``cpu_{ld,st}_mmu`` functions except 130that the ``mmuidx`` parameter is not combined with a ``MemOp``, 131and therefore there is no required alignment supplied or enforced. 132 133Function names follow the pattern: 134 135load: ``cpu_ld{sign}{size}{end}_mmuidx_ra(env, ptr, mmuidx, retaddr)`` 136 137store: ``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 155Regexes 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 162These functions work like the ``cpu_{ld,st}_mmuidx_ra`` functions 163except that the ``mmuidx`` parameter is taken from the current mode 164of the guest CPU, as determined by ``cpu_mmu_index(env, false)``. 165 166These are generally the preferred way to do accesses by guest 167virtual address from helper functions, unless the access should 168be performed with a context other than the default, or alignment 169should be enforced for the access. 170 171Function names follow the pattern: 172 173load: ``cpu_ld{sign}{size}{end}_data_ra(env, ptr, ra)`` 174 175store: ``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 193Regexes 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 200These functions work like the ``cpu_{ld,st}_data_ra`` functions 201except that the ``retaddr`` parameter is 0, and thus does not 202unwind guest CPU state. 203 204This means they must only be used from helper functions where the 205translator has saved all necessary CPU state. These functions are 206the right choice for calls made from hooks like the CPU ``do_interrupt`` 207hook or when you know for certain that the translator had to save all 208the CPU state anyway. 209 210Function names follow the pattern: 211 212load: ``cpu_ld{sign}{size}{end}_data(env, ptr)`` 213 214store: ``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 232Regexes 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 239These functions perform a read for instruction execution. The ``mmuidx`` 240parameter is taken from the current mode of the guest CPU, as determined 241by ``cpu_mmu_index(env, true)``. The ``retaddr`` parameter is 0, and 242thus does not unwind guest CPU state, because CPU state is always 243synchronized while translating instructions. Any guest CPU exception 244that is raised will indicate an instruction execution fault rather than 245a data read fault. 246 247In general these functions should not be used directly during translation. 248There are wrapper functions that are to be used which also take care of 249plugins for tracing. 250 251Function names follow the pattern: 252 253load: ``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 266Regexes for git grep: 267 - ``\<cpu_ld[us]\?[bwlq]_code\>`` 268 269``translator_ld*`` 270~~~~~~~~~~~~~~~~~~ 271 272These functions are a wrapper for ``cpu_ld*_code`` which also perform 273any actions required by any tracing plugins. They are only to be 274called during the translator callback ``translate_insn``. 275 276There is a set of functions ending in ``_swap`` which, if the parameter 277is true, returns the value in the endianness that is the reverse of 278the guest native endianness, as determined by ``TARGET_BIG_ENDIAN``. 279 280Function names follow the pattern: 281 282load: ``translator_ld{sign}{size}(env, ptr)`` 283 284swap: ``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 297Regexes for git grep 298 - ``\<translator_ld[us]\?[bwlq]\(_swap\)\?\>`` 299 300``helper_{ld,st}*_mmu`` 301~~~~~~~~~~~~~~~~~~~~~~~~~ 302 303These functions are intended primarily to be called by the code 304generated by the TCG backend. Like the ``cpu_{ld,st}_mmu`` functions 305they perform accesses by guest virtual address, with a given ``MemOpIdx``. 306 307They differ from ``cpu_{ld,st}_mmu`` in that they take the endianness 308of the operation only from the MemOpIdx, and loads extend the return 309value to the size of a host general register (``tcg_target_ulong``). 310 311load: ``helper_ld{sign}{size}_mmu(env, addr, opindex, retaddr)`` 312 313store: ``helper_{size}_mmu(env, addr, val, opindex, retaddr)`` 314 315``sign`` 316 - (empty) : for 32 or 64 bit sizes 317 - ``u`` : unsigned 318 - ``s`` : signed 319 320``size`` 321 - ``b`` : 8 bits 322 - ``w`` : 16 bits 323 - ``l`` : 32 bits 324 - ``q`` : 64 bits 325 326Regexes for git grep 327 - ``\<helper_ld[us]\?[bwlq]_mmu\>`` 328 - ``\<helper_st[bwlq]_mmu\>`` 329 330``address_space_*`` 331~~~~~~~~~~~~~~~~~~~ 332 333These functions are the primary ones to use when emulating CPU 334or device memory accesses. They take an AddressSpace, which is the 335way QEMU defines the view of memory that a device or CPU has. 336(They generally correspond to being the "master" end of a hardware bus 337or bus fabric.) 338 339Each CPU has an AddressSpace. Some kinds of CPU have more than 340one AddressSpace (for instance Arm guest CPUs have an AddressSpace 341for the Secure world and one for NonSecure if they implement TrustZone). 342Devices which can do DMA-type operations should generally have an 343AddressSpace. There is also a "system address space" which typically 344has all the devices and memory that all CPUs can see. (Some older 345device models use the "system address space" rather than properly 346modelling that they have an AddressSpace of their own.) 347 348Functions are provided for doing byte-buffer reads and writes, 349and also for doing one-data-item loads and stores. 350 351In all cases the caller provides a MemTxAttrs to specify bus 352transaction attributes, and can check whether the memory transaction 353succeeded using a MemTxResult return code. 354 355``address_space_read(address_space, addr, attrs, buf, len)`` 356 357``address_space_write(address_space, addr, attrs, buf, len)`` 358 359``address_space_rw(address_space, addr, attrs, buf, len, is_write)`` 360 361``address_space_ld{sign}{size}_{endian}(address_space, addr, attrs, txresult)`` 362 363``address_space_st{size}_{endian}(address_space, addr, val, attrs, txresult)`` 364 365``sign`` 366 - (empty) : for 32 or 64 bit sizes 367 - ``u`` : unsigned 368 369(No signed load operations are provided.) 370 371``size`` 372 - ``b`` : 8 bits 373 - ``w`` : 16 bits 374 - ``l`` : 32 bits 375 - ``q`` : 64 bits 376 377``endian`` 378 - ``le`` : little endian 379 - ``be`` : big endian 380 381The ``_{endian}`` suffix is omitted for byte accesses. 382 383Regexes for git grep 384 - ``\<address_space_\(read\|write\|rw\)\>`` 385 - ``\<address_space_ldu\?[bwql]\(_[lb]e\)\?\>`` 386 - ``\<address_space_st[bwql]\(_[lb]e\)\?\>`` 387 388``address_space_write_rom`` 389~~~~~~~~~~~~~~~~~~~~~~~~~~~ 390 391This function performs a write by physical address like 392``address_space_write``, except that if the write is to a ROM then 393the ROM contents will be modified, even though a write by the guest 394CPU to the ROM would be ignored. This is used for non-guest writes 395like writes from the gdb debug stub or initial loading of ROM contents. 396 397Note that portions of the write which attempt to write data to a 398device will be silently ignored -- only real RAM and ROM will 399be written to. 400 401Regexes for git grep 402 - ``address_space_write_rom`` 403 404``{ld,st}*_phys`` 405~~~~~~~~~~~~~~~~~ 406 407These are functions which are identical to 408``address_space_{ld,st}*``, except that they always pass 409``MEMTXATTRS_UNSPECIFIED`` for the transaction attributes, and ignore 410whether the transaction succeeded or failed. 411 412The fact that they ignore whether the transaction succeeded means 413they should not be used in new code, unless you know for certain 414that your code will only be used in a context where the CPU or 415device doing the access has no way to report such an error. 416 417``load: ld{sign}{size}_{endian}_phys`` 418 419``store: st{size}_{endian}_phys`` 420 421``sign`` 422 - (empty) : for 32 or 64 bit sizes 423 - ``u`` : unsigned 424 425(No signed load operations are provided.) 426 427``size`` 428 - ``b`` : 8 bits 429 - ``w`` : 16 bits 430 - ``l`` : 32 bits 431 - ``q`` : 64 bits 432 433``endian`` 434 - ``le`` : little endian 435 - ``be`` : big endian 436 437The ``_{endian}_`` infix is omitted for byte accesses. 438 439Regexes for git grep 440 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_phys\>`` 441 - ``\<st[bwlq]\(_[bl]e\)\?_phys\>`` 442 443``cpu_physical_memory_*`` 444~~~~~~~~~~~~~~~~~~~~~~~~~ 445 446These are convenience functions which are identical to 447``address_space_*`` but operate specifically on the system address space, 448always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and 449ignore whether the memory transaction succeeded or failed. 450For new code they are better avoided: 451 452* there is likely to be behaviour you need to model correctly for a 453 failed read or write operation 454* a device should usually perform operations on its own AddressSpace 455 rather than using the system address space 456 457``cpu_physical_memory_read`` 458 459``cpu_physical_memory_write`` 460 461``cpu_physical_memory_rw`` 462 463Regexes for git grep 464 - ``\<cpu_physical_memory_\(read\|write\|rw\)\>`` 465 466``cpu_memory_rw_debug`` 467~~~~~~~~~~~~~~~~~~~~~~~ 468 469Access CPU memory by virtual address for debug purposes. 470 471This function is intended for use by the GDB stub and similar code. 472It takes a virtual address, converts it to a physical address via 473an MMU lookup using the current settings of the specified CPU, 474and then performs the access (using ``address_space_rw`` for 475reads or ``cpu_physical_memory_write_rom`` for writes). 476This means that if the access is a write to a ROM then this 477function will modify the contents (whereas a normal guest CPU access 478would ignore the write attempt). 479 480``cpu_memory_rw_debug`` 481 482``dma_memory_*`` 483~~~~~~~~~~~~~~~~ 484 485These behave like ``address_space_*``, except that they perform a DMA 486barrier operation first. 487 488**TODO**: We should provide guidance on when you need the DMA 489barrier operation and when it's OK to use ``address_space_*``, and 490make sure our existing code is doing things correctly. 491 492``dma_memory_read`` 493 494``dma_memory_write`` 495 496``dma_memory_rw`` 497 498Regexes for git grep 499 - ``\<dma_memory_\(read\|write\|rw\)\>`` 500 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_dma\>`` 501 - ``\<st[bwlq]\(_[bl]e\)\?_dma\>`` 502 503``pci_dma_*`` and ``{ld,st}*_pci_dma`` 504~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 505 506These functions are specifically for PCI device models which need to 507perform accesses where the PCI device is a bus master. You pass them a 508``PCIDevice *`` and they will do ``dma_memory_*`` operations on the 509correct address space for that device. 510 511``pci_dma_read`` 512 513``pci_dma_write`` 514 515``pci_dma_rw`` 516 517``load: ld{sign}{size}_{endian}_pci_dma`` 518 519``store: st{size}_{endian}_pci_dma`` 520 521``sign`` 522 - (empty) : for 32 or 64 bit sizes 523 - ``u`` : unsigned 524 525(No signed load operations are provided.) 526 527``size`` 528 - ``b`` : 8 bits 529 - ``w`` : 16 bits 530 - ``l`` : 32 bits 531 - ``q`` : 64 bits 532 533``endian`` 534 - ``le`` : little endian 535 - ``be`` : big endian 536 537The ``_{endian}_`` infix is omitted for byte accesses. 538 539Regexes for git grep 540 - ``\<pci_dma_\(read\|write\|rw\)\>`` 541 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_pci_dma\>`` 542 - ``\<st[bwlq]\(_[bl]e\)\?_pci_dma\>`` 543