# -------------------------------------------------------------------
# JERRY                                 (c) Copyright 1996 Nat! & KKP
# -------------------------------------------------------------------
# These are some of the results/guesses that Klaus and Nat! found
# out about the Jaguar with a few helpful hints by other people, 
# who'd prefer to remain anonymous. 
# Thanks to Bastian Schick for the information about the ADCs.
# Thanks to NEUROMANCER for the information about JOYIN bit#15
# Thanks to Mr.Nemo for the second PIT info
#
# Since we are not under NDA or anything from Atari we feel free to 
# give this to you for educational purposes only.
#
# Please note, that this is not official documentation from Atari
# or derived work thereof (both of us have never seen the Atari docs)
# and Atari isn't connected with this in any way.
#
# Please use this informationphile as a starting point for your own
# exploration and not as a reference. If you find anything inaccurate,
# missing, needing more explanation etc. by all means please write
# to us:
#    nat@zumdick.ruhr.de
# or
#    kp@eegholm.dk
#
# If you could do us a small favor, don't use this information for
# those lame flamewars on r.g.v.a or the mailing list.
#
# HTML soon ?
# -------------------------------------------------------------------
# $Id: jerry.htm,v 1.22 1997/11/16 18:14:41 nat Exp $
# -------------------------------------------------------------------
Here are some of the leftovers of JERRY that aren't described in the 
RISC dox.


  1. Joystick/Joypad

  2. Analog Joystick

  3. Interrupt control

  4. Sound Production

  5. Clock Registers

  6. Programmable Timers

  7. Networking


JOYSTICK/JOYPAD:
===============

Digital Joypad JOYSTICK:
=-=-=-=-=-=-=-=-=-=-=-=-=

   It seems that as a rule the bits are low active in these
   registers.


W: JOYSTICK ($F01400)
~~~~~~~~~~~~~~~~~~~~~
  16        12         8         4         0
   +-+-------^------+--+---------+---------+
   |r|    unused    |mu|  col 1  |  col 0  |  
   +-+--------------+--+---------+---------+
    15                8   7...4     3...0

   col 0:   column control of joypad 0 

      Here you select which column of the joypad to poll. 
      The columns are:

                Joystick       Joybut 
      col_bit|11 10  9  8     1    0  
      -------+--+--+--+--    ---+------
         0   | R  L  D  U     A  PAUSE       (RLDU = Joypad directions)
         1   | *  7  4  1     B       
         2   | 2  5  8  0     C       
         3   | 3  6  9  #   OPTION

      You select a column my clearing the appropriate bit and setting
      all the other "column" bits. 


   col1:    column control of joypad 1

      This is pretty much the same as for joypad EXCEPT that the
      column addressing is reversed (strange!!)
            
                Joystick      Joybut 
      col_bit|15 14 13 12     3    2
      -------+--+--+--+--    ---+------
         4   | 3  6  9  #   OPTION
         5   | 2  5  8  0     C
         6   | *  7  4  1     B
         7   | R  L  D  U     A  PAUSE     (RLDU = Joypad directions)

   mute (mu):   sound control

      You can turn off the sound by clearing this bit.

   read enable (r):  

      Set this bit to read from the joysticks, clear it to write
      to them.

    
R: JOYSTICK ($F14000)
~~~~~~~~~~~~~~~~~~~~~
   16        12        8         4         0
   +---------+---------+---------^---------+
   |  pad 1  |  pad 0  |      unused       |
   +---------+---------+-------------------+
     15...12   11...8          7...0

   Reading this register gives you the output of the selected columns
   of the pads.
   The buttons pressed will appear as cleared bits. 
   See the description of the column addressing to map the bits 
   to the buttons.


RO: JOYBUTS/CONFIG ($F14002)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   16       12         8         4         0
   +---------^---------^----+--+-+----+----+
   |           unused       | e|p| b1 | b0 |  
   +------------------------+--+-+----+----+
         15...9       8 7..6  5 4 3..2 1..0
   
   b0:   button read out for pad 0
      bit 0:   PAUSE, OPTION status
      bit 1:   A, B, C status

   b1:   button read out for pad 1
      bit 2:   PAUSE, OPTION status
      bit 3:   A, B, C status

   Returns the status of some of the Joypad buttons. You address which
   information you want with the JOYSTICK register (described above).

   palflag (p):  
      if this flag is set, you have a NTSC jaguar else
      it's a PAL Jag

   endianess (e):
      Always set for Motorola endianess.

   unused/unkown (u):



