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