Updated Jaguar Documentation V10

[+cubanismo]

More typos:

 

• In the Software Reference RISC opcode appendix, the "NOT" instruction is listed as "NOR"
• In the Software Reference RISC opcode appendix, the SAT16S instruction is listed as GPU only, but it's DSP only.
• In the Software Reference RISC opcode appendix, the STORE instruction is missing parenthesis around its destination register.

[+DrTypo]

To complete cubanismo post, I also noticed a typo in the Software Reference RISC opcode appendix, in the UNPACK instruction description: "The reg1 field should be set to one to differentiate this from PACL". The last word should be "PACK".

 

 

[42bs]

I did some test on real HW to see what "undefined" or "unaffected" really means.

 

I added some notes to the PDF (currently mostly for C flag).

 

 

SoftRef_V10_ext.pdf

[alucardX]

2 hours ago, 42bs said:

I did some test on real HW to see what "undefined" or "unaffected" really means.

 

I added some notes to the PDF (currently mostly for C flag).

 

 

SoftRef_V10_ext.pdf 1.54 MB · 5 downloads

Are you just editing PDF in a program that allows for that or is there a source document floating around that is composed in an actual word processor document format?

[42bs]

I added notes. So no change to the original document.

Also I added some bookmarks for the opcodes.

Edited March 4 by 42bs

[alucardX]

Do you know if anyone has an original document? It would be nice to have in an easily editable format for anyone trying to offer changes.

[42bs]

7 hours ago, alucardX said:

Do you know if anyone has an original document? It would be nice to have in an easily editable format for anyone trying to offer changes.

I found at least one online editor. Adobe tools should also allow to edit the PDFs.

[42bs]

Here a version with fixed typos, annotations removed and added as normal text (in red).

I did this with an online PDF editor.

 

SoftRef_V10_ext.pdf

[+Stephen Moss]

10 hours ago, alucardX said:

Do you know if anyone has an original document? It would be nice to have in an easily editable format for anyone trying to offer changes.

I have it as a word document as I created the updated documents.

14 hours ago, 42bs said:

I did some test on real HW to see what "undefined" or "unaffected" really means.

 

I added some notes to the PDF (currently mostly for C flag).

When I have time I will take a look at adding your notes to the documents, unless you would like to take over the ongoing maintenance of them in which case I could give you all the relevant files.  

[42bs]

5 minutes ago, Stephen Moss said:

When I have time I will take a look at adding your notes to the documents, unless you would like to take over the ongoing maintenance of them in which case I could give you all the relevant files.  

You did a tremendous job, so please continue. But maybe put it on github/bitbucket or any other public repo. Unless you fear some vandalism.

 

Anyway, currently the flag stuff is my finding on a Model M Jaguar and the GPU, so it needs some others checking it also.

 

I will publish my "test" setup soon.

[42bs]

Here the test program to check timing or flags.

 

https://github.com/42Bastian/new_bjl/tree/main/exp/gpu_check

 

 

[alucardX]

I don't find a PDF editing solution to be a great ultimate solution and word is slightly better. There are two really good solutions that could be ultimately useful:

 

1) An OpenDocument format. Libreoffice allows you to export a PDF with the original document embedded. You open the PDF in LibreOffice Writer, make the changes to the original document then export it again making sure to embed the updated ODF in the PDF again. This is usable as a main solution but not as flexible as one would like. This would be better used at the end of a workflow for solution 2.

 

2) Text and markup which is then converted to other formats automatically using pandoc. In this way the workflow would be to update the text, then offer the converted text in other formats. This would allow a git repository to very easily track all changes since it is plain text.

 

I think this would be very useful for the community to have the updated document handled in this way.

[42bs]

We use ASCIIDOCTOR in our company. Though it is very handy for generating all kinds of formats (we use HTML and PDF), rewriting the whole document seems to be overkill given the fact that there are at max. 20 persons interested in an updated version.

 

If converting the M$ Word format to ODF will not destroy the formating, I'd also suggest to use ODF on the long run.

 

