KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
sip.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  dc/maple/sip.h
4  Copyright (C) 2005, 2008, 2010, 2013 Lawrence Sebald
5 
6 */
7 
8 /** \file dc/maple/sip.h
9  \brief Definitions for using the Sound Input Peripheral.
10 
11  This file contains the definitions needed to access the Maple microphone
12  type device (the Seaman mic). Many thanks go out to ZeZu who pointed me
13  toward what some of the commands actually do in the original version of this
14  driver.
15 
16  As a note, the device itself is actually referred to by the system as the
17  Sound Input Peripheral, so hence why this driver is named as it is.
18 
19  \author Lawrence Sebald
20 */
21 
22 #ifndef __DC_MAPLE_SIP_H
23 #define __DC_MAPLE_SIP_H
24 
25 #include <sys/cdefs.h>
26 __BEGIN_DECLS
27 
28 #include <sys/types.h>
29 #include <dc/maple.h>
30 
31 /** \brief Type for a microphone sample callback.
32 
33  This is the signature that is required for a function to accept samples
34  from the microphone as it is sampling. This function will be called about
35  once per frame, and in an interrupt context (so it should be pretty quick
36  to execute). Basically, all you should do in one of these is copy the
37  samples out to your own buffer -- do not do any processing on the samples
38  in your callback other than to copy them out!
39 
40  \param dev The device the samples are coming from.
41  \param samples Pointer to the sample buffer.
42  \param len The number of bytes in the sample buffer.
43 
44  \headerfile dc/maple/sip.h
45 */
46 typedef void (*sip_sample_cb)(maple_device_t *dev, uint8 *samples, size_t len);
47 
48 /** \brief SIP status structure.
49 
50  This structure contains information about the status of the microphone
51  device and can be fetched with maple_dev_status(). You should not modify
52  any of the values in here, it is all "read-only" to your programs. Modifying
53  any of this, especially while the microphone is sampling could really screw
54  things up.
55 
56  \headerfile dc/maple/sip.h
57 */
58 typedef struct sip_state {
59  /** \brief The gain value for the microphone amp. */
60  int amp_gain;
61 
62  /** \brief The type of samples that are being recorded. */
64 
65  /** \brief What frequency are we sampling at? */
66  int frequency;
67 
68  /** \brief Is the mic currently sampling? */
70 
71  /** \brief Sampling callback. */
73 } sip_state_t;
74 
75 /** \brief Get recorded samples from the microphone device.
76 
77  This subcommand is used with the MAPLE_COMMAND_MICCONTROL command to fetch
78  samples from the microphone.
79 */
80 #define SIP_SUBCOMMAND_GET_SAMPLES 0x01
81 
82 /** \brief Start and stop sampling.
83 
84  This subcommand is used with the MAPLE_COMMAND_MICCONTROL command to start
85  and stop sampling on the microphone.
86 */
87 #define SIP_SUBCOMMAND_BASIC_CTRL 0x02
88 
89 /** \brief Minimum microphone gain. */
90 #define SIP_MIN_GAIN 0x00
91 
92 /** \brief Default microphone gain. */
93 #define SIP_DEFAULT_GAIN 0x0F
94 
95 /** \brief Maximum microphone gain. */
96 #define SIP_MAX_GAIN 0x1F
97 
98 /** \brief Set the microphone's gain value.
99 
100  This function sets the gain value of the specified microphone device to
101  the value given. This should only be called prior to sampling so as to keep
102  the amplification constant throughout the sampling process, but can be
103  changed on the fly if you really want to.
104 
105  \param dev The microphone device to set gain on.
106  \param g The value to set as the gain.
107  \retval MAPLE_EOK On success.
108  \retval MAPLE_EINVALID If g is out of range.
109  \see SIP_MIN_GAIN
110  \see SIP_DEFAULT_GAIN
111  \see SIP_MAX_GAIN
112 */
113 int sip_set_gain(maple_device_t *dev, unsigned int g);
114 
115 /* Sample types. These two values are the only defined types of samples that
116  the SIP can output. 16-bit signed is your standard 16-bit signed samples,
117  where 8-bit ulaw is obvously encoded as ulaw. */
118 
119 /** \brief Record 16-bit signed integer samples. */
120 #define SIP_SAMPLE_16BIT_SIGNED 0x00
121 
122 /** \brief Record 8-bit ulaw samples. */
123 #define SIP_SAMPLE_8BIT_ULAW 0x01
124 
125 /** \brief Set the sample type to be recorded by the microphone.
126 
127  This function sets the sample type that the microphone will return. The
128  default value for this is 16-bit signed integer samples. You must call this
129  prior to sip_start_sampling() if you wish to change it from the default.
130 
131  \param dev The microphone device to set sample type on.
132  \param type The type of samples requested.
133  \retval MAPLE_EOK On success.
134  \retval MAPLE_EINVALID If type is invalid.
135  \retval MAPLE_EFAIL If the microphone is sampling.
136  \see SIP_SAMPLE_16BIT_SIGNED
137  \see SIP_SAMPLE_8BIT_ULAW
138 */
139 int sip_set_sample_type(maple_device_t *dev, unsigned int type);
140 
141 /* Sampling frequencies. The SIP supports sampling at either 8kHz or 11.025 kHz.
142  One of these values should be passed to the sip_set_frequency function. */
143 /** \brief Record samples at 11.025kHz. */
144 #define SIP_SAMPLE_11KHZ 0x00
145 
146 /** \brief Record samples at 8kHz. */
147 #define SIP_SAMPLE_8KHZ 0x01
148 
149 /** \brief Set the sample frequency to be recorded by the microphone.
150 
151  This function sets the sample frequency that the microphone will record. The
152  default value for this is about 11.025kHz samples. You must call this prior
153  to sip_start_sampling() if you wish to change it from the default.
154 
155  \param dev The microphone device to set sample type on.
156  \param freq The type of samples requested.
157  \retval MAPLE_EOK On success.
158  \retval MAPLE_EINVALID If freq is invalid.
159  \retval MAPLE_EFAIL If the microphone is sampling.
160  \see SIP_SAMPLE_11KHZ
161  \see SIP_SAMPLE_8KHZ
162 */
163 int sip_set_frequency(maple_device_t *dev, unsigned int freq);
164 
165 /** \brief Start sampling on a microphone.
166 
167  This function informs a microphone it should start recording samples.
168 
169  \param dev The device to start sampling on.
170  \param cb A callback to call when samples are ready.
171  \param block Set to 1 to wait for the SIP to start sampling.
172  Otherwise check the is_sampling member of the status
173  for dev to know when it has started.
174  \retval MAPLE_EOK On success.
175  \retval MAPLE_EAGAIN If the command couldn't be sent, try again later.
176  \retval MAPLE_EFAIL If the microphone is already sampling or the
177  callback function is NULL.
178  \retval MAPLE_ETIMEOUT If the command timed out while blocking.
179 */
180 int sip_start_sampling(maple_device_t *dev, sip_sample_cb cb, int block);
181 
182 /** \brief Stop sampling on a microphone.
183 
184  This function informs a microphone it should stop recording samples.
185 
186  \param dev The device to stop sampling on.
187  \param block Set to 1 to wait for the SIP to stop sampling.
188  Otherwise check the is_sampling member of the status
189  for dev to know when it has finished.
190  \retval MAPLE_EOK On success.
191  \retval MAPLE_EAGAIN If the command couldn't be sent, try again later.
192  \retval MAPLE_EFAIL If the microphone is not sampling.
193  \retval MAPLE_ETIMEOUT If the command timed out while blocking.
194 */
195 int sip_stop_sampling(maple_device_t *dev, int block);
196 
197 /* \cond */
198 /* Init / Shutdown */
199 int sip_init();
200 void sip_shutdown();
201 /* \endcond */
202 
203 __END_DECLS
204 
205 #endif /* __DC_MAPLE_SIP_H */
int sample_type
The type of samples that are being recorded.
Definition: sip.h:63
void(* sip_sample_cb)(maple_device_t *dev, uint8 *samples, size_t len)
Type for a microphone sample callback.
Definition: sip.h:46
int sip_set_sample_type(maple_device_t *dev, unsigned int type)
Set the sample type to be recorded by the microphone.
int sip_set_gain(maple_device_t *dev, unsigned int g)
Set the microphone's gain value.
One maple device.
Definition: maple.h:237
int sip_set_frequency(maple_device_t *dev, unsigned int freq)
Set the sample frequency to be recorded by the microphone.
Maple Bus driver interface.
sip_sample_cb callback
Sampling callback.
Definition: sip.h:72
SIP status structure.
Definition: sip.h:58
int sip_start_sampling(maple_device_t *dev, sip_sample_cb cb, int block)
Start sampling on a microphone.
struct sip_state sip_state_t
SIP status structure.
int amp_gain
The gain value for the microphone amp.
Definition: sip.h:60
unsigned char uint8
8-bit unsigned integer
Definition: types.h:30
int frequency
What frequency are we sampling at?
Definition: sip.h:66
int is_sampling
Is the mic currently sampling?
Definition: sip.h:69
int sip_stop_sampling(maple_device_t *dev, int block)
Stop sampling on a microphone.