Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[bruceuncle]

As anyone who's been following the AMOS Manuals and AMOS Resource Kit project (project thread - http://www.ultimateamiga.co.uk/index.php/topic,9418.0.html) will have seen, I'm up to my neck in documentation.  Current task is the Reference Guide for AMOS Pro V2.0.

This lead me to a lot of delving into the AMOS Extension Libraries.  Many thanks to Lonewolf10 for:

That is exactly why I created the AMOS Extension Examiner, which has been available on Aminet since 18th March 2011:

http://aminet.net/dev/amos/ADBs_Ext_Examiner.lha

which inspired me to get stuck in and have a good look around.

As I'm doing all this work in a database system (makes it a lot easier to do searches, comparisons and distribution - see the project thread) I took the liberty of writing my own Extension Examiner in Access 2010 (Heresy!!!  ).  The results were then easily available to me for tracking down missing syntax and anomalies in AMOSPro.Lib for my current docs task. 

It was then that I discovered that all the stuff on Extensions in the AMOS Pro V2.0 release refers to differences between AMOS V1.3x and (presumably) AMOS Pro V1.0x - and the format has changed again for V2.0.  The most obvious is the "AP20" marker at the start of the offsets table.  So assembling AMOSPro_Tutorial/Extensions/|Music.s  will not produce AMOSPro_Music.Lib. 

But it's also obvious that the format in AMOSPro.Lib is slightly different too.  Which I suppose is not entirely relevant to extensions as AMOSPro.Lib is the 'main man' as far as AMOS is concerned and not an extension as such.  There' a $D9 $FD at the end of a couple the parameter strings and some use of $8000 as an instruction/function number.  However, it's got to follow the same format rules as an extension for the compiler to make use of it (initialisation, relocatable chunks for each instruction, what's passed in the registers, where AMOS stores its data, etc).

I've trawled the 'net looking for any info on V2.0 extension formats, but not turned up anything apart from a little more confusion (for me!).

I'll ask MadAngus (when he's settled in his new 'nest'    ) if we can add Extension Docs to the project as it's an important part of AMOS development.  When my current task is completed (still a few months off yet) I'll happily put my hand up to document Extension formats and writing them.

• Has anyone any info (docs, source, etc) on the V2.0 format and the differences to V1.0x and AMOS V1.3x?
• Are the includes files (in AMOSPro_Tutorial/Extensions) still valid for AMOS Pro V2.0?  |Music.s isn't, what about the rest?

Any help would be greatly appreciated and contribute enormously to the effort it's taking to get the definitive docs written.

[MadAngus]

I'll ask MadAngus (when he's settled in his new 'nest'    ) if we can add Extension Docs to the project as it's an important part of AMOS development.  When my current task is completed (still a few months off yet) I'll happily put my hand up to document Extension formats and writing them.

I'll add the AMOS Extensions Reference Guide to the todo list. However when we move onto that we will need to collaborate with Lonewolf10 and take the lead from him as he has a body of work already in place at Amiga Coding. He has also expressed his desire to do this project particularly the database side of things.

Considering the number of extensions and amount of work required, the more hands on deck the better .

[bruceuncle]

Considering the number of extensions and amount of work required, the more hands on deck the better

I've gained a fair understanding of the formats, just need some confirmation if anyone's got any. 

My current interest is solely in AMOSPro.Lib.  There's a few 'undocumented' instructions in there that look interesting.  I'd like to be able to find out what they do before I include some (or any!).  And it would be very helpful to know if anyone else knows anything about the stuff in AMOSPro.Lib.  I'll post a list of the 'undocumenteds' as soon as I get back to it.  They might be little gems or they might be abandoned leftovers  .  At least I managed to get the full set out of the library and into the database c/w their code offsets.  Piece of cake to find the 'missing' ones after that.  Not to mention picking up a couple of typos in the original help file again.

I used Resource to reverse-engineer AMOSPro_Music.Lib so's I can do a 'spot the difference' against the early format, for which there's a precious source in the Extensions tutorial.  I suspect that AMOSPro.Lib pulls a few tricks that an add-in extension wouldn't.  The relocatable library functions that can call each other is a bit of a pain as all the AFLINE exceptions that implement the concept have to be dealt with by hand (with a few macros to ease the pain).

