add xenon_tone, xenon_post_beep, some documentation to sound.h (#69)

* add xenon_tone and xenon_post_beep

* add some documentation to sound.h

* Update sound.c

Author: mitchellwaite

libxenon/drivers/xenon_sound/sound.c

@@ -1,4 +1,5 @@
 #include <pci/io.h>
+#include <stdint.h>
 #include <string.h>
 #include <xenon_smc/xenon_smc.h>
 #include <xenon_smc/xenon_gpio.h>
@@ -122,4 +123,49 @@ int xenon_sound_get_unplayed(void)
 	l += cur_len;
 
 	return l;
-}
+}
+
+void xenon_tone(uint32_t frequency, uint32_t duration, int16_t amplitude)
+{
+   uint8_t pcm_data[1024];
+
+   // xenon assumes a 48kHz sample rate for submitted audio data
+   const uint32_t sample_rate = 48000;
+
+	uint32_t phase = 0;
+	uint32_t phase_step = (uint32_t)(((uint64_t)frequency << 32) / sample_rate);
+
+	const uint32_t bytes_per_frame = sizeof(int16_t) * 2;
+	const uint32_t total_frames = (sample_rate * duration) / 1000;
+	uint32_t frames_remaining = total_frames;
+
+	while (frames_remaining)
+	{
+		uint32_t i;
+		uint32_t chunk_frames = sizeof(pcm_data) / bytes_per_frame;
+
+		if (chunk_frames > frames_remaining)
+			chunk_frames = frames_remaining;
+
+		for (i = 0; i < chunk_frames; ++i)
+		{
+			// 50% duty square wave
+			int16_t v = (phase & 0x80000000U) ? -amplitude : amplitude;
+			uint16_t le = (uint16_t)v;
+			uint32_t o = i * bytes_per_frame;
+
+			// Write little-endian 16-bit stereo PCM
+			pcm_data[o + 0] = le & 0xFF;
+			pcm_data[o + 1] = (le >> 8) & 0xFF;
+			pcm_data[o + 2] = le & 0xFF;
+			pcm_data[o + 3] = (le >> 8) & 0xFF;
+
+			phase += phase_step;
+		}
+
+		while (xenon_sound_get_unplayed() >= 32768);
+
+		xenon_sound_submit(pcm_data, sizeof(pcm_data));
+		frames_remaining -= chunk_frames;
+	}
+}

libxenon/drivers/xenon_sound/sound.h

@@ -5,13 +5,50 @@
 extern "C" {
 #endif
 
-	/* you init, you get the nr. of LE, 16bit x 2 channels, signed audio bytes to write, and submit that as max. */
-
+/**
+ * Initialize DAC, de-assert AUD_CLAMP, initialize HDMI audio
+ */
 void xenon_sound_init(void);
+
+/**
+ * Submit PCM audio data to be played on the conencted TV, monitor, audio device
+ *
+ * 48kHz sample rate
+ * Signed 16-bit stereo PCM, little endian
+ *
+ * @param data Pointer to buffer of audio data
+ * @param len Number of bytes from the buffer to submit
+ */
 void xenon_sound_submit(void *data, int len);
+
+/**
+ * @return Available free buffer space in bytes.
+ */
 int xenon_sound_get_free(void);
+
+/**
+ * @return Unplayed queued data size in bytes.
+ */
 int xenon_sound_get_unplayed(void);
 
+/**
+ * Generare a square wave tone
+ *
+ * @param frequency Tone frequency
+ * @param duration Tone length in milliseconds.
+ * @param amplitude Peak sample amplitude (signed 16-bit).
+ */
+void xenon_tone(uint32_t frequency, uint32_t duration, int16_t amplitude);
+
+#define XENON_TONE_AMPLITUDE_100 12000
+#define XENON_TONE_AMPLITUDE_50  6000
+#define XENON_TONE_AMPLITUDE_25  3000
+
+/**
+ * Does the classic POST beep that old computers do (950hz tone, 250ms)
+ */
+#define xenon_post_beep() xenon_tone(950, 250, XENON_TONE_AMPLITUDE_50)
+
 #ifdef __cplusplus
 };
 #endif