pinkit.c File Reference

#include <p18cxxx.h>
#include <stdlib.h>
#include "types.h"
#include "pinkit.h"

Functions
UINT16	rand_lfsr (UINT16 min, UINT16 max, BYTE mask)
	Return a random 16-bit number between min and max.
BYTE	rand8 (BYTE min, BYTE max)
int	choice16 (UINT16 *list, BYTE min, BYTE max)
	Choose an item from a list, picking each item only once.
void	sched_init (void)
void	pk_q_init (void)
void	pinkit_init (void)
	Initializes all internal data structures.
BYTE	ensched_cmd (BYTE time, BYTE cmd1, BYTE cmd2)
	Schedule a command for a future time.
BYTE	ensched_fn (BYTE time, void(*func)(void))
BYTE	desched (BYTE time)
BYTE	enqueue (BYTE cmd1, BYTE cmd2)
	Queue a command for execution in the next available time slot.
BYTE	dequeue (BYTE *cmd1, BYTE *cmd2)
	Dequeue a command for transmission.
void	requeue (void)
void	coil_on (BYTE n)
void	coil_off (BYTE n)
void	lamp_on (BYTE n)
void	lamp_off (BYTE n)
void	lamp_group_assign (BYTE lnum, BYTE group)
	Assign a lamp to a group.
void	lamp_group_on (BYTE group)
	Turn ON the set of lamps for the given group.
void	lamp_group_off (BYTE group)
void	lamp_group_reset (BYTE group)
void	lamp_group_toggle (BYTE group)
void	set_lamp (BYTE lnum, BYTE state, BYTE pwm, BYTE blink)
void	local_coil_pulse (BYTE n, BYTE dur)
void	zero_scores (BYTE n)
void	set_scores (BYTE n)
	Sets each digit of each player's score to the given value. Usually used to set all score reels to zero.
BYTE	score_reset (void)
void	add_score (BYTE player, BYTE value)
	Add the score specified to the given player's score.
Variables
BYTE	PULSE_LOOKUP [] = { 0, 16, 32, 48, 64, 80, 96, 112, 128, 144, 160, 176, 192, 208, 224, 240 }
UINT16	BLINK_RATE [] = { 1548, 1293, 1068, 870, 698, 551, 427, 324, 241, 176, 127, 92, 69, 56, 51 }
struct {
BYTE   lampID
BYTE   x
BYTE   y
}	attract [MAX_ATTRACT]
BYTE	attract_rate
BYTE	attract_enable
BYTE	wheel [WHEELSIZE]
BYTE	freelist
struct EVENT	eventq [MAX_SCHED]
BYTE	pk_q_head
BYTE	pk_q_tail
BYTE	pk_q_full
struct PK_QCMD	qdata [MAX_EVENTS]
struct LAMP	lamp [MAX_LAMPS]
BYTE	lamp_group [15]
BYTE	cmd_patt [2]
struct SW	sw [MAX_SWITCHES]
struct COIL	coil [MAX_COILS]
BYTE	player
BYTE	score [MAX_PLAYER][MAX_DIGITS]
BYTE	reel [MAX_DIGITS]
BYTE	reg [MAX_REGS]
BYTE	num_digits
BYTE	coil_dummy

---

Detailed Description

PinKit common routines

---

Function Documentation

void add_score	(	BYTE	player,
		BYTE	value
	)

Add the score specified to the given player's score.

Parameters:

player	The player to which the score is to be added. Used to index into the "score" data structure. There is no range checking on player.
value	The score to be added, encoded as reel<<4 | n. That is, the upper nybble indicates the reel number, where 0 is the ones reel. The lower nybble is the number to add to the selected reel. In other words, "reel" is stepped "n" times. For example, value 15 steps the 10s reel 5 times.

Returns:

Does not return a value.

int choice16	(	UINT16 *	list,
		BYTE	min,
		BYTE	max
	)

Choose an item from a list, picking each item only once.

Given a list of items, passed in as a 16-bit value, pick a random, non-zero, bit position from the list. The bit number is returned along with the updated list value. The same value should be passed in on subsequent calls until -1 is returned to indicate that all items between min and max inclusive have been chosen.

Parameters:

list	An unsigned 16-bit value in which each bit represents an item to choose from. This should be set to zero on the first call. Bits will be set to indicate selected items. The updated value should be passed back in on subsequent calls. This value must be passed by reference (i.e. &master_list)
min	The lowest value on the list to be checked. Returned value will be >= min.
max	The largest value on the list to be checked. Returned value will be <= max.

BYTE dequeue	(	BYTE *	cmd1,
		BYTE *	cmd2
	)

