git: adba3c74209e - main - vt: add comments for KDMKTONE ioctl implementation

The branch main has been updated by emaste:

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

commit adba3c74209eb5d2197b9092002cc9d7505fd3c6
Author:     Ed Maste <emaste@FreeBSD.org>
AuthorDate: 2024-11-01 16:29:32 +0000
Commit:     Ed Maste <emaste@FreeBSD.org>
CommitDate: 2024-11-02 14:39:04 +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
---
 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 8f5e45306d61..87020b6e6f19 100644
--- a/sys/dev/vt/vt_core.c
+++ b/sys/dev/vt/vt_core.c
@@ -1135,6 +1135,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)
 {
@@ -1148,6 +1155,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);