At this stage, I'm interested solely in AMOS Pro V2.0 as originally distributed.  The rationale being that it is the base on which everything else is built.  So we need to be sure we've got an accurate doumentation of it.  If I'm not in need of respite care after that, I'd be only too happy to help out with anything else documentation-wise.
 
Anyway.  This is one of those little side distractions that make the main slog bearable  .

[MadAngus]

Assuming your not fed up with the digging, the AMOS Extensions Reference Guide would be something I would like yourself and Lonewolf10 to collaborate on. That is when you are ready. 

You already have a format for the guide and yours and Lonewolf10's knowledge and experience at extracting the undocumented features and of the 68k code base is invaluable and would be an ideal combination to make this reference guide happen. Not to mention the body of work already available at AmigaCoding.

With both the main reference and the extension reference available at some point, mequa would have a detailed analysis of the features and functions to use with the development of jAmos and xAmos.

If there are other areas of the resource kit you would rather work on we can discuss them once your current works complete and at that point I know were I am in the project.

[bruceuncle]

Only too happy to oblige.  But it will be quite a while before the full ref manual is complete (months).

I've made the mistake (sic) of checking the stuff out as I document it.  Which is really useful but time consuming!  Oh, well.  At least we'll be able to say it's 'exhaustive'.   

That's why I'm trying to get the quick-ref guides out for publishing as I come across them.  That way the patrons have something to chew on while they're waiting for the main course... 

In the meantime, a couple of interesting instructions have popped out:

Follow
Follow Off

They're both shown as instructions number 1188.  As far as I can make out they're at offset $0EBB4 from the library code start (don't quote me on that yet! - I haven't had time to delve in there and check my offset calcs are correct). 

If anyone konws anything about them, post to this thread.

[Lonewolf10]

    * Has anyone any info (docs, source, etc) on the V2.0 format and the differences to V1.0x and AMOS V1.3x?

V1.0x and V1.3x should be very similar (as AMOS Pro 1 is supposed to be compatible with V1.3 code) in terms of commands.
I do know that the data order in the extensions changes from AMOS to AMOS Pro (which is why extensions only work on one or the other, unless the author made 2 versions of the same extension - one for AMOS and the other for AMOSPro). I believe that the AMOS Pro extensions also contain extra data too.

    * Are the includes files (in AMOSPro_Tutorial/Extensions) still valid for AMOS Pro V2.0?  |Music.s isn't, what about the rest?

Music.s should be. Are you sure you have all the correct files it needs to assemble it? As Francois put alot of useful notes into it, some labels and/or code may have accidentally been broken.
The test extension I have written was based on the Colours extension sourcecode and I added my own code onto the end.

But it's also obvious that the format in AMOSPro.Lib is slightly different too.  Which I suppose is not entirely relevant to extensions as AMOSPro.Lib is the 'main man' as far as AMOS is concerned and not an extension as such.  There' a $D9 $FD at the end of a couple the parameter strings and some use of $8000 as an instruction/function number.  However, it's got to follow the same format rules as an extension for the compiler to make use of it (initialisation, relocatable chunks for each instruction, what's passed in the registers, where AMOS stores its data, etc).

The AMOSPro.Lib is a very special extension. It contains quite a large chunk of AMOS commands, but the first few "commands" are actually syntax specifics for the editor screen.
When AMOS was originally written, the executable was huge (it contained most of the commands and syntax specifics). Later AMOS was completely re-written, was renamed AMOS Pro and the executable shrunk in size as the rest of it was contained in AMOSPro.Lib

In the meantime, a couple of interesting instructions have popped out:

Follow
Follow Off

They're both shown as instructions number 1188.  As far as I can make out they're at offset $0EBB4 from the library code start (don't quote me on that yet! - I haven't had time to delve in there and check my offset calcs are correct). 

I'm not sure whether they are mentioned in the AMOS Pro manuals or not, but I believe they are used to follow what happens to a specific (or a list of) variables. I'm not sure it works, which is why it may be undocumented.
Have you tried seeing if they are in the AMOS help guide? (the "online help" series of text files included with AMOS Pro)

[bruceuncle]

Many thanks for the comprehensive reply - very much appreciated. 

Music.s should be. Are you sure you have all the correct files it needs to assemble it?

