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