porting checklist

porting checklist

[Rich Felker]

[-- Attachment #1: Type: text/plain, Size: 346 bytes --]

Hi all,
At Rob Landley's suggestion, here's a quick checklist of the
essentials for porting musl to a new arch. There's some duplication
with njk's porting guide, but I wrote this one just now off the top of
my head to be up-to-date. I'm hoping this will help speed up work
developing and integrating rdp's ports and any further new ports.

Rich

[-- Attachment #2: arch.txt --]
[-- Type: text/plain, Size: 3419 bytes --]

The following is a porting checklist for musl. It lists all essential
header and asm file locations that need to be ported to get a new arch
working on musl. It's grouped/ordered so that you can focus first on
getting a basic test program to run, then add features from there.



========================================================================
Requirements to be able to run anything at all:

crt: must provide entry point code to call __libc_start_main, and
_init/_fini function prologue/epilogue for the linker to paste
together with the calls provided by the compiler's crt functions.

arch/*/bits: headers for the arch's user and kernel abi. types which
are used in multiple headers are defined in alltypes.h.sh which is a
shell script that, when run, generates an alltypes.h full of the
necessary #ifdef directives to control which types are made visible.
generally, macro and struct definitions that do not seem to vary
between archs have been put directly in the main headers rather than
arch-specific bits headers, so if additional variations are found in
new archs, it may be necessary to reorganize some definitions into the
bits headers for both existing archs and the new arch.

arch/*/atomic.h: must provide certain atomic/asm ops. 32-bit and
pointer-size atomic cas are essential; everything else can be
implemented in terms of cas if no better implementation is possible.
the and/or ops do not need to be atomic on the whole object; really
they should be considered atomic set-bit/clear-bit functions.

src/internal: generic syscall code



========================================================================
Requirements for most single-threaded, static-linked programs to work:

src/setjmp: needs arch-specific setjmp/longjmp code. no signal mask
save/restore or unwinding is wanted or allowed.

src/signal: sa_restorer code for signal handler return must match what
gdb expects for the arch, and sigsetjmp must call sigprocmask and then
tail-call to setjmp.



========================================================================
Requirements for dynamic linking:

arch/*/reloc.h: this file is just a code fragment containing the
arch-specific parts of the dynamic linker. generally the types of
relocations that must be performed in do_single_reloc are the same for
most archs, but their names are arch-specific.

src/ldso: dlsym asm must pass the return address as the third argument
to __dlsym. _start is the dynamic linker entry point.


========================================================================
Requirements for threads:

src/thread: __unmapself must make an munmap syscall without touching
the stack then make the exit syscall. __set_thread_area must provide a
unified interface (same on all archs) for setting the thread pointer
register. syscall_cp must check cancellation flag and make a syscall,
and provide the proper labels so that the cancellation handler code
can determine if it was invoked at a cancellation point. clone
function always takes the desired thread pointer value as one of its
arguments (not a user_desc pointer on x86, etc.).

arch/*/pthread_arch.h: the __pthread_self function must return the
thread pointer (pthread_t) for the current thread. it may assume it
has already been initialized. the CANCEL_REG_IP is the word offset in
the arch's ucontext_t object of the saved instruction pointer, needed
for cancellation handling purposes.