Universidade Federal de Pernambuco

Projeto Brazil IP

Padro de Codificao SystemC, C++

Verso <1.0.1>

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

Histrico
Data
21/05/2003

Verso
1.0

Descrio
Definio da primeira verso do documento por Tiago Sampaio Lins, Diogo Jos Costa Alves e Marlia Souto Maior de Lima Primeira correo e insero de novas regras por Tiago Sampaio Lins, Diogo Jos Costa Alves e Marlia Souto Maior de Lima

Autor
Tiago Sampaio Lins

01/07/2003

1.0.1

Tiago Sampaio Lins

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

Contedo
CONTEUDO..............................................................3 1. INTRODUO.........................................................4 2. ARQUIVOS...........................................................4 2.1 NOMENCLATURA...................................................4 2.2 DOCUMENTAO...................................................4 2.3 DECLARAO.....................................................5 3. VARIVEIS, PORTAS E SINAIS DE CLASSE, DE INSTCIAS E CONSTANTES....5 3.1 NOMENCLATURA...................................................5 3.2 DOCUMENTAO...................................................5 3.3 DECLARAO.....................................................6 4. MTODOS............................................................6 4.1 NOMENCLATURA...................................................6 4.2 DOCUMENTAO...................................................6 4.3 DECLARAO.....................................................6 5. VARIAVEIS, PORTAS E SINAIS LOCAIS E PARMETROS....................7 5.1 NOMENCLATURA...................................................7 5.2 DOCUMENTAO...................................................7 5.3 DECLARAO.....................................................7 6. COMANDOS...........................................................8 6.1 6.2 6.3 6.4 6.5 RETURN.......................................................8 WHILE, DO-WHILE, FOR..........................................8 IF-THEN-ELSE......8 SWITCH..................... .9 DOCUMENTAO DE BLOCOS.................9

7. ESPASSAMENTO E INDENTAO..........................................9 7.1 7.2 7.3 7.4 TAMANHO DE LINHA...............................................9 QUEBRA DE LINHA................................................9 LINHAS EM BRANCO..............................................10 ESPAOS EM BRANCO.............................................10

8. CONSTRUTORES......................................................11 8.1 NOMENCLATURA..................................................11 8.2 DOCUMENTAO..................................................11 8.3 DECLARAO....................................................12 APNDICE A- EXEMPLO DE CDIGO USANDO ESTE PADRO.....................12

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

1. Introduo
O maior esforo no desenvolvimento de software dispensado s atividades de manuteno, desta forma, quanto mais fcil for o entendimento do cdigo do sistema, mais produtiva ser a equipe de desenvolvimento. Freqentemente as pessoas que escrevem o cdigo no so as mesmas que o mantm e, quando so, geram uma dependncia com o cdigo desenvolvido que dificilmente dissolvida. Um padro de codificao visa minimizar esses problemas, pois estabelece regras definindo como o cdigo deve ser escrito para favorecer a impessoalidade do artefato. Este documento tem como objetivo definir um padro de codificao que, quando usado, garante um melhor entendimento por qualquer pessoa que conhea e siga o mesmo. Ao final deste documento, apresentado no Apndice A um exemplo de cdigo utilizando as regras definidas no padro.

2. Arquivos
2.1 Nomenclatura Os arquivos devem ter o mesmo nome do mdulo que ele implementa. 2.2 Documentao Em todo incio de arquivo deve existir o cabealho abaixo: /***************************************************************************** Universidade Federal de Pernambuco - UFPE Centro de Informtica - CIn Adviser: Edna Natividade da Silva Barros Project: Brazil IP Date: data de incio do mdulo *****************************************************************************/ /***************************************************************************** nome_do_arquivo.h ou cpp -- Uma descrio do mdulo Original Authors: authors affiliation e-mail

*****************************************************************************/ /***************************************************************************** MODIFICATION LOG - modifiers, enter your name, affiliation, date and changes you are making here. Name, Affiliation, Date: Description of Modification: *****************************************************************************/

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

2.3 Declarao Aps os comentrios do mdulo, deve ser declarado as clausulas de define e include como no exemplo abaixo: #ifndef nome_do_modulo #define nome_do_modulo #include <modulo_desejado.h> Deve ser declarado somente um mdulo por arquivo.

3. Variveis, portas e sinais de classe, de instancias e constantes

