Revise package WM8994, packages Audio and STM32.Board for F746 and F769

[pat-rogers]

Revision of package WM8994, leading to revisions of packages Audio and STM32.Board
for F746 and F769

• wm8994.ads:

  • The primary ADT name is changed from WM8994_Device to Audio_CODEC and
    is moved to the top of the package declaration.

  • The implementation of the primary ADT was a null record, but now includes
    a component tracking the current output device selected by the client, and
    whether input is enabled. These components are used in the subprogram bodies
    to implement the functionality, and replace two global variables previously
    declared in the package body (and Current_Output is no longer a Boolean).

  • The ADT name change is propagated throughout the routines' parameter profiles.

  • Four additional frequencies are now declared and supported.

  • New type Audio_Sample_Width is introduced for new support of specifying
    audio sample bit widths.

  • The Volume_Level type is changed from a percentage to the device-specific
    range. (Package Audio, the wrapper for WM8994, uses a percentage for the
    volume and so it translates the client's percentage value to the device-specific
    value.

  • Procedure Init is renamed to Initialize, and a new bit-width formal parameter
    is added.

  • New procedure Set_Sample_Width is declared.

  • The name of procedure Set_Output_Mode is changed to Set_Output_Device
    since that's what it does.

  • The name of function Read_Id is changed to Chip_Id.

  • The declaration for each subprogram is given comments describing the
    routine's purpose.

  • Procedure I2C_Write and function I2C_Read are moved from the private part to
    a new child package named WM8994.IO.

• wm8994-io.ads/adb:

  • The many numeric literals passed to calls to I2C_Write and I2C_Read in
    the body of WM8994 that specify the register to write/read are replaced
    by named constants for readability and correctness. These constants are
    declared in the spec of this new child package named WM8994.IO. The new
    package body declares the bodies for the two I2C routines.

• wm8994.adb:

• Much code is refactored into several new helper routines for the sake of
  readability and comprehension, replacing long sequences of calls to the
  I2C_Wrte routine.

• Most routines now include explanatory comments, especially when the code is not
  otherwise clear. For example, the body of procedure Initialize starts with a
  sequence of I2C_Write calls that are workarounds for errata but that are not
  documented in any way in the original.

• Several of the routines did not take into account which input or output
  device was selected for use. Instead, for example, they enabled both speaker
  and headphone paths regardless. That has been corrected, occasionally requiring
  additional parameters/components (such as Current_Output).

• The refactoring helper routines make the code much simpler to read and
  follow, and the named numbers used for the register values greatly facility
  comprehension and correctness.

• audio.ads, in both the F746 and F769 source folders:

  • There are two versions of package Audio. Although they are highly similar, there
    are some hardware differences, reflected in the package bodies. In the
    following change descriptions those differences are largely irrelevant.

  • These Audio packages are wrappers for the board-specific CODEC on the boards.
    Both boards use the WM8994 so both of their package Audio packages were
    affected and improved by the changes to package WM8994.

  • The package Audio spec is now standalone, defining types for the sampling
    frequency, sampling bit-width, and buffer, independent of the HAL.Audio
    package. These Audio packages define a primary ADT type that was never an
    extension of the HAL.Audio types and just used some of that package's
    types for convenience. It is better to declare the types locally in that
    case, and these new types reflect (by derivation) the WM8994 types they
    wrap.

  • The primary ADT name is changed from type WM8994_Audio_Device to type
    WM8994_Audio_CODEC since "_Device" added nothing meaningful.

  • The frequency and bit-width types are declared in the package spec,
    as derivatives of the two types declared by WM8994.

  • The array type Audio_Buffer replaces the type from HAL.Audio, for the
    reasons given above but also for the sake of reflecting the CODEC being
    wrapped. Note that the component type is still 16-bits, thus limiting the
    sample width to that size. The CODEC can handle larger widths so we should
    consider making the component type 32 bits, which argues against it being
    set in stone in the HAL.Audio package.

  • Procedure Initialize (renamed from Init) now also takes two new formal
    parameters for the bit-width and the output device chosen.

  • The primary ADT WM8994_Audio_CODEC now has an additional component indicating
    the output device selected by the client (via Initialize). This component is
    used to only manage the actual device in use, rather than managing most/all
    of the options regardless.

• audio.ads, in both the F746 and F769 source folders:

  • Procedure Set_Audio_Clock now supports the additional frequencies added to
    package WM8994.

  • Procedure Initialize_SAI_Out now takes an additional formal parameter
    indicating the output device. That parameter is used to determine the
    specific "active slots" required, rather than the hard-coded subset
    previously specified.

  • New convenience function As_Device_Volume converts the given percentage
    from the client's view into the value range defined by the CODEC.

• stm32-board.ads, in both in both the F746 and F769 source folders:

  • The type name for the existing object Audio_Device is changed to
    WM8994_Audio_CODEC.