Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Projeto Brazil IP
Verso <1.0.1>
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
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
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: *****************************************************************************/
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.
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.
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:
/** * 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.
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:
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) { ...
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)
10
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).
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
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;
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 ) {
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
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;
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) ;
17