I'll try an assembly of Music.s and see what I get.  So far, I've been working the other way around - disassembling and comparing to source to see what the differences are.  The main one seems to be the insertion of "AP20" into a library file to identify it as AMOS Pro V2.0.  But AMOS Pro V2.0 will work quite happily with a library without that identifier embedded in it, as long as it follows the relocation rules.  So I'm thinking that it's there to switch the way AMOS uses a library (maybe).

Haven't got much further with the above as my main interest has been in a complete disassembly of AMOSPro.Lib to make sure I'm not missing anything for the Reference Manual.  Apart from the few peculiarities in the format for the instruction names and parameters, it behave just like any other library file (well, mostly  ).  The disassembly is ongoing as I've had to re-learn Resource (last time I used it was 20 years ago ...).  I've now got large chunks of AMOSPro.Lib in readable format and added a few macros to Resource to reformat the AFLINE interrupts in readable Rbsr, etc comments.  Don't want to spend too much time on it as my main task is the Reference Manual (and avoiding massive headaches from painstaking disassembly  ).  The great thing about Resource is that you can leave off and save the whole mess as a work-in-progress and come back to exactly where you left off later.

Follow
Follow Off

Not mentioned in either the Manual or the Help Files.  The base structure for the Reference Manual is the Help Files as they contain much more than the manual.  And have a useful grouping for the instructions.  As well as expanding that base into the format MadAngus and I have agreed on for the Reference Manual, corrections are being made and any undocumented stuff added.  It's all being done in a database, so that any chunks of it can be extracted to whatever level of detail is appropriate.  If you have a read through the (rather lengthy) AMOS Manuals / AMOS Pro Resource Kit thread http://www.ultimateamiga.co.uk/index.php/topic,9418.0.html you'll get an idea of where we're going with it.

I'm just about to post another bit in there to excuse why my last promised deliverable is running a bit late (testing it out as I go has turned up a few more errors and undocumented stuff...).

Thanks again.  Looking forward to getting together with you in a tour-de-force on extensions when the Reference Manual is complete.   

[bruceuncle]

I posted the above very late last night (being on the other side of the planet to the Olympics ...  ).

So, another example of why I queried how relevant are the includes in AMOS Pro V2.0:

The original format for a Resource Bank used two long words at the start (excluding the file header stuff) that pointed to the image and string elements.  The V2.0 format needed to include the DBL programs as well.  So, where to put it without breaking existing code?

As the first long word would always have zeros in its high word (because the pointer only ever needs values in the low word to do their job) François appears to have chosen to use that high word to indicate the new format.  If it's zeros, then it's the original format with only graphics and string elements and the first long word can be used as a pointer as originally intended.  If it's greater than zero, then it's the new format and the first word contains the number of element types in the bank.  When AMOS development ceased, this was usually $0003 - one each for images, strings and DBL programs.  But it's interesting to note that this was left open for more element types to be added - the Resource Bank Editor handles numbers greater than $0003 and safely tucks extra element types away without destroying them if it finds any.  It doesn't so anything with them, it just makes sure they're preserved.  I can't think what other element types would be useful, but it at least allows further expansion for third-party developers.

The Editor also handles both the old and new formats by simply testing that first word and adjusting the start position accordingly.

The two formats are (excluding the bank header stuff):

Old format

            dc.b    "Resource"
Start       dc.l    Images-Start    * Offset to the compressed images (optional)
            dc.l    Texts-Start     * Offset to the message list (optional)
            dc.l    0               * Reserved for future expansion
V2.0 format

            dc.b    "Resource"
Elements    equ     3               * Number of Element Types (can be more or less than 3)
            dc.w    Elements        * Element Types in this Bank
Start       dc.l    Images-Start    * Offset to the compressed images
            dc.l    Texts-Start     * Offset to the message list
            dc.l    DBL-Start       * Offset to the DBL programs

So, the Manual is out-of-date and inaccurate.  This lead me to wonder how out-of-date and inaccurate the original includes are as they all refer to V1.3 formats.

For example, how would I call an AMOSPro.Lib routine from an extension?

Enough for now.  I've shelved it until I get the docs finished.  Otherwise, they'll never get done!   

[bruceuncle]

Okay, okay.  I get it now.  After a lot of pouring over what docs and examples exist, it appears that the status when AMOS Pro V2.0 was released is as follows:

