git: 752c25c01c17 - stable/14 - vt: add comments for KDMKTONE ioctl implementation

The branch stable/14 has been updated by emaste:

URL: https://cgit.FreeBSD.org/src/commit/?id=752c25c01c171811bab622b558e97d611c228c7d

commit 752c25c01c171811bab622b558e97d611c228c7d
Author:     Ed Maste <emaste@FreeBSD.org>
AuthorDate: 2024-11-01 16:29:32 +0000
Commit:     Ed Maste <emaste@FreeBSD.org>
CommitDate: 2024-11-04 13:54:10 +0000

    vt: add comments for KDMKTONE ioctl implementation
    
    The KDMKTONE ioctl, introduced in commit 916347f77e6c, is used to beep
    the PC speaker.  For historical reasons the frequency is specified as an
    8254 PIT divisor for a 1.19MHz clock.  Linux provides this same ioctl.
    Add a comment to vtterm_beep to avoid someone wanting to "fix" this in
    the future.
    
    Also add an XXX comment that the period unit is supposed to be "timer
    ticks."  Note that nothing in the base system uses this ioctl.
    
    Reviewed by:    imp
    Sponsored by:   The FreeBSD Foundation
    Differential Revision: https://reviews.freebsd.org/D47395
    
    (cherry picked from commit adba3c74209eb5d2197b9092002cc9d7505fd3c6)
---
 sys/dev/vt/vt_core.c | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/sys/dev/vt/vt_core.c b/sys/dev/vt/vt_core.c
index f3cc4e29cf07..50f12512a81c 100644
--- a/sys/dev/vt/vt_core.c
+++ b/sys/dev/vt/vt_core.c
@@ -1136,6 +1136,13 @@ vtterm_bell(struct terminal *tm)
 	sysbeep(vw->vw_bell_pitch, vw->vw_bell_duration);
 }
 
+/*
+ * Beep with user-provided frequency and duration as specified by a KDMKTONE
+ * ioctl (compatible with Linux).  The frequency is specified as a 8254 PIT
+ * divisor for a 1.19MHz clock.
+ *
+ * See https://tldp.org/LDP/lpg/node83.html.
+ */
 static void
 vtterm_beep(struct terminal *tm, u_int param)
 {
@@ -1149,6 +1156,7 @@ vtterm_beep(struct terminal *tm, u_int param)
 		return;
 	}
 
+	/* XXX period unit is supposed to be "timer ticks." */
 	period = ((param >> 16) & 0xffff) * SBT_1MS;
 	freq = 1193182 / (param & 0xffff);