[people/ms/u-boot.git] / doc / README.displaying-bmps

If you are experiencing hangups/data-aborts when trying to display a BMP image,
the following might be relevant to your situation...

Some architectures cannot handle unaligned memory accesses, and an attempt to
perform one will lead to a data abort. On such architectures it is necessary to
make sure all data is properly aligned, and in many situations simply choosing
a 32 bit aligned address is enough to ensure proper alignment. This is not
always the case when dealing with data that has an internal layout such as a
BMP image:

BMP images have a header that starts with 2 byte-size fields followed by mostly
32 bit fields. The packed struct that represents this header can be seen below:

typedef struct bmp_header {
	/* Header */
	char signature[2];
	__u32	file_size;
	__u32	reserved;
	__u32	data_offset;
	... etc
} __attribute__ ((packed)) bmp_header_t;

When placed in an aligned address such as 0x80a00000, char signature offsets
the __u32 fields into unaligned addresses (in our example 0x80a00002,
0x80a00006, and so on...). When these fields are accessed by U-Boot, a 32 bit
access is generated at a non-32-bit-aligned address, causing a data abort.
The proper alignment for BMP images is therefore: 32-bit-aligned-address + 2.
Commit	Line	Data
c0880485 NK	1	If you are experiencing hangups/data-aborts when trying to display a BMP image,
	2	the following might be relevant to your situation...
	3
	4	Some architectures cannot handle unaligned memory accesses, and an attempt to
	5	perform one will lead to a data abort. On such architectures it is necessary to
	6	make sure all data is properly aligned, and in many situations simply choosing
	7	a 32 bit aligned address is enough to ensure proper alignment. This is not
	8	always the case when dealing with data that has an internal layout such as a
	9	BMP image:
	10
	11	BMP images have a header that starts with 2 byte-size fields followed by mostly
	12	32 bit fields. The packed struct that represents this header can be seen below:
	13
	14	typedef struct bmp_header {
	15	/* Header */
	16	char signature[2];
	17	__u32 file_size;
	18	__u32 reserved;
	19	__u32 data_offset;
	20	... etc
	21	} __attribute__ ((packed)) bmp_header_t;
	22
	23	When placed in an aligned address such as 0x80a00000, char signature offsets
	24	the __u32 fields into unaligned addresses (in our example 0x80a00002,
	25	0x80a00006, and so on...). When these fields are accessed by U-Boot, a 32 bit
	26	access is generated at a non-32-bit-aligned address, causing a data abort.
	27	The proper alignment for BMP images is therefore: 32-bit-aligned-address + 2.