Adding content to NewLib

Please read some previous guidelines on adding new software to NewLib.

Things to consider:

• Paths:

  • Under libsrc/_DEVELOPMENT:
    • Target independent code: just in libsrc/_DEVELOPMENTor subdirectory under it for better organization.
    • Target dependent code: specific directory under libsrc/_DEVELOPMENT/arch/<target>. Example: target-specific versions of SP1, Arkos
    • C stubs: they are commonly generated with c/{sccz80,sdcc_ix,sdcc_iy} directory structures inside their own directory, and they are normally target independent code (see previous point about location of target-independent code)
    • Examples: under libsrc/_DEVELOPMENT/EXAMPLES, in a dedicated directory for the library or software. A Makefile must be provided in that directory to easily compile all examples inside with a single command
  • Under include/_DEVELOPMENT:
    • Include files: create an M4 proto in include/_DEVELOPMENT/proto (see below)

• The main C Library list files (LST) for each target are stored in libsrc/_DEVELOPMENT/arch/<target>/library/{sccz80,sdcc_ix,sdcc_iy}/*.lst. They can be used as a starting point for identificating which other LST files to modify in order to include the new code in the compiled C library for the target.

• Compiled libraries are generated under libsrc/_DEVELOPMENT/lib/{sccz80,sdcc_ix,sdcc_iy} and they are used by the compiler in that location!

• Header .h files will be generated for SCCZ80 and SDCC (IX and IY) when bulding Z88DK, in include/_DEVELOPMENT/{sccz80,sdcc_ix,sdcc_iy} from M4 prototypes in include/_DEVELOPMENT/proto. Don't modify the generated files, do it with the proto ones.

• LST files must be adjusted (in created/modified directories and the ones above it) to take the correct paths into account.

• Remember that the SDCC_IX flavor of Newlib compilation shares the IX register between program code and the library. This means that any library calls must preserve IX, so e.g. a C assembler stub for a function which uses tail call optimization, could look like this for SDCC_IY mode:

  ;; void my_library_func( uint16_t arg ) __z88dk_callee;
  _my_library_func:
      pop bc       ;; save return address
      pop hl       ;; HL = arg
      push bc      ;; restore retaddr
      jp asm_my_library_func
  ;; end of function
  

  ...but in SDCC_IX mode the tail call optimization cannot be used, and instead it should be like this:

  ;; void my_library_func( uint16_t arg ) __z88dk_callee;
  _my_library_func:
      pop bc       ;; save return address
      pop hl       ;; HL = arg
      push bc      ;; restore retaddr
  
      push ix      ;; save IX for sdcc_ix
      call asm_my_library_func
      pop ix       ;; restore IX
      ret
  ;; end of function