Magazyn Exec 3/CD_Magazyn_EXEC_nr_3.iso/Programy/Biblioteki/ppclibemu07.lha/README

Text File | 1999-12-12 | 16KB | 459 lines

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


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

    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 SAS/C HunkObj format is supported since V0.6d. It uses an
    illegal version of 0 in the ELF header's e_ident[EI_VERSION] field.

    New in this release (V0.7):
    - Load and create new PPC tasks and threads from the PPC side:
      PPCLoadObject(), PPCLoadObjectTagList(), PPCUnLoadObject() and
      PPCCreateTask().
    - A limited implementation of PPCprintf().
    - PPCSetTaskAttrs().
    - Task priorities are recognized and converted into a nice-value.
    - PPCAllocMem/Vec() will return 32-byte aligned memory for
      compatibility reasons (there will be no cache line problems
      under WarpOS, though).
    - Asynchronous PPC tasks will inherit the current directory and
      PROGDIR: paths from their parent task. Before, all paths were
      reset to SYS:, which was a problem for many PowerUp programs,
      like MAME for example.
      No, I don't think that MAME will work now, but in some ver-
      sions you can already start a game (35.12 for example, which
      doesn't work at all with original PowerUp on my system. The
      latest 36.8 crashes a lot). MAME needs PortLists, which are
      still unsupported. Wait for V0.8 and a more stable MAME. :)

    The following functions from the original ppc.library are supported:
      o PPCLoadObject
      o PPCUnLoadObject
      o PPCRunObject
      o PPCAllocMem (NOCACHESYNCM68K simulated by allocating chip RAM)
      o PPCFreeMem
      o PPCAllocVec (NOCACHESYNCM68K simulated by allocating chip RAM)
      o PPCFreeVec
      o PPCCreatePool (NOCACHESYNCM68K simulated by allocating chip RAM)
      o PPCDeletePool
      o PPCAllocPooled
      o PPCFreePooled
      o PPCAllocVecPooled
      o PPCFreeVecPooled
      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
      o PPCSetTaskAttrs()

    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 PPCCreateTask
      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 PPCLoadObject
      o PPCLoadObjectTagList
      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 PPCReadByte
      o PPCReadLong
      o PPCReadWord
      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 PPCUnLoadObject
      o PPCVersion
      o PPCWait
      o PPCWaitPort
      o PPCWrite
      o PPCWriteByte
      o PPCWriteLong
      o PPCWriteWord
      o PPCXor64
      o PPCXor64p
      o PPCprintf
      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 Port lists (The documentation is nearly unusable, so if anybody
        knows exactly how to use port lists, then please mail me!)
      o Some stdio-compatible vararg functions in the kernel
        (this makes no sense IMHO, as va_list is compiler dependant
         and original ppc.library works with gcc only)
      o PPCDoMethodA/SuperMethodA (anybody with an example source?)
      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 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 with a CSPPC). Please use a
    Terminator setting of '1' or '0'. The emulation will not work with
    WarpOS in terminator-mode '2'.


INSTALLATION
    Just start the "Installer_Script". Or if you want to do it manually:

    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:powerpc/

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

    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 >NIL:
        [...]

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


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

    Please remove PPCInstall from your startup-sequence. You will get
    the same effect by using "loadlib path:ppc.library", but don't
    place the call before "C:Copy >NIL: ENVARC: RAM:ENV ALL NOREQ" !

    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
      0x08D45A40      0x00000000
      0x08586860      0x00000000
      0x08587280      0x00000000
      0x085868C0      0x00000000
      0x08586940      0x00000000
      0x08D45B50      0x00000000      __error
      0x08D45C38      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.

    threadtest.elf starts a PPC thread, using the PPCCreateTask()
    function implemented in V0.7, which counts from 1 to 10.


COMPATIBILITY
    The emulation is nearly complete, but still there might be some
    programs which don't run. 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 MAME and IsisPPC
    are starting now, but refuse to work some time later (MAME runs a
    lot better in V0.7, but depending on the MAME version used, still
    not good enough). Since V0.6d the SAS/C HunkObj files are supported,
    which means that the RC5-client will run under emulation. Also some
    more demos, like VA_OffShore, are running since this version (not
    on my P96 system - but it says "screen mode not found", so I think
    it should do on others :). Since V0.7 Frogger (an mpeg video player)
    works, which calls PPCCreateTask() to spawn new threads.

    The following list of programs should work under emulation:

      o Games: VDoom (PPCLoad or old PPCRun only!),
        ADoomPPC (when started by runelf, use "setenv DOOMWADDIR"),
        ADoM, HereticPPC, HexenPPC
      o Some demos: VAEDies, VAGhost, VA_OffShore, ...
      o musicin, musicout, mpeg2encode, "Lame" MP3 encoder
      o Packers: unlzx, lha, unrar, uuencode, uudecode, etc.
      o Emulators: PPCFrodo, AmigaVGBPPC, PCEmulator, UAE-PPC, Ami-Generator
      o Graphics: SManPPC, PowerView, Benoit, Reflections 4.3,
        Tornado 3D, ShowPPC
      o Anim: Ripley, Frogger
      o Misc: qmap, ADFLibPPC
      o ak-PPC-datatypes, SuperView NG
      o rc5des_PPC
      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 :).

    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.


SOURCE
    Since V0.7 the full source text of ppclibemu is included. This
    is because I can't guarantee that I always have enough time for
    ppclibemu (there are so many other projects to care for :).
    Other developers could take a look at the source and help me
    finding bugs or suggest improvements, while I am busy with other
    projects.

    To compile the source, you need vbcc 0.7, which also includes
    the required PhxAss and pasm assemblers, and a make-utility.
    I'm using GNU-make V3.74 (the SAS/C-compiled one). "Makefile"
    builds the standard ppc.library and "Makefile.debug" the
    ppc.library.debug, which does debugging output to the serial
    port. Check the include paths in the Makefiles and change them
    to your needs. The rest should fit.



Frank Wille                  12-Dec-1999                [e-mail]