Analog Joystick:
=-=-=-=-=-=-=-=

The analog joystick feature was apparently removed from later
models of the Jaguar. The registers might exist still, but you 
might not necessarily get anything useable.


W: ANAJOY ($F17C00)
~~~~~~~~~~~~~~~~~~~
   16       12         8         4         0
   +---------^---------^---------^-+--+--+-+
   |            ???                |p |n |a|    WO
   +-------------------------------+--+--+-+

   axis (a) :  select X or Y for polling

      Set this bit to 1 for Y-axis polling, cleared: X-axis

   joystick (n):  select joystick   (??)
   
      Clear for joystick 0, set for joystick 1

   poll (p):    poll bit (??)

      Set this to one to initiate polling/ADC conversion ?
      It appears that after you start polling you need to give the ADC
      40 us time to convert the value.


R: ANAJOY ($F17C00) 
~~~~~~~~~~~~~~~~~~~
   16       12         8         4         0
   +---------^---------+---------^---------+
   |       unused      |       value       |    
   +-------------------+-------------------+
                         7...............0

   value:   8 bit value from the ADC



INTERRUPT CONTROL:
=================

W: INT ($F10020):
~~~~~~~~~~~~~~~~~
  16        12         8         4         0
   +---------^---------+---------^---------+
   |       latches     |       enable      | 
   +-------------------+-------------------+
           15...8              7...0

   enable:
      bit 0:   LEVEL 0 IRQ enable  (CPU)
      bit 1:   LEVEL 1 IRQ enable  (DSP)
      bit 2:   LEVEL 2 IRQ enable  (PIT1)
      bit 3:   LEVEL 3 IRQ enable  (PIT2)    
      bit 4:   LEVEL 4 IRQ enable  (NETWORK)    
      bit 5:   LEVEL 5 IRQ enable  (I2S)
      bit 6:   unused

   Enable by setting the appropriate bits

   latches:
      bit 8:   LEVEL 0 IRQ         (CPU)
      bit 9:   LEVEL 1 IRQ         (DSP)
      bit10:   LEVEL 2 IRQ         (PIT1)
      bit11:   LEVEL 3 IRQ         (PIT2)
      bit12:   LEVEL 4 IRQ         (NETWORK)
      bit13:   LEVEL 5 IRQ         (I2S)
      bit14:   unused

   Clear the latch by setting the appropriate bit. This will clear
   a pending interrupt.

   The interrupts that occur are not routed to the 68K directly,
   but rather to 
SOUND PRODUCTION:
================


RW: L_I2S ($F1A148)
~~~~~~~~~~~~~~~~~~~
  32       28       24       20       16       12        8        4        0
   +--------^--------^--------^--------+--------^--------^--------^--------+
   |              unused               |             value                 |
   +-----------------------------------+-----------------------------------+

   just a guess


RW: R_I2S ($F1A14C)
~~~~~~~~~~~~~~~~~~~
  32       28       24       20       16       12        8        4        0
   +--------^--------^--------^--------+--------^--------^--------^--------+
   |              unused               |             value                 |
   +-----------------------------------+-----------------------------------+

   just a guess

   Actually these are apparently not just DACs but rather ports, where
   you can read and write data. The written data is sent to the DACs.
   The data you read might come from the CDROM (or some other device ?)
   I suspect this is a synchronous serial port.
   Only the lower 16 bits are in actual use.


RW: SCLK ($F1A150)
~~~~~~~~~~~~~~~~~~
  32       28       24       20       16       12        8        4        0
   +--------^--------^--------^--------^--------^--------^--------^--------+
   |                        unused                       |      divide     |
   +-----------------------------------------------------------------------+

