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