AC'97 audio functions. More...

#include <UEFIStarter/pci.h>
#include <UEFIStarter/core/cmdline.h>

Data Structures
struct	ac97_bar_t
	Data type for an AC'97 "baseline audio register set". More...

struct	ac97_buffer_descriptor_t
	data type for AC'97 buffer descriptor More...

struct	ac97_buffers_s16_t
	data type for signed 16-bit integer audio buffers descriptor More...

struct	ac97_handle_t
	AC'97 handle, this is the high-level handle for library use. More...

union	ac97_busmaster_status_t
	data type for bus master status register More...

Macros
#define	AC97_BUFFER_COUNT 32
	number of audio data buffers, up to 32 supported by AC'97 specs

#define	ARG_MUTE ac97_argument_list[0].value.uint64
	shortcut macro to access "mute" argument

#define	ARG_VOLUME ac97_argument_list[1].value.dbl
	shortcut macro to access "volume" argument

#define	ARG_SAMPLE_RATE ac97_argument_list[2].value.uint64
	shortcut macro to access "sample rate" argument

#define	AC97_MIXER_RESET 0x00
	"reset" mixer register

#define	AC97_MIXER_MASTER 0x02
	"master volume" mixer register

#define	AC97_MIXER_PCM_OUT 0x18
	"PCM OUT volume" mixer register

#define	AC97_PCM_RATE_FRONT 0x2C
	"PCM front channel DAC sample rate" mixer register

#define	AC97_PCM_RATE_SURROUND 0x2E
	"PCM surround channel DAC sample rate" mixer register

#define	AC97_PCM_RATE_LFE 0x30
	"PCM LFE channel DAC sample rate" mixer register

#define	AC97_DESCRIPTOR_PCM_OUT 0x10
	"PCM OUT descriptor base address" bus master register

#define	AC97_CIV_PCM_OUT 0x14
	"PCM OUT current index value" bus master register

#define	AC97_LVI_PCM_OUT 0x15
	"PCM OUT last valid index" bus master register

#define	AC97_STATUS_PCM_OUT 0x16
	"PCM OUT status" bus master register

#define	AC97_CONTROL_PCM_OUT 0x1B
	"PCM OUT control" bus master register

#define	AC97_GLOBAL_CONTROL 0x2C
	"global control" bus master register

#define	ac97_mixer_value(LEFT, RIGHT, MUTE) ((((LEFT)&0x3F)<<8)\|((RIGHT)&0x3F)\|((MUTE)?0x8000:0))
	Generates an AC'97 mixer value. More...

#define	AC97_DUMP_VOLUME 0x00000001
	flag for dump_audio_registers(): dump volume registers

#define	AC97_DUMP_OTHER 0x80000000
	flag for dump_audio_registers(): dump other registers

#define	AC97_DUMP_ALL -1
	flag for dump_audio_registers(): dump all registers

Functions
EFI_PCI_IO_PROTOCOL *	find_ac97_device ()
	Gets a PCI device handle for the AC'97 device. More...

void *	init_ac97_handle (ac97_handle_t handle, EFI_PCI_IO_PROTOCOL pip)
	Initializes an AC'97 handle. More...

void	close_ac97_handle (ac97_handle_t *handle)
	Destroys an AC'97 handle. More...

EFI_STATUS	write_mixer_reg (ac97_handle_t *handle, UINT32 reg, UINT16 value)
	Writes to an AC'97 mixer register. More...

EFI_STATUS	read_mixer_reg (ac97_handle_t handle, UINT32 reg, UINT16 value)
	Reads an AC'97 mixer register. More...

void	print_volume_register (UINT16 *text, UINT16 value)
	Prints a volume register's contents. More...

void	print_volume_register_mono (UINT16 *text, UINT16 value)
	Prints a mono volume register's contents. More...

EFI_STATUS	set_ac97_cmdline_volume (ac97_handle_t *handle)
	Takes the "volume" and "mute" command-line arguments and configures the AC'97 PCM OUT channel with them. More...

EFI_STATUS	set_ac97_cmdline_sample_rate (ac97_handle_t *handle)
	Takes the "sample rate" command-line argument and sets the AC'97 PCM OUT channel's sample rate to that. More...

EFI_STATUS	write_busmaster_reg (ac97_handle_t *handle, UINT32 reg, UINTN value)
	Writes to an AC'97 bus master register. More...

EFI_STATUS	read_busmaster_reg (ac97_handle_t handle, UINT32 reg, UINTN value)
	Reads an AC'97 bus master register. More...

EFI_STATUS	flush_ac97_output (ac97_handle_t *handle)
	Flushes all pending AC'97 memory writes. More...

EFI_STATUS	ac97_play (ac97_handle_t *handle)
	Starts AC'97 playback. More...

void	ac97_wait_until_last_buffer_sent (ac97_handle_t *handle, UINTN timeout_in_milliseconds)
	Waits until the AC'97 codec signaled the "last valid buffer completion" event. More...

void	dump_audio_registers (ac97_handle_t *handle, UINTN flags)
	Prints some of the AC'97 registers. More...

Variables
cmdline_argument_t	ac97_argument_list []
	AC'97 command-line argument list.

cmdline_argument_group_t	ac97_arguments
	command-line argument group for AC'97

Detailed Description

AC'97 audio functions.

Check these documents for details on how AC'97 works (they're both available from Intel):

Audio Codec '97 specification
Intel I/O Controller Hub 6 (ICH6) High Definition Audio / AC '97 Programmer's Reference Manual

Author: Richard Nusser

Copyright: 2017-2018 Richard Nusser