divide:
   This determines the sampling rate (or the IRQ rate). A source clock is
   divided by the "divide" value according to the following highly 
   mathematical formula:

         frequency = clock_frequency / (divide + 1)

   If the SCLK isn't tied to one of the "mystery Clocks", then the 
   clock_frequency is running at a rate of:

         bus_frequency / 64

   So the other way around now:

         desired_frequency = bus_frequency / 64 / (divide + 1)
         divide = bus_frequency / 64 / desired_frequeny - 1

   Lets try with 44100: 26591000 / 64 / 44100 - 1 =  8.42 ~ 8  -> 45072
        and with 32000: 26591000 / 64 / 32000 - 1 = 11.98 ~ 12 -> 31960
        and with 25000: 26591000 / 64 / 44100 - 1 = 15.62 ~ 16 -> 25968

   
         
RW: SMODE ($F1A154)
~~~~~~~~~~~~~~~~~~~
  32       28       24       20       16       12        8        4        0
   +--------^--------^--------^--------^--------^--------^--------^--------+
   |                                                                       |
   +-----------------------------------------------------------------------+

   Set this to $15 for sound production. Maybe this is a bit like the
   Falcon Matrix, where you can switch between several input sources and
   output sinks.



CLOCK REGISTERS:
=-=-=-=-=-=-=-=

The clock registers are said to be for jaguar hardware on a card, that
wants to communicate its configuration with the outside world. The registers
don't have any effect on the working of the Jaguar.

R: CLK1 ($F10010)
~~~~~~~~~~~~~~~~~
  16        12         8         4         0
   +---------^---------^---------^---------+
   |                unknown                |  
   +---------------------------------------+

   Supposedly has something to do with the processor 
   clock frequency. I'd guess read only. 
   This register neither affects sound (SCLK) nor video appreciably.


WR: CLK2 ($F10012)
~~~~~~~~~~~~~~~~~~
  16        12         8         4         0
   +---------^---------^---------^---------+
   |                unknown                |  
   +---------------------------------------+

   Sets the video clock frequency ? Hmm,I don't really know what
   this is good for. Haven't noticed any effects either.
   This register neither affects sound (SCLK) nor video appreciably.
   
   Default values:   NTSC=181 PAL=226


RW: CHRO_CLK ($F10014)
~~~~~~~~~~~~~~~~~~~~~~
  16        12         8         4         0
   +---------^---------^---------^---------+
   |                unknown                |  
   +---------------------------------------+

   Maybe used to control the color DACs ? I haven't seen any effect
   with this register.
   This register neither affects sound (SCLK) nor video appreciably.

   Default value: 4



PROGRAMMABLE TIMERS:
====================

RW: JPIT1 ($F10000)
~~~~~~~~~~~~~~~~~~
RW: JPIT2 ($F10004)
~~~~~~~~~~~~~~~~~~
 32       28        24        20       16       12        8        4        0
  +--------^---------^---------^--------^--------^--------^--------^--------+
  |           pre-scale                 |             divider               |
  +-------------------------------------------------------------------------+

value:
   Probably works like this:
   As soon as you write a value into the register, then the counter is cleared
   and starts decrementing immediately. If the register reaches zero then
   it will issue an IRQ and will keep on decrementing. (JUST A GUESS)



NETWORKING:
==========

Finally there's a little description of networking code. Most probably
some of the ASISTAT bits are hooked to the JERRY interrupts, that's 
for future research...

The transmitter/receiver hardware is double register buffered on input and
output (as usual). You have quite some freedom in configuring the 
hardware to drive the serial protocol to your liking.

The network hardware can generate four input interrupts, namely:

receive register full and parity error, framing error, overrun error

   and one output interrupt:

transmit register empty 

I'd suspect that the DSP provides three IRQs slots for TRANSMIT/RECEIVE 
and ERROR, but that remains to be tested.

As you can see, the ASI is a normal serial line, that is said to be
interfaceable with MIDI and COMLYNX. Because the voltage on the signal
lines is TTL (0V - 5V) level, you can't connect your modem (-15V - 15V) 
to it.

Data is encoded in the format below:
       ___  ___  ___  ___  ___  ___  ___  ___  ___  ______
\     / 0 \/ 1 \/ 2 \/ 3 \/ 4 \/ 5 \/ 6 \/ 7 \/   \/ 
 \___/\___/\___/\___/\___/\___/\___/\___/\___/\___/