3.1 Nomenclatura Os nomes das variveis de classe e instncia atendem aos requisitos abaixo: A primeira letra das palavras, exceto da primeira palavra, maiscula Os nomes no so abreviados, exceto nos casos que a sua abreviao seja mais sugestiva que o nome completo No se mistura palavras de mais de uma lngua No se utiliza nenhum caracter especial nem especfico de uma lngua Os nomes das constantes (define) so compostos de palavras no abreviadas com todas as letras maisculas utilizando underscores como separadores Todo nome de varivel deve iniciar com uma letra

Veja abaixo nomes de constantes e variveis de classes e instncia: CYCLE_NUMBER //constante bitAddress //varivel de classe aluModule //varivel de instncia A nomenclatura das portas atendem aos requisitos das variveis, sendo que todo nome de porta deve comear com a letra P (maisculo). Veja exemplo abaixo: PmuxIncrement //note que o primeiro m est em minsculo PdataIn PwrPc O nome dos sinais deve atender aos requisitos das variveis, sendo que todo ele deve comear com a letra S (maisculo). Veja exemplo: SaluMod8Bits SmuxRom SregisterA Nomes de portas e sinais que funcionam como clock, devem iniciar com ClknomeDaPortaOuSinal. Nomes de sinais de sada no conectados devem terminar com Nc. Nomes de sinais three-state devem terminar com Z.

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

 Os nomes dos sinais que representam prximo estado em mquina de estado devem terninar com Next ou Ns. Sinais de teste devem ter seus nome terminados com Test. A nomenclatura das instncias de mdulo devem ter o mesmo nome do mdulo mais um nmero que dever comear por 1(um) sendo incrementado a cada nova instncia do mesmo mdulo declara. Veja exemplo: AluInt AluInt1(AluInt1); AluInt AluInt2(AluInt2); AluInt AluInt3(AluInt3); 3.2 Documentao A documentao de uma varivel, porta, sinal ou constante feita em linha exceto nos casos em que no caiba em uma linha de cdigo. Faz parte da documentao a descrio do invariante que se aplique varivel como, por exemplo, o intervalo de 1 a 31 para uma varivel inteira que represente o dia do ms.

3.3 Declarao Apenas uma declarao de varivel, porta, sinal ou constante deve ser feita por linha.

4. Mtodos
4.1 Nomenclatura Os nomes dos mtodos atendem aos requisitos abaixo: A primeira letra das palavras, exceto da primeira palavra, maiscula Os nomes no so abreviados

No se utiliza nenhum caracter especial Apesar da aplicao deste padro resultar em nomes maiores, necessitando digitao extra, o efeito da sua conformidade um cdigo mais fcil de compreender, pois o propsito do mtodo j esclarecido no seu nome. Veja abaixo alguns exemplos de nomes de mtodos: resetSystem(void) swap(sc_bv<8> data) setRegister(sc_uint<8> psw) 4.2 Documentao Todo mtodo contm um cabealho de documentao que fornece informaes suficientes para seu entendimento e uso adequado. Inicialmente, documenta-se o que o mtodo faz e porque faz, aps isto, relaciona-se todos os parmetros necessrios para sua chamada, a clusula de retorno, caso exista, e a data de criao. Veja um exemplo de documentao de mtodo:

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

/** * This function checks the active bank and return the corresponding register * * @param psw The actual program status work * * @return The register address * * @since 25/05/2003 */ Pode ser usado o comentrio em linha para determinados trechos do cdigo dando algum esclarecimento, alerta de bugs ou correes. 4.3 Declarao A declarao do prottipo do mtodo deve ser feita aps a declarao das variveis, portas e sinais. Declare as variveis locais o mais prximo possvel da primeira instruo em que so utilizadas. Um objeto inicializado (construdo) no momento em que declarado. Se voc no tem informaes suficientes para inicializar o objeto at o meio do mtodo, ento o declare no meio do memso, quando o objeto poder ser inicializado corretamente. No declare o objeto vazio no topo do mtodo para atribuir-lhe um valor posteriormente, isso prejudica a performance do seu cdigo. Construir um objeto corretamente mais rpido do que constru-lo incorretamente e remodel-lo mais tarde.

5. Variveis, portas e sinais locais e parmetros

