Nallepuh

* Project to restore NallePuh *****************************

About AmigaOS4.1 version

	Originally created by Martin Blom
	First ported by Stephan Rupprecht
	Stephan Rupprecht has not been active since 2009 on OS4Depot.net.
	it has gone 13 years without any updates, it's now time to dust it off, 
	and get it working again. We (Damien Stewart and Kjetil Hvalstrand)
	believe something changed in the Petunia JIT compiler, and possibly some
	 of the OS4.1 internal emulation of the custom chips where removed. 
	This left NallePuh in a horrible state.

Please repport bugs and problems here:

	https://github.com/khval/NallePuh/issues

	Please do not report bugs in forums and comment sections.

What works with NallePuh on AmigaOS4.1

	HippoPlayer.
	Dpaint4 (starts, you can do simple drawings, most of the tools are broken)
	Payback (game sound now works)
	SamplitudeOpus Light 3.5
	Myst playable demo (CGX)
	Symphonie Pro player (Some sound quality issues, 15bit playback not supported.)
	Symphonie Pro Editor (works partially can be unstable, some sound issues.)

	if you find anything working, please report, 
	lets make this list longer.

	https://github.com/khval/NallePuh/issues/12

List of tested - unsupported is here:

	https://github.com/khval/NallePuh/edit/main/not-working.md

	If you find more thats not working, please report, 
	it saves people from wasting time on things that’s not working.
	
Not tested please report back. (2023)

	Music-X

	Musicline Editor 1.5

	SoundProbe
		(locks up when I press play. this might need CIAA/B Timers)

Changes in 1 October 2023 Version 1.2

	* Added Joy 1 and 2 fire button 1 and 2 support
	* Fixed install script
	* Fixed make_lha script
	* Updated docs and readme

Changes in 28 September 2023 Version 1.1

	* Added CIAA / Timer A
	* Added CIAA / Timer B
	* Added CIAA / Timer VSync
	* Added CIAB / Timer A
	* Added CIAB / Timer B
	* Added CIAB / Timer HSync
	(No support for Serial, Parallel Port, Joy Port A, Joy Port B)

	Candidates that might work with this addition are Games / Demos and Music
programs
	that freeze and locks up, (Please retest these programs.)

Changes in Nov. 2022

	* Added two missing PowerPC oppcodes to the exception handler.
	* VPOS/VPOSR support
	* ADKCON/ADKCONR is now handled correct.
	* libblitter.library is used.
	* Deprecated functions replaced.
	* Code cleanup, std style format.
	* Improved debugging (task name, etc).
	* Fixed/added a new GUI
	* Fixed/added iconify support
	* WB startup support
	* Load/save config file
	* Install script
	* Test button working (V0.6)
	* BBUSY flag is now set & cleared (V0.6)
	
Disclaimer:

	NallePuh for AmigaOS4.1 is not an Amiga hardware replacement project in
	software, it can never do what hardware does, because it depends on
multitasking
	for time keeping, if multitasking is disabled, it will try its best to get out
	of nano/micro waits in forbid states, but can't do any real time keeping if
that
	happens.

	NallePuh for AmigaOS4.1 is an exception handle, it does not hack function
calls, 
	it does not depend on external MMU libs, I wont call it a hack exactly.

	NallePuh does not fix broken software, if the mc680x0 game/application/demo,
	has bugs, there is nothing NallePuh can do to solve this issues.

	If you run several mc680x0 programs at the same time, that all depends on
	NallePuh. Then this can result in a unpredictable results. I know nothing
	that can be done about it.

	Programs that crash with DSI or ISI error, are unlikely to work, but plase
	check snoopy log, and make sure programs / demos / games are correctly
installed.
	some programs has poor sanity checks when opening libraries.

	Please install this libs from os4depot.net

	* ptreplayer.library 
	* powerpacker.library
	* reqtools.library
	
	Keep in mind cia.resource / misc.resource is not included, so some programs
	might refuse to run.

	Always start Nalle Puh first, if you don't timers might not be setup correct.
	(when program has frozen its already too late...)