One                                                  One
Start|------------8 BITS--------------------|Parity  Stop
Bit                                          Bit     Bit



R: ASIDATA ($F10030)
~~~~~~~~~~~~~~~~~~~~
  16        12         8         4         0
   +---------^---------+---------^---------+
   |      zeroes       |        data       |  
   +-------------------+-------------------+
     15.............8     7.............0

zeroes:     just zero bits
data:       incoming data byte. Only the lower byte contains data,
            the upper byte will be/should be zero.
 
   Reading this register will clear the receiver register full bit
   in the status register.


W: ASIDATA ($F10030)
~~~~~~~~~~~~~~~~~~~~
  16        12         8         4         0
   +---------^---------+---------^---------+
   |      zeroes       |       data        |  
   +-------------------+-------------------+
     15.............8     7.............0

zeroes:     just zero bits
data:       data to be written  


W: ASICTRL ($F10032)
~~~~~~~~~~~~~~~~~~~~
  16          12            8           4           0
   +--+--+-----^------------^--+--+--+--+--+--+--+--+
   | u|br|      unused         |cl|ri|ti|rp|tp|pa|od|
   +--+--+---------------------+--+--+--+--+--+--+--+
    15 14  13...............7    6  5  4  3  2  1  0

odd (od):                     0: even parity   1: odd parity
parity (pa):                  0: no parity     1: parity
transmitter polarity (tp):    0: active hi     1: active lo
receiver polarity (rp):       0: active hi     1: active lo
transmitter irq (ti):         0: disable       1: enable
receiver irq (ri):            0: disable       1: enable
clear (cl):                   1: clear all errors (see below)
break (br):                   1: send a break level
unused (u):                   unused write zeroes


R: ASISTAT ($F10032)
~~~~~~~~~~~~~~~~~~~~
  16          12           8           4           0
   +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
   |er|br|si| u|oe|fe|pe|te|rf| u|ri|ti|rp|tp|pa|od|
   +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
    15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0

odd (od):                     see ASICTRL
parity (pa):                   "     "
transmitter polarity (tp):     "     "
receiver polarity (rp):        "     "
transmitter irq (ti):          "     "
receiver irq (ri):             "     "
receive register full (rf):   1: there's something for you to read
transmit register empty (te): 1: you may write something
parity error (pe):            1: a parity error has occurred 
frame error (fe):             1: frame error (serial protocol fault)
overrun error (oe):           1: overrun error (CPU to slow to grab data)
serial input state (si):      look at the current bit received by the hardware
break (br):                   see ASICTRL
error (er):                   all the error states combined (pe, fe, oe)
unused (u):                   unused write zeroes


RW: ASICLK ($F10034)
~~~~~~~~~~~~~~~~~~~~
  16        12         8         4         0
   +---------^---------^---------^---------+
   |                 value                 |  
   +---------------------------------------+
     15.................................0

   This register is used to set the network transfer speed.
   Use this formula to calculate the clock value:
   'frq' is the desired serial transfer frequency

      value = 26593900 / (frq << 4) - 1


BUGS:
~~~~~

Everyone knows the network is buggy, but noone seems to know why. Judging
from some example code, I could get a glimpse at, it might be a good idea
to treat ASICLK carefully like this:

      move.l   #clock_val,d0
      move.l   #ctrl_val,d1
      move.l   d0,ASICLK
      move.l   d1,ASICTRL
      move.l   d0,ASICLK
      move.l   d1,ASICTRL

but maybe this is just superstition!


Example:
~~~~~~~~

Here's some example code how to read a byte from the network and
to write it back, no timeouts no error checking, no optimizing...

; read a byte, return in D0
read_a_byte:
.wait:
      move.w   ASISTAT,d0
      btst     #7,d0
      beq.b    .wait

      move.w   ASIDATA,d0
      rts


; send byte in D0, waste D1
write_a_byte:
.wait:
      move.w   ASISTAT,d1
      btst     #8,d1
      beq.b    .wait

      move.w   d0,ASIDATA
      rts

Nat! (nat@zumdick.ruhr.de)
Klaus (kp@eegholm.dk)

$Id: jerry.htm,v 1.22 1997/11/16 18:14:41 nat Exp $