My Jaguar SDK environment is now on github

[+cubanismo]

I've tidied up most of the remaining issues with my attempt at an updated Jaguar SDK, and documented the outstanding problems in github issues.  Here it is:

 

https://github.com/cubanismo/jaguar-sdk

 

See the README.md for cloning, setup, and general getting started instructions.  If you have a skunkboard or a BJL cable and know enough to run bash scripts and make, you should be up and running "hello world" built from source in a few minutes.  Beyond that, you're on your own.  A good amount of Jaguar documentation is included (All the scanned Atari docs and the searchable tech ref PDF, plus all the docs from Belboz's SDK), so everything I used to get from "What's a Tom?" to "I'm writing my own RISC code and it works!" is there if you're willing to read it.

 

This SDK includes all the original Atari samples and demos found in Belboz's old SDK/dev environment with cleaned up Makefiles that use rmac/rln by default (You can tweak the master Makefile helper files to substitute good ol' mac/aln if your system supports a.out binaries) and also converts them to end with infinite loops rather than "illegal" instructions to break into the debugger you probably don't have, meaning everything plays nicely with virtualjaguar and regular BJL/skunkboard HW setups out of the box.

 

Couple gotchas if you're trying to build some of the cooler stuff, such as the Atari 3D demo (which is included there under jaguar/3d, working Makefile and all, as well as resurrected versions of the Atari tools that are required to build its data files, 3dsconv and the original tga2cry) :

 

• It only works on Linux right now.  I've been meaning to add windows setup scripts a well, but haven't gotten around to it yet and didn't want to let that hold up releasing what I have so far.
• To build the 3D demo, you need to patch rmac.  See the issue here: https://github.com/cubanismo/jaguar-sdk/issues/6
• To build the cinepak demos, you need a patch to rln to support Alcyon-format object files that I haven't posted anywhere yet because I need to make a 2nd pass at it.  I'll do that pretty soon, but again, didn't want to hold up release of everything else.  This is needed because the Atari cinepak library is only available as an Alcyon object file with no source.

 

Besides using this to build the included samples, I use it for all my other little projects as well.  You can source in the env.sh file and then make calls to any of the included tools (rmac, rln, jcp, tga2cry, etc.) on the command line from anywhere, as well as write Makefiles in your project that use the included Makefile helper headers/footers to reduce Makefile clutter as well.  For example, here's all the Makefile code needed for my simple lightgun test program that uses a mixture of C and assembly, and lives outside of the SDK itself:

ALIGN=q
include $(JAGSDK)/tools/build/jagdefs.mk

CFLAGS += -mshort -Wall -fno-builtin

OBJS =	startup.o \
	bullets.o \
	lightgun.o \
	font.o \
	sprintf.o \
	util.o

RAW_DATA = -ii clr6x12.jft _fnt

PROGS = bullets.cof

bullets.cof: $(OBJS) clr6x12.jft
	$(LINK) $(LINKFLAGS) $(OBJS) -o $@ $(RAW_DATA)

include $(JAGSDK)/tools/build/jagrules.mk

I hope others find this useful.  Half the difficulty in ramping up for me was just rounding up all the docs, utilities, and samples that I needed and getting them somewhere I could find and run them easily in a way that persisted across reboots.  And of course, if something is broken, let me know, either here, or by filing an issue on github.  I'll support it when I have free time, but hey, this is a hobby, so no guarantees.

Edited September 21, 2020 by cubanismo
Fixed typo in Makefile sample code

[JagChris]

There is an updated include file. Did you find that?

[+cubanismo]

3 hours ago, JagChris said:

There is an updated include file. Did you find that?

You mean the missing tri.h?  Not needed with the updated source.  tri.h is actually from an even earlier version of the demo AFAICT, and was just mistakenly included by some files in the version included in Belboz's SDK, but not actually used IIRC.  However, even when dropping it in the old version I could never get it to produce functional code personally, though I've seen the thread where you and a few others appear to have gotten something out of it.  Don't know what to make of that, but I know this version works!

[JagChris]

