---------- ppclibemu V0.6  - The ppc.library emulation for WarpOS ----------


INTRODUCTION
    The importance of WarpOS for PowerPC equipped Amigas is constantly
    increasing. OS3.5 will support WarpOS and future PowerPC G3/G4
    boards will also be based on this kernel.

    Some may like it and some not. I like features in both kernels,
    and in my opinion there must be a possibility to run most of the old
    PowerUp software under WarpOS in future. I'm also sick of rebooting
    my system, when switching the kernel. So the only solution is:
    ppc.library emulation under WarpOS!


FEATURES
    Since V0.5 you can start ELF objects directly (from shell or
    from Workbench). The emulation library installs a LoadSeg()-patch
    which detects and starts ELF objects. But in opposition to the
    original library, the patch can be removed when the library is
    expunged ("avail flush"). ;)

    Of course you can also start ELF objects by using SAS/C's RunElf,
    Ralph Schmidt's PPCLoad or vbcc's PPCRun.

    Since V0.6 the whole PowerUp message system is supported. It's
    slower than the original, but there is still room for improvement.

    The following functions of the original ppc.library are supported:
      o PPCLoadObject
      o PPCUnLoadObject
      o PPCRunObject
      o PPCAllocMem (MEMF_NOCACHESYNCxxx not supported)
      o PPCFreeMem
      o PPCAllocVec (MEMF_NOCACHESYNCxxx not supported)
      o PPCFreeVec
      o PPCDebugMode (private, doesn't work like the original)
      o PPCCreateTask
      o PPCDeleteTask
      o PPCGetTaskAttrs (not all tags supported)
      o PPCGetAttrs (PPCINFOTAG_EXCEPTIONHOOK not supported)
      o PPCReadLong
      o PPCWriteLong
      o PPCGetObjectAttrs
      o PPCWriteLongFlush
      o PPCReadWord
      o PPCWriteWord
      o PPCReadByte
      o PPCWriteByte
      o PPCCacheClearE
      o PPCCacheInvalidE
      o PPCCacheTrashE
      o PPCLoadObjectTagList
      o PPCCreatePort
      o PPCDeletePort
      o PPCObtainPort
      o PPCReleasePort
      o PPCWaitPort
      o PPCCreateMessage
      o PPCDeleteMessage
      o PPCGetMessage
      o PPCGetMessageAttr
      o PPCReplyMessage
      o PPCSendMessage

    The following functions of the original PowerUp kernel are supported:
      o PPCAdd64
      o PPCAdd64p
      o PPCAddHead
      o PPCAddHeadSync (implementation might be incorrect)
      o PPCAddTail
      o PPCAddTailSync (implementation might be incorrect)
      o PPCAllocMem (NOCACHESYNCM68K simulated by allocating chip RAM)
      o PPCAllocPooled (No pooled mem under WOS, same as PPCAllocMem)
      o PPCAllocSignal
      o PPCAllocVec (NOCACHESYNCM68K simulated by allocating chip RAM)
      o PPCAllocVecPooled (No pooled mem under WOS, same as PPCAllocVec)
      o PPCAnd64
      o PPCAnd64p
      o PPCAsl64
      o PPCAsl64p
      o PPCAsr64
      o PPCAsr64p
      o PPCAttemptSemaphore
      o PPCAttemptSemaphoreByName
      o PPCAttemptSemaphoreShared
      o PPCCacheFlush
      o PPCCacheFlushAll
      o PPCCacheInvalid
      o PPCCallM68k (Flags ignored. Asynchronous calls are synchronous.)
      o PPCCallOS (Flags ignored. Asynchronous calls are synchronous.)
      o PPCClose
      o PPCCloseLibrary
      o PPCCmp64
      o PPCCmp64p
      o PPCCreateMessage
      o PPCCreatePool
      o PPCCreatePort
      o PPCCreateSemaphore
      o PPCCreateTimerObject
      o PPCDeleteMessage
      o PPCDeletePool
      o PPCDeletePort
      o PPCDeleteTimerObject
      o PPCDeleteSemaphore
      o PPCDivRem64
      o PPCDivRem64p
      o PPCDivs64
      o PPCDivs64p
      o PPCDivu64
      o PPCDivu64p
      o PPCEnqueue
      o PPCEnqueueSync (implementation might be incorrect)
      o PPCFindName
      o PPCFindNameSync (implementation might be incorrect)
      o PPCFindTagItem
      o PPCFindTask
      o PPCFinishTask
      o PPCFreeMem
      o PPCFreePooled
      o PPCFreeSignal
      o PPCFreeVec
      o PPCFreeVecPooled
      o PPCGetAttr
      o PPCGetLibSymbol
      o PPCGetMessage
      o PPCGetMessageAttr
      o PPCGetTagData
      o PPCGetTaskAttr (not all tags supported)
      o PPCGetTimerObject
      o PPCInput
      o PPCInsert
      o PPCInsertSync (implementation might be incorrect)
      o PPCLsl64
      o PPCLsl64p
      o PPCLsr64
      o PPCLsr64p
      o PPCMods64
      o PPCMods64p
      o PPCModu64
      o PPCModu64p
      o PPCMuls64
      o PPCMuls64p
      o PPCMulu64
      o PPCMulu64p
      o PPCNeg64
      o PPCNeg64p
      o PPCNewList
      o PPCNextTagItem
      o PPCObtainPort
      o PPCObtainSemaphore
      o PPCObtainSemaphoreByName
      o PPCObtainSemaphoreShared
      o PPCOpen
      o PPCOpenLibrary
      o PPCOr64
      o PPCOr64p
      o PPCOutput
      o PPCRawDoFmt
      o PPCRead
      o PPCReleasePort
      o PPCReleaseSemaphore
      o PPCRemHead
      o PPCRemHeadSync (implementation might be incorrect)
      o PPCRemove
      o PPCRemoveSync (implementation might be incorrect)
      o PPCRemTail
      o PPCRemTailSync (implementation might be incorrect)
      o PPCReplyMessage
      o PPCRevision
      o PPCSeek
      o PPCSendMessage
      o PPCSetSignal
      o PPCSetTaskAttr (not all tags supported)
      o PPCSetTimerObject
      o PPCSignal (might not work, because of different task definitions)
      o PPCSub64
      o PPCSub64p
      o PPCVersion
      o PPCWait
      o PPCWaitPort
      o PPCWrite
      o PPCXor64
      o PPCXor64p
      o memcpy
      o strcmp
      o strcpy
      o strlen
      o __adddi3
      o __anddi3
      o __ashldi3
      o __ashrdi3
      o __cmpdi2
      o __divdi3
      o __fixdfdi
      o __fixsfdi
      o __fixunsdfdi
      o __fixunssfdi
      o __floatdidf
      o __floatdisf
      o __floatunsdidf
      o __iordi3
      o __lmulq
      o __lshldi3
      o __lshrdi3
      o __moddi3
      o __muldi3
      o __negdi2
      o __qdivrem
      o __subdi3
      o __ucmpdi2
      o __udivdi3
      o __umoddi3
      o __xordi3

    Unimplemented M68k functions will return with d0=0 and PPC
    functions return with r3=0.

    These are still missing:
      o Asynchronous 68k function calls
      o Exception handling, debugger support
      o Loading an ELF object from a PowerPC task
      o Port lists
      o Pooled memory support for M68k (missing in WarpOS)
      o PPCprintf and other vararg functions
      o PPCDoMethodA/SuperMethodA
      o Some tags are missing for the GetAttrs and GetTaskAttrs functions.


POWERUP DEVELOPERS
    If you are the author of a program, which doesn't work under
    emulation, then I need your help! Please try to determine the
    reason for crashes or failures in your source and tell me about the
    problem. I think the whole Amiga community would be very grateful!

    By using your source and the debugging facilities of ppclibemu it
    should be not too hard. Refer to the BUGS section for debugging
    informations.


REQUIREMENTS
    o 68040 or 68060
    o CyberstormPPC or BlizzardPPC
    o WarpOS V4 (powerpc.library V15)


BLIZZARD PPC NOTES
    You will get some problems on a BPPC with a new flash ROM, because
    the original ppc.library is a resident module and will be
    initialized during reset.

    The only chance is to use BPPCFix (should be included in the
    WarpOS V4 distribution) and install another resident module, which
    removes the ppc.library from the system before it can initialize
    itself. Refer to INSTALLATION for further informations.

    Afterwards you have a 'clean' system, which allows you to start
    WarpOS without using a Terminator (as on a CSPPC). Please use a
    Terminator setting of '1' or '0'. WarpOS will not work with the
    emulation in terminator-mode '2'.


INSTALLATION
    Save your original ppc.library:

      > copy libs:ppc.library libs:ppc.library.orig

    Copy the ppc.library emulation from this directory to libs:

      > copy ppc.library libs:

    Set the environment variable powerpc/NoPatch to "1":

      > setenv powerpc/NoPatch 1
      > copy ENV:powerpc/NoPatch ENVARC:

    Optionally, all these steps can be done automatically, by executing
    the INSTALL script:
      > execute INSTALL

    BLIZZARD PPC OWNERS ONLY:
      Disable the original ppc.library resident module with
        > BPPCFix install

      If you want to disable the original library for a longer
      time, you may also put the BPPCFix into your S:Startup-Sequence:
        ; $VER: Startup-Sequence_HardDrive 40.2 (25.2.93)
        ; Startup-Sequence for hard drive systems
        BPPCFix install reboot
        [...]

      If the fix is not already installed, it will do so and
      automatically reboot the system.

    Finally reboot your system to flush the old ppc.library.


USAGE
    Either you install the emulation ppc.library permamently in LIBS:
    or use "loadlib" to temporarily activate the emulation library. It
    can be completely flushed from the system at any time, by using
    "avail flush" (provided that no application needs it anymore).

    For a check, you might want to try some of the supplied test ELF
    objects, which were compiled by vbcc-ppc. For example:

      > hello_world.elf
      Hello World!

    or:
      > runelf hello_world.elf
      Hello World!

    timerobj.elf demonstrates the usage of TimerObjects.

    objattr_demo is a 68k program for testing the PPCGetObjectAttrs()
    function. For example, you can try to list all symbols of
    hello_world.elf:

      > objattr_demo hello_world.elf
      0x00000000      0x00000000
      0x00000000      0x00000000
      0x00000000      0x00000000
      0x00000000      0x00000000
      0x00000000      0x00000000
      0x00000110      0x00000000      __error
      0x000001F8      0x00000100      parse_cli_args
      [...]

    msgtest is a 68k program which starts an asynchronous PPC task
    (msgtest.elf) to test the message system. It sends one message
    to the PPC task and waits for reply.


COMPATIBILITY
    The emulation is nearly complete, but there is still a lot of
    stuff, which doesn't run. I would not be surprised if the compati-
    bility is far below 50%. Though, since the implementation of the
    message system emulation in V0.6, there are first life-signs from
    some of the 'difficult' candidates. For example M.A.M.E and IsisPPC
    are starting now, but refuse to work some time later. Most demos
    which run under PowerUp, e.g. VA_OffShore, don't work neither. I
    don't know which strange techniques they are using and have not the
    slightest chance to find it out.

    I don't have the time for testing numerous PowerUp programs,
    but the following should work:
      o ADoomPPC (when started by runelf, use "setenv DOOMWADDIR")
      o VDoom (PPCLoad or old PPCRun only!)
      o ADoM, HereticPPC, HexenPPC
      o Some demos: VAEDies and VAGhost
      o musicin, musicout
      o Packers: unlzx, lha, unrar, uuencode, uudecode, etc.
      o Emulators: PPCFrodo, AmigaVGBPPC, PCEmulator
      o qmap
      o SManPPC
      o PowerView
      o Benoit
      o Reflections 4.3
      o PowerUp developer examples
      o PowerUp demos: Plane, Mountain, Memtest


BUGS
    There are still some functions of ppc.library and the PowerUp kernel
    which are not supported (and there might be a lot of bugs in the
    functions which *are* supported :), so I'm not interested in bug
    reports like: "Program-xyz doesn't work...".

    If you get any difficulties (I'm sure you will :), then try to
    isolate the problem by enabling the debugging mode. You can
    enable debugging mode on the 68k-side by using the ppcdbmode
    utility:
      ppcdbmode 1      - enables all error requesters
      ppcdbmode 0x8000 - enables serial debugging (you can use Sushi)
    (or ppcdbmode 0x8001 to enable both).

    You can get full serial debugging (kernel emulation too) by
    exchanging ppc.library with ppc.library.debug. This is the
    recommended method - but execution will be *much* slower.

    If you think that you found a bug, then send me your serial debugging
    output, which you got from Sushi or a terminal. Also give me the name
    of the program and the arguments used. You should be able to determine
    by yourself, if it's a real bug or only an unimplemented function
    which causes the problems.



Frank Wille                  13-Apr-1999                frank@phoenix.owl.de