SizeCoding - User contributions [en]

Linux

2024-03-15T17:32:26Z

Byteobserver: /* Additional Resources */ add Tiny bitfield based text renderer

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old XOR pattern:

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 10 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_<>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 or mmap directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Syncing audio with visuals is unfortunately not as easy as one would hope. Unlike many oldskool platforms, you can't just write audio and video data in your main loop and have everything work out nicely. The reason for this is that the audio is buffered with a relatively large buffer size, which is not easy to change. The effect of this is that audio writes will succeed instantly without blocking until about 1 second of audio has been written, and then the next write will block for about 1 second. This process then repeats. As you can imagine this means the visuals will run at about 1 FPS.

Even if you know the exact audio buffer size, it doesn't really help to synchronize things because the synchronization will be dependent on the CPU speed (as well as how much CPU time background processes are taking, etc). In order to synchronize things properly you will need to use a timer. See the Limiting FPS section below for how to do this. You are looking at a cost of about 22 bytes for this timer at the very least.

After you have a timer set up, you just need to decide on a target FPS and calculate how much audio you should write per frame. The general formula that you should write <tt>rate * channels * sample width in bytes / FPS</tt> bytes per frame. For example, if your intro runs at 50 FPS and your audio uses 16bit samples in stereo at 8000Hz, then you should write <tt>8000*2*2/50 = 640</tt> bytes of audio for every frame.

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program (all registers zeroed)
timer:
; NEW: smaller 18-byte setup!
add ax,0x142
push ecx
mov edx,esp
int 0x80
push 1000000000/50 ; 50 fps
add ebx,eax
jns timer

main:
xor eax,eax
mov al,3 ; read syscall
mov ebx,eax ; file descriptor of timer
mov dl,8 ; num bytes to read, edx can be any value >= 8
mov ecx,esp ; write timer expiration info to the stack
int 0x80 ; blocks until the next frame

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

<syntaxhighlight lang=nasm>
; assuming this is at the beginning of the program (all registers zeroed)
call callback ; set up signal handler initially

; assume eax < 65536, ebx = 1
mov ax,0x103 ; timer_create
dec ebx
push ebx
push 1 ; SIGHUP
push ebx
mov ecx,esp
mov edx,esp
int 0x80

mov ax,0x104 ; timer_settime
push 1000000000/50 ; 50 fps
push ebx
mov edx,esp
int 0x80

jmp $ ; loop forever

callback:
; assume eax < 256, ebx = 0
mov al,0x30 ; signal
inc ebx
mov ecx,callback
int 0x80 ; (re)install signal handler
ret
</syntaxhighlight>

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

