• EndianIssues

Part of the WritingPortableDrivers section

Processors store internal data in one of two ways: little-endian or big-endian. Little-endian processors store data with the right-most bytes (those with a higher address value) being the most significant, while big-endian processors store data with the left-most bytes (those with a lower address value) being the most significant.

For example, the table below shows how the decimal value 684686 is stored in a 4-byte integer on the two different processor types (684686 decimal = a728e hex = 00000000 00001010 01110010 10001110 binary).

The Intel i386 family are little-endian machines, whereas the SPARC and 68k processors are big-endian. The Alpha, IA-64 and PowerPC processors can be run in either little- or big-endian mode; for Linux the Alpha and IA-64 are typically run in little-endian mode and the PowerPC is run in big-endian mode. The ARM processor can be either, depending on the specific ARM chip being used, the original ARMs were little-endian but for devices designed for network processing they are usually big-endian.

Because of the different endian types of processors, you need to be aware of data you receive from external sources and the order in which it appears. For example, the USB specification dictates that all multibyte data fields are in little-endian form. So if you have a USB driver that reads a multibyte field from the USB connection, you need to convert that data into the processor's native format. Code that assumes the processor is little-endian could ignore the data format coming from the USB connection successfully. But this same code would not work on PowerPC and is the leading cause of drivers that are broken on different platforms. Conversely most networking data is defined in terms of big endian data structures.

Thankfully, there are a number of helpful macros that have been created to make this an easy task. All of the following macros can be found in the asm/byteorder.h header file.

To convert from the processor's native format into little-endian form you can use the following functions:

   1 __le64 cpu_to_le64(u64);
   2 __le32 cpu_to_le32(u32);
   3 __le16 cpu_to_le16(u16);

To convert from little-endian format into the processor's native format you should use these functions:

   1 u64 le64_to_cpu(__le64);
   2 u32 le32_to_cpu(__le32);
   3 u16 le16_to_cpu(__le16);

For big-endian forms, the following functions are available:

   1 __be64 cpu_to_be64(u64);
   2 __be32 cpu_to_be32(u32);
   3 __be16 cpu_to_be16(u16);
   4 u64 be64_to_cpu(__be64);
   5 u32 be32_to_cpu(__be32);
   6 u16 be16_to_cpu(__be16);

If you have a pointer to the value to convert, then you should use the following functions:

   1 __le64 cpu_to_le64p(u64 *);
   2 __le32 cpu_to_le32p(u32 *);
   3 __le16 cpu_to_le16p(u16 *);
   4 u64 le64_to_cpup(__le64 *);
   5 u32 le32_to_cpup(__le32 *);
   6 u16 le16_to_cpup(__le16 *);
   7 __be64 cpu_to_be64p(u64 *);
   8 __be32 cpu_to_be32p(u32 *);
   9 __be16 cpu_to_be16p(u16 *);
  10 u64 be64_to_cpup(__be64 *);
  11 u32 be32_to_cpup(__be32 *);
  12 u16 be16_to_cpup(__be16 *);

If you want to convert the value within a variable and store the modified value in the same variable (in situ), then you should use the following functions:

   1 void cpu_to_le64s(u64 *);
   2 void cpu_to_le32s(u32 *);
   3 void cpu_to_le16s(u16 *);
   4 void le64_to_cpus(u64 *);
   5 void le32_to_cpus(u32 *);
   6 void le16_to_cpus(u16 *);
   7 void cpu_to_be64s(u64 *);
   8 void cpu_to_be32s(u32 *);
   9 void cpu_to_be16s(u16 *);
  10 void be64_to_cpus(u64 *);
  11 void be32_to_cpus(u32 *);
  12 void be16_to_cpus(u16 *);

As stated before, the USB protocol is in little-endian format. The code snippet from drivers/usb/serial/visor.c below shows how a structure is read from the USB connection and then converted into the proper CPU format.

   1 struct visor_connection_info *connection_info;
   2 /* send a get connection info request */
   3 usb_control_msg(serial->dev,
   4                 usb_rcvctrlpipe(serial->dev, 0),
   5                 VISOR_GET_CONNECTION_INFORMATION,
   6                 0xc2, 0x0000, 0x0000,
   7                 transfer_buffer, 0x12, 300);
   8 connection_info = (struct visor_connection_info *)transfer_buffer;
   9 num_ports = le16_to_cpu(connection_info->num_ports);

Wikipedia has a larger discussion on Endianness.