5.1 Nomenclatura A nomenclatura de variveis, portas e sinais locais a mesma usada para variveis, portas e sinais de instncia e classes (veja Seo 3.1), entretanto, por fora de convenincia, essa nomenclatura relaxada para os casos abaixo: Contadores Usam-se letras do alfabeto para nomear contadores. A letra i a primeira a ser usada; sendo necessrio o uso de outros contadores, declara-se a letra j e assim sucessivamente at a ltima letra do alfabeto. 5.2 Documentao A documentao de variveis, portas e sinais locais feita da mesma forma que a de variveis, portas e sinais de classe e instncia. 5.3 Declarao Para facilitar a documentao e organizao dos mtodos, apenas uma declarao de varivel, porta ou sinal local feita por linha de cdigo. Toda porta e sinal devem ser lidos e escritos utilizando os mtodos padro de SystemC, nomeDaPortaOuDoSinal.read() e nomeDaPortaOuDoSinal.write(valor), respectivamente. Na declarao de variveis, portas e sinais em uma classe deve ser declarado primeiro portas de entrada, portas de sada, sinais e por fim as variveis, separados por uma linha em branco.

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

Veja exemplo: sc_in< bool > Pclock; sc_in< sc_uint<8> > PregSource; sc_in< sc_uint<2> > Pshifter; sc_in< sc_uint<2> > PmuxPc; //fim das portas de entrada sc_out< sc_uint<8> > Pp0; sc_out< sc_uint<8> > Pp1;//fim das portas de sada sc_signal< sc_uint<16> > SmuxPcOut; //sinais sc_signal< sc_uint<16> > SpcOut; sc_signal< sc_uint<8> > SromOut; sc_signal< sc_uint<8> > SirOut; //fim sinais int countReset; //variveis double countClock; Uma boa prtica de programao, que deve ser seguida pelo programador, a declarao de variveis auxiliares para as portas. O programador nunca deve trabalhar direto com os valores das portas, deve-se atribuir o valor da porta, no incio do mtodo, a uma varivel do mesmo tipo e utilizar esta, isso garante a consistncia dos dados dentro de um mesmo mtodo.

6. Comandos
6.1 return Uma sentena return com valor de retorno no utiliza parntesis, ao menos que esta fique mais clara. 6.2 while, do-while for Veja abaixo o estilo de formatao para esses comandos: while (condio) { comandos; } do { comandos; } while (condio); for (inicializao; condio; atualizao) { comandos; } 6.3 if-then-else O comando if-then-else usado com as chaves {} para evitar ambigidade no escopo do comando. Veja abaixo os estilos de formatao vlidos do comando:

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

if (condio { ) comandos ; } if (condio { ) comandos ; } else { comandos ; } if (condio1 { ) comandos ; } else if c ondio2 { ( ) comandos ; } else{ comandos ; } 6.4 switch Abaixo so apresentados os estilos de formatao vlidos do comando: switch ( arivel { v ) case 123: comandos ; break; case 456: comandos ; break; case 789: comandos ; break; default: comandos ; break; } O ltimo comando de toda sentena case o break. Toda sentena switch possui uma clusula default. 6.5 Documentao de blocos As declaraes de blocos so comentadas no estilo em linha aps o caracter de fechamento de bloco }. Abaixo, so apresentados exemplos de uso do comentrio de blocos: if (condio) { ... } // fim do if (condio) switch ( arivel { v ) ... } // fim do switchvarivel ( ) for (exp1; exp2; exp3) { ...

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

} // fim do for(exp1; exp2; exp3)

7. Espaamento e indentao
Quatro (4) espaos em branco so usados com unidades de indentao. 7.1 Tamanho de linha As linhas tm menos de 80 caracteres para facilitar impresso e visualizao do cdigo. 7.2 Quebra de linha Quando uma expresso no cabe em uma linha, as seguintes regras so utilizadas: A linha quebrada depois de uma vrgula. A linha quebrada antes de um operador. Prefira quebrar uma linha em uma expresso de um nvel mais alto. A nova linha alinhada com o comeo da expresso do mesmo nvel da linha anterior.

Veja alguns exemplos de chamadas de mtodos onde necessrio utilizar mais de uma linha: setRegisters(register1, register2, register3, register4, register5, register6, register7, register8); Veja alguns exemplos de expresses aritmticas onde necessrio utilizar mais de uma linha: longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; // PREFIRA ! longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; // EVITE ! A quebra de linha da condio do comando if e de mtodos utiliza uma indentao de 8 espaos, conforme ilustrado nos exemplos abaixo: //No use esta indentao if ((condition1 && condition2) || (condition3 && condition4) || !(condition5 && condition6)) { comandos; } //USE ESTA if ((condition1 && condition2) || (condition3 && condition4) || !(condition5 && condition6)) { comandos; } //OU ESTA if ((condition1 && condition2) || (condition3 && condition4)

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

