******************************************************************
*Document type: Library reference
*Readme file name: manper.txt
*Library prefix: per
*Library name: System/peripheral
*Version: 1.04
*Creator: N.T
*Created: 12/27/94
*Comments: 3rd Step (12/27/94)
******************************************************************

******************************************************************
Description of Version 1.03 to Version 1.04 Changes

* Corrections

The following fixes were made for Version 1.03 problems:

1. manper.doc Documentation Error

The calculation method used for the work area of PER_LInit on line
174 was incorrect.  The correction is shown below.

Incorrect:

n = (num * size * 2) + size

Correct:

n = (num * (size + 2) * 2) + size

In addition, size differs with each peripheral as shown below.
Size is described as data size in the SMPC hardware manual.
Following is an excerpt from the manual:

Peripheral              size
----------------------------
Digital device             2
Analog device              5
Pointing device            3
Keyboard device            4
Genesis 3 Button Pad       1
Genesis 6 Button Pad       2
----------------------------

2. Mouse Peripheral ID Output Value Error

The mouse peripheral ID was incorrectly output as EO.  This was
corrected to be output as 20 (PER_ID_PNT).

* Other

[Version 1.03 Peripheral Data Output Spec Change]

The differences in peripheral connection state output data are
described below for pre-1.02 and post-1.03 versions.

+ Connection State

  Control Port 1: Disconnected
  Control Port 2: Digital device

+ Output Result

  - Before Version 1.02

    Array 0 = Disconnected
    Array 1 = Digital device

  - After Version 1.03

    Array 0 = Digital device
    Array 1 = Unknown

    6Player Data

      Control Port 1 port count = 0
      Control Port 2 port count = 0

Peripheral output data pre-Version 1.02 and post-Version 1.03
differ as shown above.

After Version 1.03, access peripheral output data based on 6Player
data.  (The addition of 6Player data support is to maintain
compatibility with the peripheral support requirements found in
the Sega Saturn Software Development Standards.)

******************************************************************
Manual Addenda

[Summary of Changes]

Two changes were made from the previous version of the manual.
The first part explains the main changes.  The second part details
changes and additions as an documentation update.

* Required Changes for Supporting Software Development Standards
  for Peripherals

* Documentation Update
  Troubleshooting tips, etc.

+ Required Changes for Supporting Software Development Standards
  for Peripherals

A portion of the specifications for reading peripheral data was
changed to comply with the Sega Saturn Software Development
Standards.

The main changes are as described below.  To provide more
implementation flexibility, the libraries are now more low-level
compared with the previous version of the library.  The number of
functions is the same as the previous version.  Function names
have been changed so that they can be differentiated from those
contained in the previous version.

***** IMPORTANT!!! *****

LIBRARIES BEFORE VERSION 1.02 DO NOT SUPPORT THE SEGA SATURN
SOFTWARE DEVELOPMENT STANDARDS.  UPDATE YOUR LIBRARY TO VERSION
1.03 OR LATER!!


1) Addition of 6Player Data Output

This was added to provide the active port information in
peripheral data.

2) Addition of Peripheral Size Output

This was added to provide a method of determining peripheral type.

3) Elimination of PUSH (no button input before, button input
   present now) Data Output

This was eliminated from the library to optimize memory
efficiency.

4) Output of Unprocessed Peripheral Data

The library has been modified so that peripheral data is output
unprocessed.  This change was made to enable different peripherals
to be used in one game.  (Example: Game where Control Port 1 =
analog device, Control Port 2 = pointer device)

[Changes to the Manual]

* Note

1) Change in SCU Interrupt Status Register Use

The SCU interrupt status register was used with Version 1.01
(8/22/94) sample code.  This register can no longer be used due to
hardware limitations.

2) Caution on 2+ Interrupt Applications

