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