• François seems to have concentrated on maintaining full backward compatibility between AMOS Pro V2.0 back to AMOS The Creator V1.3.  This means that obsolete instructions were deprecated rather than removed entirely.  So the elusive Follow and Follow Off are still in AMOSPro.Lib to avoid changing the lookup tables and throwing the whole thing into incompatibility-nightmare-land.  If used in Pro V2.0 they just throw a syntax error.  They were replaced by the much more powerful Monitor instruction and its associated accessory.
• All the Extensions examples and includes files still work for that reason, even though a lot of the stuff was originally intended for V1.3.  Some of it has, on closer examination, been upgraded to V2.0 level but still refers to V1.3 in the comments.
• Any of the V2.0 specific stuff (and, no, I haven't even tried to track down what that may be yet!) is therefore easily accessible if you know what its 'instruction number' is and understand what it does.  It just may not be in the equates yet.  So updating the equates (when we find out what may be missing) would be a priority task.  I've got all the keywords, instruction numbers and offsets databased.  So it shouldn't be too difficult to do.  Coming up with unique names for updated equates files could be easily overcome by including "AP20" in the names.
• The only remaining mystery (for me anyway) is why François put that "AP20" identifier in the V2.0 libs.  But I expect we'll find out some day...

All the above is just my opinion of the situation.  So feel free to take it as such.

Must get on with other stuff, so that's all for now.  To be continued later...   

[bruceuncle]

Oops!

All the above is just my opinion of the situation.  So feel free to take it as such.

A good job I put that caveat in! 

That "AP20" identifier kept bugging me.  So I had a look at AMOSPro - the program that launches the whole thing.  And, sure enough, it's referenced there too.  A quick look (no, I haven't got time to do a full disassemble) showed that it seems to set a flag (in the AMOS data area?) and switches a pointer (to a different lookup table?).

So I disassembled enough of AMOSPro_Music.Lib to compare it to the |Music.s source supplied with AMOS Pro.  Sure enough, the first Rjsr macro I came across has an entirely different index number into the offsets table!  A bit further into the code and where |Music.s references calls to Rbsr L_Amiga.Lib (the workaround to make the Amiga.Lib calls relocatable) they have been completely replaced with straight Rjsr macros with index numbers.  This fits the AMOS Pro V2.0 pattern in its version of AMOSPro.Lib.

Conclusions?  I hesitate to make any after the previous post!    My favourite quote from 2011 was "2011 was the year that opinion replaced fact." by someone whose name I forget, but I think it was a political commentator.

Anyway, I'll stick my neck out and suppose that AMOSPro.Lib also contains a re-mapping table somewhere that it switches to when a non-V2.0 AMOS Library (one with out the "AP20" identifier) is loaded.  There's a suspiciously long table of offsets or vectors (?) straight after the table of instruction-names+parameters+index-numbers that you'd find in any AMOS library.  Up to that point, everything that |Music.s shows for the format of a library holds true (with a very few slightly different extras in the tables - well, it is the core library!).  Maybe that's used for the remapping?

Anyway, that is as much as I can do for now as I really must get on with the AMOS Basic Command Ref docs.  But it's certainly worth putting on the list "to be investigated - later".  The implication is that there is a completely different set of includes files needed to write extensions that take full advantage of the Pro V2.0 capabilities.  Though you can still use the supplied ones for most purposes.

Anyone else got the time to have a look? 

And the original includes set for AMOS Pro V2.0 must have been around in the 1990s.  Anyone ever seen or heard of them? 

It would be a real nightmare to have to build them up from scratch - even assuming that the AMOS data area couldn't have changed much...

[Lonewolf10]

A quick look (no, I haven't got time to do a full disassemble) showed that it seems to set a flag (in the AMOS data area?) and switches a pointer (to a different lookup table?).

The data area (which fills a whole lot of bytes) starting at Screen Base hasn't been fully documented. It's certainly possible that a whole bunch of various flags are set there.

Anyway, I'll stick my neck out and suppose that AMOSPro.Lib also contains a re-mapping table somewhere that it switches to when a non-V2.0 AMOS Library (one with out the "AP20" identifier) is loaded.  There's a suspiciously long table of offsets or vectors (?) straight after the table of instruction-names+parameters+index-numbers that you'd find in any AMOS library.  Up to that point, everything that |Music.s shows for the format of a library holds true (with a very few slightly different extras in the tables - well, it is the core library!).  Maybe that's used for the remapping?

Sounds interesting. I'm off work next week, so may have at look at that myself (assuming I don't forget).