[alucardX]

It looks like Pandoc can go from docx to plain text, that may be an option. I didn't know about ASCIIDOCTOR so I'll check into that as well. Thanks for pointing that one out.

[42bs]

ASCIIDOCTOR is a markup language not a converter.

[+Stephen Moss]

On 3/5/2024 at 8:27 AM, 42bs said:

You did a tremendous job, so please continue. But maybe put it on github/bitbucket or any other public repo. Unless you fear some vandalism.

Thanks, while you have shown it is not impossible to prevent individuals making changes and releasing their own version, If I am to continue being responsible for the on going maintenance and updating (when I can find the time) then I would be inclined not to put it on a public repo.

 

Mainly as I don't really know that much about them and thus what version control methods are in place, for example...

can two two people edit it at the same time and if so what happens when each saves, are they merged, do the changes to section A in one get lost then get lost they are overwritten by second version one where changes were made to section B and not section A.

 

Thus for now I think that to try and maintain some semblance of version control and thus ensure that each new version of a document builds upon the changes made in the last rather than potentially having multiple versions floating around created by many different people all containing various random versions of updates that it would be better if potential updates/changes either...

1. Go through a small technical committee for verification before being forwarded to one individual responsible for the updating and maintenance of the documentation for updating or
2. Go directly to the person (be that myself or someone else willing to take over the updating and maintenance of the documentation) responsible for the updating and maintenance of the documentation for updating.

I am not sure I explained that very well but I hope it make sense.

 

On 3/5/2024 at 8:27 AM, 42bs said:

Anyway, currently the flag stuff is my finding on a Model M Jaguar and the GPU, so it needs some others checking it also.

It would be nice to know enough about Jaguar programming to be able to verify it myself, but as I don't my preference would be for a third party to verify it before I make any changes permanent so I would use the "subject to change" text colouring if it is goes in and the new version released with the changes still unverified.

I am not saying that your changes are necessarily wrong, inappropriate or in the wrong section, it is just that having a second party verify the information is correct and relevant increases confidence that no potentially incorrect/misleading changes are being added to the documentation.

[dilinger]

47 minutes ago, Stephen Moss said:

Mainly as I don't really know that much about them and thus what version control methods are in place, for example...

can two two people edit it at the same time and if so what happens when each saves, are they merged, do the changes to section A in one get lost then get lost they are overwritten by second version one where changes were made to section B and not section A.

You can put your file(s) in a google drive, this is free for a certain amount of GB.

People can edit file(s) at the same time, you can track the changes, etc. I use it since several years with other people.

[alucardX]

I think version control makes the most sense for something like this. Though a text version would be easier to manage under version control because then small changes get tracked very effectively just like in source code files.

 

Changes are not made simultaneously on the same document in something like git but rather in your own private branch. If the change is worth adding to the main branch then a pull request is made and the person running the project can choose to include it or not to.

 

I think we should look at what it would take to get that manual into a plain text format which can then be converted into any format from there. It would be nice to have the ability to build an epub document out of that for example.

[42bs]

Version control with GIT (on github or elsewhere) is easy. People can fork the docs and make a pull request. Only problem is that neither PDF, ODF or DOCX are diff-friendly.

 

But IMHO we should just start. So I suggest that @Stephen Moss puts the docx version of SoftRef on github and stays the "official" maintainer.

 

I used black for typo fixing and red for the additions which should be counter-checked but I propose for a pull request we should maybe use bold blue for typo fixes and red for additions. And since a diff is not possible note pages in the pull comment.

 

 

[alucardX]

If he wants to put the docx up I'll take a stab at converting to a plain text format so that version control can be more effective.

[+cubanismo]

