[U-Boot,RFC] rewrite doc/README.arm-unaligned-accesses

diff --git a/doc/README.arm-unaligned-accesses b/doc/README.arm-unaligned-accesses
index c37d135..5873689 100644
--- a/doc/README.arm-unaligned-accesses
+++ b/doc/README.arm-unaligned-accesses
@@ -1,55 +1,229 @@ 
-If you are reading this because of a data abort: the following MIGHT
-be relevant to your abort, if it was caused by an alignment violation.
-In order to determine this, use the PC from the abort dump along with
-an objdump -s -S of the u-boot ELF binary to locate the function where
-the abort happened; then compare this function with the examples below.
-If they match, then you've been hit with a compiler generated unaligned
-access, and you should rewrite your code or add -mno-unaligned-access
-to the command line of the offending file.
+Notes:
 
-Note that the PC shown in the abort message is relocated. In order to
-be able to match it to an address in the ELF binary dump, you will need
-to know the relocation offset. If your target defines CONFIG_CMD_BDI
-and if you can get to the prompt and enter commands before the abort
-happens, then command "bdinfo" will give you the offset. Otherwise you
-will need to try a build with DEBUG set, which will display the offset,
-or use a debugger and set a breakpoint at relocate_code() to see the
-offset (passed as an argument).
-
-*
-
-Since U-Boot runs on a variety of hardware, some only able to perform
-unaligned accesses with a strong penalty, some unable to perform them
-at all, the policy regarding unaligned accesses is to not perform any,
-unless absolutely necessary because of hardware or standards.
-
-Also, on hardware which permits it, the core is configured to throw
-data abort exceptions on unaligned accesses in order to catch these
-unallowed accesses as early as possible.
-
-Until version 4.7, the gcc default for performing unaligned accesses
-(-mno-unaligned-access) is to emulate unaligned accesses using aligned
-loads and stores plus shifts and masks. Emulated unaligned accesses
-will not be caught by hardware. These accesses may be costly and may
-be actually unnecessary. In order to catch these accesses and remove
-or optimize them, option -munaligned-access is explicitly set for all
-versions of gcc which support it.
-
-From gcc 4.7 onward starting at armv7 architectures, the default for
-performing unaligned accesses is to use unaligned native loads and
-stores (-munaligned-access), because the cost of unaligned accesses
-has dropped on armv7 and beyond. This should not affect U-Boot's
-policy of controlling unaligned accesses, however the compiler may
-generate uncontrolled unaligned accesses on its own in at least one
-known case: when declaring a local initialized char array, e.g.
+i) If you are reading this because of a data abort: section 10 is what
+you're looking for, but please read the whole document.
 
