docs/keep_data_small.txt

   1                 Keeping data small
   2
   3 When many applets are compiled into busybox, all rw data and
   4 bss for each applet are concatenated. Including those from libc,
   5 if static busybox is built. When busybox is started, _all_ this data
   6 is allocated, not just that one part for selected applet.
   7
   8 What "allocated" exactly means, depends on arch.
   9 On NOMMU it's probably bites the most, actually using real
  10 RAM for rwdata and bss. On i386, bss is lazily allocated
  11 by COWed zero pages. Not sure about rwdata - also COW?
  12
  13 In order to keep busybox NOMMU and small-mem systems friendly
  14 we should avoid large global data in our applets, and should
  15 minimize usage of libc functions which implicitly use
  16 such structures.
  17
  18 Small experiment to measure "parasitic" bbox memory consumption:
  19 here we start 1000 "busybox sleep 10" in parallel.
  20 busybox binary is practically allyesconfig static one,
  21 built against uclibc. Run on x86-64 machine with 64-bit kernel:
  22
  23 bash-3.2# nmeter '%t %c %m %p %[pn]'
  24 23:17:28 .......... 168M    0  147
  25 23:17:29 .......... 168M    0  147
  26 23:17:30 U......... 168M    1  147
  27 23:17:31 SU........ 181M  244  391
  28 23:17:32 SSSSUUU... 223M  757 1147
  29 23:17:33 UUU....... 223M    0 1147
  30 23:17:34 U......... 223M    1 1147
  31 23:17:35 .......... 223M    0 1147
  32 23:17:36 .......... 223M    0 1147
  33 23:17:37 S......... 223M    0 1147
  34 23:17:38 .......... 223M    1 1147
  35 23:17:39 .......... 223M    0 1147
  36 23:17:40 .......... 223M    0 1147
  37 23:17:41 .......... 210M    0  906
  38 23:17:42 .......... 168M    1  147
  39 23:17:43 .......... 168M    0  147
  40
  41 This requires 55M of memory. Thus 1 trivial busybox applet
  42 takes 55k of memory on 64-bit x86 kernel.
  43
  44 On 32-bit kernel we need ~26k per applet.
  45
  46 (Data from NOMMU arches are sought. Provide 'size busybox' output too)
  47
  48
  49                 Example 1
  50
  51 One example how to reduce global data usage is in
  52 archival/libunarchive/decompress_unzip.c:
  53
  54 /* This is somewhat complex-looking arrangement, but it allows
  55  * to place decompressor state either in bss or in
  56  * malloc'ed space simply by changing #defines below.
  57  * Sizes on i386:
  58  * text    data     bss     dec     hex
  59  * 5256       0     108    5364    14f4 - bss
  60  * 4915       0       0    4915    1333 - malloc
  61  */
  62 #define STATE_IN_BSS 0
  63 #define STATE_IN_MALLOC 1
  64
  65 (see the rest of the file to get the idea)
  66
  67 This example completely eliminates globals in that module.
  68 Required memory is allocated in inflate_gunzip() [its main module]
  69 and then passed down to all subroutines which need to access 'globals'
  70 as a parameter.
  71
  72
  73                 Example 2
  74
  75 In case you don't want to pass this additional parameter everywhere,
  76 take a look at archival/gzip.c. Here all global data is replaced by
  77 single global pointer (ptr_to_globals) to allocated storage.
  78
  79 In order to not duplicate ptr_to_globals in every applet, you can
  80 reuse single common one. It is defined in libbb/messages.c
  81 as struct globals *const ptr_to_globals, but the struct globals is
  82 NOT defined in libbb.h. You first define your own struct:
  83
  84 struct globals { int a; char buf[1000]; };
  85
  86 and then declare that ptr_to_globals is a pointer to it:
  87
  88 #define G (*ptr_to_globals)
  89
  90 ptr_to_globals is declared as constant pointer.
  91 This helps gcc understand that it won't change, resulting in noticeably
  92 smaller code. In order to assign it, use PTR_TO_GLOBALS macro:
  93
  94         PTR_TO_GLOBALS = xzalloc(sizeof(G));
  95
  96 Typically it is done in <applet>_main().
  97
  98 Now you can reference "globals" by G.a, G.buf and so on, in any function.
  99
 100
 101                 bb_common_bufsiz1
 102
 103 There is one big common buffer in bss - bb_common_bufsiz1. It is a much
 104 earlier mechanism to reduce bss usage. Each applet can use it for
 105 its needs. Library functions are prohibited from using it.
 106
 107 'G.' trick can be done using bb_common_bufsiz1 instead of malloced buffer:
 108
 109 #define G (*(struct globals*)&bb_common_bufsiz1)
 110
 111 Be careful, though, and use it only if globals fit into bb_common_bufsiz1.
 112 Since bb_common_bufsiz1 is BUFSIZ + 1 bytes long and BUFSIZ can change
 113 from one libc to another, you have to add compile-time check for it:
 114
 115 if(sizeof(struct globals) > sizeof(bb_common_bufsiz1))
 116         BUG_<applet>_globals_too_big();
 117
 118
 119                 Drawbacks
 120
 121 You have to initialize it by hand. xzalloc() can be helpful in clearing
 122 allocated storage to 0, but anything more must be done by hand.
 123
 124 All global variables are prefixed by 'G.' now. If this makes code
 125 less readable, use #defines:
 126
 127 #define dev_fd (G.dev_fd)
 128 #define sector (G.sector)
 129
 130
 131                 Word of caution
 132
 133 If applet doesn't use much of global data, converting it to use
 134 one of above methods is not worth the resulting code obfuscation.
 135 If you have less than ~300 bytes of global data - don't bother.
 136
 137
 138                 gcc's data alignment problem
 139
 140 The following attribute added in vi.c:
 141
 142 static int tabstop;
 143 static struct termios term_orig __attribute__ ((aligned (4)));
 144 static struct termios term_vi __attribute__ ((aligned (4)));
 145
 146 reduces bss size by 32 bytes, because gcc sometimes aligns structures to
 147 ridiculously large values. asm output diff for above example:
 148
 149  tabstop:
 150         .zero   4
 151         .section        .bss.term_orig,"aw",@nobits
 152 -       .align 32
 153 +       .align 4
 154         .type   term_orig, @object
 155         .size   term_orig, 60
 156  term_orig:
 157         .zero   60
 158         .section        .bss.term_vi,"aw",@nobits
 159 -       .align 32
 160 +       .align 4
 161         .type   term_vi, @object
 162         .size   term_vi, 60
 163
 164 gcc doesn't seem to have options for altering this behaviour.
 165
 166 gcc 3.4.3 and 4.1.1 tested:
 167 char c = 1;
 168 // gcc aligns to 32 bytes if sizeof(struct) >= 32
 169 struct {
 170     int a,b,c,d;
 171     int i1,i2,i3;
 172 } s28 = { 1 };    // struct will be aligned to 4 bytes
 173 struct {
 174     int a,b,c,d;
 175     int i1,i2,i3,i4;
 176 } s32 = { 1 };    // struct will be aligned to 32 bytes
 177 // same for arrays
 178 char vc31[31] = { 1 }; // unaligned
 179 char vc32[32] = { 1 }; // aligned to 32 bytes
 180
 181 -fpack-struct=1 reduces alignment of s28 to 1 (but probably
 182 will break layout of many libc structs) but s32 and vc32
 183 are still aligned to 32 bytes.
 184
 185 I will try to cook up a patch to add a gcc option for disabling it.
 186 Meanwhile, this is where it can be disabled in gcc source:
 187
 188 gcc/config/i386/i386.c
 189 int
 190 ix86_data_alignment (tree type, int align)
 191 {
 192 #if 0
 193   if (AGGREGATE_TYPE_P (type)
 194        && TYPE_SIZE (type)
 195        && TREE_CODE (TYPE_SIZE (type)) == INTEGER_CST
 196        && (TREE_INT_CST_LOW (TYPE_SIZE (type)) >= 256
 197            || TREE_INT_CST_HIGH (TYPE_SIZE (type))) && align < 256)
 198     return 256;
 199 #endif
 200
 201 Result (non-static busybox built against glibc):
 202
 203 # size /usr/srcdevel/bbox/fix/busybox.t0/busybox busybox
 204    text    data     bss     dec     hex filename
 205  634416    2736   23856  661008   a1610 busybox
 206  632580    2672   22944  658196   a0b14 busybox_noalign