The device system generally assumes that there is one ball-sensing switch for every ball that might be in the device. Thus, a 4-ball trough needs 4 switches. The tracker recounts balls periodically and does this just by polling each switch to see if a ball is present or not.
For some devices, this is not possible. Consider the Twilight Zone gumball machine, which can hold 3 or 4 balls but there are no switches inside to verify this. To handle this case, virtual balls are supported. This is a per-device counter that is completely software controlled. APIs exist to add/remove virtual balls that cannot be seen by switches. Machine-specific code must be written to manage this.
When a device driver knows for sure that a ball has entered the device,
it calls device_add_virtual. The extra ball will be tracked and
counted even though there is no switch to see it anymore. When virtual
balls are added, the device enter event is thrown as usual, as
if a physical ball had entered.
When it knows that a ball has exited the device, it calls
device_remove_virtual. This decrements the virtual ball counter.
This behaves exactly like when a real ball is kicked out, so the
kick_success event is thrown and the live ball count goes up.