[Qemu-devel] [PATCH] docs: memory.txt document the endian field

["Michael S. Tsirkin" <mst@redhat.com>]

This is an attempt to document the endian
field in memory API. As this is a confusing topic,
it's best to make the text as explicit as possible.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 docs/memory.txt |   28 ++++++++++++++++++++++++++++
 1 files changed, 28 insertions(+), 0 deletions(-)

diff --git a/docs/memory.txt b/docs/memory.txt
index 5bbee8e..ff92b52 100644
--- a/docs/memory.txt
+++ b/docs/memory.txt
@@ -170,3 +170,31 @@ various constraints can be supplied to control how these callbacks are called:
  - .old_portio and .old_mmio can be used to ease porting from code using
    cpu_register_io_memory() and register_ioport().  They should not be used
    in new code.
+- .endianness; specifies the device endian-ness, which affects
+   the value parameter passed from guest to write and returned
+   to guest from read callbacks, as follows:
+        void write(void *opaque, target_phys_addr_t addr,
+                   uint64_t value, unsigned size)
+        uint64_t read(void *opaque, target_phys_addr_t addr,
+                       unsigned size)
+   Legal values are:
+   DEVICE_NATIVE_ENDIAN - Callbacks accept and return value in
+        host endian format. This makes it possible to do
+        math on values without type conversions.
+        Low size bytes in value are set, the rest are zero padded
+        on input and ignored on output.
+   DEVICE_LITTLE_ENDIAN - Callbacks accept and return value
+        in little endian format. This is appropriate
+        if you need to directly copy the data into device memory,
+        and the device programming interface is little endian
+        (true for most pci devices).
+        First size bytes in value are set, the rest are zero padded
+        on input and ignored on output.
+   DEVICE_BIG_ENDIAN - Callbacks accept and return value
+        in big endian format.
+        in little endian format. This is appropriate
+        if you need to directly copy the data into device memory,
+        and the device programming interface is big endian
+        (true e.g. for some system devices on big endian architectures).
+        Last size bytes in value are set, the rest are zero padded
+        on input and ignored on output.
-- 
1.7.9.111.gf3fb0