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