On applications that require 2 or more interrupt periods to
execute (i.e., the V-Blank skip count set with the PER_LInit
function is 1 or more), note that peripheral data is read only on
the final interrupt.  With this specification, there are cases
when edge detection does not occur because inter-interrupt
peripheral data is not read (no button input before, button input
present now).  When accurate edge detection is required, set the
V-BLANK skip count to 0, and execute the PER_LGetPer function at
every interrupt.

3) Using PER_LGetPer with the VDP2 Library

The manual requires that the PER_LGetPer function be executed
immediately after exiting V Blank.  However, when using the VDP2
library's SCL_VblankEnd function, execute the PER_LGetPer function
after the SCL_VblankEnd function.  If the SCL_VblankEnd function
execution timing is late, the sprite frame update is delayed until
the next processing cycle.  As a result, screen movement of
sprites will be slower.

* Calling Sequence

See the sample program.  (The purpose of the sample program is to
show the use of functions.  Therefore, note that there are parts
of the sample program which do not comply with the Software
Development Standards.)

* Data Specifications

+ Peripheral Data Output

The peripheral data output structure was changed as follows:

  +-Peripheral ID
  |    +-Peripheral size
  |    |    +-Data 1                    1 byte
  |    |    |    +-Data 2                <-->
  |    |    |    |                      |    |
+----+----+----+----+--  +----+----+----+----+----+----+----+
| ID | SZ | D1 | D2 | | ID | SZ | D1 | D2 | ID | SZ | D
+----+----+----+----+--  +----+----+----+----+----+----+----+
 <----------------->
  1 device data
 <------------------------------------------> <--------------
               Peripheral data                 Peripheral data
               of all ports at                 of all ports at
               Control Port 1                  Control Port 2

The number of active ports at the Control Port is contained in the
following 6Player data.

+ Peripheral ID

PER_ID_NCON_UNKNOWN /* Disconnected or SMPC UNKNOWN */
PER_ID_DGT          /* Digital device */
PER_ID_ANL          /* Analog device */
PER_ID_PNT          /* Pointing device */
PER_ID_KBD          /* Keyboard */
PER_ID_MD           /* Genesis */

+ Peripheral Size

PER_SIZE_NCON_15    /* Disconnected or a 15 byte device */
PER_SIZE_DGT        /* Digital device */
PER_SIZE_ANL        /* Analog device */
PER_SIZE_PNT        /* Pointing device */
PER_SIZE_KBD        /* Keyboard */
PER_SIZE_M3BP       /* Genesis 3 button pad */
PER_SIZE_M6BP       /* Genesis 6 button pad */

* Note

+ Elimination of PerXxxInfo and PerXxxData Data Types

PerXxxInfo and PerXxxData data types were deleted, however, the
PerXxxData bit position constant remains with its name changed.
Bit position is for used for byte unit access.  See sega_per.h for
details.

  Example: PER_DGT_U --> PER_LDGT_U

+ Elimination of the Digital Mouse Data Generation Function

With Version 1.02, digital mouse data was created as shown below.
Please use this information as a reference.

1) The following tasks are performed for each read:

+ When Y data is negative:

  Add the Y movement absolute value to the DOWN add variable.

+ When Y data is positive:

  Add the Y movement absolute value to the UP add variable.

+ When X data is negative:

  Add the X movement absolute value to the LEFT add variable.

+ When X data is positive:

  Add the X movement absolute value to the RIGHT add variable.

When each add variable value reaches 256 or more, the bit is set
in the button pressed state.  Add variables in that state are zero
cleared.

* 6Player Data

typedef struct {
  PerMulId    id;  /* 6Player ID */
  PerMulCon   con; /* Port count */
}PerMulInfo;       /* 6Player data */

+ 6Player ID

  PER_MID_NCON_ONE        /* Disconnected or through */

+ 6Player Active Port Count

  PER_MCON_NCON_UNKNOWN   /* Disconnected or unknown */

* Peripheral Data Output and 6Player Data

Following are the differences in peripheral output data during
connected states for pre-Version 1.02 and after Version 1.03.

+ Connection State

  Control Port 1: Disconnected
  Control Port 2: Digital device

