KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Data Structures | Macros | Typedefs | Functions
sip.h File Reference

Definitions for using the Sound Input Peripheral. More...

#include <sys/cdefs.h>
#include <sys/types.h>
#include <dc/maple.h>

Go to the source code of this file.

Data Structures

struct  sip_state
 SIP status structure. More...
 

Macros

#define SIP_SUBCOMMAND_GET_SAMPLES   0x01
 Get recorded samples from the microphone device. More...
 
#define SIP_SUBCOMMAND_BASIC_CTRL   0x02
 Start and stop sampling. More...
 
#define SIP_MIN_GAIN   0x00
 Minimum microphone gain. More...
 
#define SIP_DEFAULT_GAIN   0x0F
 Default microphone gain. More...
 
#define SIP_MAX_GAIN   0x1F
 Maximum microphone gain. More...
 
#define SIP_SAMPLE_16BIT_SIGNED   0x00
 Record 16-bit signed integer samples. More...
 
#define SIP_SAMPLE_8BIT_ULAW   0x01
 Record 8-bit ulaw samples. More...
 
#define SIP_SAMPLE_11KHZ   0x00
 Record samples at 11.025kHz. More...
 
#define SIP_SAMPLE_8KHZ   0x01
 Record samples at 8kHz. More...
 

Typedefs

typedef void(* sip_sample_cb )(maple_device_t *dev, uint8 *samples, size_t len)
 Type for a microphone sample callback. More...
 
typedef struct sip_state sip_state_t
 SIP status structure. More...
 

Functions

int sip_set_gain (maple_device_t *dev, unsigned int g)
 Set the microphone's gain value. More...
 
int sip_set_sample_type (maple_device_t *dev, unsigned int type)
 Set the sample type to be recorded by the microphone. More...
 
int sip_set_frequency (maple_device_t *dev, unsigned int freq)
 Set the sample frequency to be recorded by the microphone. More...
 
int sip_start_sampling (maple_device_t *dev, sip_sample_cb cb, int block)
 Start sampling on a microphone. More...
 
int sip_stop_sampling (maple_device_t *dev, int block)
 Stop sampling on a microphone. More...
 

Detailed Description

Definitions for using the Sound Input Peripheral.

This file contains the definitions needed to access the Maple microphone type device (the Seaman mic). Many thanks go out to ZeZu who pointed me toward what some of the commands actually do in the original version of this driver.

As a note, the device itself is actually referred to by the system as the Sound Input Peripheral, so hence why this driver is named as it is.

Author
Lawrence Sebald

Macro Definition Documentation

#define SIP_DEFAULT_GAIN   0x0F

Default microphone gain.

#define SIP_MAX_GAIN   0x1F

Maximum microphone gain.

#define SIP_MIN_GAIN   0x00

Minimum microphone gain.

#define SIP_SAMPLE_11KHZ   0x00

Record samples at 11.025kHz.

#define SIP_SAMPLE_16BIT_SIGNED   0x00

Record 16-bit signed integer samples.

#define SIP_SAMPLE_8BIT_ULAW   0x01

Record 8-bit ulaw samples.

#define SIP_SAMPLE_8KHZ   0x01

Record samples at 8kHz.

#define SIP_SUBCOMMAND_BASIC_CTRL   0x02

Start and stop sampling.

This subcommand is used with the MAPLE_COMMAND_MICCONTROL command to start and stop sampling on the microphone.

#define SIP_SUBCOMMAND_GET_SAMPLES   0x01

Get recorded samples from the microphone device.

This subcommand is used with the MAPLE_COMMAND_MICCONTROL command to fetch samples from the microphone.

Typedef Documentation

typedef void(* sip_sample_cb)(maple_device_t *dev, uint8 *samples, size_t len)

Type for a microphone sample callback.

This is the signature that is required for a function to accept samples from the microphone as it is sampling. This function will be called about once per frame, and in an interrupt context (so it should be pretty quick to execute). Basically, all you should do in one of these is copy the samples out to your own buffer – do not do any processing on the samples in your callback other than to copy them out!

Parameters
devThe device the samples are coming from.
samplesPointer to the sample buffer.
lenThe number of bytes in the sample buffer.
typedef struct sip_state sip_state_t

SIP status structure.

This structure contains information about the status of the microphone device and can be fetched with maple_dev_status(). You should not modify any of the values in here, it is all "read-only" to your programs. Modifying any of this, especially while the microphone is sampling could really screw things up.

Function Documentation

int sip_set_frequency ( maple_device_t dev,
unsigned int  freq 
)

Set the sample frequency to be recorded by the microphone.

This function sets the sample frequency that the microphone will record. The default value for this is about 11.025kHz samples. You must call this prior to sip_start_sampling() if you wish to change it from the default.

Parameters
devThe microphone device to set sample type on.
freqThe type of samples requested.
Return values
MAPLE_EOKOn success.
MAPLE_EINVALIDIf freq is invalid.
MAPLE_EFAILIf the microphone is sampling.
See also
SIP_SAMPLE_11KHZ
SIP_SAMPLE_8KHZ
int sip_set_gain ( maple_device_t dev,
unsigned int  g 
)

Set the microphone's gain value.

This function sets the gain value of the specified microphone device to the value given. This should only be called prior to sampling so as to keep the amplification constant throughout the sampling process, but can be changed on the fly if you really want to.

Parameters
devThe microphone device to set gain on.
gThe value to set as the gain.
Return values
MAPLE_EOKOn success.
MAPLE_EINVALIDIf g is out of range.
See also
SIP_MIN_GAIN
SIP_DEFAULT_GAIN
SIP_MAX_GAIN
int sip_set_sample_type ( maple_device_t dev,
unsigned int  type 
)

Set the sample type to be recorded by the microphone.

This function sets the sample type that the microphone will return. The default value for this is 16-bit signed integer samples. You must call this prior to sip_start_sampling() if you wish to change it from the default.

Parameters
devThe microphone device to set sample type on.
typeThe type of samples requested.
Return values
MAPLE_EOKOn success.
MAPLE_EINVALIDIf type is invalid.
MAPLE_EFAILIf the microphone is sampling.
See also
SIP_SAMPLE_16BIT_SIGNED
SIP_SAMPLE_8BIT_ULAW
int sip_start_sampling ( maple_device_t dev,
sip_sample_cb  cb,
int  block 
)

Start sampling on a microphone.

This function informs a microphone it should start recording samples.

Parameters
devThe device to start sampling on.
cbA callback to call when samples are ready.
blockSet to 1 to wait for the SIP to start sampling. Otherwise check the is_sampling member of the status for dev to know when it has started.
Return values
MAPLE_EOKOn success.
MAPLE_EAGAINIf the command couldn't be sent, try again later.
MAPLE_EFAILIf the microphone is already sampling or the callback function is NULL.
MAPLE_ETIMEOUTIf the command timed out while blocking.
int sip_stop_sampling ( maple_device_t dev,
int  block 
)

Stop sampling on a microphone.

This function informs a microphone it should stop recording samples.

Parameters
devThe device to stop sampling on.
blockSet to 1 to wait for the SIP to stop sampling. Otherwise check the is_sampling member of the status for dev to know when it has finished.
Return values
MAPLE_EOKOn success.
MAPLE_EAGAINIf the command couldn't be sent, try again later.
MAPLE_EFAILIf the microphone is not sampling.
MAPLE_ETIMEOUTIf the command timed out while blocking.