I was actually referring to this

 

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;
;    JAGUAR.INC  Hardware Equates for JAGUAR System
;
;    COPYRIGHT 1992-1995 Atari Computer Corporation
;    UNAUTHORIZED REPRODUCTION, ADAPTATION, DISTRIBUTION,
;    PERFORMANCE OR DISPLAY OF THIS COMPUTER PROGRAM OR
;    THE ASSOCIATED AUDIOVISUAL WORK IS STRICTLY PROHIBITED.
;    ALL RIGHTS RESERVED.
;
; Revision History:
; 9/19/94 - Consolidated several files into first master JAGUAR.INC (SDS)
; 2/16/95 - MF
; 4/24/95 - Added UART Error Control and Mask definitions (NBK)
; 5/16/95 - Added Asynchronous Serial/DAC Synonyms (SDS) 
; 8/08/95 - Fixed two Blitter LFU Equates, added ProController equates,
;           added blitter BLITMASK flag, removed MOD_MASK/DSPINT0,
;           removed private hardware register definitions.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

It's the latest known hardware equates file not included in any SDK's

Edited September 23, 2020 by JagChris

[+cubanismo]

Ah, OK, I didn't know that version actually made it out. Is there a link to the full file somewhere? I'd probably undo any register removals, but it'd certainly be good to merge in the additions.  I'm curious what the ProController equates are, given the changes there are just alternate locations for the numpad buttons.  Just some synonyms for ease of use I assume?

[JagChris]

It's here with a personal file from someone at the company. Very interesting reading. I never separated them.

 

 

PERSONAL.zip

[+Stephen]

With it being linux based, and chance of creating a Docker file for your setup?

[JagChris]

Wow, it's been 25 years ago last month since those latest additions were added 

[+cubanismo]

8 hours ago, Stephen said:

With it being linux based, and chance of creating a Docker file for your setup?

Not my preferred workflow, and I'd never built a docker image before, but hey, it's the new shiny, right? So... done! Here are the instructions on using it from the updated README.md:

 

---

 

The SDK is also available as a docker image for those who prefer a ready-made environment. Assuming you have docker installed and configured on your system, you can fetch it using this command:

$ docker pull cubanismo/jaguar-sdk

And then start an interactive session in it, mapping in a project in your home directory named 'MyJagProj' for building, build it, and exit, deleting the container and leaving you with a built project in your home directory.

$ docker run --rm -it -v ~/MyJagProj:/MyJagProj cubanismo/jaguar-sdk
# cd /MyJagProj
# make
# exit

 

---

 

I haven't set up automatic image updates from the github repo or anything yet, but that looks to be pretty straightforward, so I'll give that a try soon.

[Cyprian]

nice idea,

thanks @cubanismo

[+Stephen]

8 hours ago, cubanismo said:

Not my preferred workflow, and I'd never built a docker image before, but hey, it's the new shiny, right? So... done! Here are the instructions on using it from the updated README.md:

 

---

 

The SDK is also available as a docker image for those who prefer a ready-made environment. Assuming you have docker installed and configured on your system, you can fetch it using this command:

$ docker pull cubanismo/jaguar-sdk

And then start an interactive session in it, mapping in a project in your home directory named 'MyJagProj' for building, build it, and exit, deleting the container and leaving you with a built project in your home directory.

$ docker run --rm -it -v ~/MyJagProj:/MyJagProj cubanismo/jaguar-sdk
# cd /MyJagProj
# make
# exit

 

---

 

I haven't set up automatic image updates from the github repo or anything yet, but that looks to be pretty straightforward, so I'll give that a try soon.

That was fast - thanks!  Only reason I asked, is we are being made to use this at work now and it's always better to learn with fun stuff rather than slogging through job related crap

[+cubanismo]

On 9/22/2020 at 8:17 PM, JagChris said:

There is an updated include file. Did you find that?

I've merged the useful bits of this into the version in the SDK now.  Haven't bothered generating a new docker image, as after playing with @SebRmv's dev environment, I realized my Dockerfile is a bit lacking (TIL you don't have to leave everything running as root in your container), so I'm going to improve mine a bit and/or wait for some more substantial updates before pushing another blob to docker hub and setting up automatic docker image generation.