10

|| !(condition5 && condition6)) { comandos;

7.3 Linhas em branco Tem-se duas (2) linhas em branco na seguinte situao: Entre a declarao da classe e o bloco das variveis, portas e sinais de instncia. Usa-se uma (1) linha em branco nas seguintes situaes: Entre declaraes de mtodos. Entre as declaraes de variveis, portas e sinais locais e o incio do mtodo. Antes de um comentrio. Antes da declarao de uma varivel, porta ou sinal local. Entre blocos lgicos dentro do corpo de um mtodo. Entre a ltima declarao de mtodo da classe e o final da classe ( } ). 7.4 Espaos em branco Uma palavra reservada seguida por parntesis separada destes por um espao em branco: while (true) { comandos; } Um espao em branco aparece depois de cada vrgula em uma lista de parmetros ou na inicializao dos elementos de um array. int i, j, l; Todos os operadores binrios so separados dos operandos por um espao em branco, conforme os exemplo abaixo: a += c + d; a = (a + b) / (d * c); As expresses de um comando for so separadas por espaos em branco. Exemplo: for (exp1; exp2; exp3){ comandos ; } Um cast seguido por um espao em branco: dataIn = (sc_uint<8>) Sdata;

8. Construtor
8.1 Nomenclatura Deve ser usado sempre o construtor padro de SystemC, SC_CTOR(nomeDoModulo).

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

11

8.2 Documentao O programador deve informar quais processos ele ir chamar a partir do construtor, bem como a lista de sensibilidade dos mesmos, veja abaixo a declarao dos construtores dos mtodos process e readCard: /** * Constructor for the AluInt module * * SC_METHOD process sensitive << PdataA << PdataB << Pselection * * SC_THREAD readCard << clk.pos() * */ SC_CTOR( AluInt) { SC_METHOD( process ); sensitive << PdataA; sensitive << PdataB; sensitive << Pselection; SC_CTHREAD(readCard, clk.pos()); } Note que no SC_METHOD(process) colocamos uma porta por linha na lista de sensibilidade do processo process. No caso de SC_CTHREAD devemos declarar a sensibilidade do mtodo dentro do parntesis, e no usando o operador <<. 8.3 Declarao

Apndice A- Exemplo de cdigo usando este padro

Este exemplo tem como objetivo ilustrar algumas prticas recomendadas neste padro de codificao. AluInt.h
/***************************************************************************** Universidade Federal de Pernambuco - UFPE Centro de Informtica - CIn Adviser: Edna Natividade da Silva Barros Project: Brazil IP Date: 20/03/2003 *****************************************************************************/ /***************************************************************************** AluInt.h -- This is the interface file for the AluInt module which is responsible to process all the logical end arithmetical operations.

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

12

Original Authors: Diogo Jos Costa Alves Cin UFPE djca@cin.ufpe.br Silvio Veloso Cin UFPE svfn@cin.ufpe.br Tiago Sampaio Lins Cin UFPE tsl@cin.ufpe.br *****************************************************************************/ /***************************************************************************** MODIFICATION LOG - modifiers, enter your name, affiliation, date and changes you are making here. Name, Affiliation, Date: Marlia Souto Maior de Lima, Cin UFPE, 29/05/2003 Description of Modification: insert function increment *****************************************************************************/ #ifndef ALUINTINC #define ALUINTINC #include <systemc.h> SC_MODULE( AluInt ) { sc_in< sc_uint<8> > PdataA; //data A in ALU sc_in< sc_uint<8> > PdataB; //data B in ALU sc_in< sc_uint<5> > Pselection; //response to select operation sc_in< sc_uint<8> > PpswIn; //Program Status Work, coming from memory sc_out< sc_uint<8> > PpswOut; //Program Status Work, out for memory sc_out< sc_uint<8> > Pout8Bits; //data out with 8 bits sc_out< bool > Pzero; //true if the operation result is zero else false sc_int<8> dataA; //auxiliar variable for PdataA sc_int<8> dataB; //auxiliar variable for PdataB sc_uint<8> psw; //auxiliar variable for PpswIn void process( void ); //see comments in AluInt.cpp sc_int<8> load( void ); //see comments in AluInt.cpp sc_int<8> sum( void ); //see comments in AluInt.cpp sc_int<8> sub( void ); //see comments in AluInt.cpp sc_int<8> increment( void ); //see comments in AluInt.cpp /** * Constructor for the AluInt module * * SC_METHOD process sensitive << PdataA << PdataB << Pselection * */ SC_CTOR( AluInt ) { SC_METHOD( process ); sensitive << PdataA; sensitive << PdataB;

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

