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