-function foo()
-{
-	char buffer[] = "initial value";
-/* or */
-	char buffer[] = { 'i', 'n', 'i', 't', 0 };
-	...
-}
+ii) In order to make sure the following is self-sufficient, it goes
+through the basics of alignment and assumes only good, not expert,
+knowledge of the C language.
+
+1. C99 alignment requirements
+
+The C99 standard [1] (henceforth: 'C99') defines alignment requirements
+as a "requirement that objects of a particular type be located on
+storage boundaries with addresses that are particular multiples of a
+byte address".
+
+In C99, unaligned accesses (those which which do not respect alignment
+requirements of the object type being accessed) are deemed 'undefined'.
+This means programs which contain unaligned accesses might build and
+execute as if there were no alignment constraints, or build and execute
+but not as expected, or build and crash at execution, or not build
+at all--or even crash the compiler.
+
+2. Implementation alignment requirements
+
+While C99 does define alignment requirements, it does not lay out any
+actual alignment requirements, because these depend greatly on the
+hardware involved; they are thus defined by C99 implementations.
+
+For ARM, the C alignment requirements are laid out in the ARM EABI [2].
+For instance, is is the ARM EABI which sets the alignment constraint of
+type 'long' to four-byte boundaries.
+
+Alignment requirements for a given architecture may differ from
+hardware capabilities, i.e. they might be stricter than what the
+hardware can actually do. One example is (32-bit) x86, which can do
+unaligned accesses at the hardware level at some performance cost, but
+has stricter requirement analogous to the ARM EABI ones. ARM is a mixed
+bag: some older ARM hardware cannot perform unaligned access at all;
+some can but at a cost; some can at virtually no cost.
+
+Further, even when a given architecture is capable of emitting such
+unaligned accesses at the core or CPU level, at a higher (system) level
+they might be forbidden because the target address falls within a
+region in which only aligned accesses are possible.
+
+3. Native vs emulated unaligned accesses.
+
+There is a different between the alignment of accesses in a C program
+source code and the alignment of accesses at the core or CPU level. In
+the following, translated accesses (core or CPU accesses) will be
+qualified as /native/ accesses to distinguish them from (untranslated) C
+program accesses.
+
+A C99 implementation might translate an unaligned access into a native
+unaligned access, or it might emulate it by a combination of native
+aligned accesses. 
+
+4. Alignment requirements in U-Boot
+
+As U-Boot runs on a variety of hardware using a variety of C99
+implementations, alignment requirements for the U-Boot code are the
+strictest possible so that all implementations building U-Boot will have
+their requirements satisfied. For instance, aligning longs to four-byte
+boundaries is compatible with all implementations and is thus the
+requirement for U-Boot.
+
+[U-Boot alignment requirements are actually stricter than just C99: in
+U-Boot, at least some accesses of a given width must not be broken into
+smaller accesses or lumped into a wider access, because they are done
+to or from a device for which each physical access may have side
+effects. C99 does not explicitly state such a constraint except in
+general terms, that a C99 implementation .]
+
+The strict alignment requirements imply that all type declarations in
+U-Boot should respect alignment requirements; especially, that no
+structure should contain unaligned members.
+
+5. Purposeful unaligned accesses in U-Boot
+
+However, there might be cases where some data representation may need
+to include objects which are not aligned to their requirements. This
+happens in structs representing protocols such as IP or USB, for
+instance, or de facto standards such as FAT. Taking FAT as an example,
+here is the start of the FAT header, expressed as a succession of C
+types from position 0 in the first disk sector:
+
+        0       3       jump instruction
+        3       8       Name of the tool which formatted the FAT
+        11      2       Number of bytes per sector
+
+Since the third field is a short, as per ARM EABI it should be
+even-aligned. However, it is not: its offset is 11, an odd value.
+Therefore, a struct representing the FAT header (examples below are
+adapted from actual code in fs/fdos/dos.h) would either have to split
+the field in two smaller bytes...
+
+    typedef struct bootsector
+    {
+        unsigned char jump [3];  /* 0  Jump to boot code */
+        char banner[BANNER_LG];	 /* 3  OEM name & version */
+        unsigned char secsiz_lo; /* 11 Bytes per sector LO */
+        unsigned char secsiz_hi; /* 12 Bytes per sector HI */
+        [...]
+    } Directory_t;
+
+... but this is awkward and makes accesses to the field more
+complicated to express and read. The alternative is to use a short
+field, made unaligned by way of a 'packed' attribute on the struct:
+
+    typedef struct bootsector
+    {
+        unsigned char jump [3]; /* 0  Jump to boot code */
+        char banner[BANNER_LG];	/* 3  OEM name & version */
+        unsigned short secsiz;  /* 11 Bytes per sector */
+        [...]
+    } __attribute__ ((packed))  Directory_t;
+
+The latter is what is done in the U-Boot code, and the access is then
+explicitly turned from one unaligned 16-bit to two aligned 8-bit ones
+by using the macro __le16_to_cpu (which is slightly below U-Boot
+requirements, as we should be using put_unaligned_le16 instead).
+
+6. Unintended unaligned accesses in U-Boot
+
+As stated in section 4, U-Boot code should be conforming enough that it
+would not perform accesses which are unaligned as per ARM EABI, and
+access to intentionally unaligned C objects in U-Boot should be done by
+emulating through get_unaligned/put_unaligned macros.
+
+However, mistakes do happen, and therefore a patch might slip past
+review, or a developer might write new code before submitting it, which
+could cause some unintended unaligned access.
+
+Mostly, the cause of unintended unaligned accesses fall into two
+categories: needlessly packed structs and pointer arithmetic mistakes,
+the latter including compile-time mistakes and run-time mistakes.
+
+Such unaligned accesses might only actually happen on some architecture
+different from the one the developer is working on, which will delay
+discovery of the issue and complicate its analysis and resolution.
+As we cannot test for all targets at each release, it might even happen
+that some release of U-Boot out there would fail to work for a given
+target because an unintended unaligned access was not detected early.
+
+Early detection of unaligned accesses is therefore important, even on
+architecture which could handle such unaligned accesses natively or
+by emulation, for the benefit of architectures which could not.
+
+7. ARM: detecting unintentional unaligned accesses by hardware
+
+[This section assumes that unaligned accesses are translated into native
+unaligned accesses rather than emulated. For a discussion of this
+assumption, see next section.]
+
+In order to catch unintended unaligned accesses on ARM platforms, we can
+use the A bit in SRC: setting it will cause the core to throw a Data
+Abort when a native unaligned access occurs.
+
+This will catch pointer arithmetic errors when they result in badly
+aligned pointers, as well as accesses to unaligned fields in packed
+structures of -munaligned-access is in effect (see next section).
+
+8. ARM: detecting unintentional unaligned accesses by software
+
+In the previous section, we have chosen to configure the ARM hardware
+to catch native unaligned accesses. However, whether unaligned accesses
+are translated into native or emulated accesses depends, on ARM, on a
+compiler option: -m[no-]unaligned-access.
+
+With -munaligned-access, the compiler is allowed to translate unaligned
+accesses from a C program into native unaligned accesses at the core
+level.
+
+With -mno-unaligned-access, the compiler is *not* allowed to translate
+unaligned accesses from a C program into native unaligned accesses at
+the core level, and must therefore emulate them with a combination of
+smaller aligned native accesses.
+
+At first sight, -mno-unaligne-access seems to solve our problem as it
+prevents the core from emitting native unaligned accesses; and
+-munaligned-access appears counter-intuitive as it allows the compiler
+to emit native unaligned accesses, which we precisely want to avoid.
+
+However, if -mno-unaligned-access prevents native unaligned accesses on
+ARM, it has no effect on other architectures for which it does not even
+always have an equivalent; thus, a C program which builds and runs
+without error with -mno-unaligned-access on ARM platforms might fail to
+build, or build but fail to run properly, on other platforms.
+
+On the other hand, -munaligned-access only causes natie unaligned
+accesses if the C program has unaligned accesses to begin with; for C
+programs in which unaligned accesses are all intentional, the compiler
+will not generate native unaligned accesses (except in very specific
+situations which can be controlled, see next section).
+
+We can see that while -mno-unaligned-accesses prevents the ill effects
+of unintended unaligned accesses by turning them into smaller native
+aligned ones, this translation also prevents detecting unaligned
+accesses early, whereas -munaligned-access does.
+
+Again, building ARM U-Boot with -munaligned-access might seem
+contradictory with setting the SRC A bit to catch native unaligned
+accesses; but this is because what we want is not to get rid of native
+unaligned accesses /per se/; what we want is to find and fix unintended
+unaligned accesses in the source code, and we use -munaligned-access
+for this because it makes a better job of translating unintended
+unaligned accesses into native unaligned accesses, and thus at getting
+the SCR.A bit setting to detect them, than -mno-unaligned-access does. 
+
+Again: if we had wanted to just not emit native unaligned accesses, then
+globally turning -mno-unaligned-access on would have been our option of
+choice; but this is not what we want.
+
+9. Corner cases: array initializations
+
+There is actually one single corner case where gcc might generate
+native unaligned accesses from a C program which does not at first
+sight appear to contain unaligned accesses at all. Consider the
+following:
+
+    function foo()
+    {
+        char buffer[] = "initial value";
+        ...
+    }
 
 Under -munaligned-accesses with optimizations on, this declaration
 causes the compiler to generate native loads from the literal string
