ctrl_init()

Your Audio HW DLL must provide an entry point called ctrl_init(), of type ado_ctrl_dll_init_t. When io-audio loads your Audio HW DLL, it calls this function. The prototype is:

int32_t ctrl_init( HW_CONTEXT_T **hw_context,
                   ado_card_t *card,
                   char *args )

The arguments are:

hw_context

A location where your ctrl_init() function can store a pointer to a context-specific state structure for the card. You can define HW_CONTEXT_T to be whatever structure you want; by default, it's defined to be struct hw_context.

card

A pointer to an internal card structure, ado_card_t.

This structure isn't defined in the scope of this DDK; its contents are only known to the io-audio layer. You'll need to save this pointer to pass to some functions, such as ado_mixer_create(), that your Audio HW DLL might call.

args

Any command-line arguments that were part of the io-audio or mount command (for more information, see the QNX Utilities Reference).

The first job of this initialization code is to allocate its context-specific state structure. You can allocate the hardware context by calling ado_calloc() or ado_malloc().

Next, you need to verify that the hardware is present in the system. How you do this depends on your driver; in some cases, it isn't possible:

• If your card is a PCI device, the easiest way to attach to the card is by calling ado_pci_device(). This function even parses the driver arguments to find the right card to attach to.

  The ado_pci_device() function returns a pointer to a ado_pci structure that describes a selected PCI card. Keep a copy of this pointer in your hardware context.

• If your hardware is on another bus, you have to check the arguments, using getsubopt() (see the QNX Library Reference) to determine what hardware your driver should try to use.

You should set the short and long names that audio applications will use to identify your card's type and the specific instance of the hardware; call ado_card_set_shortname() and ado_card_set_longname().

In addition to the above, the initialization depends on what features your Audio HW DLL supports:

• If you're writing your own audio mixer, you need to create it and its elements. See "Writing an analog mixer" in the Handling Analog Audio Data chapter.
• If you're using a standard audio mixer, you need to open its DLL. See "Using a standard mixer DLL" in the Handling Analog Audio Data chapter.
• If you want to support digital audio, you need to create a Pulse Code Modulation (PCM) device. See the Handling PCM Audio Data chapter.

If the initialization is successful, ctrl_init() should return 0. If an error occurs, ctrl_init() should return -1; in this case, io-audio unmounts the card.