Dequeue a command for transmission.

Returns the next entry from the queue. Command is returned in function parameters that are passed by reference. Returns 0 if successful, 1 if the queue is empty

BYTE desched

(

BYTE

time

)

Removes one item from the queue at the specified time slot.

Entry MUST be used right away because it is returned to the free list and the next ensched could overwrite it.

This function is intended for use by the game engine.

NOTE: it would be better to return a pointer to the structure here. This is easier (also faster since it only returns one byte

Parameters:

time	The time for which an entry should be returned, if any entries are available for that time. Normally this would be the current time. By convention, time is specified in 8mn quanta.

Returns:

Returns the index of the next entry from the requested time slot. Returns 0 if there are no more items scheduled in that time slot.

BYTE enqueue	(	BYTE	cmd1,
		BYTE	cmd2
	)

Queue a command for execution in the next available time slot.

The game engine dequeues up to one command per milli-second and transmits it onto the PinCAN bus.

Currently, local commands can not be enqueued. ensched should be used if the command may need to be processed on the local controller.

BYTE ensched_cmd	(	BYTE	time,
		BYTE	cmd1,
		BYTE	cmd2
	)

Schedule a command for a future time.

Schedules a command for transmission up to 248ms in the future. The time quanta of 8ms was chosen as a trade-off between timing resolution and scheduling delay. 8ms at 31 steps gives a scheduling duration of 248ms. A different quanta could be used without problems as long as the ensched and desched references are consistent.

Note that scheduling anything more than 256 ms into the future will wrap back MOD 256 and will not execute in the intended order.

Scheduled commands are intended for functions that operate on a playfield object with an ID. If the upper nibble of the command operand match the slave id the command will be executed locally and not transmitted onto the PinCAN bus. Returns 0 if ensched fails.

Parameters:

[in]	time	Time (in units of 8ms) for which to schedule command
[in]	cmd1	Byte 1 of command (opcode)
[in]	cmd2	Byte 2 of command (data)

Returns:

Returns the index of the entry created if success. Returns 0 if fails. Typical usaage would only check for fail.

BYTE ensched_fn	(	BYTE	time,
		void(*)(void)	func
	)

Schedules a function for execution up to 248ms in the future.

See ensched_cmd for details on scheduling times.

When the scheduled time is reached the game engine executes the function specified.

void lamp_group_assign	(	BYTE	lnum,
		BYTE	group
	)

Assign a lamp to a group.

Assigns the given lamp to the given group. Lamp groups are used to improve performance since a set of lamps in a group can be turned on and off with a single PinCAN message.

Parameters:

lnum	The lamp number on this board to assign to a group.
group	The group number to assign the lamp to. Group number 15 is reserved for a broadcast, i.e. ALL lamps

void lamp_group_off

(

BYTE

group

)

Turn OFF the set of lamps for the given group

void lamp_group_on

(

BYTE

group

)

Turn ON the set of lamps for the given group.

Turns on all the lamps that are assigned to the specified group. Setting group to 15 turns on ALL lamps on the card.

Parameters:

group

The group number to turn on, 15 = ALL lamps

void pinkit_init

(

void

)

Initializes all internal data structures.

Must be called at startup, before any other PinKit functions are used.

UINT16 rand_lfsr	(	UINT16	min,
		UINT16	max,
		BYTE	mask
	)

Return a random 16-bit number between min and max.

Returns a random 16-bit number x, where min <= X <= max.

Parameters:

min	The lower inclusive bound of the range of requested values
max	The upper inclusive bound of the range of requested values
mask	A right justified 1's mask that selects enough bits to satisfy the requested range. For example, if the range is 28 values the mask should be 0x1F.

Returns:

A 16-bit random number x, where min <= x <= max.

void requeue

(

void

)

Restores the last entry dequeued. It has the effect of pushing it back onto the head of the queue.

WARNING: only valid after last dequeue; prior to any other queue operations. For optimal performance this command assumes that no queue entries have been changed since the last dequeue operation. The intended use is to immediately restore a queue entry if the transmit hardware is busy.

void set_scores

(

BYTE

n

)

Sets each digit of each player's score to the given value. Usually used to set all score reels to zero.

Parameters:

player	The player (0-MAX_PLAYERS) to which the score should be added
value	The score to be added in digit || N format. WARNING: the lower nibble of value (N) must be 9 or less or the score will not be recorded correctly.

void zero_scores

(

BYTE

n

)

Zero the score for one or more players

Parameters:

[in]

n

n == 0-MAX_PLAYER-1, reset specified player n == 15, reset ALL players else, reset score for current player