StuBS
PIT Namespace Reference

Abstraction of the historical Programmable Interval Timer (PIT). More...

Classes

struct  Control.__unnamed76__
 I/O-port bitmap for the NMI Status and Control Register. More...
 

Enumerations

enum  AccessMode {
  LATCH_COUNT_VALUE = 0 ,
  LOW_BYTE_ONLY = 1 ,
  HIGH_BYTE_ONLY = 2 ,
  LOW_AND_HIGH_BYTE = 3
}
 Access mode.
 
enum  OperatingMode {
  INTERRUPT_ON_TERMINAL_COUNT = 0 ,
  PROGRAMMABLE_ONE_SHOT = 1 ,
  RATE_GENERATOR = 2 ,
  SQUARE_WAVE_GENERATOR = 3 ,
  SOFTWARE_TRIGGERED_STROBE = 4 ,
  HARDWARE_TRIGGERED_STROBE = 5
}
 Operating Mode. More...
 
enum  Format {
  BINARY = 0 ,
  BCD = 1
}
 data format More...
 

Functions

bool set (uint16_t us)
 Start timer. More...
 
uint16_t get (void)
 Reads the current timer value. More...
 
bool isActive (void)
 Check if the timer is running. More...
 
bool waitForTimeout (void)
 (Active) waiting for timeout More...
 
bool delay (uint16_t us)
 Set the timer and wait for timeout. More...
 
void pcspeaker (uint32_t freq)
 Play a given frequency on the PC speaker. More...
 
void disable (void)
 Deactivate the timer.
 

Constants

const uint8_t CHANNEL = 2
 
const uint64_t BASE_FREQUENCY = 1193182ULL
 

Detailed Description

Abstraction of the historical Programmable Interval Timer (PIT).

Historically, PCs had a Timer component of type 8253 or 8254, modern systems come with a compatible chip. Each of these chips provides three 16-bit wide counters ("channel"), each running at a frequency of 1.19318 MHz. The timer's counting speed is thereby independent from the CPU frequency.

Traditionally, the first counter (channel 0) was used for triggering interrupts, the second one (channel 1) controlled the memory refresh, and the third counter (channel 2) was assigned to the PC speaker.

As the PIT's frequency is fixed to a constant value of 1.19318 MHz, the PIT can be used for calibration. For this purpose, we use channel 2 only.

Note
Interrupts should be disabled while configuring the timer.

Class Documentation

◆ PIT::Control.__unnamed76__

struct PIT::Control.__unnamed76__

I/O-port bitmap for the NMI Status and Control Register.

Note
Over time, the meaning of the bits stored at I/O port 0x61 changed; don't get the structure confused with old documentation on the IBM PC XT platform.
See also
IntelĀ® I/O Controller Hub 7 (ICH7) Family, page 415
Class Members
uint8_t enable_timer_counter2: 1 If enabled, the interrupt state will be visible at status_timer_counter2.
uint8_t enable_speaker_data: 1 If set, speaker output is equal to status_timer_counter2.
uint8_t enable_pci_serr: 1 not important, do not modify
uint8_t enable_nmi_iochk: 1 not important, do not modify
const uint8_t refresh_cycle_toggle: 1 not important, must be 0 on write
const uint8_t status_timer_counter2: 1 will be set on timer expiration; must be 0 on write
const uint8_t status_iochk_nmi_source: 1 not important, must be 0 on write
const uint8_t status_serr_nmi_source: 1 not important, must be 0 on write

Enumeration Type Documentation

◆ OperatingMode

Operating Mode.

Warning
Channel 2 is not able to send interrupts, however, the status bit will be set
Enumerator
SQUARE_WAVE_GENERATOR 

useful for the PC speaker

◆ Format

data format

Enumerator
BCD 

Binary Coded Decimals.

Function Documentation

◆ set()

bool PIT::set ( uint16_t  us)

Start timer.

Sets the channel 2 timer to the provided value and starts counting.

Note
The maximum waiting time is approx. 55 000 us due to the timers being limited to 16 bit.
Parameters
usWaiting time in us
Returns
true if the counter is running; false if the waiting time exceeds the limits.

◆ get()

uint16_t PIT::get ( void  )

Reads the current timer value.

Returns
Current timer value

◆ isActive()

bool PIT::isActive ( void  )

Check if the timer is running.

Returns
true if running, false otherwise

◆ waitForTimeout()

bool PIT::waitForTimeout ( void  )

(Active) waiting for timeout

Returns
true when timeout was successfully hit, false if the timer was not active prior to calling.

◆ delay()

bool PIT::delay ( uint16_t  us)

Set the timer and wait for timeout.

Note
The maximum waiting time is approx. 55 000 us due to the timers being limited to 16 bit.
Parameters
usWaiting time in us
Returns
true when waiting successfully terminated; false on error (e.g., waiting time exceeds its limits)

◆ pcspeaker()

void PIT::pcspeaker ( uint32_t  freq)

Play a given frequency on the PC speaker.

As the PC speaker is connected to PIT channel 2, the PIT can be used to play an acoustic signal. Playing sounds occupies the PIT, so it cannot be used for other purposes while playback.

Note
Not every PC has an activated PC speaker
Qemu & KVM have to be launched with -audiodev If you still cannot hear anything, try to set QEMU_AUDIO_DRV to alsa (by launching StuBS with QEMU_AUDIO_DRV=alsa make kvm)
Parameters
freqFrequency (in Hz) of the sound to be played, or 0 to deactivate playback.