[JagChris]

Everything evolves. It never stops. But glad you were able to make it useful. It's a bit of history I found.

 

[OVERRiDE]

First of all, thank you cubanismo for taking the time to put this together, and for sharing with the community.

 

I am new the Jaguar community, but I am very curious about its hardware potential and would like to test a few things out using this sdk.

 

I have the sdk up and running under WSL / Windows 10 + Ubuntu 20.4 LTS without issue.  Besides your short tutorial, all I had to do beyond the initial WSL setup is install make and gcc.

 

Now the basic examples are compiling fine and running in Virtual Jaguar without issue.

 

However, the 3d demo compiles fine, but is giving some hassles in Virtual Jaguare and I am not sure what to make of it.

• Compiling the source as-is seems to crash the emulator.  Nothing gets rendered and the emulator becomes unresponsive.
• I observed compiler warnings about 'g' flag being unsupported.  Seems a debug feature so I removed this flag from 'jagdefs.mk'.  This removed all compiler warnings, but made no functional difference.
• I noticed the default compiler flags are for 02 - I thought perhaps some regression was introduced by these optimizations so I compiled with O0 and O1 instead, but same results.
• Started ripping out code sections in demo.c to get things to a working point.  After trial and error I found that commenting out some of the spfrintf / FNTstr calls ( all calls execpt for the first - buffer overflow ? ) finally got the demo running without crashing the emulator
• BUT even after getting the demo running, the 3d objects are not visible - all I can see is the blue background and the font overlay.  I have made no meaningful changes to the N3DRender routine.  And does not matter what renderer is invoked, all result in no 3d objects visible on screen.
• Disabled call to N3Dclrbuf just in case there was some z buffer issue and the 3d objects ended up behind the background plane - but all this did was end up with black background instead

So a bit stuck at the moment, it would be nice to have a working 3d demo as a jumping off point.  Not sure if my results are unique or if this is known to be broken.  

 

Any help will be appreciated.  Thanks!

[+cubanismo]

Glad to hear it's useful to someone besides me!

 

