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_WORDS_BIGENDIAN``. 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. They may also be called by target 305CPU helper function code. Like the ``cpu_{ld,st}_mmuidx_ra`` functions 306they perform accesses by guest virtual address, with a given ``mmuidx``. 307 308These functions specify an ``opindex`` parameter which encodes 309(among other things) the mmu index to use for the access. This parameter 310should be created by calling ``make_memop_idx()``. 311 312The ``retaddr`` parameter should be the result of GETPC() called directly 313from the top level HELPER(foo) function (or 0 if no guest CPU state 314unwinding is required). 315 316**TODO** The names of these functions are a bit odd for historical 317reasons because they were originally expected to be called only from 318within generated code. We should rename them to bring them more in 319line with the other memory access functions. The explicit endianness 320is the only feature they have beyond ``*_mmuidx_ra``. 321 322load: ``helper_{endian}_ld{sign}{size}_mmu(env, addr, opindex, retaddr)`` 323 324store: ``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 342Regexes 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 349These functions are the primary ones to use when emulating CPU 350or device memory accesses. They take an AddressSpace, which is the 351way 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 353or bus fabric.) 354 355Each CPU has an AddressSpace. Some kinds of CPU have more than 356one AddressSpace (for instance Arm guest CPUs have an AddressSpace 357for the Secure world and one for NonSecure if they implement TrustZone). 358Devices which can do DMA-type operations should generally have an 359AddressSpace. There is also a "system address space" which typically 360has all the devices and memory that all CPUs can see. (Some older 361device models use the "system address space" rather than properly 362modelling that they have an AddressSpace of their own.) 363 364Functions are provided for doing byte-buffer reads and writes, 365and also for doing one-data-item loads and stores. 366 367In all cases the caller provides a MemTxAttrs to specify bus 368transaction attributes, and can check whether the memory transaction 369succeeded 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 397The ``_{endian}`` suffix is omitted for byte accesses. 398 399Regexes 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 407This function performs a write by physical address like 408``address_space_write``, except that if the write is to a ROM then 409the ROM contents will be modified, even though a write by the guest 410CPU to the ROM would be ignored. This is used for non-guest writes 411like writes from the gdb debug stub or initial loading of ROM contents. 412 413Note that portions of the write which attempt to write data to a 414device will be silently ignored -- only real RAM and ROM will 415be written to. 416 417Regexes for git grep 418 - ``address_space_write_rom`` 419 420``{ld,st}*_phys`` 421~~~~~~~~~~~~~~~~~ 422 423These 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 426whether the transaction succeeded or failed. 427 428The fact that they ignore whether the transaction succeeded means 429they should not be used in new code, unless you know for certain 430that your code will only be used in a context where the CPU or 431device 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 453The ``_{endian}_`` infix is omitted for byte accesses. 454 455Regexes for git grep 456 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_phys\>`` 457 - ``\<st[bwlq]\(_[bl]e\)\?_phys\>`` 458 459``cpu_physical_memory_*`` 460~~~~~~~~~~~~~~~~~~~~~~~~~ 461 462These are convenience functions which are identical to 463``address_space_*`` but operate specifically on the system address space, 464always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and 465ignore whether the memory transaction succeeded or failed. 466For 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 479Regexes for git grep 480 - ``\<cpu_physical_memory_\(read\|write\|rw\)\>`` 481 482``cpu_memory_rw_debug`` 483~~~~~~~~~~~~~~~~~~~~~~~ 484 485Access CPU memory by virtual address for debug purposes. 486 487This function is intended for use by the GDB stub and similar code. 488It takes a virtual address, converts it to a physical address via 489an MMU lookup using the current settings of the specified CPU, 490and then performs the access (using ``address_space_rw`` for 491reads or ``cpu_physical_memory_write_rom`` for writes). 492This means that if the access is a write to a ROM then this 493function will modify the contents (whereas a normal guest CPU access 494would ignore the write attempt). 495 496``cpu_memory_rw_debug`` 497 498``dma_memory_*`` 499~~~~~~~~~~~~~~~~ 500 501These behave like ``address_space_*``, except that they perform a DMA 502barrier operation first. 503 504**TODO**: We should provide guidance on when you need the DMA 505barrier operation and when it's OK to use ``address_space_*``, and 506make sure our existing code is doing things correctly. 507 508``dma_memory_read`` 509 510``dma_memory_write`` 511 512``dma_memory_rw`` 513 514Regexes 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 522These functions are specifically for PCI device models which need to 523perform accesses where the PCI device is a bus master. You pass them a 524``PCIDevice *`` and they will do ``dma_memory_*`` operations on the 525correct 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 553The ``_{endian}_`` infix is omitted for byte accesses. 554 555Regexes for git grep 556 - ``\<pci_dma_\(read\|write\|rw\)\>`` 557 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_pci_dma\>`` 558 - ``\<st[bwlq]\(_[bl]e\)\?_pci_dma\>`` 559