Dependencies

	AmigaOS4.1 SDK can be downloaded from Hyperion Entertainment
	https://www.hyperion-entertainment.com/index.php/downloads?view=details&file=12
7
	
	Flexcat - needed for building language catalogs.
	http://os4depot.net/?function=showfile&file=development/misc/flexcat.lha
	
******************************************************************

Orginal ReadME 

Short:    Redirects any (hw-banging) sound program to AHI
Uploader: Martin Blom <martin()blom.org>
Author:   Martin Blom <martin()blom.org>
Type:     mus/misc
Requires: An MMU, 68020+, AHI v4, OS 3.5 for GUI mode
Version:  0.3

Q: What is "Nalle Puh"?
A: It's the Swedish name for Winnie the Pooh.

Q: Really?
A: Yup.

Q: But... Ehm. What does this program, "Nalle PUH", do?
A: It's a hack that intercepts some custom chip register accesses and
   turns them into AHI function calls.

Q: How?
A: By using the MMU to mark the page at $dff000 as invalid.

Q: Invalid? Doesn't that mean you will get an exception each time the OS
   or an application touches the registers?
A: Exactly.

Q: Isn't that kind of... slow?
A: You bet.

Q: How slow?
A: Unbearable.

Q: So the program is useless, then?
A: Not quite. It can be instructed to patch the OS and all applications that
   read or write to the custom chip registers, so that next time the 
   instruction is executed, no exception will be generated.

Q: How?
A: A new chip register area is created at $80dff000.  For the kickstart ROM,
   all modules except audio.device will be patched to access this address
   instead of $dff000. For applications, I simply guess when it's ok to
   patch the instructions.

Q: Is that fool-proof?
A: Of course not. It's a hack. A proof of concept. Nothing more.

Q: Alright then. So what programs can be redirected?
A: I've tried the following programs, and they seem to work:

   * audio.device
   * Digibooster 1.7
   * Musicline Editor 1.5
   * Octamed Soundstudio 1.03c
   * Protracker (version 2.3 and 4.0)
   * THX Sound System 2.3d.

   I've also tried the following, and they don't:
   
   * Delitracker 2.32
   * Newtracker
   * PlaySID

   (Note that Protracker disables multitasking and cannot be used with AHI
   drivers that are not interrupt based.)

   Previously, I wrote that Sid4Amiga also could be redirected, which is just
   plain stupid, since Sid4Amiga already uses AHI. Duh! Sorry, Paul.

Q: Will you extend Nalle PUH so the all of those program work?
A: Unlikely.

Q: Pretty, pretty please!
A: No. The source code is available. Why don't you give it a shot yourself?

Q: Because <insert lame excuse here>.
A: Too bad.

Q: Suppose I do fix the program, is there anything else I should do?
A: You could certanly improve the instruction patching method. And it could
   also be wise to set up a cachable Chip-RAM mirror so AHI won't have to
   mix the samples from a non-cachable memory area. 

Q: Hey! I found a memory leak: You don't close mmu.library! And you don't
   clean up the MMU tables fully either.
A: I know.  The custom chip register mirror must stay if applications were
   patched. mmu.library must not be flushed from memory, or we loose the
   mirror.


Version history:

0.1, 2001-04-23:	* Initial release.
0.2, 2001-04-28:	* Redirected logging to the listview in GUI mode.
			* Minor GUI updates.
0.3, 2001-05-04		* Clears insr. caches when patching applications.
			* Added a few more instr. patches (base relative).
			This means that I had to move the register mirror
			to $e00000. At least that area is unused on my A4000.
			* The GUI does not touch the Paula registers on exit, 
			unless the user has pressed "Test" at least once.
			* Final update! I've returned the sound card I
                        borrowed to write this hack. Thus, no more updates.