Yeah, the 3D demo doesn't work in VJ. You've debugged it further than I have (Though somewhere in some git tree, I have a fix for the font rendering code. It's a bug (Well, a mismatch between emulator and HW behavior, hard to say which is a "bug"...) in the VJ blitter code in that it samples the pattern register different than the HW does (IIRC, VJ chooses the high dword for <64-bit blits, HW chooses the low dword). As you noted though, it still doesn't work, and I didn't pursue it further as I generally test on real hardware.

 

You may be interested in this thread:

 

 

[OVERRiDE]

Thanks for the quick reply, that is the answer I was afraid of lol.

 

I don't actually have a Jag (had one when I was a kid), but I see a listing that just went up 2 days ago on Craigslist near me for a Jag, 2 controllers, a Game Drive and 1 game for 500$.  This listing almost seems like fate lol.  Does this sound like a good deal?  Prices have gone up since I sold my Jag back in 2000 lol.

 

Are there any 3d rendering demos that do run on the emulator? 

 

I am not making any promises by any means, but I have experience with writing graphics API's and I am interested in seeing what I can do on the Jag, thinking a very light set of OpenGL 1-esque functions may be doable ( matrix stack management, vertex transforms, primitive rasterization ) to exploit the GPU with minimal understanding of the hardware intrinsics.  Not sure if something like this already exists though, so just trying to get a grip on the starting point here.

 

But this is going to be painful trying to make any progress testing code changes if I have to run them on the Game Drive each compile.  At least while I am figuring out the basics of the system and how the processors all work, and how they work together.  Once I get past the learning curve it will be fine, but the faster I can get to that point the better.  And working via an emulator is certainly a nice shortcut for the time being.

[+cubanismo]

Unfortunately that probably is as good a deal as you're going to get these days.

 

That thread I linked above is a good rundown of the available 3D demos and their status. They tend to not run that well in emulation unfortunately. I'd recommend getting HW if you want to experiment with 3D without debugging an emulator as a side project. It's pretty easy to iterate quickly on a GD.

[JagChris]

Grab that Jaguar. With the game drive it's a good deal. I mean like now before it disappears. 

 

Like now.

[dilinger]

2 hours ago, OVERRiDE said:

I am not making any promises by any means, but I have experience with writing graphics API's and I am interested in seeing what I can do on the Jag, thinking a very light set of OpenGL 1-esque functions may be doable ( matrix stack management, vertex transforms, primitive rasterization ) to exploit the GPU with minimal understanding of the hardware intrinsics.  Not sure if something like this already exists though, so just trying to get a grip on the starting point here.

Many years ago, I have tried to "port" TinyGL on the Atari Jaguar.

It is doable, it "runs", requires lot of memory depend the tests, 16bits RGB, and has a (very) low fps. I've used only the 68000. It was just an experiment for me.

Various people have improved TinyGL for different platforms, some claims to have replaced the floating point with fixed point.

Feel free to give it a try but it is a hell of a job.

[+cubanismo]

I've updated my SDK with a small new addition: A native version of the filefix utility, as well as a build of the "size" program included in the DOS tools.

 

I'd noticed filefix.exe v6.81 didn't behave exactly as it claimed (Namely a few bugs the documentation claims are fixed aren't for some reason: It refused to generate "roms" from ABS files that weren't in ROM space, generated corrupt symbol files, and a few other small issues), and while digging around in the various dumps of Atari tools looking for a better version, I found the source to the "size" utility, and reading it a bit, realized it was clearly just a cut-down version of the filefix source. Unfortunately, I couldn't find the filefix source itself anywhere, but it was pretty easy to add the missing parts back in. A few other utilities based on the same code were also there, so I fixed those up as well. The result is in this new code repo:

 

https://github.com/cubanismo/jag_utils

 

It is automatically pulled down and built as part of the maketools.sh script in the latest version of my SDK, but it also builds stand-alone on Linux and Windows, with a Visual Studio 2019 solution included for the latter. It's possible to do most of the stuff these utilities do in other ways, e.g., linking programs as raw files up front, using pc_jagcrypt, or using a hex editor, but it was a fun little side project to restore the code and they're still convenient.

 

I've attached builds of the Windows versions of the utilities here for convenience.

allsyms.exe size.exe symval.exe

filefix.exe

Edited April 2, 2022 by cubanismo
Updated filefix.exe to version 7.1

[42bs]

filefix is nice, means I can get rid of "dd" to fill a rom.

Small bug:

"

printf( "-p = Pad ROM file with zero bytes to next 2mb boundary\n" );

printf( " (this must be used alongwith the -r or -rs switch)\n\n" );

"

Default is 0xff (which makes sense as an "empty" flash is all FF)

 

Edited April 1, 2022 by 42bs

[42bs]

Hmm, though filefix is nice, but it does not seem to respect the start address of an COF file. Though it prints correct values

 

Starting Address for executable = 0x00802000
Start of Text Segment = 0x00802000
Start of Data Segment = 0x00802100

 

it copies the content of the COF at the start.

 

[42bs]

Forked and extended "filefix" to add the universal header

So no longer a "header less" ROM (Readme not updated yet).

[+cubanismo]

21 hours ago, 42bs said:

it copies the content of the COF at the start.

Ran some tests, and I'm not sure what you mean by this one. I built some object files and linked all of them using aln with otherwise identical parameters into both COFF and DRI/Alcyon absolute files. Then I ran 'filefix -r file_abs.rom file.abs' and 'filefix -r file_cof.rom file.cof'. The results are identical according to diff, with both containing a raw dump of the text section followed by the data section. Do you have an example workflow and/or files that aren't behaving as expected?

[42bs]

I took one of my 256 byte intros linked them for $802000 and used filefix. The text segment was not a offset $2000 but at 0 in the ROM file.

Anyway, since it did not add a decryption header, I needed to change it anyway