AC'97 audio functions. More...

#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <UEFIStarter/ac97.h>
#include <UEFIStarter/core/memory.h>
#include <UEFIStarter/core/string.h>
#include <UEFIStarter/core/logger.h>

Functions
BOOLEAN	validate_volume (cmdline_value_t value)
	validator for "-volume" command-line argument More...

BOOLEAN	validate_sample_rate (cmdline_value_t value)
	validator for "-sample-rate" command-line argument More...

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

int	init_buffers (ac97_buffers_s16_t *buffers, UINT64 hardware_address)
	Initializes AC'97 audio buffers. 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...

static UINTN	get_busmaster_register_width (UINT32 reg)
	internal: returns a bus master register's width 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	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...

static void	_determine_maximum_master_volume (ac97_handle_t *handle)
	Internal: determines the maximum master volume value. 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	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...

static void	_trace_busmaster_status_register (CHAR16 *name, ac97_busmaster_status_t value)
	internal: dumps a bus master status register's content More...

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. 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...

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. More...

cmdline_argument_group_t	ac97_arguments ={ L"Audio options" ,sizeof( ac97_argument_list )/sizeof(cmdline_argument_t), ac97_argument_list }
	command-line argument group for AC'97

static CHAR16 *	AC97_REVISION_IDS []
	internal: list of AC'97 revision ID strings More...

static CHAR16 *	AC97_CODEC_CONFIGURATION_IDS []
	internal: list of AC'97 code configuration ID string More...

Detailed Description

AC'97 audio functions.

Author: Richard Nusser

Copyright: 2017-2018 Richard Nusser

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

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

Todo:: could add double-rate audio support

Function Documentation

◆ validate_volume()

BOOLEAN validate_volume ( cmdline_value_t value )

validator for "-volume" command-line argument

Parameters

value the value to validate

Returns: whether the valid is a valid volume

◆ validate_sample_rate()

BOOLEAN validate_sample_rate ( cmdline_value_t value )

validator for "-sample-rate" command-line argument

Parameters

value the value to validate

Returns: whether the valid is a valid sample rate

◆ 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_buffers()

int init_buffers	(	ac97_buffers_s16_t *	buffers,
		UINT64	hardware_address
	)

Initializes AC'97 audio buffers.

Parameters

buffers	the buffer structure to initialize
hardware_address	the hardware memory address to write into the descriptor structure

Returns: 0 on success, anything else on error

◆ 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

◆ get_busmaster_register_width()

static UINTN get_busmaster_register_width ( UINT32 reg )

inlinestatic

internal: returns a bus master register's width

Parameters

reg	the bus master register

Returns: the width, for use in UEFI's Io.Write() and Io.Read()

◆ 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

◆ 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

◆ _determine_maximum_master_volume()

static void _determine_maximum_master_volume ( ac97_handle_t * handle )

static

Internal: determines the maximum master volume value.

The master volume register is either 5 or 6 bits wide. If the 6th bit is written to but not supported the first 5 bits will be set to 1 instead.

Parameters

handle the AC'97 handle to use and update

◆ 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

◆ 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

◆ _trace_busmaster_status_register()

static void _trace_busmaster_status_register	(	CHAR16 *	name,
		ac97_busmaster_status_t	value
	)

static

internal: dumps a bus master status register's content

Parameters

name	the register's name to display
value	the register's value

◆ 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

◆ 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

◆ 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

Variable Documentation

◆ ac97_argument_list

cmdline_argument_t ac97_argument_list[]

Initial value:

= {
  {{uint64:0},    ARG_BOOL,  NULL,                L"-mute",       L"mutes output"},
  {{dbl:0.66},    ARG_DOUBLE,validate_volume,     L"-volume",     L"sets output volume min=0.0, max=1.0"},
  {{uint64:44100},ARG_INT,   validate_sample_rate,L"-sample-rate",L"sets sample rate (only 48000 guaranteed by AC'97 specs)"},
}

AC'97 command-line argument list.

◆ AC97_REVISION_IDS

CHAR16* AC97_REVISION_IDS[]

static

Initial value:

={
  L"Revision 2.1 or earlier",
  L"Revision 2.2",
  L"Revision 2.3",
  L"Reserved"
}

internal: list of AC'97 revision ID strings

◆ AC97_CODEC_CONFIGURATION_IDS

CHAR16* AC97_CODEC_CONFIGURATION_IDS[]

static

Initial value:

={
  L"Primary",
  L"Secondary",
  L"Secondary",
  L"Secondary"
}

internal: list of AC'97 code configuration ID string

Functions

Variables

Detailed Description

Function Documentation

◆ validate_volume()

◆ validate_sample_rate()

◆ find_ac97_device()

◆ init_buffers()

◆ write_mixer_reg()

◆ read_mixer_reg()

◆ get_busmaster_register_width()

◆ write_busmaster_reg()

◆ read_busmaster_reg()

◆ set_ac97_cmdline_volume()

◆ set_ac97_cmdline_sample_rate()

◆ _determine_maximum_master_volume()

◆ init_ac97_handle()

◆ close_ac97_handle()

◆ flush_ac97_output()

◆ ac97_play()

◆ _trace_busmaster_status_register()

◆ ac97_wait_until_last_buffer_sent()

◆ print_volume_register()

◆ print_volume_register_mono()

◆ dump_audio_registers()

Variable Documentation

◆ ac97_argument_list

◆ AC97_REVISION_IDS

◆ AC97_CODEC_CONFIGURATION_IDS