Renesas
Sound Generator Library
Fork of
Sound_Generator
by 
GR-PEACH_producer_meeting
Information
Japanese version is available in lower part of this page.
このページの後半に日本語版が用意されています．
Sound Generator
What is this?
Driver library for Sound Generator that is function of RZ/A1H.
API
Driver Wrapper API
You can use music playback function to call following APIs.
void piano4int_start( const int8_t *scores[SDG_CH_TOTAL], PIANO4INT_CB callback )
| description | starts music playback |
|---|---|
| arguments | scores : music data of each chanel. The number of channels is specified by SDG_CH_TOTAL. callback : call back function by playing synchonized marker |
| return value | - |
| explanation | Starts music playback. For channels not to play, set NULL to the corresponding element of scores[]. Playback is controlled by interrupt handler. So, this function returns after initialization. "Callback" function will be called from interrupt handler when synchronized marker is played. |
void piano4int_stop( bool force )
| description | stops music playback |
|---|---|
| arguments | force : When this value is 1, force stop will be executed (not implemented). |
| return value | - |
| explanation | Stop misic playback. This function returns after finishing music playback of all channels. This function stops interrupts, but does not release objects. |
bool piano4int_status( void )
| description | Gets the plaback status |
|---|---|
| arguments | - |
| return value | The plaback status |
| explanation | Gets the plaback status. If any of the channel plays music, this function returns true. |
typedef void (*PIANO4INT_CB)( uint32_t channel, uint32_t value )
| description | call back function by playing synchonized marker |
|---|---|
| arguments | channel : Channel number value : Synchronized marker ID |
| return value | - |
| explanation | This is a user function call back by playing synchronized marker.. The argument "value" is set to the number that is described after synchronized marker. This function is called in interrupt hander, so please shorten the processing of this function. |
Driver API
int32_t R_SDG_Open( uint32_t channel, R_SDG_CLOCK clock )
| description | opens driver |
|---|---|
| arguments | channel : Channel number (0～3) clock : clock |
| return value | success : DEVDRV_SUCCESS error : DEVDRV_ERROR, etc. |
| explanation | This function initializes sound generator specified by argument "channel". "clock" to set the clock to be used in the internal sound generator from either from P0φ/2 to P0φ/16. Sample code accepts channel 1 and channel 3 only. If channel 0 or 2 is specified, this function returns an error. |
int32_t R_SDG_Close( uint32_t channel )
| description | Closes driver |
|---|---|
| arguments | channel : Channel number (0～3) |
| return value | success : DEVDRV_SUCCESS error : DEVDRV_ERROR,etc. |
| explanation | This function terminates sound generator specified by argument "channel". In Sample code, once this function is called, clock supply is stopped, this driver will not work until calling R_SDG_Open(). If target channel has not initialized by R_SDG_Open(), this function returns error code. |
int32_t R_SDG_Tone( uint32_t channel, NOTE *note )
| description | Generates single tone. |
|---|---|
| arguments | channel : Channel number (0～3) note : Tone parameters |
| return value | success : DEVDRV_SUCCESS error ： DEVDRV_ERROR,etc. |
| explanation | This function generates single tone. Tone is specified by argument "note". Pitch is determined by the following equation. Reference frequency = "clock" / [note->sfs] Pitch = [Reference frequency] / ( 2 × [note->tone] ) Loudness is determined by note->loud. note->loud specifies the duty of the square wave to be syncthesized sound to be output. Period square wave is high will be calculated in [note->loud / 256]. Attenuation rate is specified by note->attenuation. Attenuation is achieved by make the note->loud to 31/32 with the given period by note->attenuation. If target channel has not initialized by R_SDG_Open(), this function returns error code. |
User Definition Functions
int32_t Userdef_SDG0_Open( void )
int32_t Userdef_SDG1_Open( void )
int32_t Userdef_SDG2_Open( void )
int32_t Userdef_SDG3_Open( void )
| description | Open driver |
|---|---|
| argument | - |
| return value | success : DEVDRV_SUCCESS error : the other |
| explanation | User of this driver must create this function. This function is called from R_SDG_Open(), so user must create this function for each 4 channels. In this function, user must operate following operation. ・Supplies clock to the sound generator. ・Sets pin-mux for the sound generator. In the case this function is succeed, please set the return value of this function to DEVDRV_SUCCESS. The other value indicate an error and copy to the return value of R_SDG_Open() function. In the sample code, initializing routine is described for channel 1 and 3, and an error routine is described for channel 0 and 2. |
int32_t Userdef_SDG0_Close( void )
int32_t Userdef_SDG1_Close( void )
int32_t Userdef_SDG2_Close( void )
int32_t Userdef_SDG3_Close( void )
| description | Close driver | |
|---|---|---|
| argument | - | |
| return value | success : DEVDRV_SUCCESS error : the other | |
| explanation | User of this driver must create this function. This function is called from R_SDG_Close(), so user must create this function for each 4 channels. In this function, user must operate following operation. ・Sets pin-mux for GPIO. ・Stops the clock supply to the sound generator In the case this function is succeed, please set the return value of this function to DEVDRV_SUCCESS. The other value indicate an error and copy to the return value of R_SDG_Close() function. In the sample code, uninitializing routine is described for channel 1 and 3, and an error routine is described for channel 0 and 2. |
structures
typedef struct {
UINT8_T TONE; /* TONE VALUE ( 0 < TONE <= 127 ) */
UINT8_T SFS; /* SFS VALUE ( 0 < SFS <= 255 ) */
UINT8_T LOUD; /* LD VALUE ( 0 <= LD <= 255 ) */
UINT8_T ATTENUATION; /* ATTENUATION VALUE */
} NOTE;
This structure specifies single tone.This structure is used in argument of R_SDG_Tone().
| member | meaning | hardware register |
|---|---|---|
| tone | specifies single tone | TONE[6:0] |
| sfs | referrence frequency | SFS[7:0] |
| loud | stores the duty data for pulse output. | LD[7:0] |
| attenuation | Turns the attenuator function on and off, and select the attenuation cycle | DPF[2:0] |
enumerate
typedef enum {
R_SDG_CLOCK_2 = 0,
R_SDG_CLOCK_4 = 1,
R_SDG_CLOCK_8 = 2,
R_SDG_CLOCK_16 = 3,
} R_SDG_CLOCK;
Selects the operating clock.
| enumereate | meaning |
|---|---|
| R_SDG_CLOCK_2 | P0φ/2 |
| R_SDG_CLOCK_4 | P0φ/4 |
| R_SDG_CLOCK_8 | P0φ/8 |
| R_SDG_CLOCK_16 | P0φ/16 |
typedef enum {
R_SDG_ATT_OFF = 0,
R_SDG_ATT_1 = 1,
R_SDG_ATT_2 = 2,
R_SDG_ATT_4 = 3,
R_SDG_ATT_8 = 4,
R_SDG_ATT_16 = 5,
R_SDG_ATT_32 = 6,
} R_SDG_ATTENUATION;
Turns the attenuator function on and off, and select the attenuation cycle.
| enumerate | meaning |
|---|---|
| R_SDG_ATT_OFF | Attenuator function is off. |
| R_SDG_ATT_1 | Attenuates at the TONE frequency |
| R_SDG_ATT_2 | Attenuates at the TONE frequency/2 |
| R_SDG_ATT_4 | Attenuates at the TONE frequency/4 |
| R_SDG_ATT_8 | Attenuates at the TONE frequency/8 |
| R_SDG_ATT_16 | Attenuates at the TONE frequency/16 |
| R_SDG_ATT_32 | Attenuates at the TONE frequency/32 |
サウンドジェネレータ
概要
RZ/A1Hに搭載されているサウンドジェネレータを使用するためのライブラリです。
API
Driver Wrapper API
下記に示すAPIはDriver APIをコールすることで楽曲再生機能を実現します。
void piano4int_start( const int8_t *scores[SDG_CH_TOTAL], PIANO4INT_CB callback )
| 概要 | 楽曲再生開始関数 |
|---|---|
| 引数 | scores ： SDG_CH_TOTALで指定されるチャネル数分の楽譜 callback ： 同期指示関数 |
| 戻り値 | なし |
| 解説 | 楽曲の再生を開始します。 再生しないチャネルは、scores[ ]の該当する要素にNULLを設定します。 再生は、内部でもっているTickerオブジェクトに従って、すべて割り込みで行われます。 従って、この関数は初期化を終えると戻ってきます。 同期指示関数callbackは、楽曲データに埋め込まれた同期マーカを再生したとき、割り込みから呼び出されます。 |
void piano4int_stop( bool force )
| 概要 | 楽曲再生停止関数 |
|---|---|
| 引数 | force ： 強制停止フラグ(未実装) |
| 戻り値 | なし |
| 解説 | 楽曲の再生を停止します。 この関数を呼び出すと、すべての楽曲を再生し終えた後、戻ってきます。 割り込みは使用しなくなりますが、オブジェクトの解放はしません。 |
bool piano4int_status( void )
| 概要 | 楽曲再生状態取得関数 |
|---|---|
| 引数 | なし |
| 戻り値 | 再生状態 |
| 解説 | 現在の再生の状況を取得します。 与えられた楽曲の一つでも再生中ならば、trueを返します。 |
typedef void (*PIANO4INT_CB)( uint32_t channel, uint32_t value )
| 概要 | 同期提示関数 |
|---|---|
| 引数 | channel ： チャネル番号 value ： 同期マーカID |
| 戻り値 | なし |
| 解説 | 楽曲データに組み込んだ同期マーカ付音符を再生するときに呼び出されるユーザ関数です。 valueは、同期マーカの次に書かれている1～2桁の数字を整数型にしたものです。 割り込みの中から呼ばれますので、処理は軽めにしてください。あまり長いと音がずれます。 |
Driver API
int32_t R_SDG_Open( uint32_t channel, R_SDG_CLOCK clock )
| 概要 | サウンドジェネレータ初期化関数 |
|---|---|
| 引数 | channel ： チャネル番号 (0～3) clock ： 動作クロック |
| 戻り値 | 正常終了 ： DEVDRV_SUCCESS エラー終了 ： DEVDRV_ERRORなど |
| 解説 | チャネル番号で指定したサウンドジェネレータを初期化します。 動作クロックは、P0φ／2～P0φ／16から、今後使用するTONEやLOUDNESSに合わせて選択します。 サンプルコードでは、チャネル1及びチャネル3だけが使用できます。チャネル0及びチャネル2を指定した場合はエラー終了します。 |
int32_t R_SDG_Close( uint32_t channel )
| 概要 | サウンドジェネレータ終了関数 |
|---|---|
| 引数 | channel ： チャネル番号 (0～3) |
| 戻り値 | 正常終了 ： DEVDRV_SUCCESS エラー終了 ： DEVDRV_ERRORなど |
| 解説 | 指定したチャネルのサウンドジェネレータの使用を終了します。サンプルコードでは、クロックの供給も停止しますので、 再びR_SDG_Open( )で初期化するまで使用できなくなります。 R_SDG_Open( )を呼び出していないチャネルを指定した場合はエラー終了します。 |
int32_t R_SDG_Tone( uint32_t channel, NOTE *note )
| 概要 | 単音作成関数 |
|---|---|
| 引数 | channel ： チャネル番号 (0～3) note ： トーン設定パラメータ |
| 戻り値 | 正常終了 ： DEVDRV_SUCCESS エラー終了 ： DEVDRV_ERRORなど |
| 解説 | 単音を出力します。音はnoteで指定します。 note->tone、note->sfs、R_SDG_Open( )で指定した動作クロックから、次の式で音の高さを決めます。 基準周波数 ＝ 動作クロック／sfs TONE周波数 ＝ 基準周波数／( 2 × tone ) note->loudで音の大きさを指定します。loudは出力する音に合成する方形波のデューティ比で、 loud ／256が方形波のHighの区間になります。 note->attenuationで減衰率を指定します。指定した周期ごとに、loudを31／32にすることで減衰します。 R_SDG_Open( )を呼び出していないチャネルを指定した場合はエラー終了します。 |
ユーザ定義関数
int32_t Userdef_SDG0_Open( void )
int32_t Userdef_SDG1_Open( void )
int32_t Userdef_SDG2_Open( void )
int32_t Userdef_SDG3_Open( void )
| 概要 | サウンドジェネレータ初期化ユーザ定義関数 |
|---|---|
| 引数 | なし |
| 戻り値 | 正常終了 ： DEVDRV_SUCCESS エラー終了 ： その他 |
| 解説 | このドライバの利用者が作成する関数です。 R_SDG_Open( )から呼び出される関数で、4チャネル分の関数が必要です。 使用するサウンドジェネレータのサウンドジェネレータ初期化ユーザ定義関数では、 最低限、次のことを実施してください。 ・サウンドジェネレータにクロックを供給します。 ・サウンドジェネレータが使う出力ピンの設定をします。 また、正常に終了したとき、DEVDRV_SUCCESSを返してください。この値以外はエラーとみなし、 R_SDG_Open( )の戻り値になります。 サンプルコードでは、チャネル1及びチャネル3は初期化処理を行い、チャネル0及びチャネル2はエラーになります。 |
int32_t Userdef_SDG0_Close( void )
int32_t Userdef_SDG1_Close( void )
int32_t Userdef_SDG2_Close( void )
int32_t Userdef_SDG3_Close( void )
| 概要 | サウンドジェネレータ終了ユーザ定義関数 |
|---|---|
| 引数 | なし |
| 戻り値 | 正常終了 ： DEVDRV_SUCCESS エラー終了 ： その他 |
| 解説 | このドライバの利用者が作成する関数です。 R_SDG_Close( )から呼び出される関数で、4チャネル分の関数が必要です。 これらの関数では、次のことを実施してください。 ・サウンドジェネレータが使う出力ピンをGPIOに変更します。 ・サウンドジェネレータへのクロックの供給を停止します。 また、正常に終了したとき、DEVDRV_SUCCESSを返してください。 この値以外はエラーとみなし、R_SDG_Close( )の戻り値になります。 サンプルコードでは、チャネル1及びチャネル3は終了処理を行い、チャネル0及びチャネル2はエラーになります。 |
構造体
typedef struct {
UINT8_T TONE; /* TONE VALUE ( 0 < TONE <= 127 ) */
UINT8_T SFS; /* SFS VALUE ( 0 < SFS <= 255 ) */
UINT8_T LOUD; /* LD VALUE ( 0 <= LD <= 255 ) */
UINT8_T ATTENUATION; /* ATTENUATION VALUE */
} NOTE;
単音を表す構造体です。R_SDG_Tone( )の引数で使用します。意味と設定するビットを次に示します。
| 要素 | 意味 | ビット名 |
|---|---|---|
| tone | 音色を決める値です | TONE[6:0] |
| sfs | 基準周波数を決める値です | SFS[7:0] |
| loud | 出力パルスのデューティ比を決める値です | LD[7:0] |
| attenuation | 出力の減衰率を決める値です | DPF[2:0] |
列挙型
typedef enum {
R_SDG_CLOCK_2 = 0,
R_SDG_CLOCK_4 = 1,
R_SDG_CLOCK_8 = 2,
R_SDG_CLOCK_16 = 3,
} R_SDG_CLOCK;
動作クロックを表す列挙型です。それぞれ、次の意味をもちます。
| 要素 | 意味 |
|---|---|
| R_SDG_CLOCK_2 | P0φ／2 |
| R_SDG_CLOCK_4 | P0φ／4 |
| R_SDG_CLOCK_8 | P0φ／8 |
| R_SDG_CLOCK_16 | P0φ／16 |
typedef enum {
R_SDG_ATT_OFF = 0,
R_SDG_ATT_1 = 1,
R_SDG_ATT_2 = 2,
R_SDG_ATT_4 = 3,
R_SDG_ATT_8 = 4,
R_SDG_ATT_16 = 5,
R_SDG_ATT_32 = 6,
} R_SDG_ATTENUATION;
減衰率を表す列挙型です。それぞれ、次の意味をもちます。
| 要素 | 意味 |
|---|---|
| R_SDG_ATT_OFF | 減衰しません |
| R_SDG_ATT_1 | TONE周波数で減衰します |
| R_SDG_ATT_2 | TONE周波数の1／2で減衰します |
| R_SDG_ATT_4 | TONE周波数の1／4で減衰します |
| R_SDG_ATT_8 | TONE周波数の1／8で減衰します |
| R_SDG_ATT_16 | TONE周波数の1／16で減衰します |
| R_SDG_ATT_32 | TONE周波数の1／32で減衰します |