@@ -57,8 +231,12 @@  and native stores to the buffer, and the literal string alignment
 cannot be controlled. If it is misaligned, then the core will throw
 a data abort exception.
 
-Quite probably the same might happen for 16-bit array initializations
-where the constant is aligned on a boundary which is a multiple of 2
+[under -munaligned-accesses *without* optimizations, there is no issue
+as the compiler emits the initialization as a memcpy() which does not
+cause any native unaligned access]
+
+The same might happen for 16-bit array initializations where the
+literal constant array is aligned on a boundary which is a multiple of 2
 but not of 4:
 
 function foo()
@@ -67,12 +245,17 @@  function foo()
 	...
 }
 
-The long term solution to this issue is to add an option to gcc to
-allow controlling the general alignment of data, including constant
-initialization values.
+Under -munaligned-accesses with optimizations on, the compiler will
+use unaligned long native accesses to copy the literal into the
+variable.
+
+The long term solution to this issue is to modify the compiler in
+order to get finer control on this particular initialization either by
+controlling literal alignment, or by controlling use of native
+unaligned accesses in this case.
 
-However this will only apply to the version of gcc which will have such
-an option. For other versions, there are four workarounds:
+However this will at best only apply to a future version of gcc. For
+existing versions, there are four workarounds:
 
 a) Enforce as a rule that array initializations as described above
    are forbidden. This is generally not acceptable as they are valid,
