SH7125RSLIB

SH7125RSLIB 2.4
easy SH2-7125F RS-232C LIBrary by I.N. 2017/12/7

３ポート（SCI0,1,2）を使用する通信テストのための装置
（RS-232CインターフェースIC：SP233ACP ×２個使用）
更新履歴

2017/12/7　ver.2.4 (v2.2からの変更点）
　　　　　　　　　複数バイトの送受信でたまに発生する問題の解消
　　　　　　　　　.cppからのインクルード用にextern"C"の記述を追加
　　　　　　　　　受信リングバッファおよび送信リングバッファの設計変更
　　　　　　　　　未オープン時のエラー処理を廃止
　　　　　　　　　受信割り込みRXInとERInを別関数にした（割り込み関数名も変更）
　　　　　　　　　いくつかの関数の戻り値をvoid型に変更
　　　　　　　　　バッファサイズを２のべき乗に限定
　　　　　　　　　４．４を削除
2017/12/1　　４．４注意事項を追加，ボーレートの例を追加
2017/11/30　#define SHRS_SENDBUFFERSIZE0の記述で不要なVを削除，４．４注意事項を追加
2011/06/15　ver.2.2　送信関数SHRS_Send()を改良（送信リングバッファ処理の不具合を修正）
2008/10/07　ver.2.1　SHRS_ClearSend()追加
2008/09/11　ver.2.0　送信もリングバッファ仕様とした
2008/07/24　ver.1.1　SCI0/1/2に異なるバッファサイズ指定可，使用ポートを細かく指定可
2008/07/22　ver.1.0　初版

１．はじめに

　CPUボード SH2/7125F でRS-232Cシリアル通信プログラムを作成するための関数ライブラリです．
　動作確認は秋月SH7125F + 開発環境（HEW 4.0.9 または e2studio 5.4.0 & SHC v9.4.3）で行いました．

２．特長

　リングバッファ構造の受信バッファがあり，受信割り込みによって受信データは
バックグラウンドで自動的に受信バッファへ格納されます．
　受信データが来る瞬間にメインプログラムで他の作業を実行していてもデータを
取りこぼすことがありません．
　ただし，受信バッファが一杯になった後に受信したデータはすべて無視（破棄）
されますので，受信バッファが一杯になる前にデータを読み出すようにしてください．

　リングバッファ構造の送信バッファがあり，送信ではデータはいったん送信バッファへ
格納されます．送信バッファへデータの格納が終わると，送信関数の制御はすぐに戻って
くるのでメインプログラムでは次の他の処理を行うことができます．
　送信割り込みによって送信バッファ内のデータはバックグラウンドで自動的に送信されます．
　送信バッファが一杯になった状態で送信関数を実行するとデータはすべて無視（破棄）され
ますので，送信バッファに空きがあることを確認してから送信するようにしてください．

３．使用方法とサンプル

３．１　使用方法
　HEWでプロジェクトを作成したら，まず，割り込みベクタ記述ファイル intprg.c を開き，
次のように216～226番（219, 223を除く）の関数名を書き換えてください．
　これを忘れるとデータの送受信ができません．
　e2studioの場合は interrupt_handlers.c を書き換えてください．

// 216 SCI0 ERI0
void INT_SCI0_ERI0(void){SHRS_recv_eri0();}
// 217 SCI0 RXI0
void INT_SCI0_RXI0(void){SHRS_recv_rxi0();}
// 218 SCI0 TXI0
void INT_SCI0_TXI0(void){SHRS_send_txi0();}
// 219 SCI0 TEI0
void INT_SCI0_TEI0(void){/* sleep(); */}
// 220 SCI1 ERI1
void INT_SCI1_ERI1(void){SHRS_recv_eri1();}
// 221 SCI1 RXI1
void INT_SCI1_RXI1(void){SHRS_recv_rxi1();}
// 222 SCI1 TXI1
void INT_SCI1_TXI1(void){SHRS_send_txi1();}
// 223 SCI1 TEI1
void INT_SCI1_TEI1(void){/* sleep(); */}
// 224 SCI2 ERI2
void INT_SCI2_ERI2(void){SHRS_recv_eri2();}
// 225 SCI2 RXI2
void INT_SCI2_RXI2(void){SHRS_recv_rxi2();}
// 226 SCI2 TXI2
void INT_SCI2_TXI2(void){SHRS_send_txi2();}
// 227 SCI2 TEI2
void INT_SCI2_TEI2(void){/* sleep(); */}

　あとはソースファイルの先頭で次のようにインクルードするだけです．

#include "iodefine.h"
#include "sh7125rslib.h"

３．２　サンプル
　受信した文字をそのまま送り返すプログラム

#include "iodefine.h"
#include "sh7125rslib.h"

int main(void)
{
        char buf[32];
        int n;
        
        SHRS_Open(1);
        SHRS_Sends(1,"Hello!\r\n");

        for(;;){
                n=SHRS_CheckRecv(1);     //受信データの確認

                //もし１文字でも受信データがあれば以下の処理をする
                if(n){
                        n=SHRS_Recv(1,buf,n);   //データの受信

                        while(SHRS_CheckSend(1)<n);     //送信バッファの確認

                        SHRS_Send(1,buf,n);     //データの送信
                }

                //...
                //この間，別の作業をしてもかまわない．
                //...
        }
        return 0;
}

//e2studioの場合，下の記述も追加
extern "C" {
void abort(void){}
}

４．設定の変更

４．１　送受信バッファのサイズ変更
　バッファのサイズのデフォルト値は，送信・受信・いずれのチャンネルも32バイトですが，
下記のようにして変更できます．デフォルト値より大きくすることも小さくすることもできます．
ただし，2のべき乗となる値だけが指定できます．（例，2, 4, 8, 16, 32, 64, …）
最小値は 2 です．大きくすれば，それだけRAMを食います．
SCIの各チャンネルごとに異なるバッファサイズを指定できます．
また，受信と送信で異なるバッファサイズを指定できます．
　v2.4よりリングバッファの構造が変更されたため，
蓄えられる最大データ数は（バッファサイズ-1）バイトとなります．

//受信バッファのサイズ変更
#define SHRS_RECVBUFFERSIZE0 64
#define SHRS_RECVBUFFERSIZE1 512
#define SHRS_RECVBUFFERSIZE2 8
//送信バッファのサイズ変更
#define SHRS_SENDBUFFERSIZE0 16
#define SHRS_SENDBUFFERSIZE1 128
#define SHRS_SENDBUFFERSIZE2 256

#include "sh7125rslib.h"

４．２　ボーレートの変更
　ボーレート（通信速度）のデフォルトは38,400 bps（厳密には39062.5 bps）ですが，
下記のように#define SHRS_BRRx (x=0~2)の追記により変更できます．
　SCIの各チャンネルごとに異なるボーレートを設定できます．

//SCI0/SCI1/SCI2 をすべて 9600 bpsにする場合
#define SHRS_BRR0 80
#define SHRS_BRR1 80
#define SHRS_BRR2 80
#include "sh7125rslib.h"

なお，CPUの周辺クロックPφ=25.0MHz(12.5MHz X'tal)の場合，SCBRR値に対応するボーレートは次のようになります．

SCBRR	ボーレート[bps]	備考
0	781250.0
1	390625.0
2	260416.7
3	195312.5
4	156250.0
5	130208.3
6	111607.1	115200に対し-3.12%
7	97656.3
8	86805.6
9	78125.0
10	71022.7
11	65104.2
12	60096.2
13	55803.6	57600に対し-3.12%
14	52083.3
15	48828.1
16	45955.9
17	43402.8
18	41118.4
19	39062.5	38400に対し+1.73%
20	37202.4
21	35511.4
22	33967.4
23	32552.1
24	31250.0	31250に対し 0.00%
40	19054.9	19200に対し-0.76%
80	9645.1	9600に対し+0.47%

・SCBRR値から動作ボーレートを求める式
　baudrate = 25000000 / ( 32 * (SCBRR + 1) )
　※ただし，Pφ=25.0MHz，ボーレートジェネレータ入力クロックがPφ(n=0)の場合

通信相手との誤差が大きなボーレート設定において，連続した大量のデータを送受信しようと
する場合，誤差が累積して，誤通信（文字化け）が発生する可能性があります．

４．３　使用するポートの変更
　デフォルトでは，SCI0にはRXD0=PA0, TXD0=PA1，SCI1にはRXD1=PA3, TXD1=PA4を
使う設定になっています．これ以外のポートを使うには以下の宣言文の中から必要なものを
#include "sh7125rslib.h" より前に記述します．
　SCI2にはRXD2=PA8, TXD2=PA9以外の選択肢はありません．

・次の２つのうちいずれか一方
#define SHRS_RXD0_PA10
#define SHRS_RXD0_PE1

・次の２つのうちいずれか一方
#define SHRS_TXD0_PA11
#define SHRS_TXD0_PE2

・次の２つのうちいずれか一方
#define SHRS_RXD1_PA14
#define SHRS_RXD1_PE4

・次の２つのうちいずれか一方
#define SHRS_TXD1_PA15
#define SHRS_TXD1_PE5

５．関数リファレンス

================全体に関するもの================

--------------------------------------------------------
void SHRS_Open(int n);
--------------------------------------------------------
説明
　シリアル通信(RS-232C)のポートをオープンします．最初に必要です．
　通信設定は，ボーレート38400bps，スタートビット1bit，ストップビット1bit，パリティなし，
　キャラクタ長8bit，XON/XOFFなしです．
　オープンに成功すると，SHRS_Close() でクローズするまで SH7125RSLIB の各関数が使用可能となります．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
使用例
　SHRS_Open(1);

--------------------------------------------------------
void SHRS_Close(int n);
--------------------------------------------------------
説明
　シリアル通信ポートをクローズします．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
使用例
　SHRS_Close(1);

================送信に関するもの================

--------------------------------------------------------
int SHRS_Send(int n, char *buf, int size);
--------------------------------------------------------
説明
　データの送信を行います．
　送信バッファへデータの格納が終わると制御はすぐに戻ってきます．
　（実際のデータ送信はただちに実行されますが，送信バッファが空で
　ない場合，バッファにたまっているデータの送信が優先されます）
　送信バッファからあふれたデータは無視（破棄）されます．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
　buf：送信データが格納されている領域の先頭アドレス（ポインタ）
　size：送信データのサイズ（単位：バイト）
戻り値
　送信バッファへ格納されたデータのバイト数（単位：バイト）
　（オープンされていないときのエラーチェックはありません）
使用例
　char buf[32];
　SHRS_Send(1,buf,32);

--------------------------------------------------------
int SHRS_CheckSend(int n);
--------------------------------------------------------
説明
　送信バッファの空きサイズをバイト単位で返します．
　データを送信するときは，この関数でバッファの空きを確認してから
　送信するようにすると，データの送信洩れがありません．
　（送信バッファのサイズ－１）より大きな値を返すことはありません．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
戻り値
　送信バッファの空きサイズ（単位：バイト）
使用例
　int n=16;
　char buf[32];
　while(SHRS_CheckSend(1)<n);
　SHRS_Send(1,buf,n);

--------------------------------------------------------
void SHRS_ClearSend(int n);
--------------------------------------------------------
説明
　送信バッファをクリアします．
　バッファに残っている送信前のデータはすべて破棄され送信されません．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
使用例
　SHRS_ClearSend(1);

--------------------------------------------------------
int SHRS_Putc(int n, int c);
--------------------------------------------------------
説明
　１バイト送信します．
　送信バッファへデータの格納が終わると制御はすぐに戻ってきます．
　（実際のデータ送信はただちに実行されますが，送信バッファが空で
　ない場合，バッファにたまっているデータの送信が優先されます）
　送信バッファからあふれたデータは無視（破棄）されます．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
　c：送信データ（下位８ビットのみ有効）[0～255]　
戻り値
　送信バッファへ格納されたデータのバイト数（単位：バイト）[0 or 1]
　（オープンされていないときのエラーチェックはありません）
使用例
　SHRS_Putc(1, 'A');

--------------------------------------------------------
int SHRS_Puts(int n, char *s);
--------------------------------------------------------
説明
　文字列を送信します．
　文字列の終端コード(\0)は改行文字(\n)へ変換して送信されます．
　送信バッファへデータの格納が終わると制御はすぐに戻ってきます．
　（実際のデータ送信はただちに実行されますが，送信バッファが空で
　ない場合，バッファにたまっているデータの送信が優先されます）
　送信バッファからあふれたデータは無視（破棄）されます．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
　s：送信される文字列が格納してある領域の先頭アドレス（ポインタ）
戻り値
　送信バッファへ格納されたデータのバイト数（単位：バイト）（最後の改行も含む）
　（オープンされていないときのエラーチェックはありません）
使用例
　char *s="ABC";
　SHRS_Puts(1, s);
　SHRS_Puts(1, "Hello");

--------------------------------------------------------
int SHRS_Sends(int n, char *s);
--------------------------------------------------------
説明
　文字列を送信します．
　文字列の終端コード(\0)の直前文字までを送信し，終端コードは送信しません．
　送信バッファへデータの格納が終わると制御はすぐに戻ってきます．
　（実際のデータ送信はただちに実行されますが，送信バッファが空で
　ない場合，バッファにたまっているデータの送信が優先されます）
　送信バッファからあふれたデータは無視（破棄）されます．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
　s：送信される文字列が格納してある領域の先頭アドレス（ポインタ）
戻り値
　送信バッファへ格納されたデータのバイト数（単位：バイト）
　（オープンされていないときのエラーチェックはありません）
使用例
　char *s="ABC";
　SHRS_Sends(1, s);
　SHRS_Sends(1, "Hello\r\n");

--------------------------------------------------------
int SHRS_Printf(int n, char *format [, argument]...);
--------------------------------------------------------
説明
　※この関数は#include "sh7125rslib.h"より前に #define SHRS_USE_PRINTF を
　　書かないと使えません．
　　（注意）この関数を使うとプログラムのサイズが大きくなります．
　書式付き文字列を送信します．
　使える書式は，一般的な printf() と同じです．制御文字や漢字もそのまま送信されます．
　文字列の終端コード(\0)は改行文字(\n)へ変換して送信されます．
　送信バッファへデータの格納が終わると制御はすぐに戻ってきます．
　（実際のデータ送信はただちに実行されますが，送信バッファが空で
　ない場合，バッファにたまっているデータの送信が優先されます）
　送信バッファからあふれたデータは無視（破棄）されます．
　＜補足＞
　一回に作成できる文字列の上限は256バイトです．このデフォルト値を変更するには
　#define SHRS_PRINTF_BUFFERSIZE 1024（←1024バイトに変更する例）を
　#include "sh7125rslib.h"より前に記述してください．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
　format：書式付き文字列へのポインタ
　argument...：引数（必要に応じて）
戻り値
　送信バッファへ格納されたデータのバイト数（単位：バイト）（最後の改行も含む）
　（オープンされていないときのエラーチェックはありません）
使用例
　SHRS_Printf(1, "a=%03d",a);

================受信に関わるもの================

--------------------------------------------------------
int SHRS_Recv(int n, char *buf, int size);
--------------------------------------------------------
説明
　データの受信を行います．
（注意）
　指定されたデータ数よりも受信バッファのデータ数が少ない場合，
　バッファ内のデータがなくなった時点で制御が戻ってきます．
　指定された数のデータが来るまで待つことはしません．
　この関数は実際に読み込んだデータの数を返します．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
　buf：受信データを格納する領域の先頭アドレス（ポインタ）
　size：受信データ数（単位：バイト）
戻り値
　受信できたデータ数（単位：バイト）
　（オープンされていないときのエラーチェックはありません）
使用例
　char buf[32];
　int n;
　n=SHRS_Recv(1,buf,32);

--------------------------------------------------------
int SHRS_CheckRecv(int n);
--------------------------------------------------------
説明
　受信バッファにたまっているデータの数(単位:バイト)を返します．
　（受信バッファのサイズ－１）より大きな値を返すことはありません．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
戻り値
　受信バッファ内のデータ数（単位：バイト）
使用例
　int n;
　char buf[32];
　n=SHRS_CheckRecv(1);
　SHRS_Recv(1,buf,n);

--------------------------------------------------------
void SHRS_ClearRecv(int n);
--------------------------------------------------------
説明
　受信バッファをクリアします．
　バッファにたまっている読み出し前のデータはすべて破棄されます．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
使用例
　SHRS_ClearRecv(1);

--------------------------------------------------------
int SHRS_Getc(int n);
--------------------------------------------------------
説明
　１バイト受信し，その値を返します．
　もしバッファにデータがない等の理由で受信できなかった場合は-1を返します．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
戻り値
　受信データ[0～255]または-1
使用例
　int c;
　c=SHRS_Getc(1);
　if (c<0) ...

--------------------------------------------------------
int SHRS_Gets(int n, char *s);
--------------------------------------------------------
説明
　文字列を受信します．
　最初に改行または終端コード(\r or \n or \0)が来るまで受信し，
　その改行または終端コードは\0に置き換えて格納されます．
　最初の改行または終端コードが来るまで制御は戻ってきません．
引数
　n：ポート番号 [0～2]　(SCI0～SCI2に対応します)
　s：受信した文字列を格納する領域の先頭アドレス（ポインタ）
　　格納領域 s のサイズを超える場合もチェックされないので注意してください．
戻り値
　受信できた文字列のバイト数（改行または終端コードを含む）
使用例
　char buf[100];
　SHRS_Gets(1,buf);

６．宣言文の使用例
　デフォルト設定を変更する（オプションの）宣言文が色々出てきたので，以下にまとめも兼ねて
使用例を書いておきます．

#include "iodefine.h"

#define SHRS_BRR0 13
#define SHRS_BRR1 6
#define SHRS_BRR2 80

#define SHRS_RECVBUFFERSIZE0 64
#define SHRS_RECVBUFFERSIZE1 512
#define SHRS_RECVBUFFERSIZE2 8

#define SHRS_SENDBUFFERSIZE0 16
#define SHRS_SENDBUFFERSIZE1 128
#define SHRS_SENDBUFFERSIZE2 256

#define SHRS_RXD0_PA10
#define SHRS_TXD0_PA11

//#define SHRS_RXD0_PE1
//#define SHRS_TXD0_PE2

#define SHRS_RXD1_PA14
#define SHRS_TXD1_PA15

//#define SHRS_RXD1_PE4
//#define SHRS_TXD1_PE5

#define SHRS_USE_PRINTF
#define SHRS_PRINTF_BUFFERSIZE 512

#include "sh7125rslib.h"

ダウンロード

　sh7125rslib.h　ファイル sh7125rslib.h がZIP圧縮してあります．

　旧バージョン（ver.2.2)　→　SH7125RSLIB ver.2.2
　旧バージョン（ver.1.1)のページ　→　SH7125RSLIB ver.1.1

１つ上へ戻る