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}_*`` 76~~~~~~~~~~~~~~~~~ 77 78These functions operate on a guest virtual address. Be aware 79that these functions may cause a guest CPU exception to be 80taken (e.g. for an alignment fault or MMU fault) which will 81result in guest CPU state being updated and control longjumping 82out of the function call. They should therefore only be used 83in code that is implementing emulation of the target CPU. 84 85These functions may throw an exception (longjmp() back out 86to the top level TCG loop). This means they must only be used 87from helper functions where the translator has saved all 88necessary CPU state before generating the helper function call. 89It's usually better to use the ``_ra`` variants described below 90from helper functions, but these functions are the right choice 91for calls made from hooks like the CPU do_interrupt hook or 92when you know for certain that the translator had to save all 93the CPU state that ``cpu_restore_state()`` would restore anyway. 94 95Function names follow the pattern: 96 97load: ``cpu_ld{sign}{size}_{mmusuffix}(env, ptr)`` 98 99store: ``cpu_st{size}_{mmusuffix}(env, ptr, val)`` 100 101``sign`` 102 - (empty) : for 32 or 64 bit sizes 103 - ``u`` : unsigned 104 - ``s`` : signed 105 106``size`` 107 - ``b`` : 8 bits 108 - ``w`` : 16 bits 109 - ``l`` : 32 bits 110 - ``q`` : 64 bits 111 112``mmusuffix`` is one of the generic suffixes ``data`` or ``code``, or 113(for softmmu configs) a target-specific MMU mode suffix as defined 114in the target's ``cpu.h``. 115 116Regexes for git grep 117 - ``\<cpu_ld[us]\?[bwlq]_[a-zA-Z0-9]\+\>`` 118 - ``\<cpu_st[bwlq]_[a-zA-Z0-9]\+\>`` 119 120``cpu_{ld,st}_*_ra`` 121~~~~~~~~~~~~~~~~~~~~ 122 123These functions work like the ``cpu_{ld,st}_*`` functions except 124that they also take a ``retaddr`` argument. This extra argument 125allows for correct unwinding of any exception that is taken, 126and should generally be the result of GETPC() called directly 127from the top level HELPER(foo) function (i.e. the return address 128in the generated code). 129 130These are generally the preferred way to do accesses by guest 131virtual address from helper functions; see the documentation 132of the non-``_ra`` variants for when those would be better. 133 134Calling these functions with a ``retaddr`` argument of 0 is 135equivalent to calling the non-``_ra`` version of the function. 136 137Function names follow the pattern: 138 139load: ``cpu_ld{sign}{size}_{mmusuffix}_ra(env, ptr, retaddr)`` 140 141store: ``cpu_st{sign}{size}_{mmusuffix}_ra(env, ptr, val, retaddr)`` 142 143Regexes for git grep 144 - ``\<cpu_ld[us]\?[bwlq]_[a-zA-Z0-9]\+_ra\>`` 145 - ``\<cpu_st[bwlq]_[a-zA-Z0-9]\+_ra\>`` 146 147``helper_*_{ld,st}*mmu`` 148~~~~~~~~~~~~~~~~~~~~~~~~ 149 150These functions are intended primarily to be called by the code 151generated by the TCG backend. They may also be called by target 152CPU helper function code. Like the ``cpu_{ld,st}_*_ra`` functions 153they perform accesses by guest virtual address; the difference is 154that these functions allow you to specify an ``opindex`` parameter 155which encodes (among other things) the mmu index to use for the 156access. This is necessary if your helper needs to make an access 157via a specific mmu index (for instance, an "always as non-privileged" 158access) rather than using the default mmu index for the current state 159of the guest CPU. 160 161The ``opindex`` parameter should be created by calling ``make_memop_idx()``. 162 163The ``retaddr`` parameter should be the result of GETPC() called directly 164from the top level HELPER(foo) function (or 0 if no guest CPU state 165unwinding is required). 166 167**TODO** The names of these functions are a bit odd for historical 168reasons because they were originally expected to be called only from 169within generated code. We should rename them to bring them 170more in line with the other memory access functions. 171 172load: ``helper_{endian}_ld{sign}{size}_mmu(env, addr, opindex, retaddr)`` 173 174store: ``helper_{endian}_st{size}_mmu(env, addr, val, opindex, retaddr)`` 175 176``sign`` 177 - (empty) : for 32 or 64 bit sizes 178 - ``u`` : unsigned 179 - ``s`` : signed 180 181``size`` 182 - ``b`` : 8 bits 183 - ``w`` : 16 bits 184 - ``l`` : 32 bits 185 - ``q`` : 64 bits 186 187``endian`` 188 - ``le`` : little endian 189 - ``be`` : big endian 190 - ``ret`` : target endianness 191 192Regexes for git grep 193 - ``\<helper_\(le\|be\|ret\)_ld[us]\?[bwlq]_mmu\>`` 194 - ``\<helper_\(le\|be\|ret\)_st[bwlq]_mmu\>`` 195 196``address_space_*`` 197~~~~~~~~~~~~~~~~~~~ 198 199These functions are the primary ones to use when emulating CPU 200or device memory accesses. They take an AddressSpace, which is the 201way QEMU defines the view of memory that a device or CPU has. 202(They generally correspond to being the "master" end of a hardware bus 203or bus fabric.) 204 205Each CPU has an AddressSpace. Some kinds of CPU have more than 206one AddressSpace (for instance ARM guest CPUs have an AddressSpace 207for the Secure world and one for NonSecure if they implement TrustZone). 208Devices which can do DMA-type operations should generally have an 209AddressSpace. There is also a "system address space" which typically 210has all the devices and memory that all CPUs can see. (Some older 211device models use the "system address space" rather than properly 212modelling that they have an AddressSpace of their own.) 213 214Functions are provided for doing byte-buffer reads and writes, 215and also for doing one-data-item loads and stores. 216 217In all cases the caller provides a MemTxAttrs to specify bus 218transaction attributes, and can check whether the memory transaction 219succeeded using a MemTxResult return code. 220 221``address_space_read(address_space, addr, attrs, buf, len)`` 222 223``address_space_write(address_space, addr, attrs, buf, len)`` 224 225``address_space_rw(address_space, addr, attrs, buf, len, is_write)`` 226 227``address_space_ld{sign}{size}_{endian}(address_space, addr, attrs, txresult)`` 228 229``address_space_st{size}_{endian}(address_space, addr, val, attrs, txresult)`` 230 231``sign`` 232 - (empty) : for 32 or 64 bit sizes 233 - ``u`` : unsigned 234 235(No signed load operations are provided.) 236 237``size`` 238 - ``b`` : 8 bits 239 - ``w`` : 16 bits 240 - ``l`` : 32 bits 241 - ``q`` : 64 bits 242 243``endian`` 244 - ``le`` : little endian 245 - ``be`` : big endian 246 247The ``_{endian}`` suffix is omitted for byte accesses. 248 249Regexes for git grep 250 - ``\<address_space_\(read\|write\|rw\)\>`` 251 - ``\<address_space_ldu\?[bwql]\(_[lb]e\)\?\>`` 252 - ``\<address_space_st[bwql]\(_[lb]e\)\?\>`` 253 254``address_space_write_rom`` 255~~~~~~~~~~~~~~~~~~~~~~~~~~~ 256 257This function performs a write by physical address like 258``address_space_write``, except that if the write is to a ROM then 259the ROM contents will be modified, even though a write by the guest 260CPU to the ROM would be ignored. This is used for non-guest writes 261like writes from the gdb debug stub or initial loading of ROM contents. 262 263Note that portions of the write which attempt to write data to a 264device will be silently ignored -- only real RAM and ROM will 265be written to. 266 267Regexes for git grep 268 - ``address_space_write_rom`` 269 270``{ld,st}*_phys`` 271~~~~~~~~~~~~~~~~~ 272 273These are functions which are identical to 274``address_space_{ld,st}*``, except that they always pass 275``MEMTXATTRS_UNSPECIFIED`` for the transaction attributes, and ignore 276whether the transaction succeeded or failed. 277 278The fact that they ignore whether the transaction succeeded means 279they should not be used in new code, unless you know for certain 280that your code will only be used in a context where the CPU or 281device doing the access has no way to report such an error. 282 283``load: ld{sign}{size}_{endian}_phys`` 284 285``store: st{size}_{endian}_phys`` 286 287``sign`` 288 - (empty) : for 32 or 64 bit sizes 289 - ``u`` : unsigned 290 291(No signed load operations are provided.) 292 293``size`` 294 - ``b`` : 8 bits 295 - ``w`` : 16 bits 296 - ``l`` : 32 bits 297 - ``q`` : 64 bits 298 299``endian`` 300 - ``le`` : little endian 301 - ``be`` : big endian 302 303The ``_{endian}_`` infix is omitted for byte accesses. 304 305Regexes for git grep 306 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_phys\>`` 307 - ``\<st[bwlq]\(_[bl]e\)\?_phys\>`` 308 309``cpu_physical_memory_*`` 310~~~~~~~~~~~~~~~~~~~~~~~~~ 311 312These are convenience functions which are identical to 313``address_space_*`` but operate specifically on the system address space, 314always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and 315ignore whether the memory transaction succeeded or failed. 316For new code they are better avoided: 317 318* there is likely to be behaviour you need to model correctly for a 319 failed read or write operation 320* a device should usually perform operations on its own AddressSpace 321 rather than using the system address space 322 323``cpu_physical_memory_read`` 324 325``cpu_physical_memory_write`` 326 327``cpu_physical_memory_rw`` 328 329Regexes for git grep 330 - ``\<cpu_physical_memory_\(read\|write\|rw\)\>`` 331 332``cpu_memory_rw_debug`` 333~~~~~~~~~~~~~~~~~~~~~~~ 334 335Access CPU memory by virtual address for debug purposes. 336 337This function is intended for use by the GDB stub and similar code. 338It takes a virtual address, converts it to a physical address via 339an MMU lookup using the current settings of the specified CPU, 340and then performs the access (using ``address_space_rw`` for 341reads or ``cpu_physical_memory_write_rom`` for writes). 342This means that if the access is a write to a ROM then this 343function will modify the contents (whereas a normal guest CPU access 344would ignore the write attempt). 345 346``cpu_memory_rw_debug`` 347 348``dma_memory_*`` 349~~~~~~~~~~~~~~~~ 350 351These behave like ``address_space_*``, except that they perform a DMA 352barrier operation first. 353 354**TODO**: We should provide guidance on when you need the DMA 355barrier operation and when it's OK to use ``address_space_*``, and 356make sure our existing code is doing things correctly. 357 358``dma_memory_read`` 359 360``dma_memory_write`` 361 362``dma_memory_rw`` 363 364Regexes for git grep 365 - ``\<dma_memory_\(read\|write\|rw\)\>`` 366 367``pci_dma_*`` and ``{ld,st}*_pci_dma`` 368~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 369 370These functions are specifically for PCI device models which need to 371perform accesses where the PCI device is a bus master. You pass them a 372``PCIDevice *`` and they will do ``dma_memory_*`` operations on the 373correct address space for that device. 374 375``pci_dma_read`` 376 377``pci_dma_write`` 378 379``pci_dma_rw`` 380 381``load: ld{sign}{size}_{endian}_pci_dma`` 382 383``store: st{size}_{endian}_pci_dma`` 384 385``sign`` 386 - (empty) : for 32 or 64 bit sizes 387 - ``u`` : unsigned 388 389(No signed load operations are provided.) 390 391``size`` 392 - ``b`` : 8 bits 393 - ``w`` : 16 bits 394 - ``l`` : 32 bits 395 - ``q`` : 64 bits 396 397``endian`` 398 - ``le`` : little endian 399 - ``be`` : big endian 400 401The ``_{endian}_`` infix is omitted for byte accesses. 402 403Regexes for git grep 404 - ``\<pci_dma_\(read\|write\|rw\)\>`` 405 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_pci_dma\>`` 406 - ``\<st[bwlq]\(_[bl]e\)\?_pci_dma\>`` 407