git + docx/pdf/odf honestly sounds like kind of a nightmare. At Khronos (Maintainers of Vulkan/OpenGL/etc. specs, which I work on at my day job), we use asciidoctor as well for the newer specs, along with some conventions (E.g., newline after every sentence) to improve diff-ability of English language content, and it works out... OK. The older stuff is LaTeX, which I've managed to never actually learn myself, though many people still swear by it for technical document layout. Raw revision control of formatted documents is sort of hard, and honestly I think things like Google docs/Office365/etc. with the doc shared as read-only but readers allowed to make comments or suggested edits that the maintainer can apply with the click of a button work out better for this sort of collaboration, especially if the maintainer isn't a github/gitlab expert.

 

Asking @Stephen Moss to convert from Word -> asciidoctor or some other markup language after going through all the effort to create the Word version seems like a pretty heavy lift, unless someone has a tool that can get you 99% of the way there via automation, which given some of the non-trivial formatting in this document, doesn't seem likely. A conversion like that would be the sort of thing non-technical or technically-inclined-but-not-assembly-coder enthusiasts could probably do in their spare time though, especially if there were a handful willing to collaborate and tackle it in chunks.

 

Given I'm not actually going to do much contributing personally, my main concern with the source files not being public is Stephen gets hit by a bus or wanders off and they're just lost to time, like the originals.

 

Musings aside, thanks again for tackling this Stephen! The updated doc is a great asset for the community. I still need to get my SDK updated to include your updated, searchable docs instead of the ancient scans.

[alucardX]

I agree with you @cubanismo

 

Maybe a wiki would be a better solution than a PDF or word document? I know there is wiki software out there that will output a nice PDF file for export (or other formats too) I just think that maintaining something in a format other than a word processor or a "digital paper" (pdf - have you seen the markup code for a pdf? The shit wasn't meant to be edited) would be far more malleable and better for everyone in the community.

 

I'm still willing to look at trying to convert that document into a plaintext file. I've not use LateX myself but have heard that once you understand it, it's very flexible for layout.

[42bs]

A wiki needs also maintainers to fight vandalism. And also needs a lot of work to convert the docx.

[laoo]

I'm hesitating... but I'm not sure whether the formula for making amendments to the original documentation hasn't depleted. We are talking about documents rooted in original times with official information. It's ok to make corrections for example to PACK and UNPACK where the docs states that the flags are unaffected whilst it's a bug, but changing the entries where the docs says that the flag is "undefined" isn't the way to do, because the engineers did not defined them and it just happens that they are as they are. It's the same as with "undefined" opcodes of 6502 or Z80 etc. There are some bizarre commands in undefined space but it would be a mistake to alter official docs of 6502 to include that behavior.

That said, I believe we just need a new documentation with new findings specifying originally unspecified facts and with the official docs only correcting errors.

There are plenty such initiatives for other platforms.

There are specs for Nintendo systems written by emulator's author:

• http://problemkaputt.de/gbatek.htm
• http://problemkaputt.de/fullsnes.htm
• http://problemkaputt.de/everynes.htm

There are sacred tech scrolls written by other enthusiast:

• http://perfectkiosk.net/stsws.html
• http://perfectkiosk.net/stsvb.html
• http://perfectkiosk.net/ststgc.html

 

I think it's a quite good convention / format. Especially that I don't find official docs succint enough and easy to read (and I find it even as a sort of marketing pamphlet in some places, but that was its purpose - to lure game programmers of the 90-ties to invest their time in the console, which is very irrelevant nowadays).

 

We just need some markup that can be html-ized and to host it on some github, one or few caretakers with access to the repository and everything managed as any other open source project by pull-requests.

 

That's my view on the matter.

 

Edited March 8 by laoo

[+CyranoJ]

1 hour ago, laoo said:

I'm hesitating... but I'm not sure whether the formula for making amendments to the original documentation hasn't depleted. We are talking about documents rooted in original times with official information. It's ok to make corrections for example to PACK and UNPACK where the docs states that the flags are unaffected whilst it's a bug, but changing the entries where the docs says that the flag is "undefined" isn't the way to do, because the engineers did not defined them and it just happens that they are as they are.

 

I disagree with this. If the documentation is wrong, it should be corrected. There's enough false narriative around the Jaguar as it is.