linux/Documentation/unaligned-memory-access.txt
<<
>>
Prefs
   1UNALIGNED MEMORY ACCESSES
   2=========================
   3
   4Linux runs on a wide variety of architectures which have varying behaviour
   5when it comes to memory access. This document presents some details about
   6unaligned accesses, why you need to write code that doesn't cause them,
   7and how to write such code!
   8
   9
  10The definition of an unaligned access
  11=====================================
  12
  13Unaligned memory accesses occur when you try to read N bytes of data starting
  14from an address that is not evenly divisible by N (i.e. addr % N != 0).
  15For example, reading 4 bytes of data from address 0x10004 is fine, but
  16reading 4 bytes of data from address 0x10005 would be an unaligned memory
  17access.
  18
  19The above may seem a little vague, as memory access can happen in different
  20ways. The context here is at the machine code level: certain instructions read
  21or write a number of bytes to or from memory (e.g. movb, movw, movl in x86
  22assembly). As will become clear, it is relatively easy to spot C statements
  23which will compile to multiple-byte memory access instructions, namely when
  24dealing with types such as u16, u32 and u64.
  25
  26
  27Natural alignment
  28=================
  29
  30The rule mentioned above forms what we refer to as natural alignment:
  31When accessing N bytes of memory, the base memory address must be evenly
  32divisible by N, i.e. addr % N == 0.
  33
  34When writing code, assume the target architecture has natural alignment
  35requirements.
  36
  37In reality, only a few architectures require natural alignment on all sizes
  38of memory access. However, we must consider ALL supported architectures;
  39writing code that satisfies natural alignment requirements is the easiest way
  40to achieve full portability.
  41
  42
  43Why unaligned access is bad
  44===========================
  45
  46The effects of performing an unaligned memory access vary from architecture
  47to architecture. It would be easy to write a whole document on the differences
  48here; a summary of the common scenarios is presented below:
  49
  50 - Some architectures are able to perform unaligned memory accesses
  51   transparently, but there is usually a significant performance cost.
  52 - Some architectures raise processor exceptions when unaligned accesses
  53   happen. The exception handler is able to correct the unaligned access,
  54   at significant cost to performance.
  55 - Some architectures raise processor exceptions when unaligned accesses
  56   happen, but the exceptions do not contain enough information for the
  57   unaligned access to be corrected.
  58 - Some architectures are not capable of unaligned memory access, but will
  59   silently perform a different memory access to the one that was requested,
  60   resulting in a subtle code bug that is hard to detect!
  61
  62It should be obvious from the above that if your code causes unaligned
  63memory accesses to happen, your code will not work correctly on certain
  64platforms and will cause performance problems on others.
  65
  66
  67Code that does not cause unaligned access
  68=========================================
  69
  70At first, the concepts above may seem a little hard to relate to actual
  71coding practice. After all, you don't have a great deal of control over
  72memory addresses of certain variables, etc.
  73
  74Fortunately things are not too complex, as in most cases, the compiler
  75ensures that things will work for you. For example, take the following
  76structure:
  77
  78        struct foo {
  79                u16 field1;
  80                u32 field2;
  81                u8 field3;
  82        };
  83
  84Let us assume that an instance of the above structure resides in memory
  85starting at address 0x10000. With a basic level of understanding, it would
  86not be unreasonable to expect that accessing field2 would cause an unaligned
  87access. You'd be expecting field2 to be located at offset 2 bytes into the
  88structure, i.e. address 0x10002, but that address is not evenly divisible
  89by 4 (remember, we're reading a 4 byte value here).
  90
  91Fortunately, the compiler understands the alignment constraints, so in the
  92above case it would insert 2 bytes of padding in between field1 and field2.
  93Therefore, for standard structure types you can always rely on the compiler
  94to pad structures so that accesses to fields are suitably aligned (assuming
  95you do not cast the field to a type of different length).
  96
  97Similarly, you can also rely on the compiler to align variables and function
  98parameters to a naturally aligned scheme, based on the size of the type of
  99the variable.
 100
 101At this point, it should be clear that accessing a single byte (u8 or char)
 102will never cause an unaligned access, because all memory addresses are evenly
 103divisible by one.
 104
 105On a related topic, with the above considerations in mind you may observe
 106that you could reorder the fields in the structure in order to place fields
 107where padding would otherwise be inserted, and hence reduce the overall
 108resident memory size of structure instances. The optimal layout of the
 109above example is:
 110
 111        struct foo {
 112                u32 field2;
 113                u16 field1;
 114                u8 field3;
 115        };
 116
 117For a natural alignment scheme, the compiler would only have to add a single
 118byte of padding at the end of the structure. This padding is added in order
 119to satisfy alignment constraints for arrays of these structures.
 120
 121Another point worth mentioning is the use of __attribute__((packed)) on a
 122structure type. This GCC-specific attribute tells the compiler never to
 123insert any padding within structures, useful when you want to use a C struct
 124to represent some data that comes in a fixed arrangement 'off the wire'.
 125
 126You might be inclined to believe that usage of this attribute can easily
 127lead to unaligned accesses when accessing fields that do not satisfy
 128architectural alignment requirements. However, again, the compiler is aware
 129of the alignment constraints and will generate extra instructions to perform
 130the memory access in a way that does not cause unaligned access. Of course,
 131the extra instructions obviously cause a loss in performance compared to the
 132non-packed case, so the packed attribute should only be used when avoiding
 133structure padding is of importance.
 134
 135
 136Code that causes unaligned access
 137=================================
 138
 139With the above in mind, let's move onto a real life example of a function
 140that can cause an unaligned memory access. The following function adapted
 141from include/linux/etherdevice.h is an optimized routine to compare two
 142ethernet MAC addresses for equality.
 143
 144unsigned int compare_ether_addr(const u8 *addr1, const u8 *addr2)
 145{
 146        const u16 *a = (const u16 *) addr1;
 147        const u16 *b = (const u16 *) addr2;
 148        return ((a[0] ^ b[0]) | (a[1] ^ b[1]) | (a[2] ^ b[2])) != 0;
 149}
 150
 151In the above function, the reference to a[0] causes 2 bytes (16 bits) to
 152be read from memory starting at address addr1. Think about what would happen
 153if addr1 was an odd address such as 0x10003. (Hint: it'd be an unaligned
 154access.)
 155
 156Despite the potential unaligned access problems with the above function, it
 157is included in the kernel anyway but is understood to only work on
 15816-bit-aligned addresses. It is up to the caller to ensure this alignment or
 159not use this function at all. This alignment-unsafe function is still useful
 160as it is a decent optimization for the cases when you can ensure alignment,
 161which is true almost all of the time in ethernet networking context.
 162
 163
 164Here is another example of some code that could cause unaligned accesses:
 165        void myfunc(u8 *data, u32 value)
 166        {
 167                [...]
 168                *((u32 *) data) = cpu_to_le32(value);
 169                [...]
 170        }
 171
 172This code will cause unaligned accesses every time the data parameter points
 173to an address that is not evenly divisible by 4.
 174
 175In summary, the 2 main scenarios where you may run into unaligned access
 176problems involve:
 177 1. Casting variables to types of different lengths
 178 2. Pointer arithmetic followed by access to at least 2 bytes of data
 179
 180
 181Avoiding unaligned accesses
 182===========================
 183
 184The easiest way to avoid unaligned access is to use the get_unaligned() and
 185put_unaligned() macros provided by the <asm/unaligned.h> header file.
 186
 187Going back to an earlier example of code that potentially causes unaligned
 188access:
 189
 190        void myfunc(u8 *data, u32 value)
 191        {
 192                [...]
 193                *((u32 *) data) = cpu_to_le32(value);
 194                [...]
 195        }
 196
 197To avoid the unaligned memory access, you would rewrite it as follows:
 198
 199        void myfunc(u8 *data, u32 value)
 200        {
 201                [...]
 202                value = cpu_to_le32(value);
 203                put_unaligned(value, (u32 *) data);
 204                [...]
 205        }
 206
 207The get_unaligned() macro works similarly. Assuming 'data' is a pointer to
 208memory and you wish to avoid unaligned access, its usage is as follows:
 209
 210        u32 value = get_unaligned((u32 *) data);
 211
 212These macros work for memory accesses of any length (not just 32 bits as
 213in the examples above). Be aware that when compared to standard access of
 214aligned memory, using these macros to access unaligned memory can be costly in
 215terms of performance.
 216
 217If use of such macros is not convenient, another option is to use memcpy(),
 218where the source or destination (or both) are of type u8* or unsigned char*.
 219Due to the byte-wise nature of this operation, unaligned accesses are avoided.
 220
 221
 222Alignment vs. Networking
 223========================
 224
 225On architectures that require aligned loads, networking requires that the IP
 226header is aligned on a four-byte boundary to optimise the IP stack. For
 227regular ethernet hardware, the constant NET_IP_ALIGN is used. On most
 228architectures this constant has the value 2 because the normal ethernet
 229header is 14 bytes long, so in order to get proper alignment one needs to
 230DMA to an address which can be expressed as 4*n + 2. One notable exception
 231here is powerpc which defines NET_IP_ALIGN to 0 because DMA to unaligned
 232addresses can be very expensive and dwarf the cost of unaligned loads.
 233
 234For some ethernet hardware that cannot DMA to unaligned addresses like
 2354*n+2 or non-ethernet hardware, this can be a problem, and it is then
 236required to copy the incoming frame into an aligned buffer. Because this is
 237unnecessary on architectures that can do unaligned accesses, the code can be
 238made dependent on CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS like so:
 239
 240#ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS
 241        skb = original skb
 242#else
 243        skb = copy skb
 244#endif
 245
 246--
 247Authors: Daniel Drake <dsd@gentoo.org>,
 248         Johannes Berg <johannes@sipsolutions.net>
 249With help from: Alan Cox, Avuton Olrich, Heikki Orsila, Jan Engelhardt,
 250Kyle McMartin, Kyle Moffett, Randy Dunlap, Robert Hancock, Uli Kunitz,
 251Vadim Lobanov
 252
 253
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.