@@ -80,43 +263,59 @@  a) Enforce as a rule that array initializations as described above
    is when they actually equate to a const char* declaration, i.e. the
    array is initialized and never modified in the function's scope.
 
-b) Drop the requirement on unaligned accesses at least for ARMv7,
-   i.e. do not throw a data abort exception upon unaligned accesses.
-   But that will allow adding badly aligned code to U-Boot, only for
-   it to fail when re-used with a stricter target, possibly once the
-   bad code is already in mainline.
+b) Drop the hardware requirement on unaligned accesses at least for
+   ARMv7, i.e. do not throw a data abort exception upon unaligned
+   accesses. But that will allow adding badly aligned code to U-Boot,
+   only for it to fail when re-used with a stricter target, possibly
+   once the bad code is already in mainline.
 
 c) Relax the -munaligned-access rule globally. This will prevent native
-   unaligned accesses of course, but that will also hide any bug caused
-   by a bad unaligned access, making it much harder to diagnose it. It
-   is actually what already happens when building ARM targets with a
-   pre-4.7 gcc, and it may actually already hide some bugs yet unseen
-   until the target gets compiled with -munaligned-access.
-
-d) Relax the -munaligned-access rule only for for files susceptible to
-   the local initialized array issue and for armv7 architectures and
+   unaligned accesses from being generated of course, but that will also
+   hide any bug caused by an unwanted unaligned access, making it much
+   harder    to diagnose it. It is actually what already happens
+   when building ARM targets with a pre-4.7 gcc, and it may actually
+   already hide some bugs yet unseen until the target gets compiled
+   with -munaligned-access.
+
+d) Relax the -munaligned-access rule only for files susceptible to the
+   local initialized array issue and for armv7 architectures and
    beyond. This minimizes the quantity of code which can hide unwanted
    misaligned accesses.
 
 The option retained is d).
 
-Considering that actual occurrences of the issue are rare (as of this
-writing, 5 files out of 7840 in U-Boot, or .3%, contain an initialized
-local char array which cannot actually be replaced with a const char*),
-contributors should not be required to systematically try and detect
-the issue in their patches.
-
-Detecting files susceptible to the issue can be automated through a
-filter installed as a hook in .git which recognizes local char array
-initializations. Automation should err on the false positive side, for
-instance flagging non-local arrays as if they were local if they cannot
-be told apart.
-
-In any case, detection shall not prevent committing the patch, but
-shall pre-populate the commit message with a note to the effect that
-this patch contains an initialized local char or 16-bit array and thus
-should be protected from the gcc 4.7 issue.
-
-Upon a positive detection, either $(PLATFORM_NO_UNALIGNED) should be
-added to CFLAGS for the affected file(s), or if the array is a pseudo
-const char*, it should be replaced by an actual one.
+10. Alignment issues and Data Aborts
+
+If you are reading this file because of the message displayed during a
+data abort: the following MIGHT be relevant to your abort, if it was
+caused by an alignment requirement violation. This may have been caused
+by bad pointer arithmetic, or improper access to unaligned fields in a
+packed struct, or a corner case as described in the previous section,
+or an unlikely new corner case.
+
+In order to determine which is which, you must first determine whether
+the data abort is an alignment abort. Refer to the ARM architecture
+reference manual to determine the exact cause of the abort.
+
+If the abort is indeed an alignment one, then use the PC from the abort
+dump along with an objdump -d -S of the u-boot ELF binary to locate the
+function where the abort happened; then compare this function with the
+examples of this file. If they match, then you've been hit with a
+compiler-generated unaligned access, and you should rewrite your code
+or add -mno-unaligned-access to the command line of the offending file.
+Otherwise, you're probably having a bad pointer arithmetic case.
+
+Note that the PC shown in the abort message is relocated. In order to
+be able to match it to an address in the ELF binary dump, you will need
+to know the relocation offset. If your target defines CONFIG_CMD_BDI
+and if you can get to the prompt and enter commands before the abort
+happens, then command "bdinfo" will give you the offset. Otherwise you
+will need to try a build with DEBUG set, which will display the offset
+(but you'll have to witness the abort again on the DEBUG build, as the
+abort PC will have changed), or use a debugger and set a breakpoint at
+relocate_code() to see the offset (passed as an argument).
+
+11. References
+
+[1] ISO/IEC 9899:1999
+[2] ARM IHI 0042E (AAPCS)