License: GPLv3 (see http://www.gnu.org/licenses/)

See also: https://github.com/rinusser/UEFIStarter

Todo:: maybe combine find and init functions

Macro Definition Documentation

◆ ac97_mixer_value

#define ac97_mixer_value	(	LEFT,
		RIGHT,
		MUTE
	)	((((LEFT)&0x3F)<<8)\|((RIGHT)&0x3F)\|((MUTE)?0x8000:0))

Generates an AC'97 mixer value.

Parameters

LEFT	the left channel's value, within [0..63]
RIGHT	the right channel's value, within [0..63]
MUTE	whether to mute (0 for no, anything else for yes)

Returns: the mixer value, ready to write into an AC'97 mixer register

Function Documentation

◆ find_ac97_device()

EFI_PCI_IO_PROTOCOL* find_ac97_device ( )

Gets a PCI device handle for the AC'97 device.

Returns: the PCI device handle, or NULL if none found

◆ init_ac97_handle()

void* init_ac97_handle	(	ac97_handle_t *	handle,
		EFI_PCI_IO_PROTOCOL *	pip
	)

Initializes an AC'97 handle.

Parameters

handle	the AC'97 handle to initialize
pip	the UEFI PCI I/O protocol to use

Returns: the handle on success, NULL otherwise

◆ close_ac97_handle()

void close_ac97_handle ( ac97_handle_t * handle )

Destroys an AC'97 handle.

Parameters

handle the AC'97 handle to destroy

◆ write_mixer_reg()

EFI_STATUS write_mixer_reg	(	ac97_handle_t *	handle,
		UINT32	reg,
		UINT16	value
	)

Writes to an AC'97 mixer register.

Parameters

handle	the AC'97 handle to use
reg	the register to write to
value	the value to write

Returns: the resulting status, EFI_SUCCESS if everything went well

◆ read_mixer_reg()

EFI_STATUS read_mixer_reg	(	ac97_handle_t *	handle,
		UINT32	reg,
		UINT16 *	value
	)

Reads an AC'97 mixer register.

Parameters

handle	the AC'97 handle to use
reg	the register to read from
value	the output value

Returns: the resulting status, EFI_SUCCESS if everything went well

◆ print_volume_register()

void print_volume_register	(	UINT16 *	text,
		UINT16	value
	)

Prints a volume register's contents.

Parameters

text	the register's name to print
value	the register's value

◆ print_volume_register_mono()

void print_volume_register_mono	(	UINT16 *	text,
		UINT16	value
	)

Prints a mono volume register's contents.

Parameters

text	the register's name to print
value	the register's value

◆ set_ac97_cmdline_volume()

EFI_STATUS set_ac97_cmdline_volume ( ac97_handle_t * handle )

Takes the "volume" and "mute" command-line arguments and configures the AC'97 PCM OUT channel with them.

Parameters

handle the AC'97 handle to use

Returns: the resulting status, EFI_SUCCESS if everything went well

◆ set_ac97_cmdline_sample_rate()

EFI_STATUS set_ac97_cmdline_sample_rate ( ac97_handle_t * handle )

Takes the "sample rate" command-line argument and sets the AC'97 PCM OUT channel's sample rate to that.

Careful, this operation resets the "mute" flag on at least the master output channel, so call this before set_ac97_cmdline_volume().

Parameters

handle the AC'97 handle to use

Returns: the resulting status, EFI_SUCCESS if everything went well

◆ write_busmaster_reg()

EFI_STATUS write_busmaster_reg	(	ac97_handle_t *	handle,
		UINT32	reg,
		UINTN	value
	)

Writes to an AC'97 bus master register.

Parameters

handle	the AC'97 handle to use
reg	the register to write to
value	the value to write

Returns: the resulting status, EFI_SUCCESS if everything went well

◆ read_busmaster_reg()

EFI_STATUS read_busmaster_reg	(	ac97_handle_t *	handle,
		UINT32	reg,
		UINTN *	value
	)

Reads an AC'97 bus master register.

Parameters

handle	the AC'97 handle to use
reg	the register to read from
value	the output value

Returns: the resulting status, EFI_SUCCESS if everything went well

◆ flush_ac97_output()

EFI_STATUS flush_ac97_output ( ac97_handle_t * handle )

Flushes all pending AC'97 memory writes.

Parameters

handle the AC'97 handle to use

Returns: the resulting status, EFI_SUCCESS if everything went well

◆ ac97_play()

EFI_STATUS ac97_play ( ac97_handle_t * handle )

Starts AC'97 playback.

Parameters

handle the AC'97 handle to use

Returns: the resulting status, EFI_SUCCESS if everything went well

◆ ac97_wait_until_last_buffer_sent()

void ac97_wait_until_last_buffer_sent	(	ac97_handle_t *	handle,
		UINTN	timeout
	)

Waits until the AC'97 codec signaled the "last valid buffer completion" event.

Parameters

handle	the AC'97 handle to use
timeout	the (approximate) number of milliseconds to wait before aborting

◆ dump_audio_registers()

void dump_audio_registers	(	ac97_handle_t *	handle,
		UINTN	flags
	)

Prints some of the AC'97 registers.

Parameters

handle	the AC'97 handle to use
flags	which registers to print, see the AC97_DUMP_* flags

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ac97_mixer_value

Function Documentation

◆ find_ac97_device()

◆ init_ac97_handle()

◆ close_ac97_handle()

◆ write_mixer_reg()

◆ read_mixer_reg()

◆ print_volume_register()

◆ print_volume_register_mono()

◆ set_ac97_cmdline_volume()

◆ set_ac97_cmdline_sample_rate()

◆ write_busmaster_reg()

◆ read_busmaster_reg()

◆ flush_ac97_output()

◆ ac97_play()

◆ ac97_wait_until_last_buffer_sent()

◆ dump_audio_registers()