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 )

descriptionstarts music playback
argumentsscores : 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-
explanationStarts 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 )

descriptionstops music playback
argumentsforce : When this value is 1, force stop will be executed (not implemented).
return value-
explanationStop 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 )

descriptionGets the plaback status
arguments-
return valueThe plaback status
explanationGets the plaback status.
If any of the channel plays music, this function returns true.

typedef void (*PIANO4INT_CB)( uint32_t channel, uint32_t value )

descriptioncall back function by playing synchonized marker
argumentschannel : Channel number
value : Synchronized marker ID
return value-
explanationThis 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 )

descriptionopens driver
argumentschannel : Channel number (0~3)
clock : clock
return valuesuccess : DEVDRV_SUCCESS
error : DEVDRV_ERROR, etc.
explanationThis 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 )

descriptionCloses driver
argumentschannel : Channel number (0~3)
return valuesuccess : DEVDRV_SUCCESS
error : DEVDRV_ERROR,etc.
explanationThis 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 )

descriptionGenerates single tone.
argumentschannel : Channel number (0~3)
note : Tone parameters
return valuesuccess : DEVDRV_SUCCESS
error : DEVDRV_ERROR,etc.
explanationThis 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 )

descriptionOpen driver
argument-
return valuesuccess : DEVDRV_SUCCESS
error : the other
explanationUser 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 )

descriptionClose driver
argument-
return valuesuccess : DEVDRV_SUCCESS
error : the other
explanationUser 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().

