12 Platform APIs

The platform APIs define how the hardware is accessed on a particular platform. They only need to be written once, and then all games on that hardware architecture can be supported.

If you are developing code for a WPC machine, you do not need to understand the platform APIs in detail, because they are already written for you. If you plan to port FreeWPC to a different hardware architecture, then you will need to write these functions first before you can create any game code.

Every platform must define a header file in include/platform/platform.h. This file defines a number of inline functions, all of which begin with pinio. It also defines a handful of constants, which begin with PINIO.

Platform APIs are the functions that perform the physical I/O. On WPC, these functions read and write the WPC ASIC registers. All reads and writes to I/O registers should use the readb and writeb macros. How these work depends on the platform. For most platforms, these turn into memory-mapped operations. However, they could also use a parallel port or USB.

Platform APIs are not suitable for game code to call directly, as they are too low-level. Instead, game code uses the core APIs to access a device driver; the device driver then uses the platform APIs.

pinio_write_switch_column

Set the current switch matrix column.

pinio_read_switch_rows

Read all of the switches on the currently selected column.

pinio_read_dedicated_switches

Read all of the dedicated switches.

pinio_read_flippers

Read all of the Fliptronic switches.

pinio_read_flipper_buttons

Read all of the Fliptronic button switches.

pinio_read_flipper_eos

Read all or some of the flipper switches.

pinio_read_locale

Read the locale indicator (jumpers or DIP switches).

pinio_write_lamp_strobe

Set the current lamp matrix strobe.

pinio_write_lamp_data

Write lamp row data for the currently selected column.

pinio_write_solenoid_set (bank, value)

Refresh a set of 8 solenoids.

pinio_read_ac_zerocross (CONFIG_AC)

Return nonzero if currently at a zerocross point.

pinio_reset_sound

Reset the sound board.

pinio_write_sound

Write an 8-bit code to the sound board.

pinio_sound_ready_p

Return true if the sound board has an 8-bit waiting to be read.

pinio_read_sound

Read an 8-bit code from the sound board.

pinio_write_gi (CONFIG_GI)

Write to the set of all general illumination strings. This API is only used when the platform does not support dimming.

pinio_read_triac (CONFIG_TRIAC)

If the platform supports dimming through triacs, this call returns the input-side latch values.

pinio_write_triac (CONFIG_TRIAC)

Write to the triacs. This API is only used when the platform supports dimming.

pinio_watchdog_reset (CONFIG_WATCHDOG)

Reset the hardware watchdog timer.

pinio_active_led_toggle (CONFIG_DIAG_LED)

Toggle the diagnostic LED.

pinio_dmd_window_set (CONFIG_DMD)

Sets the display page that is mapped into a given portion of the CPU address space.

pinio_dmd_window_get (CONFIG_DMD)

Returns the display page that is mapped into a given portion of the CPU address space.

pinio_dmd_window_ptr (CONFIG_DMD)

Returns a pointer to the beginning of the buffer that is mapped into a given portion of the CPU address space.

pinio_dmd_set_visible (CONFIG_DMD)

Sets the display page that is currently visible on the display.

pinio_dmd_request_interrupt (CONFIG_DMD)

Request that an interrupt be generated when the DMD controller finishes refreshing the display.

pinio_parport_write (CONFIG_PARALLEL_PORT)

Write a byte to the parallel port.

pinio_set_bank (CONFIG_BANK_SWITCH)

Writes to a bank switching register. There may be multiple such registers; you specify which register, and the value to be written. The values are also platform specific.

pinio_get_bank (CONFIG_BANK_SWITCH)

Reads the value of a bank switching register.

pinio_read_timer (CONFIG_HIGHRES_TIMER)

pinio_write_timer (CONFIG_HIGHRES_TIMER)