On 26 May 2016 at 16:20, Eric Blake <ebl...@redhat.com> wrote: > On 05/26/2016 09:08 AM, Peter Maydell wrote: >> >> Apologies for the lack of any backtraces in the output, but >> this is almost certainly the result of trying to do le64_to_cpu() >> or cpu_to_le64() on a buffer which isn't necessarily aligned >> (usually some pointer into guest memory). Use the functions >> ldq_le_p() and stq_le_p() instead, which will handle a >> potentially misaligned pointer for you. (There are similar >> functions for other access widths too.) > > Since these functions are constructed by ## token pasting, it's very > hard to grep .h files to see what variations-on-a-theme are actually > available, nor is the documentation clear on what they all do (in-place > vs. copy, pass a value vs. a pointer, ...). It might be a nice > bite-sized task to beef up the documentation and at least call out ALL > of the endian-conversion functions in a nice comment (to make it > greppable), along with this tidbit of information on which forms are > optimized but require alignment, vs. work anywhere but potentially slower.
The documentation of the ld* functions is in bswap.h (the comment starting "the generic syntax is"), though I agree it is a bit awkward not having it greppable. There would probably be about 200 functions if you expanded out the names just in the ld*_p() family. We could probably also do a better job of marking which of these function families are recommended, and which are obsolete flavours which we have because a bunch of old code still uses them. (You can tell cpu_to_le64() and friends don't handle misalignment because they take a uint64_t, not a pointer to one.) thanks -- PMM