membermeaninghardware register
tonespecifies single toneTONE[6:0]
sfsreferrence frequencySFS[7:0]
loudstores the duty data for pulse output.LD[7:0]
attenuationTurns the attenuator function on and off, and select the attenuation cycleDPF[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.

enumereatemeaning
R_SDG_CLOCK_2P0φ/2
R_SDG_CLOCK_4P0φ/4
R_SDG_CLOCK_8P0φ/8
R_SDG_CLOCK_16P0φ/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.

enumeratemeaning
R_SDG_ATT_OFFAttenuator function is off.
R_SDG_ATT_1Attenuates at the TONE frequency
R_SDG_ATT_2Attenuates at the TONE frequency/2
R_SDG_ATT_4Attenuates at the TONE frequency/4
R_SDG_ATT_8Attenuates at the TONE frequency/8
R_SDG_ATT_16Attenuates at the TONE frequency/16
R_SDG_ATT_32Attenuates 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_2P0φ/2
R_SDG_CLOCK_4P0φ/4
R_SDG_CLOCK_8P0φ/8
R_SDG_CLOCK_16P0φ/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_1TONE周波数で減衰します
R_SDG_ATT_2TONE周波数の1/2で減衰します
R_SDG_ATT_4TONE周波数の1/4で減衰します
R_SDG_ATT_8TONE周波数の1/8で減衰します
R_SDG_ATT_16TONE周波数の1/16で減衰します
R_SDG_ATT_32TONE周波数の1/32で減衰します

sdg_driver/sdg.c

Committer:
MasaoHamanaka
Date:
2015-01-30
Revision:
0:a3a1d4768307

File content as of revision 0:a3a1d4768307:

/*******************************************************************************
* DISCLAIMER
* This software is supplied by Renesas Electronics Corporation and is only
* intended for use with Renesas products. No other uses are authorized. This
* software is owned by Renesas Electronics Corporation and is protected under
* all applicable laws, including copyright laws.
* THIS SOFTWARE IS PROVIDED "AS IS" AND RENESAS MAKES NO WARRANTIES REGARDING
* THIS SOFTWARE, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING BUT NOT
* LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
* AND NON-INFRINGEMENT. ALL SUCH WARRANTIES ARE EXPRESSLY DISCLAIMED.
* TO THE MAXIMUM EXTENT PERMITTED NOT PROHIBITED BY LAW, NEITHER RENESAS
* ELECTRONICS CORPORATION NOR ANY OF ITS AFFILIATED COMPANIES SHALL BE LIABLE
* FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES FOR
* ANY REASON RELATED TO THIS SOFTWARE, EVEN IF RENESAS OR ITS AFFILIATES HAVE
* BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
* Renesas reserves the right, without notice, to make changes to this software
* and to discontinue the availability of this software. By using this software,
* you agree to the additional terms and conditions found by accessing the
* following link:
* http://www.renesas.com/disclaimer
* Copyright (C) 2012 - 2015 Renesas Electronics Corporation. All rights reserved.
*******************************************************************************/

/******************************************************************************
Includes   <System Includes> , "Project Includes"
******************************************************************************/
#include <stdint.h>
#include "dev_drv.h"                    /* Device Driver common header */
#include "devdrv_sdg.h"                 /* SDG Driver header */
#include "iodefine.h"
#include "gpio_iobitmask.h"
#include "sdg_iobitmask.h"
#include "rza_io_regrw.h"

/******************************************************************************
Typedef definitions
******************************************************************************/
typedef int32_t (*Userdef_Open)(void);
typedef int32_t (*Userdef_Close)(void);

/******************************************************************************
Macro definitions
******************************************************************************/
#define REGW8(CH, REG, BIT, VAL) RZA_IO_RegWrite_8(&CH->REG, VAL, SDGn_##REG##_##BIT##_SHIFT, SDGn_##REG##_##BIT)

/******************************************************************************
Imported global variables and functions (from other files)
******************************************************************************/


/******************************************************************************
Exported global variables and functions (to be accessed by other files)
******************************************************************************/


/******************************************************************************
Private global variables and functions
******************************************************************************/
static struct st_sdg * const stSDG[SDG_CH_TOTAL] = {
    &SDG0,
    &SDG1,
    &SDG2,
    &SDG3,
};


/******************************************************************************
* Function Name: R_SDG_Open
* Description  : Start the SDG specified by the argument channel.
* Arguments    : uint32_t channel  : SDG channel (0, 1, 2, or 3)
*              : R_SDG_CLOCK clock : SGCLK
* Return Value : DEVDRV_SUCCESS    : Success to start counting SDG
*              : DEVDRV_ERROR      : Failure
******************************************************************************/
int32_t R_SDG_Open(uint32_t channel, R_SDG_CLOCK clock)
{
    static const Userdef_Open   userdef_open[SDG_CH_TOTAL] = {
        &Userdef_SDG0_Open,
        &Userdef_SDG1_Open,
        &Userdef_SDG2_Open,
        &Userdef_SDG3_Open,
    };
    int32_t ret = DEVDRV_SUCCESS;


    /* check argument */
    if (channel >= SDG_CH_TOTAL) {
        return DEVDRV_ERROR;        /* argument error */
    }

    /* ==== SDG initialization ==== */
    ret = userdef_open[channel]();
    if (DEVDRV_SUCCESS == ret) {
        /* ==== Start SDG ==== */
        REGW8(stSDG[channel], SGCR1, STPM, 1);                /* set SDG deactivate method: none */
        REGW8(stSDG[channel], SGCR1, SGCK, (uint8_t)clock);   /* clock */
        REGW8(stSDG[channel], SGCSR, SGIE, 0);                /* interrupt: disabled */
    }

    return ret;
}

/******************************************************************************
* Function Name: R_SDG_Close
* Description  : Stop the SDG specified by the argument channel.
* Arguments    : uint32_t channel : SDG channel (0, 1, 2 or 3)
* Return Value : DEVDRV_SUCCESS   : Success to stop counting SDG
*              : DEVDRV_ERROR     : Failure
******************************************************************************/
int32_t R_SDG_Close(uint32_t channel)
{
    static const Userdef_Close    userdef_close[SDG_CH_TOTAL] = {
        &Userdef_SDG0_Close,
        &Userdef_SDG1_Close,
        &Userdef_SDG2_Close,
        &Userdef_SDG3_Close,
    };
    int32_t ret = DEVDRV_SUCCESS;

    /* check argument */
    if (channel >= SDG_CH_TOTAL) {
        return DEVDRV_ERROR;        /* Argument error */
    }

    /* ==== SDG finalization ==== */
    ret = userdef_close[channel]();

    return ret;
}


/******************************************************************************
* Function Name: R_SDG_Tone
* Description  : Set freqency registers
* Arguments    : uint32_t channel : SDG channel (0, 1, 2 or 3)
*              : NOTE *note       : a note parameters
* Return Value : DEVDRV_SUCCESS   : Success to play a note
*              : DEVDRV_ERROR     : Failure
******************************************************************************/
int32_t R_SDG_Tone(uint32_t channel, NOTE *note)
{
    uint16_t    tone;
    uint16_t    sfs;
    uint16_t    loud;
    uint16_t    att;
    int32_t     ret = DEVDRV_SUCCESS;


    /* check parameter */
    if ((channel >= SDG_CH_TOTAL) || (note->tone > SDG_TONE_MAX)) {
        return DEVDRV_ERROR;        /* Argument error */
    }

    tone = (0 == note->tone) ? (1): (note->tone);
    sfs  = (0 == note->sfs ) ? (1): (note->sfs);
    loud = note->loud;
    att  = note->attenuation;

    /* ==== Set frequency registers ==== */
    /* start sgd */
    REGW8(stSDG[channel], SGCR1, SGST,  1);         /* start sgd */
    REGW8(stSDG[channel], SGCR2, SGEND, 0);         /* stop bit : continue */
    /* enable SGTFR / SGSFR register to write */
    REGW8(stSDG[channel], SGCR2, TCHG,  1);         /* change : enable */
    /* set each parameter */
    REGW8(stSDG[channel], SGTFR, TONE,  tone);      /* tone */
    REGW8(stSDG[channel], SGSFR, SFS,   sfs);       /* sfs */
    REGW8(stSDG[channel], SGLR,  LD,    loud);      /* loud */
    REGW8(stSDG[channel], SGCR1, DPF,   att);       /* attenuation */
    if (note->attenuation != 0) {
        REGW8(stSDG[channel], SGCR1, SGST, 0);      /* stop sgd */
    }

    return ret;
}

/* End of File */