=== Self modifying code ===
With the tiny ELF header we've been using, the code segment is not writable, and unfortunately we need to sacrifice some bytes to make it so.
So, in many cases it's better to avoid using self modifying code. But, if you want to try it out, there are two ways to go about it.
In the ELF header, the p_flags field stores the access permissions of the code memory (1=execute, 2=write, 4=read).
In the tiny header, p_flags overlaps with e_phoff, and e_phoff (the offset of the program header from the beginning of the file) needs to be 4.
So, the only option for p_flags is read-only (turns out that the execute bit doesn't matter, and it will be executable anyways).
To make the code writable, we have to change p_flags to 7 (6 and 3 also accomplish the same thing because some are implied by others).
To do this we can either use a less overlapped header, or we can use the mprotect syscall to change
the permissions.

See here for examples of some headers that allow you to change p_flags: http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html

The mprotect method is as follows:

<syntaxhighlight lang=nasm>
mov eax,0x7d ; mprotect
mov ebx,$$ ; start address to change permissions for
mov ecx,0x1000 ; number of bytes to change
mov edx,7 ; new permissions
int 0x80
</syntaxhighlight>

=== Getting the screen size ===

A lot of Linux intros have the screen resolution hard-coded, and some include many executables in the release, each for a different screen resolution. If you have enough space, you can easily get the screen resolution using the <tt>ioctl</tt> syscall.

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,0x36 ; ioctl
mov ebx,0 ; ***PUT THE FILE DESCRIPTOR FOR /dev/fb0 HERE***
xor ecx,ecx
mov ch,0x46 ; FBIOGET_VSCREENINFO
mov edx,esp
int 0x80
pop eax ; eax = horizontal resolution in pixels
pop ebx ; ebx = vertical resolution in pixels
</syntaxhighlight>

For more information about what you can do with ioctl on the framebuffer, see here: https://www.kernel.org/doc/html/latest/fb/api.html

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]
* [https://www.onirom.fr/wiki/blog/25-09-2022_tiny_bitfield_based_text_renderer/ Tiny bitfield based text renderer]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2022-02-11T00:28:22Z

Byteobserver: /* Method 1: timerfd */

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old XOR pattern:

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 10 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_<>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 or mmap directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Syncing audio with visuals is unfortunately not as easy as one would hope. Unlike many oldskool platforms, you can't just write audio and video data in your main loop and have everything work out nicely. The reason for this is that the audio is buffered with a relatively large buffer size, which is not easy to change. The effect of this is that audio writes will succeed instantly without blocking until about 1 second of audio has been written, and then the next write will block for about 1 second. This process then repeats. As you can imagine this means the visuals will run at about 1 FPS.

Even if you know the exact audio buffer size, it doesn't really help to synchronize things because the synchronization will be dependent on the CPU speed (as well as how much CPU time background processes are taking, etc). In order to synchronize things properly you will need to use a timer. See the Limiting FPS section below for how to do this. You are looking at a cost of about 22 bytes for this timer at the very least.

After you have a timer set up, you just need to decide on a target FPS and calculate how much audio you should write per frame. The general formula that you should write <tt>rate * channels * sample width in bytes / FPS</tt> bytes per frame. For example, if your intro runs at 50 FPS and your audio uses 16bit samples in stereo at 8000Hz, then you should write <tt>8000*2*2/50 = 640</tt> bytes of audio for every frame.

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program (all registers zeroed)
timer:
; NEW: smaller 18-byte setup!
add ax,0x142
push ecx
mov edx,esp
int 0x80
push 1000000000/50 ; 50 fps
add ebx,eax
jns timer

main:
xor eax,eax
mov al,3 ; read syscall
mov ebx,eax ; file descriptor of timer
mov dl,8 ; num bytes to read, edx can be any value >= 8
mov ecx,esp ; write timer expiration info to the stack
int 0x80 ; blocks until the next frame

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

<syntaxhighlight lang=nasm>
; assuming this is at the beginning of the program (all registers zeroed)
call callback ; set up signal handler initially

; assume eax < 65536, ebx = 1
mov ax,0x103 ; timer_create
dec ebx
push ebx
push 1 ; SIGHUP
push ebx
mov ecx,esp
mov edx,esp
int 0x80

mov ax,0x104 ; timer_settime
push 1000000000/50 ; 50 fps
push ebx
mov edx,esp
int 0x80

jmp $ ; loop forever

callback:
; assume eax < 256, ebx = 0
mov al,0x30 ; signal
inc ebx
mov ecx,callback
int 0x80 ; (re)install signal handler
ret
</syntaxhighlight>

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

=== Self modifying code ===
With the tiny ELF header we've been using, the code segment is not writable, and unfortunately we need to sacrifice some bytes to make it so.
So, in many cases it's better to avoid using self modifying code. But, if you want to try it out, there are two ways to go about it.
In the ELF header, the p_flags field stores the access permissions of the code memory (1=execute, 2=write, 4=read).
In the tiny header, p_flags overlaps with e_phoff, and e_phoff (the offset of the program header from the beginning of the file) needs to be 4.
So, the only option for p_flags is read-only (turns out that the execute bit doesn't matter, and it will be executable anyways).
To make the code writable, we have to change p_flags to 7 (6 and 3 also accomplish the same thing because some are implied by others).
To do this we can either use a less overlapped header, or we can use the mprotect syscall to change
the permissions.

See here for examples of some headers that allow you to change p_flags: http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html

The mprotect method is as follows:

<syntaxhighlight lang=nasm>
mov eax,0x7d ; mprotect
mov ebx,$$ ; start address to change permissions for
mov ecx,0x1000 ; number of bytes to change
mov edx,7 ; new permissions
int 0x80
</syntaxhighlight>

=== Getting the screen size ===

A lot of Linux intros have the screen resolution hard-coded, and some include many executables in the release, each for a different screen resolution. If you have enough space, you can easily get the screen resolution using the <tt>ioctl</tt> syscall.

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,0x36 ; ioctl
mov ebx,0 ; ***PUT THE FILE DESCRIPTOR FOR /dev/fb0 HERE***
xor ecx,ecx
mov ch,0x46 ; FBIOGET_VSCREENINFO
mov edx,esp
int 0x80
pop eax ; eax = horizontal resolution in pixels
pop ebx ; ebx = vertical resolution in pixels
</syntaxhighlight>

For more information about what you can do with ioctl on the framebuffer, see here: https://www.kernel.org/doc/html/latest/fb/api.html

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2022-02-10T16:58:31Z

Byteobserver: /* Method 1: timerfd */ smaller setup code for timerfd

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old XOR pattern:

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 10 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_<>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 or mmap directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Syncing audio with visuals is unfortunately not as easy as one would hope. Unlike many oldskool platforms, you can't just write audio and video data in your main loop and have everything work out nicely. The reason for this is that the audio is buffered with a relatively large buffer size, which is not easy to change. The effect of this is that audio writes will succeed instantly without blocking until about 1 second of audio has been written, and then the next write will block for about 1 second. This process then repeats. As you can imagine this means the visuals will run at about 1 FPS.

Even if you know the exact audio buffer size, it doesn't really help to synchronize things because the synchronization will be dependent on the CPU speed (as well as how much CPU time background processes are taking, etc). In order to synchronize things properly you will need to use a timer. See the Limiting FPS section below for how to do this. You are looking at a cost of about 22 bytes for this timer at the very least.

After you have a timer set up, you just need to decide on a target FPS and calculate how much audio you should write per frame. The general formula that you should write <tt>rate * channels * sample width in bytes / FPS</tt> bytes per frame. For example, if your intro runs at 50 FPS and your audio uses 16bit samples in stereo at 8000Hz, then you should write <tt>8000*2*2/50 = 640</tt> bytes of audio for every frame.

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program (all registers zeroed)
timer:
; NEW: smaller 18-byte setup!
add ax,0x142
push ecx
mov edx,esp
int 0x80
push 1000000000/50 ; 50 fps
add ebx,eax
jns timer

main:
xor eax,eax
mov al,3 ; read syscall
mov ebx,eax ; file descriptor of timer
mov dl,8 ; num bytes to read, edx can be any value >= 8
mov ecx,esp ; write timer expiration info to the stack
int 0x80

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

<syntaxhighlight lang=nasm>
; assuming this is at the beginning of the program (all registers zeroed)
call callback ; set up signal handler initially

; assume eax < 65536, ebx = 1
mov ax,0x103 ; timer_create
dec ebx
push ebx
push 1 ; SIGHUP
push ebx
mov ecx,esp
mov edx,esp
int 0x80

mov ax,0x104 ; timer_settime
push 1000000000/50 ; 50 fps
push ebx
mov edx,esp
int 0x80

jmp $ ; loop forever

callback:
; assume eax < 256, ebx = 0
mov al,0x30 ; signal
inc ebx
mov ecx,callback
int 0x80 ; (re)install signal handler
ret
</syntaxhighlight>

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

=== Self modifying code ===
With the tiny ELF header we've been using, the code segment is not writable, and unfortunately we need to sacrifice some bytes to make it so.
So, in many cases it's better to avoid using self modifying code. But, if you want to try it out, there are two ways to go about it.
In the ELF header, the p_flags field stores the access permissions of the code memory (1=execute, 2=write, 4=read).
In the tiny header, p_flags overlaps with e_phoff, and e_phoff (the offset of the program header from the beginning of the file) needs to be 4.
So, the only option for p_flags is read-only (turns out that the execute bit doesn't matter, and it will be executable anyways).
To make the code writable, we have to change p_flags to 7 (6 and 3 also accomplish the same thing because some are implied by others).
To do this we can either use a less overlapped header, or we can use the mprotect syscall to change
the permissions.

See here for examples of some headers that allow you to change p_flags: http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html

The mprotect method is as follows:

<syntaxhighlight lang=nasm>
mov eax,0x7d ; mprotect
mov ebx,$$ ; start address to change permissions for
mov ecx,0x1000 ; number of bytes to change
mov edx,7 ; new permissions
int 0x80
</syntaxhighlight>

=== Getting the screen size ===

A lot of Linux intros have the screen resolution hard-coded, and some include many executables in the release, each for a different screen resolution. If you have enough space, you can easily get the screen resolution using the <tt>ioctl</tt> syscall.

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,0x36 ; ioctl
mov ebx,0 ; ***PUT THE FILE DESCRIPTOR FOR /dev/fb0 HERE***
xor ecx,ecx
mov ch,0x46 ; FBIOGET_VSCREENINFO
mov edx,esp
int 0x80
pop eax ; eax = horizontal resolution in pixels
pop ebx ; ebx = vertical resolution in pixels
</syntaxhighlight>

For more information about what you can do with ioctl on the framebuffer, see here: https://www.kernel.org/doc/html/latest/fb/api.html

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

File format

2022-02-10T16:41:15Z

Byteobserver: /* Linux */ add details of Linux ELF file format

=File formats=

File formats describe the content of a file.

This page is not about:
* File systems which organize files on a partition
* Disk images which save a (disk) file system within one file
* Tape file formats, as they have a higher overhead usually

==IBM PC==

===COM===
System: MS-DOS

Header: 0 bytes see [https://en.wikipedia.org/wiki/COM_file here]

Native size unit: Bytes

Loads to: 0100h

Starts at:

File extension: .com

===EXE===
System: Windows

Header: 200+

Native size unit: Bytes

Loads to:

Starts at:

File extension: .exe

===ELF===
System: Linux

Header: 45 - 100+

Native size unit: Bytes

Loads to: Random location (see [https://en.wikipedia.org/wiki/Address_space_layout_randomization#Linux here])

Starts at: from 0x10000 to around 0x80000000 for 32bit binaries

File extension: none

==Atari ST==
===TOS===
System: Atari ST

Header: 32 Bytes

Native size unit: ???

Loads to:

Starts at:

File extension:

==Amiga==
===...===
System: Amiga

Header:

Native size unit: ???

Loads to:

Starts at:

File extension:

==Commodore 64==
===PRG===
System: CBM-DOS (Commodore, e.g. C64)

Header: 2 bytes (= start address)

Native size unit: Blocks (256 bytes including 2 bytes linking to next block)

Loads to: given address in header

Starts at: given address in header

File extension: .prg

===P00===
System: CBM-DOS / PC64 Emulator

Header: extended 26 bytes; also includes the name; see [http://unusedino.de/ec64/technical/formats/pc64.html here]

Native size unit: Blocks

Loads to: given address in header

Starts at: given address in header

File extension: .p00

==Atari 8bit==
===XEX, EXE, COM===
System: Atari

Header: 6 bytes or more (FF FF <start address> <end address>); see also [https://www.atarimax.com/jindroush.atari.org/afmtexe.html here]

Native size unit: ???

Loads to: given start address in header

Starts at: given end address in header

File extension: .exe .com .xex (any ending possible)

==Amstrad==
===BIN===
System: AMSDOS (Amstrad CPC)

Header: 128 bytes (includes filename, start address, end address, etc.; 95 unused bytes; see also [https://www.cpcwiki.eu/index.php/AMSDOS_Header AMSDOS-Header]

Native size unit: kb

Loads to: given start address in header

Starts at: given end address in header

File extension: .bin (on PC)

==Spectrum==
===Binary===
System: ZX Spectrum

Header: none

Native size unit: ???

Loads to: special loader required; usually a BASIC program

Starts at: see above

File extension: ??? usually delivered within a disk image (.trd)

Linux

2021-12-27T21:48:45Z

Byteobserver: /* Getting something on screen */ Typo

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old XOR pattern:

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 10 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_<>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 or mmap directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Syncing audio with visuals is unfortunately not as easy as one would hope. Unlike many oldskool platforms, you can't just write audio and video data in your main loop and have everything work out nicely. The reason for this is that the audio is buffered with a relatively large buffer size, which is not easy to change. The effect of this is that audio writes will succeed instantly without blocking until about 1 second of audio has been written, and then the next write will block for about 1 second. This process then repeats. As you can imagine this means the visuals will run at about 1 FPS.

Even if you know the exact audio buffer size, it doesn't really help to synchronize things because the synchronization will be dependent on the CPU speed (as well as how much CPU time background processes are taking, etc). In order to synchronize things properly you will need to use a timer. See the Limiting FPS section below for how to do this. You are looking at a cost of about 22 bytes for this timer at the very least.

After you have a timer set up, you just need to decide on a target FPS and calculate how much audio you should write per frame. The general formula that you should write <tt>rate * channels * sample width in bytes / FPS</tt> bytes per frame. For example, if your intro runs at 50 FPS and your audio uses 16bit samples in stereo at 8000Hz, then you should write <tt>8000*2*2/50 = 640</tt> bytes of audio for every frame.

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program (all registers zeroed)
mov ax,0x142 ; timerfd_create
int 0x80

mov ax,0x145 ; timerfd_settime
push ebx
push 1000000000/50 ; 50 fps
push ebx
mov bl,3 ; file descriptor of timer (returned by timerfd_create)
mov edx,esp
int 0x80

main:
; assume eax < 256, ebx = 3, edx >= 8
mov al,3
mov ecx,esp
int 0x80 ; block until next frame

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

<syntaxhighlight lang=nasm>
; assuming this is at the beginning of the program (all registers zeroed)
call callback ; set up signal handler initially

; assume eax < 65536, ebx = 1
mov ax,0x103 ; timer_create
dec ebx
push ebx
push 1 ; SIGHUP
push ebx
mov ecx,esp
mov edx,esp
int 0x80

mov ax,0x104 ; timer_settime
push 1000000000/50 ; 50 fps
push ebx
mov edx,esp
int 0x80

jmp $ ; loop forever

callback:
; assume eax < 256, ebx = 0
mov al,0x30 ; signal
inc ebx
mov ecx,callback
int 0x80 ; (re)install signal handler
ret
</syntaxhighlight>

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

=== Self modifying code ===
With the tiny ELF header we've been using, the code segment is not writable, and unfortunately we need to sacrifice some bytes to make it so.
So, in many cases it's better to avoid using self modifying code. But, if you want to try it out, there are two ways to go about it.
In the ELF header, the p_flags field stores the access permissions of the code memory (1=execute, 2=write, 4=read).
In the tiny header, p_flags overlaps with e_phoff, and e_phoff (the offset of the program header from the beginning of the file) needs to be 4.
So, the only option for p_flags is read-only (turns out that the execute bit doesn't matter, and it will be executable anyways).
To make the code writable, we have to change p_flags to 7 (6 and 3 also accomplish the same thing because some are implied by others).
To do this we can either use a less overlapped header, or we can use the mprotect syscall to change
the permissions.

See here for examples of some headers that allow you to change p_flags: http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html

The mprotect method is as follows:

<syntaxhighlight lang=nasm>
mov eax,0x7d ; mprotect
mov ebx,$$ ; start address to change permissions for
mov ecx,0x1000 ; number of bytes to change
mov edx,7 ; new permissions
int 0x80
</syntaxhighlight>

=== Getting the screen size ===

A lot of Linux intros have the screen resolution hard-coded, and some include many executables in the release, each for a different screen resolution. If you have enough space, you can easily get the screen resolution using the <tt>ioctl</tt> syscall.

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,0x36 ; ioctl
mov ebx,0 ; ***PUT THE FILE DESCRIPTOR FOR /dev/fb0 HERE***
xor ecx,ecx
mov ch,0x46 ; FBIOGET_VSCREENINFO
mov edx,esp
int 0x80
pop eax ; eax = horizontal resolution in pixels
pop ebx ; ebx = vertical resolution in pixels
</syntaxhighlight>

For more information about what you can do with ioctl on the framebuffer, see here: https://www.kernel.org/doc/html/latest/fb/api.html

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-27T21:36:18Z

Byteobserver: /* Syncing audio with visuals */

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 10 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_<>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 or mmap directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Syncing audio with visuals is unfortunately not as easy as one would hope. Unlike many oldskool platforms, you can't just write audio and video data in your main loop and have everything work out nicely. The reason for this is that the audio is buffered with a relatively large buffer size, which is not easy to change. The effect of this is that audio writes will succeed instantly without blocking until about 1 second of audio has been written, and then the next write will block for about 1 second. This process then repeats. As you can imagine this means the visuals will run at about 1 FPS.

Even if you know the exact audio buffer size, it doesn't really help to synchronize things because the synchronization will be dependent on the CPU speed (as well as how much CPU time background processes are taking, etc). In order to synchronize things properly you will need to use a timer. See the Limiting FPS section below for how to do this. You are looking at a cost of about 22 bytes for this timer at the very least.

After you have a timer set up, you just need to decide on a target FPS and calculate how much audio you should write per frame. The general formula that you should write <tt>rate * channels * sample width in bytes / FPS</tt> bytes per frame. For example, if your intro runs at 50 FPS and your audio uses 16bit samples in stereo at 8000Hz, then you should write <tt>8000*2*2/50 = 640</tt> bytes of audio for every frame.

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program (all registers zeroed)
mov ax,0x142 ; timerfd_create
int 0x80

mov ax,0x145 ; timerfd_settime
push ebx
push 1000000000/50 ; 50 fps
push ebx
mov bl,3 ; file descriptor of timer (returned by timerfd_create)
mov edx,esp
int 0x80

main:
; assume eax < 256, ebx = 3, edx >= 8
mov al,3
mov ecx,esp
int 0x80 ; block until next frame

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

<syntaxhighlight lang=nasm>
; assuming this is at the beginning of the program (all registers zeroed)
call callback ; set up signal handler initially

; assume eax < 65536, ebx = 1
mov ax,0x103 ; timer_create
dec ebx
push ebx
push 1 ; SIGHUP
push ebx
mov ecx,esp
mov edx,esp
int 0x80

mov ax,0x104 ; timer_settime
push 1000000000/50 ; 50 fps
push ebx
mov edx,esp
int 0x80

jmp $ ; loop forever

callback:
; assume eax < 256, ebx = 0
mov al,0x30 ; signal
inc ebx
mov ecx,callback
int 0x80 ; (re)install signal handler
ret
</syntaxhighlight>

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

=== Self modifying code ===
With the tiny ELF header we've been using, the code segment is not writable, and unfortunately we need to sacrifice some bytes to make it so.
So, in many cases it's better to avoid using self modifying code. But, if you want to try it out, there are two ways to go about it.
In the ELF header, the p_flags field stores the access permissions of the code memory (1=execute, 2=write, 4=read).
In the tiny header, p_flags overlaps with e_phoff, and e_phoff (the offset of the program header from the beginning of the file) needs to be 4.
So, the only option for p_flags is read-only (turns out that the execute bit doesn't matter, and it will be executable anyways).
To make the code writable, we have to change p_flags to 7 (6 and 3 also accomplish the same thing because some are implied by others).
To do this we can either use a less overlapped header, or we can use the mprotect syscall to change
the permissions.

See here for examples of some headers that allow you to change p_flags: http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html

The mprotect method is as follows:

<syntaxhighlight lang=nasm>
mov eax,0x7d ; mprotect
mov ebx,$$ ; start address to change permissions for
mov ecx,0x1000 ; number of bytes to change
mov edx,7 ; new permissions
int 0x80
</syntaxhighlight>

=== Getting the screen size ===

A lot of Linux intros have the screen resolution hard-coded, and some include many executables in the release, each for a different screen resolution. If you have enough space, you can easily get the screen resolution using the <tt>ioctl</tt> syscall.

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,0x36 ; ioctl
mov ebx,0 ; ***PUT THE FILE DESCRIPTOR FOR /dev/fb0 HERE***
xor ecx,ecx
mov ch,0x46 ; FBIOGET_VSCREENINFO
mov edx,esp
int 0x80
pop eax ; eax = horizontal resolution in pixels
pop ebx ; ebx = vertical resolution in pixels
</syntaxhighlight>

For more information about what you can do with ioctl on the framebuffer, see here: https://www.kernel.org/doc/html/latest/fb/api.html

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-27T21:14:32Z

Byteobserver: /* Getting the screen size */ Fix typo

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 10 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_<>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 or mmap directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program (all registers zeroed)
mov ax,0x142 ; timerfd_create
int 0x80

mov ax,0x145 ; timerfd_settime
push ebx
push 1000000000/50 ; 50 fps
push ebx
mov bl,3 ; file descriptor of timer (returned by timerfd_create)
mov edx,esp
int 0x80

main:
; assume eax < 256, ebx = 3, edx >= 8
mov al,3
mov ecx,esp
int 0x80 ; block until next frame

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

<syntaxhighlight lang=nasm>
; assuming this is at the beginning of the program (all registers zeroed)
call callback ; set up signal handler initially

; assume eax < 65536, ebx = 1
mov ax,0x103 ; timer_create
dec ebx
push ebx
push 1 ; SIGHUP
push ebx
mov ecx,esp
mov edx,esp
int 0x80

mov ax,0x104 ; timer_settime
push 1000000000/50 ; 50 fps
push ebx
mov edx,esp
int 0x80

jmp $ ; loop forever

callback:
; assume eax < 256, ebx = 0
mov al,0x30 ; signal
inc ebx
mov ecx,callback
int 0x80 ; (re)install signal handler
ret
</syntaxhighlight>

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

=== Self modifying code ===
With the tiny ELF header we've been using, the code segment is not writable, and unfortunately we need to sacrifice some bytes to make it so.
So, in many cases it's better to avoid using self modifying code. But, if you want to try it out, there are two ways to go about it.
In the ELF header, the p_flags field stores the access permissions of the code memory (1=execute, 2=write, 4=read).
In the tiny header, p_flags overlaps with e_phoff, and e_phoff (the offset of the program header from the beginning of the file) needs to be 4.
So, the only option for p_flags is read-only (turns out that the execute bit doesn't matter, and it will be executable anyways).
To make the code writable, we have to change p_flags to 7 (6 and 3 also accomplish the same thing because some are implied by others).
To do this we can either use a less overlapped header, or we can use the mprotect syscall to change
the permissions.

See here for examples of some headers that allow you to change p_flags: http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html

The mprotect method is as follows:

<syntaxhighlight lang=nasm>
mov eax,0x7d ; mprotect
mov ebx,$$ ; start address to change permissions for
mov ecx,0x1000 ; number of bytes to change
mov edx,7 ; new permissions
int 0x80
</syntaxhighlight>

=== Getting the screen size ===

A lot of Linux intros have the screen resolution hard-coded, and some include many executables in the release, each for a different screen resolution. If you have enough space, you can easily get the screen resolution using the <tt>ioctl</tt> syscall.

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,0x36 ; ioctl
mov ebx,0 ; ***PUT THE FILE DESCRIPTOR FOR /dev/fb0 HERE***
xor ecx,ecx
mov ch,0x46 ; FBIOGET_VSCREENINFO
mov edx,esp
int 0x80
pop eax ; eax = horizontal resolution in pixels
pop ebx ; ebx = vertical resolution in pixels
</syntaxhighlight>

For more information about what you can do with ioctl on the framebuffer, see here: https://www.kernel.org/doc/html/latest/fb/api.html

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-27T21:11:57Z

Byteobserver: Add code for getting the screen resolution

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 10 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_<>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 or mmap directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program (all registers zeroed)
mov ax,0x142 ; timerfd_create
int 0x80

mov ax,0x145 ; timerfd_settime
push ebx
push 1000000000/50 ; 50 fps
push ebx
mov bl,3 ; file descriptor of timer (returned by timerfd_create)
mov edx,esp
int 0x80

main:
; assume eax < 256, ebx = 3, edx >= 8
mov al,3
mov ecx,esp
int 0x80 ; block until next frame

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

<syntaxhighlight lang=nasm>
; assuming this is at the beginning of the program (all registers zeroed)
call callback ; set up signal handler initially

; assume eax < 65536, ebx = 1
mov ax,0x103 ; timer_create
dec ebx
push ebx
push 1 ; SIGHUP
push ebx
mov ecx,esp
mov edx,esp
int 0x80

mov ax,0x104 ; timer_settime
push 1000000000/50 ; 50 fps
push ebx
mov edx,esp
int 0x80

jmp $ ; loop forever

callback:
; assume eax < 256, ebx = 0
mov al,0x30 ; signal
inc ebx
mov ecx,callback
int 0x80 ; (re)install signal handler
ret
</syntaxhighlight>

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

=== Self modifying code ===
With the tiny ELF header we've been using, the code segment is not writable, and unfortunately we need to sacrifice some bytes to make it so.
So, in many cases it's better to avoid using self modifying code. But, if you want to try it out, there are two ways to go about it.
In the ELF header, the p_flags field stores the access permissions of the code memory (1=execute, 2=write, 4=read).
In the tiny header, p_flags overlaps with e_phoff, and e_phoff (the offset of the program header from the beginning of the file) needs to be 4.
So, the only option for p_flags is read-only (turns out that the execute bit doesn't matter, and it will be executable anyways).
To make the code writable, we have to change p_flags to 7 (6 and 3 also accomplish the same thing because some are implied by others).
To do this we can either use a less overlapped header, or we can use the mprotect syscall to change
the permissions.

See here for examples of some headers that allow you to change p_flags: http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html

The mprotect method is as follows:

<syntaxhighlight lang=nasm>
mov eax,0x7d ; mprotect
mov ebx,$$ ; start address to change permissions for
mov ecx,0x1000 ; number of bytes to change
mov edx,7 ; new permissions
int 0x80
</syntaxhighlight>

=== Getting the screen size ===

A lot of Linux intros have the screen resolution hard-coded, and some include many executables in the release, each for a different screen resolution. If you have enough space, you can easily get the screen resolution using the <tt>ioctl</tt> syscall.

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,0x36 ; ioctl
mov ebx,0 ; ***PUT THE FILE DESCRIPTOR FOR /dev/fb0 HERE***
xor ecx,ecx
mov ch,0x46 ; FBIOGET_FSCREENINFO
mov edx,esp
int 0x80
pop eax ; eax = horizontal resolution in pixels
pop ebx ; ebx = vertical resolution in pixels
</syntaxhighlight>

For more information about what you can do with ioctl on the framebuffer, see here: https://www.kernel.org/doc/html/latest/fb/api.html

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-04T02:28:46Z

Byteobserver: /* Combining audio and video */

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 10 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_<>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 or mmap directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program (all registers zeroed)
mov ax,0x142 ; timerfd_create
int 0x80

mov ax,0x145 ; timerfd_settime
push ebx
push 1000000000/50 ; 50 fps
push ebx
mov bl,3 ; file descriptor of timer (returned by timerfd_create)
mov edx,esp
int 0x80

main:
; assume eax < 256, ebx = 3, edx >= 8
mov al,3
mov ecx,esp
int 0x80 ; block until next frame

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

<syntaxhighlight lang=nasm>
; assuming this is at the beginning of the program (all registers zeroed)
call callback ; set up signal handler initially

; assume eax < 65536, ebx = 1
mov ax,0x103 ; timer_create
dec ebx
push ebx
push 1 ; SIGHUP
push ebx
mov ecx,esp
mov edx,esp
int 0x80

mov ax,0x104 ; timer_settime
push 1000000000/50 ; 50 fps
push ebx
mov edx,esp
int 0x80

jmp $ ; loop forever

callback:
; assume eax < 256, ebx = 0
mov al,0x30 ; signal
inc ebx
mov ecx,callback
int 0x80 ; (re)install signal handler
ret
</syntaxhighlight>

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

=== Self modifying code ===
With the tiny ELF header we've been using, the code segment is not writable, and unfortunately we need to sacrifice some bytes to make it so.
So, in many cases it's better to avoid using self modifying code. But, if you want to try it out, there are two ways to go about it.
In the ELF header, the p_flags field stores the access permissions of the code memory (1=execute, 2=write, 4=read).
In the tiny header, p_flags overlaps with e_phoff, and e_phoff (the offset of the program header from the beginning of the file) needs to be 4.
So, the only option for p_flags is read-only (turns out that the execute bit doesn't matter, and it will be executable anyways).
To make the code writable, we have to change p_flags to 7 (6 and 3 also accomplish the same thing because some are implied by others).
To do this we can either use a less overlapped header, or we can use the mprotect syscall to change
the permissions.

See here for examples of some headers that allow you to change p_flags: http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html

The mprotect method is as follows:

<syntaxhighlight lang=nasm>
mov eax,0x7d ; mprotect
mov ebx,$$ ; start address to change permissions for
mov ecx,0x1000 ; number of bytes to change
mov edx,7 ; new permissions
int 0x80
</syntaxhighlight>

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-04T02:28:04Z

Byteobserver: /* Method 3: shell loader */

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_<>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 or mmap directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program (all registers zeroed)
mov ax,0x142 ; timerfd_create
int 0x80

mov ax,0x145 ; timerfd_settime
push ebx
push 1000000000/50 ; 50 fps
push ebx
mov bl,3 ; file descriptor of timer (returned by timerfd_create)
mov edx,esp
int 0x80

main:
; assume eax < 256, ebx = 3, edx >= 8
mov al,3
mov ecx,esp
int 0x80 ; block until next frame

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

<syntaxhighlight lang=nasm>
; assuming this is at the beginning of the program (all registers zeroed)
call callback ; set up signal handler initially

; assume eax < 65536, ebx = 1
mov ax,0x103 ; timer_create
dec ebx
push ebx
push 1 ; SIGHUP
push ebx
mov ecx,esp
mov edx,esp
int 0x80

mov ax,0x104 ; timer_settime
push 1000000000/50 ; 50 fps
push ebx
mov edx,esp
int 0x80

jmp $ ; loop forever

callback:
; assume eax < 256, ebx = 0
mov al,0x30 ; signal
inc ebx
mov ecx,callback
int 0x80 ; (re)install signal handler
ret
</syntaxhighlight>

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

=== Self modifying code ===
With the tiny ELF header we've been using, the code segment is not writable, and unfortunately we need to sacrifice some bytes to make it so.
So, in many cases it's better to avoid using self modifying code. But, if you want to try it out, there are two ways to go about it.
In the ELF header, the p_flags field stores the access permissions of the code memory (1=execute, 2=write, 4=read).
In the tiny header, p_flags overlaps with e_phoff, and e_phoff (the offset of the program header from the beginning of the file) needs to be 4.
So, the only option for p_flags is read-only (turns out that the execute bit doesn't matter, and it will be executable anyways).
To make the code writable, we have to change p_flags to 7 (6 and 3 also accomplish the same thing because some are implied by others).
To do this we can either use a less overlapped header, or we can use the mprotect syscall to change
the permissions.

See here for examples of some headers that allow you to change p_flags: http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html

The mprotect method is as follows:

<syntaxhighlight lang=nasm>
mov eax,0x7d ; mprotect
mov ebx,$$ ; start address to change permissions for
mov ecx,0x1000 ; number of bytes to change
mov edx,7 ; new permissions
int 0x80
</syntaxhighlight>

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-03T23:35:27Z

Byteobserver: /* Miscellaneous Techniques */ add self modifying code section

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program (all registers zeroed)
mov ax,0x142 ; timerfd_create
int 0x80

mov ax,0x145 ; timerfd_settime
push ebx
push 1000000000/50 ; 50 fps
push ebx
mov bl,3 ; file descriptor of timer (returned by timerfd_create)
mov edx,esp
int 0x80

main:
; assume eax < 256, ebx = 3, edx >= 8
mov al,3
mov ecx,esp
int 0x80 ; block until next frame

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

<syntaxhighlight lang=nasm>
; assuming this is at the beginning of the program (all registers zeroed)
call callback ; set up signal handler initially

; assume eax < 65536, ebx = 1
mov ax,0x103 ; timer_create
dec ebx
push ebx
push 1 ; SIGHUP
push ebx
mov ecx,esp
mov edx,esp
int 0x80

mov ax,0x104 ; timer_settime
push 1000000000/50 ; 50 fps
push ebx
mov edx,esp
int 0x80

jmp $ ; loop forever

callback:
; assume eax < 256, ebx = 0
mov al,0x30 ; signal
inc ebx
mov ecx,callback
int 0x80 ; (re)install signal handler
ret
</syntaxhighlight>

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

=== Self modifying code ===
With the tiny ELF header we've been using, the code segment is not writable, and unfortunately we need to sacrifice some bytes to make it so.
So, in many cases it's better to avoid using self modifying code. But, if you want to try it out, there are two ways to go about it.
In the ELF header, the p_flags field stores the access permissions of the code memory (1=execute, 2=write, 4=read).
In the tiny header, p_flags overlaps with e_phoff, and e_phoff (the offset of the program header from the beginning of the file) needs to be 4.
So, the only option for p_flags is read-only (turns out that the execute bit doesn't matter, and it will be executable anyways).
To make the code writable, we have to change p_flags to 7 (6 and 3 also accomplish the same thing because some are implied by others).
To do this we can either use a less overlapped header, or we can use the mprotect syscall to change
the permissions.

See here for examples of some headers that allow you to change p_flags: http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html

The mprotect method is as follows:

<syntaxhighlight lang=nasm>
mov eax,0x7d ; mprotect
mov ebx,$$ ; start address to change permissions for
mov ecx,0x1000 ; number of bytes to change
mov edx,7 ; new permissions
int 0x80
</syntaxhighlight>

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-03T23:13:19Z

Byteobserver: /* Limiting FPS */

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program (all registers zeroed)
mov ax,0x142 ; timerfd_create
int 0x80

mov ax,0x145 ; timerfd_settime
push ebx
push 1000000000/50 ; 50 fps
push ebx
mov bl,3 ; file descriptor of timer (returned by timerfd_create)
mov edx,esp
int 0x80

main:
; assume eax < 256, ebx = 3, edx >= 8
mov al,3
mov ecx,esp
int 0x80 ; block until next frame

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

<syntaxhighlight lang=nasm>
; assuming this is at the beginning of the program (all registers zeroed)
call callback ; set up signal handler initially

; assume eax < 65536, ebx = 1
mov ax,0x103 ; timer_create
dec ebx
push ebx
push 1 ; SIGHUP
push ebx
mov ecx,esp
mov edx,esp
int 0x80

mov ax,0x104 ; timer_settime
push 1000000000/50 ; 50 fps
push ebx
mov edx,esp
int 0x80

jmp $ ; loop forever

callback:
; assume eax < 256, ebx = 0
mov al,0x30 ; signal
inc ebx
mov ecx,callback
int 0x80 ; (re)install signal handler
ret
</syntaxhighlight>

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-03T18:44:15Z

Byteobserver: Add section about limiting fps

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Miscellaneous Techniques ==

=== Limiting FPS ===

The framebuffer device /dev/fb0 will allow you to write to it as quickly as your CPU can manage,
so your intro can run at different speeds depending on the CPU speed. To correct this, you can use
a timer to limit FPS. Beyond limiting the frame rate, using a timer is seemingly necessary if you
want to have synchronized sound and graphics (but more research is needed).

We will describe two approaches to setting up a timer. The first method uses the <tt>sys_timerfd_*</tt>
syscalls, which creates a file descriptor where reads block until the timer expires.
The second uses the <tt>sys_timer_*</tt> syscalls, which send signals that can be caught by installing a signal handler.
The first method is usually smaller.

==== Method 1: timerfd ====

<syntaxhighlight lang=nasm>
; assume this is placed at the beginning of the program
mov ax,0x142 ; timerfd_create
int 0x80

mov ax,0x145 ; timerfd_settime
push ebx
push 1000000000/50 ; 50 fps
push ebx
mov bl,3 ; file descriptor of timer (returned by timerfd_create)
mov edx,esp
int 0x80

main:
mov al,3
mov ecx,esp
int 0x80 ; block until next frame

jmp main
</syntaxhighlight>

==== Method 2: signal handler ====

TODO

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-01T16:27:28Z

Byteobserver: /* Allocating memory */

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Miscellaneous Tricks ==

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 15 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-01T16:26:24Z

Byteobserver: /* Allocating memory */

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Miscellaneous Tricks ==

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call brk with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 17 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-01T16:25:43Z

Byteobserver: /* Allocating memory */

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Miscellaneous Tricks ==

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit or to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call break with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 17 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-12-01T16:25:02Z

Byteobserver: Add section about allocating memory

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Miscellaneous Tricks ==

=== Allocating memory ===

On many Linux distros, the stack size is limited to 8MB by default. If this is not enough for your intro,
it is possible to increase this stack limit to to allocate memory in the data segment.

To allocate space in the data segment, you can use the brk system call (0x2d).
This call takes in a memory address and attempts to set the value of the current ''program break'' to that address,
then returns the new address. The program break is the smallest memory address that is beyond the data segment.
By default, the data segment is zero bytes long.
Unfortunately, on modern systems, the default value of the program break is
randomized, so you can't just simply call brk with the amount of memory you want.
Instead, you have to call break with an address of zero to get the current program break,
then add the amount of memory you want and call brk with the new address.
The following code does this in 17 bytes.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
mov al,0x2d
int 0x80
xchg eax,ebx
add ebx,0x1000000 ; allocate 16MB
mov al,0x2d
int 0x80
; eax now contains the address of the program break, i.e.,
; you can use memory from eax-0x1000000 to eax-1 (inclusive)
</syntaxhighlight>

To increase the stack size limit, you can use the setrlimit (0x4b) system call.
The following 11-byte snippet will remove the stack size limit completely.
Note that in some cases the user will not have permission to do this.

<syntaxhighlight lang=nasm>
; assuming all registers are zeroed, e.g., this is at the beginning of the program
dec ecx ; ecx = -1 aka set size to 'unlimited'
push ecx
push ecx
mov bl,3 ; RLIMIT_STACK
mov ecx,esp ; pointer to data for call
mov al,0x4b ; setrlimit
int 0x80
</syntaxhighlight>

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-11-30T16:40:12Z

Byteobserver: /* Method 3: shell loader */ fix syntax highlighting

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight lang=shell>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-11-30T05:50:00Z

Byteobserver: /* Adding Sound */

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method (method 1) is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method (method 2) uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers. Method 3, which saves some bytes over method 2 (especially when combined with visuals), is to use a shell based loader script.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-11-30T04:24:09Z

Byteobserver: /* Method 3: shell loader */

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed (aka remove the loader)
$_|aplay # execute the intro
rm $_ # remove the copy
exit # (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-11-30T04:22:20Z

Byteobserver: /* Method 3: shell loader */

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

Let's pick apart the shell loader. Remember that in bash, $_ is the last argument passed to the previous command,
and $0 is the filename of the current executable.

<syntaxhighlight>
cp $0 /tmp # copy the intro to /tmp
sed -i 1d $_/$0 # remove the first line from the copy with sed
$_|aplay # execute the intro
rm $_ # remove the copy
exit # exit (so that the binary data which follows doesn't get executed)
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-11-30T04:12:06Z

Byteobserver: Add Method 3

== Introduction ==
This section of the sizecoding.org wiki is about creating very small (<=256byte) 32-bit X86 based Linux binaries (ELF format).
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 Linux sizecoding.

A huge thanks goes out to byteobserver (Xorchitecture (2021) - https://www.pouet.net/prod.php?which=88982) as well as some early work by frag/fsqrt (Lintro (2012) - https://www.pouet.net/prod.php?which=58560) for all their research and hard work in producing tiny ELF binaries for linux.

=== Alternative methods and expectations ===
As the development of actual tiny ELF assembler executables on linux is still in its early days, with about a handful of actual <256 byte tiny ELF binary productions, lets look at some of the other methods of getting tiny intros onto linux.

'''1) Self-compilation tricks (using gcc or python):''' The executable executes a gcc (or python) compilation of the embedded code and executes it. This requires GCC and/or specific version of Python and potentially dynamically linked libraries to be installed.

'''2) Linking a piece of compiled C code to a stripped ELF header + dev/fb0 setup:''' This method has been used by The Orz to create
several sizecoded procedural graphics entries. For more information about this check out https://github.com/grz0zrg/tinycelfgraphics

'''So what can we realistically expect from a 256 intro on Linux?'''

Expect about ~100 byte cost for the ELF header, setting up fb0 , some form of update loop, framecounter and using either mmap setup or copying via pwrite64 to get you started. If you want audio as well, the avaialble byte-budget will shrink even more.

Additionally, since we're dealing with 32-bit code, expect some instructions (especially when dealing with direct values) to take up bit more space.

Lets hope this wiki page will inspire and help people to get started and create newer, better Linux tiny intros ;-)

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : Any X86-based Linux distribution that allows for execution of 32-bit executables.
* Assembler: NASM (or any other linux compatible 32-bit X86 assembler)

Furthermore, it is important that the user has access to the /dev/fb0 framebuffer.
This can be achieved by launching a virtual (fullscreen) console using CTRL-F3/F4 in most distributions, logging in and making sure the user is in the video group.
You can test if you are in the video group by running:

$ cp /dev/urandom /dev/fb0

which should cause the screen to fill with white noise before printing "no space left on device".
If this is not the case, you can add your user to the videogroup like so (substituting <tt>username</tt> for your username):

$ sudo usermod -a -G video username

After doing this you will need to log out and log back in for the changes to take effect.

Note: Make sure your binary is executable for everyone using the chmod 777 command after compilation :D

=== System Calls ===
Interaction with the Linux OS is mostly done via int 0x80 system calls.
This usually includes dealing with opening files/framebuffer/audio and handling timers.

A full list of system calls and their expected register arguments is available at:
https://syscalls32.paolostivanin.com/

=== ELF Header Information ===
Like a 32-bit windows executable, a 32-bit binary for linux comes with a pretty hefty ELF header.

<syntaxhighlight lang=nasm>
org 0x00010000
ehdr: ; Elf32_Ehdr
db 0x7F, "ELF", 1, 1, 1, 0 ; e_ident
times 8 db 0
dw 2 ; e_type
dw 3 ; e_machine
dd 1 ; e_version
dd _start ; e_entry
dd phdr - $$ ; e_phoff
dd 0 ; e_shoff
dd 0 ; e_flags
dw ehdrsize ; e_ehsize
dw phdrsize ; e_phentsize
dw 1 ; e_phnum
dw 0 ; e_shentsize
dw 0 ; e_shnum
dw 0 ; e_shstrndx

phdr: ; Elf32_Phdr
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dd $$ ; p_paddr
dd filesize ; p_filesz
dd filesize ; p_memsz
dd 5 ; p_flags
dd 0x1000 ; p_align

_start:

; your program here
</syntaxhighlight>

Luckily some parts of the ELF header can be repurposed and used to store some data and code.
There is quite an extensive journey about some header optimisations available at http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html for those that are interested.

After merging the ehdr and phdr parts and changing your entry point, we can get the header down to about the 48 bytes range with a nifty /dev/fb0 string inserted which we'll be able to use later for setting up the framebuffer.

<syntaxhighlight lang=nasm>
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
; this next instruction overlaps with a critical part of the elf header
; it needs to look like XX YY YY YY YY where YYYYYYYY=fname
; so you can change the register to something else or use push
; but the four byte pointer to fname cannot be changed.
mov ebx,fname ; e_phentsize, e_phnum

; e_shentsize, e_shnum, e_shstrndx are below but we can put whatever code/bytes we want there
mov cl,1 ; set read/write mode (1 or inc ecx is sufficient for pcopy method, read/write (2) is needed for mmap)
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3
</syntaxhighlight>

== Displaying Graphics ==
Graphics can be produced by using and accessing the linux /dev/fb0 framebuffer.
First the framebuffer has to be opened at the intro initialisation, and can then be used to either copy a piece of memory over using the pwrite64 syscall (0xb5) or using map a piece of memory directly to the framebuffer using syscall mmap.

==== Setting up the framebuffer ====
The dev/fb0 framebuffer can best be accessed from a virtual console (ctrl-f3/f4 in most distributions).

To make sure your dev/fb0 framebuffer is set up properly, you can apt get the fbset tool and display and/or alter the framebuffer resolution as most intros will make an assumption about the resolution of your framebuffer.

To test access to dev/fb0 framebuffer, you can use the following cat command:
<syntaxhighlight>
cat /dev/urandom > /dev/fb0
</syntaxhighlight>
which should produce random noise to the screen (ignorning the out of memory error that is expected from cat)

Alternatively, if you don't like to use the virtual console during the development of your intro, or the framebuffer setup is somehow giving you problems, there is a smalle fbe.c / fbe binary supplied with the xorchitecture intro by byteobserver that has a SDL windows mmap'ed to tmp/fb0 which you can launch alongside your intro (don't forget to redirect the dev/fb0 pointer in your intro to tmp/fb0).

==== Getting something on screen ====
First we need to fill up our local memorybuffer with pixeldata, so lets start doing that using the old AND pattern

<syntaxhighlight lang=nasm>
mov ecx,width*height
setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
and eax,edx ; xor pattern

mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
loop setpixels
</syntaxhighlight>

Once your buffer (in this case marked by the esp stackpointer) is all filled up with pixeldata, you
can copy it to the /dev/fb0 using the pwrite64 syscall like so:

<syntaxhighlight lang=nasm>
; copy memorybuffer to screen (/dev/fb0) using the pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
</syntaxhighlight>

As an alternative to using pwrite64 you can also mmap )check out intros by The Orz for an example with mmap) to map
a piece of memory to dev/fb0. However using mmap because you can get tearing, and you can't realistically do feedback effects without implementing a second buffer, as reading from the mmaped memory is VERY slow.

<syntaxhighlight lang=nasm>
;mmap(NULL, buflen, PROT_WRITE, MAP_SHARED, fd, 0);
push edx ;edx = 0
push eax ;fd
push byte 1 ;MAP_SHARED
mov al, 90
push eax ;we need to set second bit for PROT_WRITE, 90 = 01011010 and setting PROT_WRITE automatically set PROT_READ
push width*height*4 ;buffer size
push edx ;NULL
mov ebx, esp ;args pointer
int 80h ;eax <- buffer pointer
</syntaxhighlight>

== Example Framework ==

==== Munching squares ====
So when we put all the above together, we can get a minimal kind of framework running that will look something like this
munching square example provided to us by byteobserver:

<syntaxhighlight lang=nasm>
; byte.observer's munching square linux example
; assembles with nasm -fbin munch.asm -o munch
width equ 1024
height equ 768

bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4 ; e_phoff, p_flags
fname:
db "/dev/fb0",0 ; e_shoff, p_align, e_flags, e_ehsize
entry:
mov ebx,fname ; e_phentsize, e_phnum
inc ecx ; = 1 = O_WRONLY
mov al,5 ; 5 = open syscall
int 0x80 ; open /dev/fb0 = 3

mov ebp,width*height*4 ; ebp = screen size
sub esp,ebp ; make room on the stack for the video memory

mainloop:
mov ecx,ebp ; init pixel index
shr ecx,2 ; divide by bits per pixel
inc edi ; frame counter

setpixels:
mov ebx,width
mov eax,ecx
cdq
div ebx ; edx = x-coord , eax=y coord
xor eax,edx ; xor pattern
add eax,edi ; make it munch
mov [esp+ecx*4+0],al ; b
mov [esp+ecx*4+1],al ; g
mov [esp+ecx*4+2],al ; r
mov [esp+ecx*4+3],al ; a
loop setpixels

; dump the whole thing to the screen using pwrite64 syscall
mov ecx,esp ; buffer ptr
mov edx,ebp ; screen size
push edi ; save frame counter
xor esi,esi ; seek to beginning of screen
xor edi,edi
mov ebx,3 ; fd of framebuffer
mov eax,0xb5 ; pwrite64
int 0x80 ; pwrite64 to framebuffer
pop edi

jmp mainloop
</syntaxhighlight>

== Adding Sound ==
It is possible to output digital audio by binding the aplay command into your intro.
aplay is available on almost all Linux setups. You can test it by running the following, which should produce some white noise:

$ aplay /dev/urandom

By default, aplay will play 8-bit mono audio at 8000Hz, but the format can be changed easily by specifying arguments.
If no filename is passed to aplay, it will read audio data from standard input, which we will use to our
advantage.

To use aplay in the context of an intro, there is a bit of setup work involved.
The simplest method is to write audio data to standard output and pipe it to aplay on the command line.
A more clean and self-contained method uses 4 syscalls to start aplay
as a child process, so that audio data can then be simply written to the appropriate file descriptor to send it to
the speakers.

=== Method 1: pipe to aplay on the command line ===

The first method is the simplest, but will not be usable in all circumstances.
With this method, instead of running your intro with <tt>./intro</tt>, you have to do <tt>./intro | aplay 2>/dev/null</tt>,
which may not be allowed in some compos. However, with this method you can produce some extremely small generative music
intros, including some that are only 45 bytes---where the entire intro fits inside of the ELF header!

Some basic code to produce a bytebeat sound is below.
It simply consists of a loop which repeatedly writes a single 8-bit audio sample to standard output using the write syscall (0x4).

<syntaxhighlight lang=nasm>
audio:
; some bytebeat
inc esi
mov eax,esi
pop ebx ; grab previous sample from stack
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx ; push next sample to stack

mov ecx,esp ; pointer to audio data (the top of the stack)
xor eax,eax
mov al,4 ; write syscall
xor ebx,ebx
inc ebx ; write to stdout (1)
mov edx,ebx ; write 1 byte
int 0x80

jmp audio
</syntaxhighlight>

==== Case study: 45-byte generative music intro ====

Below is the complete 45-byte generative music intro.
Try saving it in a file called daemon45.asm and running it with:
$ nasm daemon45.asm
$ chmod +x daemon45
$ ./daemon45 0>&1 | aplay -fS32_LE -r16000 -c2

<syntaxhighlight lang=nasm>
; daemon 45 by byteobserver
bits 32
org $25500000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dw $001a ; e_entry, p_memsz
entry:
push eax
and eax,strict dword 4; e_phoff, p_flags
mov ecx,esp ; e_shoff, p_align
int $80
rdtsc ; e_flags
and edx,eax
loop entry ; e_ehsize
dw $20 ; e_phentsize
db 1 ; e_phnum
; e_shentsize
; e_shnum
; e_shstrndx
</syntaxhighlight>

Let's pull this apart and see how it works...

The first thing to notice that that the origin is 0x25500000, unlike the origin of 0x00010000 that we used before. This is intentional.
0x50 is the encoding of the <tt>push eax</tt> instruction, which appears after <tt>entry:</tt>,
and 0x25 is the first byte of the <tt>and eax,strict dword 4</tt> instruction. These instructions actually overlap
with the e_entry field of the header, so the high two bytes of the entry point (and origin) must match these instructions.
The word <tt>0x001a</tt> that appears immediately before <tt>entry:</tt> forms the low two bytes of the entry point, i.e.,
<tt>0x001a == (entry-$$)&0xffff</tt>.

The instruction <tt>and eax,strict dword 4</tt> may seem odd, since this instruction is encoded as <tt>2504000000</tt>, which
seems wasteful. However, doing <tt>and eax,4</tt> (which only takes 3 bytes) would not work here, because the dword 4
needs to be stored here so that e_phoff (the program header offset) is correct.

The rest of the code also overlaps the header, of course, but the fields that it overlaps are effectively ignored
when the program is loaded, so we don't need to worry about setting them to the correct values.

Now, lets strip away the header and see why this code actually produces the sound it does:

<syntaxhighlight lang=nasm>
entry:
push eax
and eax,strict dword 4
mov ecx,esp
int $80
rdtsc
and edx,eax
loop entry
</syntaxhighlight>

Clearly, this code is calling some syscall (because of the <tt>int $80</tt>), but which one is it calling?
The syscall number is stored in eax, and because of the instruction <tt>and eax,strict dword 4</tt>
we know that eax must either be 4 or 0. Syscall 4 is the write syscall, which is what we want. But
what is syscall 0? The docs say that syscall 0 is <tt>restart_syscall</tt>, which is used to
"restart a system call after interruption by a stop signal." The man page says
"This system call is designed only for internal use by the kernel." And, luckily
for us, when called from user space when the only other syscall we are using is write,
this has absolutely no effect, and will probably always return -1 (EINTR).
So, depending on eax&4, this code will either invoke the write syscall, or do nothing at all.
Which one is it? Well, the rdtsc instruction loads the low 32 bits of the CPU's
cycle counter into eax, and the high 32 bits into edx. So, whether we do a write
or not is effectively random depending on the current cycle count. Note that on
oldskool platforms, this may be quite deterministic, but on Linux the code is interrupted
many times a second, which causes effectively random fluctuations in the cycle count
that the program reads.

The write syscall takes three arguments: the file to write to (in ebx), a pointer to the data to write (in ecx), and the amount of data to write (in edx).

The code doesn't even mention ebx at all, and it is zeroed at program start. So this program writes to file descriptor 0, which is standard input.
Now, that sounds weird. It ''writes'' to standard ''input''? It turns out this is a perfectly fine thing to do, and we can redirect standard input to
standard output by using <tt>./daemon45 0>&1</tt> on the command line.

ecx is clearly set to equal esp, so the write syscall will be getting its data from the stack.

edx, the amount of data to write, is a bit more tricky. It is set to the bitwise and of the low 32 and high 32 bits of the CPU's cycle counter (rdtsc).
This may seem problematic, because this number might be larger than the size of the stack. However, the write syscall will stop either after writing edx bytes,
or when it encounters a memory access violation. So, it doesn't matter if edx is huge, because then it will just write the entire contents of the stack.

You may have noticed that the code has a <tt>push</tt> instruction but no corresponding <tt>pop</tt>. Won't it overflow the stack? Yes, eventually. But this takes quite a while.

So, overall what the program is does is it pushes the low 32 bits of the CPU's cycle counter to the stack, then
randomly plays a variable length chunk of the stack as audio, or does nothing. This repeats until the stack overflows, which on my machine takes at least half an hour (note: you can change the stack size by running <tt>ulimit -s unlimited</tt> beforehand, so that it will run until your RAM fills up completely). The output is quite variable depending on the cycle counter, which is only reset when your computer powers on. So, try running it after different amounts of time since power-on, and you may be surprised how different it can sound!

=== Method 2: pipe,fork,dup2,execve ===

This approach is as follows.
First, we create a pipe using the pipe syscall (0x2a).
This syscall takes a pointer to an array of 2 ints, which it fills with
the file descriptors of the two ends of the pipe. In the following,
we simply overwrite the top of the stack with the file descriptors. The first file descriptor is the read only/output side and the second is the write only/input side.

<syntaxhighlight lang=nasm>
mov ebx,esp
xor eax,eax
mov al,0x2a ; pipe
int 0x80
</syntaxhighlight>

Next, we fork the process (syscall 0x2). The child process will be used to exec aplay.
If you do this right after creating the pipe, you don't need to zero eax before setting it to 2, because eax should already be zero (indicating that the pipe was created successfully).

<syntaxhighlight lang=nasm>
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=1 in parent process
dec eax
js child

parent:
; code for the rest of your intro goes here
</syntaxhighlight>

Now, we bind the standard input of the child (which aplay receives audio data from) to the output of the pipe, using the dup2 syscall (0x3f).

<syntaxhighlight lang=nasm>
child:
xor eax,eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
xor ecx,ecx ; stdin is file descriptor 0
int 0x80
</syntaxhighlight>

The following is optional. aplay will usually print a message saying
some parameters of the stream that it is playing. If this interferes
with your intro, you can close stderr to stop it from printing,
with the close syscall (0x6).

<syntaxhighlight lang=nasm>
xor eax,eax
mov al,6 ; close
mov bl,2 ; stderr
int 0x80
</syntaxhighlight>

Finally, we just have to execute aplay with the execve syscall (0xb).
Constructing the arguments to this syscall takes a bit of work.
Here we are doing it in a simple way which is a bit wasteful.
You can save some bytes by constructing the arguments array
on the stack.

<syntaxhighlight lang=nasm>
xor eax,eax ; shouldn't be necessary given the above
mov al,0xb ; execve
mov ebx,aplay ; pointer to aplay filename
mov ecx,args ; pointer to null terminated array of arguments
lea edx,[esp+8] ; get pointer to environ. this assumes only one dword has been popped so far,
; and that there are no args passed to your program.
; see here: http://www.mindfruit.co.uk/2012/01/initial-stack-reading-process-arguments.html
; (we are trying to get the beginning of "Environment pointers")
int 0x80 ; nothing after this point will be executed

args:
dd aplay+5
dd 0
aplay:
db "/bin/aplay", 0
</syntaxhighlight>

Now everything should be set up, and we can start writing audio data with the write syscall (0x4). The following will produce a buzzing sound.

<syntaxhighlight lang=nasm>
parent:

audioloop:
xor eax,eax
mov al,4 ; write
mov ebx,[esp+4] ; input side of pipe created earlier
mov ecx,esp ; pointer to audio data
mov edx,1 ; length of audio data (in bytes)
int 0x80
inc byte [esp] ; increment the sample
jmp audioloop
</syntaxhighlight>

==== Putting it all together ====

Combining the above snippets and optimizing a bit, we can arrive at
the following 118 byte program which plays a familiar bytebeat track.

<syntaxhighlight lang=nasm>
bits 32
org $00010000
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd $$ ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
mov al,0x2a ; pipe
mov ebx,esp ; store output of pipe on stack
int 0x80
lea edx,[ebx+12] ; environ pointer, to be used later
mov ebp, entry ; e_phentsize, this must be here for the ELF header
mov al,2 ; fork
int 0x80 ; returns eax=0 in child process and eax=childpid in parent process
dec eax
js child

audioloop:
pusha
xor eax,eax
mov al,4 ; write
mov ebx,eax ; input side of pipe created earlier
lea ecx,[edx-12] ; pointer to audio data
xor edx,edx
inc edx ; set size to one byte
int 0x80
popa

; some bytebeat
inc esi
mov eax,esi
pop ebx
add ebx,eax
shr eax,5
or ebx,eax
shr eax,5
and ebx,eax
push ebx

jmp audioloop

child:
inc eax
mov al,0x3f ; dup2
pop ebx ; get file descriptor of output side of pipe
; ecx is already zero
int 0x80

mov al,0xb ; execve
lea ebx,[ebp+((aplay+5-entry)&0xff)] ; pointer to "aplay"
push 0 ; null terminator for args list
push ebx ; pointer to "aplay" aka argv[0]
; if you want to add more args to aplay, you can push pointers to them here
mov ecx,esp ; pointer to null terminated array of arguments
mov bl,(aplay-$$)&0xff ; pointer to "/bin/aplay"
; edx is already set up as the environ pointer
int 0x80 ; nothing after this point will be executed

aplay:
db "/bin/aplay"
; no null terminator is necessary because memory past the end of the file is always zero

</syntaxhighlight>

''Can you make this smaller? Feel free to edit it!''

=== Method 3: shell loader ===

Everything we've seen so far has been focused on producing a "pure" ELF binary, to
avoid the compatibility issues that plagued early Linux sizecoding techniques involving self compilation or
binary patching. However, there is a way to embed the ELF binary in a shell script to
save some bytes without sacrificing compatibility.

In method 1, we effectively moved the audio device handling out of the intro and put the
responsibility of connecting the intro to the audio device in the hands of the user.
This is obviously not ideal, and in method 2 we fixed this by opening the audio device
using syscalls. Here, we will use a hybrid approach. Our intro will appear to the
operating system as a shell script, which when executed will unpack the intro to /tmp
and then execute it, piping the output to aplay.

The following example of this approach assembles to a 101-byte file.

<syntaxhighlight lang=nasm>
bits 32
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay",10
org $00010000-($-$$)
top:
db $7F,"ELF" ; e_ident
dd 1 ; p_type
dd 0 ; p_offset
dd top ; p_vaddr
dw 2 ; e_type, p_paddr
dw 3 ; e_machine
dd entry ; e_version, p_filesz
dd entry ; e_entry, p_memsz
dd 4
entry:
inc ebx ; we will write to stdout (1)
main:
mov edx,esi ; copy time into edx
pop ecx ; grab previous sample from stack
; bytebeat formula
and ecx,edx
shr edx,5
mov ebp,entry ; useless, skips part of ELF header
xor ecx,edx
shr edx,5
or ecx,edx
push ecx ; write next sample

mov ecx,esp ; pointer to audio data (the top byte of the stack)
mov al,4 ; write syscall
mov edx,ebx ; write 1 byte
int 0x80

inc esi ; increment time

jmp main
</syntaxhighlight>

Note that this code will leave a file in /tmp after it exits, and will also write a bunch of garbage (the binary) to the screen when it exits.
Not only is this not very clean, but you may not be allowed to leave files around after your intro exits in some compos.
To fix this, we can use the following (slightly longer) shell loader:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_|aplay;rm $_;exit",10
</syntaxhighlight>

==== Combining audio and video ====

Although this method is already saving a lot of bytes, we haven't even gotten to the best part yet.
We can use the shell loader to also set up the framebuffer for us and make it very convenient to use, by using only 11 extra bytes!
To do this, just modify the loader as follows:

<syntaxhighlight lang=nasm>
db "cp $0 /tmp;sed -i 1d $_/$0;$_ 0>/dev/fb0|aplay",10
</syntaxhighlight>

With this loader, you can use pwrite64 directly on file descriptor 0 (stdin) to write to the screen, and write to file descriptor 1 (stdout) to play audio.
Just be careful to get the timing right if you're doing both audio and video, as the audio writes are blocking.

=== Playing MIDI ===

Coming soon...

=== Syncing audio with visuals ===

Coming soon...

== Additional Resources ==
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics A dev/fb0 framebuffer binding + ELF header for small C programs]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]

== Larger productions (1k and 4k intros) ==
Creating 1k and 4k intros on linux usually requires a different setup, for more information on this check out the following links:
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]

Linux

2021-11-29T21:57:12Z

Byteobserver: /* Method 2: pipe,fork,dup2,execve */ fix typo

Linux

2021-11-29T21:38:24Z

Byteobserver: /* Adding Sound */

Linux

2021-11-29T21:36:05Z

Byteobserver: /* Case study: 45-byte generative music intro */

Linux

2021-11-29T21:31:30Z

Byteobserver: /* Case study: 45-byte generative music intro */

Linux

2021-11-29T21:11:48Z

Byteobserver: Clarify setting up section

Linux

2021-11-29T21:07:45Z

Byteobserver: Fix typo

Linux

2021-11-29T19:57:37Z

Byteobserver: /* Case study: 45-byte generative music intro */

Linux

2021-11-29T19:11:58Z

Byteobserver: Adding section on simpler sound method

Linux

2021-11-29T17:00:23Z

Byteobserver: /* Putting it all together */

Linux

2021-11-29T16:59:32Z

Byteobserver: /* Putting it all together */

Linux

2021-11-29T16:55:22Z

Byteobserver: /* Adding Sound */

Linux

2021-11-29T16:53:36Z

Byteobserver: /* Adding Sound */

Linux

2021-11-29T02:36:11Z

Byteobserver: Add syntax highlighting to sound section

Linux

2021-11-29T01:54:19Z

Byteobserver: /* Adding Sound */

Linux

2021-11-29T01:53:26Z

Byteobserver: /* Adding Sound */

Linux

2021-11-29T01:37:30Z

Byteobserver: Writing linux audio section

Linux

2021-11-29T00:59:51Z

Byteobserver: Starting on sound section

Linux

2021-08-09T04:38:40Z

Byteobserver: /* Adding Sound */

Linux

2021-03-17T01:33:29Z

Byteobserver: /* Additional Resources */ Add additional links

== Introduction ==
For X86 related information, please check the main pages on this website, as a lot of the same tricks will also work with X86 linux sizecoding. This page goes into the specifics of getting small binaries on linux.

=== Linux system ===
To be added.

=== Setting up ===
Setting up your development platform for Linux development:

* Suggested Distributions : -
* Assembler: NASM (?)

=== ELF Header Information ===
To be added.

=== System Calls ===
To be added.

=== Self compilation ===
To be added.

== Accessing video ==
Accessing video

==== Getting something on screen ====
To be added soon.

== Sound ==
To be added soon.

==== Make some noise ====
To be added soon.

=== Additional Resources ===
* [https://pcy.ulyssis.be/pres/Lin.pdf The Intricacies of Sizecoding on Linux (PDF)]
* [https://www.pouet.net/prodlist.php?type%5B%5D=128b&platform%5B%5D=Linux Pouet: 128byte productions on Linux]
* [https://www.pouet.net/prodlist.php?type%5B%5D=256b&platform%5B%5D=Linux Pouet: 256byte productions on Linux]
* [https://github.com/grz0zrg/tinycelfgraphics Collection of tiny C ELF programs with graphics output]
* [http://www.muppetlabs.com/~breadbox/software/tiny/teensy.html A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux]
* [https://linux.weeaboo.software/Home Linux Sizecoding wiki at weeaboo.software]