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``address_space_write_rom`` 257~~~~~~~~~~~~~~~~~~~~~~~~~~~ 258 259This function performs a write by physical address like 260``address_space_write``, except that if the write is to a ROM then 261the ROM contents will be modified, even though a write by the guest 262CPU to the ROM would be ignored. This is used for non-guest writes 263like writes from the gdb debug stub or initial loading of ROM contents. 264 265Note that portions of the write which attempt to write data to a 266device will be silently ignored -- only real RAM and ROM will 267be written to. 268 269Regexes for git grep 270 - ``address_space_write_rom`` 271 272``{ld,st}*_phys`` 273~~~~~~~~~~~~~~~~~ 274 275These are functions which are identical to 276``address_space_{ld,st}*``, except that they always pass 277``MEMTXATTRS_UNSPECIFIED`` for the transaction attributes, and ignore 278whether the transaction succeeded or failed. 279 280The fact that they ignore whether the transaction succeeded means 281they should not be used in new code, unless you know for certain 282that your code will only be used in a context where the CPU or 283device doing the access has no way to report such an error. 284 285``load: ld{sign}{size}_{endian}_phys`` 286 287``store: st{size}_{endian}_phys`` 288 289``sign`` 290 - (empty) : for 32 or 64 bit sizes 291 - ``u`` : unsigned 292 293(No signed load operations are provided.) 294 295``size`` 296 - ``b`` : 8 bits 297 - ``w`` : 16 bits 298 - ``l`` : 32 bits 299 - ``q`` : 64 bits 300 301``endian`` 302 - ``le`` : little endian 303 - ``be`` : big endian 304 305The ``_{endian}_`` infix is omitted for byte accesses. 306 307Regexes for git grep 308 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_phys\>`` 309 - ``\<st[bwlq]\(_[bl]e\)\?_phys\>`` 310 311``cpu_physical_memory_*`` 312~~~~~~~~~~~~~~~~~~~~~~~~~ 313 314These are convenience functions which are identical to 315``address_space_*`` but operate specifically on the system address space, 316always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and 317ignore whether the memory transaction succeeded or failed. 318For new code they are better avoided: 319 320* there is likely to be behaviour you need to model correctly for a 321 failed read or write operation 322* a device should usually perform operations on its own AddressSpace 323 rather than using the system address space 324 325``cpu_physical_memory_read`` 326 327``cpu_physical_memory_write`` 328 329``cpu_physical_memory_rw`` 330 331Regexes for git grep 332 - ``\<cpu_physical_memory_\(read\|write\|rw\)\>`` 333 334``cpu_memory_rw_debug`` 335~~~~~~~~~~~~~~~~~~~~~~~ 336 337Access CPU memory by virtual address for debug purposes. 338 339This function is intended for use by the GDB stub and similar code. 340It takes a virtual address, converts it to a physical address via 341an MMU lookup using the current settings of the specified CPU, 342and then performs the access (using ``address_space_rw`` for 343reads or ``cpu_physical_memory_write_rom`` for writes). 344This means that if the access is a write to a ROM then this 345function will modify the contents (whereas a normal guest CPU access 346would ignore the write attempt). 347 348``cpu_memory_rw_debug`` 349 350``dma_memory_*`` 351~~~~~~~~~~~~~~~~ 352 353These behave like ``address_space_*``, except that they perform a DMA 354barrier operation first. 355 356**TODO**: We should provide guidance on when you need the DMA 357barrier operation and when it's OK to use ``address_space_*``, and 358make sure our existing code is doing things correctly. 359 360``dma_memory_read`` 361 362``dma_memory_write`` 363 364``dma_memory_rw`` 365 366Regexes for git grep 367 - ``\<dma_memory_\(read\|write\|rw\)\>`` 368 369``pci_dma_*`` and ``{ld,st}*_pci_dma`` 370~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 371 372These functions are specifically for PCI device models which need to 373perform accesses where the PCI device is a bus master. You pass them a 374``PCIDevice *`` and they will do ``dma_memory_*`` operations on the 375correct address space for that device. 376 377``pci_dma_read`` 378 379``pci_dma_write`` 380 381``pci_dma_rw`` 382 383``load: ld{sign}{size}_{endian}_pci_dma`` 384 385``store: st{size}_{endian}_pci_dma`` 386 387``sign`` 388 - (empty) : for 32 or 64 bit sizes 389 - ``u`` : unsigned 390 391(No signed load operations are provided.) 392 393``size`` 394 - ``b`` : 8 bits 395 - ``w`` : 16 bits 396 - ``l`` : 32 bits 397 - ``q`` : 64 bits 398 399``endian`` 400 - ``le`` : little endian 401 - ``be`` : big endian 402 403The ``_{endian}_`` infix is omitted for byte accesses. 404 405Regexes for git grep 406 - ``\<pci_dma_\(read\|write\|rw\)\>`` 407 - ``\<ldu\?[bwlq]\(_[bl]e\)\?_pci_dma\>`` 408 - ``\<st[bwlq]\(_[bl]e\)\?_pci_dma\>`` 409