+ Output result

  - Before Version 1.02

    Array 0 = Disconnected
    Array 1 = Digital device

  - After Version 1.03

    Array 0 = Digital device
    Array 1 = Unknown

    6Player Data

      Control Port 1 port count = 0
      Control Port 2 port count = 0

Peripheral output data for pre-Version 1.02 and post-Version 1.03
differ as shown above.

After Version 1.03, access peripheral output data based on 6Player
data.  (The addition of 6Player data support is to maintain
compatibility with the peripheral support requirements found in
the Sega Saturn Software Development Standards.)

* Function Specifications

+ Change of PER_Init to PER_LInit

Format:      Uint32 PER_LInit(PerKind kind, PerNum num, PerSize,
             Uint8 work[n], Uint8 v_blank);
Input: kind: INTBACK type
        num: Required peripheral count
       size: Peripheral size
       work: Work area (declare with a global variable)
    v_blank: V Blank skip count

  - How to Calculate the Work Area

    n = (num * (size + 2) * 2) + size

    In addition, size differs with each peripheral as shown below.
    Size is described as data size in the SMPC hardware manual.
    Following is an excerpt from the manual:

Peripheral              size
----------------------------
Digital device             2
Analog device              5
Pointing device            3
Keyboard device            4
Genesis 3 Button Pad       1
Genesis 6 Button Pad       2
----------------------------

+ Change of PER_GetPer function to PER_LGetPer

Format:            Uint32 PER_LGetPer(PerGetPer **output_dt,
                   PerMulInfo **mul_info);
Input:             None
Output: output_dt: Peripheral output address (null= no data read)
         mul_info: 6Player data output address
                   Reads the PerMulInfo mul_info[2] address.
                   mul_info[0] is Control Port 1 data.
                   mul_info[1] is Control Port 2 data.

  + Detailed Explanations

    - Guaranteed Peripheral Data

      Peripheral data is only guaranteed for values in the 6Player
      active port count range.  Therefore, when accessing
      peripheral data, be sure to determine the access location
      from the 6Player active port count.

    - Disconnected Peripherals

      When a peripheral is disconnected, note that its peripheral
      data is not initialized.  Maker sure to read peripheral data
      after reading the peripheral ID and size first.

* Troubleshooting

1) Cannot Get Peripheral Data

* Is the SH2's interrupt mask set to 15 from V-Blank exit to the
  next V-Blank entry?

  When the interrupt mask is set to 15, SMPC interrupt (as well as
  other interrupts) cannot be accepted.  Set the interrupt mask to
  0 or to a value lower than the SMPC interrupt priority.

* Is the SCU's SMPC interrupt mask bit set to 1 (disabled)?

  Peripheral data cannot be read when the SMPC interrupt is
  disabled.  Set the bit to 0 (enabled).

* An interrupt with a higher priority than the SMPC interrupt is
  executing for a long period of time.

  During processing of high priority interrupts, lower priority
  interrupts cannot be processed.  Set up your application so that
  high priority interrupt processes are not executed for a long
  period of time.  Alternatively, use the System Library's
  interrupt priority order change routine so that SMPC interrupts
  are accepted.

  * There are two kinds of interrupt priority values: 1) hardware-
    specific and 2) System Library-specific.  For details, see the
    System Library and SCU hardware manuals.

* Other

+ Changes to Compile Options

The library compile option /SP was changed to /NOSP.  This was
changed to avoid confusion that may be caused during debugging due
to the in-line expansion of functions that occurs when the library
is compiled with the /SP option.

+ Support of Sample Programs that Use System/Peripheral Library

Functions, constants, etc. from the previous versions of the
System/Peripheral library have been retained in the current
version.  This has been done to maintain compatibility with the
demo code for the other libraries that use the System/Peripheral
Library.  However, note that these functions, constants, etc. will
be eliminated in the 4th step libraries.

DO NOT USE THE FUNCTIONS, CONSTANTS, ETC. OF OLDER VERSIONS OF THE
LIBRARY.

***************************end of file***************************
