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 174load (code): ``helper_{endian}_ld{sign}{size}_cmmu(env, addr, opindex, retaddr)`` 175 176store: ``helper_{endian}_st{size}_mmu(env, addr, val, opindex, retaddr)`` 177 178``sign`` 179 - (empty) : for 32 or 64 bit sizes 180 - ``u`` : unsigned 181 - ``s`` : signed 182 183``size`` 184 - ``b`` : 8 bits 185 - ``w`` : 16 bits 186 - ``l`` : 32 bits 187 - ``q`` : 64 bits 188 189``endian`` 190 - ``le`` : little endian 191 - ``be`` : big endian 192 - ``ret`` : target endianness 193 194Regexes for git grep 195 - ``\<helper_\(le\|be\|ret\)_ld[us]\?[bwlq]_c\?mmu\>`` 196 - ``\<helper_\(le\|be\|ret\)_st[bwlq]_mmu\>`` 197 198``address_space_*`` 199~~~~~~~~~~~~~~~~~~~ 200 201These functions are the primary ones to use when emulating CPU 202or device memory accesses. They take an AddressSpace, which is the 203way QEMU defines the view of memory that a device or CPU has. 204(They generally correspond to being the "master" end of a hardware bus 205or bus fabric.) 206 207Each CPU has an AddressSpace. Some kinds of CPU have more than 208one AddressSpace (for instance ARM guest CPUs have an AddressSpace 209for the Secure world and one for NonSecure if they implement TrustZone). 210Devices which can do DMA-type operations should generally have an 211AddressSpace. There is also a "system address space" which typically 212has all the devices and memory that all CPUs can see. (Some older 213device models use the "system address space" rather than properly 214modelling that they have an AddressSpace of their own.) 215 216Functions are provided for doing byte-buffer reads and writes, 217and also for doing one-data-item loads and stores. 218 219In all cases the caller provides a MemTxAttrs to specify bus 220transaction attributes, and can check whether the memory transaction 221succeeded using a MemTxResult return code. 222 223``address_space_read(address_space, addr, attrs, buf, len)`` 224 225``address_space_write(address_space, addr, attrs, buf, len)`` 226 227``address_space_rw(address_space, addr, attrs, buf, len, is_write)`` 228 229``address_space_ld{sign}{size}_{endian}(address_space, addr, attrs, txresult)`` 230 231``address_space_st{size}_{endian}(address_space, addr, val, attrs, txresult)`` 232 233``sign`` 234 - (empty) : for 32 or 64 bit sizes 235 - ``u`` : unsigned 236 237(No signed load operations are provided.) 238 239``size`` 240 - ``b`` : 8 bits 241 - ``w`` : 16 bits 242 - ``l`` : 32 bits 243 - ``q`` : 64 bits 244 245``endian`` 246 - ``le`` : little endian 247 - ``be`` : big endian 248 249The ``_{endian}`` suffix is omitted for byte accesses. 250 251Regexes for git grep 252 - ``\<address_space_\(read\|write\|rw\)\>`` 253 - ``\<address_space_ldu\?[bwql]\(_[lb]e\)\?\>`` 254 - ``\<address_space_st[bwql]\(_[lb]e\)\?\>`` 255 256``{ld,st}*_phys`` 257~~~~~~~~~~~~~~~~~ 258 259These are functions which are identical to 260``address_space_{ld,st}*``, except that they always pass 261``MEMTXATTRS_UNSPECIFIED`` for the transaction attributes, and ignore 262whether the transaction succeeded or failed. 263 264The fact that they ignore whether the transaction succeeded means 265they should not be used in new code, unless you know for certain 266that your code will only be used in a context where the CPU or 267device doing the access has no way to report such an error. 268 269``load: ld{sign}{size}_{endian}_phys`` 270 271``store: st{size}_{endian}_phys`` 272 273``sign`` 274 - (empty) : for 32 or 64 bit sizes 275 - ``u`` : unsigned 276 277(No signed load operations are provided.) 278 279``size`` 280 - ``b`` : 8 bits 281 - ``w`` : 16 bits 282 - ``l`` : 32 bits 283 - ``q`` : 64 bits 284 285``endian`` 286 - ``le`` : little endian 287 - ``be`` : big endian 288 289The ``_{endian}_`` infix is omitted for byte accesses. 290 291Regexes for git grep 292 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_phys\>`` 293 - ``\<st[bwlq]\(_[bl]e\)\?_phys\>`` 294 295``cpu_physical_memory_*`` 296~~~~~~~~~~~~~~~~~~~~~~~~~ 297 298These are convenience functions which are identical to 299``address_space_*`` but operate specifically on the system address space, 300always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and 301ignore whether the memory transaction succeeded or failed. 302For new code they are better avoided: 303 304* there is likely to be behaviour you need to model correctly for a 305 failed read or write operation 306* a device should usually perform operations on its own AddressSpace 307 rather than using the system address space 308 309``cpu_physical_memory_read`` 310 311``cpu_physical_memory_write`` 312 313``cpu_physical_memory_rw`` 314 315Regexes for git grep 316 - ``\<cpu_physical_memory_\(read\|write\|rw\)\>`` 317 318``cpu_physical_memory_write_rom`` 319~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 320 321This function performs a write by physical address like 322``address_space_write``, except that if the write is to a ROM then 323the ROM contents will be modified, even though a write by the guest 324CPU to the ROM would be ignored. 325 326Note that unlike ``cpu_physical_memory_write()`` this function takes 327an AddressSpace argument, but unlike ``address_space_write()`` this 328function does not take a ``MemTxAttrs`` or return a ``MemTxResult``. 329 330**TODO**: we should probably clean up this inconsistency and 331turn the function into ``address_space_write_rom`` with an API 332matching ``address_space_write``. 333 334``cpu_physical_memory_write_rom`` 335 336 337``cpu_memory_rw_debug`` 338~~~~~~~~~~~~~~~~~~~~~~~ 339 340Access CPU memory by virtual address for debug purposes. 341 342This function is intended for use by the GDB stub and similar code. 343It takes a virtual address, converts it to a physical address via 344an MMU lookup using the current settings of the specified CPU, 345and then performs the access (using ``address_space_rw`` for 346reads or ``cpu_physical_memory_write_rom`` for writes). 347This means that if the access is a write to a ROM then this 348function will modify the contents (whereas a normal guest CPU access 349would ignore the write attempt). 350 351``cpu_memory_rw_debug`` 352 353``dma_memory_*`` 354~~~~~~~~~~~~~~~~ 355 356These behave like ``address_space_*``, except that they perform a DMA 357barrier operation first. 358 359**TODO**: We should provide guidance on when you need the DMA 360barrier operation and when it's OK to use ``address_space_*``, and 361make sure our existing code is doing things correctly. 362 363``dma_memory_read`` 364 365``dma_memory_write`` 366 367``dma_memory_rw`` 368 369Regexes for git grep 370 - ``\<dma_memory_\(read\|write\|rw\)\>`` 371 372``pci_dma_*`` and ``{ld,st}*_pci_dma`` 373~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 374 375These functions are specifically for PCI device models which need to 376perform accesses where the PCI device is a bus master. You pass them a 377``PCIDevice *`` and they will do ``dma_memory_*`` operations on the 378correct address space for that device. 379 380``pci_dma_read`` 381 382``pci_dma_write`` 383 384``pci_dma_rw`` 385 386``load: ld{sign}{size}_{endian}_pci_dma`` 387 388``store: st{size}_{endian}_pci_dma`` 389 390``sign`` 391 - (empty) : for 32 or 64 bit sizes 392 - ``u`` : unsigned 393 394(No signed load operations are provided.) 395 396``size`` 397 - ``b`` : 8 bits 398 - ``w`` : 16 bits 399 - ``l`` : 32 bits 400 - ``q`` : 64 bits 401 402``endian`` 403 - ``le`` : little endian 404 - ``be`` : big endian 405 406The ``_{endian}_`` infix is omitted for byte accesses. 407 408Regexes for git grep 409 - ``\<pci_dma_\(read\|write\|rw\)\>`` 410 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_pci_dma\>`` 411 - ``\<st[bwlq]\(_[bl]e\)\?_pci_dma\>`` 412