Internal Application Format

Turbo uses its own application format described in this chapter.

The main blocks of the application are:

1. head containing the minimum information necessary for application loading
2. text section as produced by binutils
3. data section as produced by binutils

Internal Application Format

To convert the ELF object into the Turbo format we use the patched avr-objdump utility, open source GNU binutils based tool.

Relocation

Because AVR does not have any memory managemnt unit, the application has to be relocated to some memory position of sufficient size. In other application formats (e.g. ELF) this is usually done by relocation table(s) containing relocation items which are used for application runtime linking. Because Turbo has very limited memory space and we wanted to be able to load application via serial cable we use mixed approach - relocation items are inserted into the text/data (red colored boxes in the above picture). This solution allows linear reading and relocation.

Relocation Item Structure

Each relocation item consists of 3 fields in 5 bytes:

1. Next Relocation Address, 0xFFFF if there is no next relocation
2. Relocation Type
3. Relocation Value

The AVR instruction scheme uses several types of addressing, i.e. there are more different types of relocation as indicated in Relocation Type field. The relocation type is bit coded, following values are OR'ed:

#define TR_AVR_16       0
#define TR_AVR_LO8      1
#define TR_AVR_HI8      2
#define TR_AVR_HH8      3

#define TR_AVR_NEG      4
#define TR_AVR_PM       8

Further the MSB indicates the memory used - if set to 0 then PROGMEM, set to 1 means RAM.

Head

Application Head Structure

The head of Turbo application consists of:

1. Magic number - 0x01, 0x02
2. CRC - all following bytes XOR'ed
3. Offest - skip following offset bytes (e.g. manifest)
4. Text Length
5. Data Length
6. BSS Length
7. Reloc Start Address - address of the first relocation item
8. Address of turbo_handler()

Total PROGMEM is Text Length+Data Length, total RAM is Data Length + BSS Length.

Optional manifest can be inserted into the application file/head. The manifest is just a text viewed by user in "Detail" menu. It can be used e.g. for vendor, version, copyright or other info.

Application Manifest

Example

Here we show the real case of the helloworld.

#include <config.h>
#include <turbo/turbo.h>

u8 PROGMEM t_Foo_en[] = "Hello World!";

void action_menu (void *data)
{
  display_text_raw (t_Foo_en, Q_DISPLAY_TEXT_USER_CLEAR);
}

void turbo_handler (u8 action, void *data)
{
  switch (action)
  {
    case ACTION_INSERT_MENU:
      insert_menu (t_Foo_en);
      break;
    case ACTION_MENU_SELECTION:
      stk_thread (action_menu, data);
      break;
    default:
      break;
  }
}

We get the resulting 133 bytes (102 bytes if without --turbo-tag manifest) long hello_world.trb file:

00000000   01 02 9A 1F  01 1D 56 65  72 73 69 6F  6E 3A 20 31  ......Version: 1
00000010   2E 32 2E 33  20 56 65 6E  64 6F 72 3A  20 42 4C 41  .2.3 Vendor: BLA
00000020   44 4F 58 3A  00 00 00 00  00 10 00 1A  00 48 65 6C  DOX>.........Hel
00000030   6C 6F 20 57  6F 72 6C 64  21 00 00 60  E8 12 00 01  lo World!..a....
00000040   00 00 80 E0  26 00 02 00  00 90 E0 0E  94 8C EE 08  ....&...........
00000050   95 99 27 86  30 91 05 39  F0 0A 97 49  F4 28 00 01  ..'.0..9...I.(..
00000060   00 00 80 E0  30 00 02 00  00 90 E0 0E  94 DC ED 08  ....0...........
00000070   95 32 00 09  0E 00 80 E0  FF FF 0A 0E  00 90 E0 0E  .2..............
00000080   94 D4 ED 08  95                                     .....

Disassembled:

00000000 <t_Foo_en>:
   0:	48 65       	ori	r20, 0x58	; 88
   2:	6c 6c       	ori	r22, 0xCC	; 204
   4:	6f 20       	and	r6, r15
   6:	57 6f       	ori	r21, 0xF7	; 247
   8:	72 6c       	ori	r23, 0xC2	; 194
   a:	64 21       	and	r22, r4
	...

0000000e <action_menu>:
   e:	60 e8       	ldi	r22, 0x80	; 128
  10:	80 e0       	ldi	r24, 0x00	; RELOC
  12:	90 e0       	ldi	r25, 0x00	; RELOC
  14:	0e 94 00 00 	call	0x0		; display_text_raw(), ABS, fixed by avr-objdump --turbo
  18:	08 95       	ret

0000001a <turbo_handler>:
  1a:	99 27       	eor	r25, r25
  1c:	86 30       	cpi	r24, 0x06	; 6
  1e:	91 05       	cpc	r25, r1
  20:	39 f0       	breq	.+14     	; 0x30
  22:	0a 97       	sbiw	r24, 0x0a	; 10
  24:	49 f4       	brne	.+18     	; 0x38
  26:	80 e0       	ldi	r24, 0x00	; RELOC
  28:	90 e0       	ldi	r25, 0x00	; RELOC
  2a:	0e 94 00 00 	call	0x0		; insert_menu(), ABS, fixed by avr-objdump --turbo
  2e:	08 95       	ret
  30:	80 e0       	ldi	r24, 0x00	; RELOC
  32:	90 e0       	ldi	r25, 0x00	; RELOC
  34:	0e 94 00 00 	call	0x0		; stk_thread(), ABS, fixed by avr-objdump --turbo
  38:	08 95       	ret