13

sensitive << Pselection; } };//end of SC_MODULE( AluInt ) #endif AluInt.cpp /***************************************************************************** Universidade Federal de Pernambuco - UFPE Centro de Informtica - CIn Adviser: Edna Natividade da Silva Barros Project: Brazil IP Date: 20/03/2003 *****************************************************************************/ /***************************************************************************** AluInt.cpp -- This module implements the interface AluInt.h. Original Authors: Diogo Jos Costa Alves Cin UFPE djca@cin.ufpe.br Silvio Veloso Cin UFPE svfn@cin.ufpe.br Tiago Sampaio Lins Cin UFPE tsl@cin.ufpe.br *****************************************************************************/ /***************************************************************************** MODIFICATION LOG - modifiers, enter your name, affiliation, date and changes you are making here. Name, Affiliation, Date: Marlia Souto Maior de Lima, Cin UFPE, 29/05/2003 Description of Modification: insert function increment *****************************************************************************/ #include "AluInt.h" /** * This method checks the port Pselection and calls the operation related * * @since 20/03/2003 */ void AluInt::process( void ) { int selection = (sc_uint<5>) Pselection.read(); dataA = (sc_int<8>) PdataA.read(); dataB = (sc_int<8>) PdataB.read(); psw = PpswIn.read(); sc_int< 8 > tmp_8bits; switch( selection ) {

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

14

case 0: tmp_8bits = load(); break; case 1: tmp_8bits = sum(); break; case 2: tmp_8bits = sub(); break; case 3: tmp_8bits = increment(); break;

bool tmp_zero; if(tmp_8bits == 0) { tmp_zero = 1; } else{ tmp_zero = 0; } out_8bits.write( (sc_uint<8>) tmp_8bits ); out_16bits.write( (sc_uint<16>) tmp_16bits ); pswOut.write( psw ); zero.write( tmp_zero );

/** * This method writes in Pout8Bits the value of PdataA. * * @return The value of dataA * * @since 20/03/2003 */ sc_int<8> AluInt::load(void) { return dataA; } /** * This method sums the value of PdataA and PdataB and store the result * in Pout8bits. The overflow bit is set if there is a carry-out of bit * 6 or out of bit 7, but not both. The carry bit is set if there is a * carry-out of bit 7. The auxiliar carry flag is set if there is a carry-out * of bit 3. * _ _ ___ _ __ * psw |C|AC| | | |OV| | | * 7 6 543 2 10 * * @return dataA + dataB

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

15

* * @since 20/03/2003 */ sc_int<8> AluInt::sum( void ) { sc_int <9> temp; temp = dataA + dataB; psw[7] = temp[8]; //carry flag sc_int <5> tmp1; sc_int <5> tmp2; sc_int <5> tmp3; tmp1.range(3,0) = dataA.range(3,0); tmp2.range(3,0) = dataB.range(3,0); tmp3 = tmp1 + tmp2; psw[6] = tmp3[4]; //auxilliar carry flag tmp1= 0; tmp2= 0; tmp1[0] = dataA[6]; tmp1[2] = dataA[7]; tmp2[0] = dataB[6]; tmp2[2] = dataB[7]; sc_int <2> tmpOv1, tmpOv2; tmpOv1 = tmp1[0] + tmp2[0]; tmpOv2 = tmp1[2] + tmp2[2]; if(tmpOv1[1] ^ tmpOv2[1]){ psw[2] = 1; } else{ psw[2] = 0; } } return temp.range(7,0) ;

/** * This method subtracts the value of PdataA by PdataB and store the result in * Pout8Bits. * * @return dataA - dataB * * @since 20/03/2003 */ sc_int<8> AluInt::sub( void ) { sc_int <8> temp;

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

16

temp = dataA - dataB; return temp; } /** * This method increments the value of PdataA by one and store the result in Pout8Bits. * * @return dataA + 1 * * @since 29/05/2003 */ sc_int<8> AluInt::increment(void) { sc_int <9> temp; temp = dataA + 1; if(temp[8] == 1) { temp = 0; } } return temp.range(7,0) ;

Padro de Codificao SystemC, C++ ltima atualizao 12/4/2012 16:16 h

17