Diff: vz_protocol.h

Revision:

69:65665afbad5d

Parent:

68:b54993674190

Child:

72:895ca792c647

diff -r b54993674190 -r 65665afbad5d vz_protocol.h
--- a/vz_protocol.h	Fri Nov 07 17:57:55 2014 +0000
+++ b/vz_protocol.h	Wed Nov 12 13:25:54 2014 +0000
@@ -1,3 +1,11 @@
+/**
+ * @file vz_protocol.h
+ * @Synopsis Implementa as principais funcionalidades do protocolo de comunicação entre os CBx -> Header e Header -> CBx.
+ * @author Jhonatan Casale
+ * @version 1
+ * @date 2014-11-05
+ */
+
 #ifndef _VZ_PROTOCOL_H__
 #define _VZ_PROTOCOL_H__
 
@@ -9,86 +17,243 @@
 //#include "prompt.h"
 // 7 + 14 + 1 == ts
 
-#define __START_PKG_COUNT__ 100
+#define __START_PKG_COUNT__ 100 
+///< Estabelece o inicio dos pacotes RTP, não utilizado atualmente
 
-#define UDP_PORT_LISTENER 11406
-#define TCP_PORT_LISTENER 7879
+#define UDP_PORT_LISTENER 11406 
+///< Porta UDP na qual a Header espera por eventuais mensagens.
+#define TCP_PORT_LISTENER 7879 
+///< Porta TCP na qual a Header espera por eventuais mensagens.
+#define UDP_BOOTLOADER_PORT 9891 
+///< Porta UDP para tratativas do procedimento de gravação dos CBx.
 
-#define UDP_BOOTLOADER_PORT 9891
+#define __UDP_PORT__ 7890 
+///< Antiga porta UDP que a Header ouvia, descontinuado.
+#define __TCP_PORT__ 8709 
+///< Antiga porta TCP que a Header ouvia, descontinuado.
 
-#define __VZ_HEADER_OFFSET__ 7
-#define __CB_BUFFER_SIZE__ 300
-#define __PROMPT_ETH_BUFFER_SIZE__ 1024
-#define __TELEMETRY_SIZE__ __CB_BUFFER_SIZE__ - ( __VZ_HEADER_OFFSET__ + __CLOCK_SYNC_SIZE__ + __SEQ_NUM_SIZE__ )
-#define __ETH_BUFFER_SIZE__ __CB_BUFFER_SIZE__ + __RTP_HEADER_SIZE__ + 1 // 313  
-#define __CB_AUDIO_DATA_SIZE__ 240
-#define __CHECKSUM_OFFSET__ 7
-#define __SEQ_NUM_SIZE__ 1
-#define __CLOCK_SYNC_SIZE__ 14
-#define __TIMESLICE_PLACE__ 22
-#define __UDP_PORT__ 7890 /* numeros arbitrarios ... */
-#define __TCP_PORT__ 8709
-    
-//#define __TELEMETRY_SERVER_IP__ "192.168.120.163"
-#define __TELEMETRY_SERVER_IP__ "192.168.120.144"
-//#define __TELEMETRY_SERVER_IP__ "192.168.120.200"
-#define __TELEMETRY_SERVER_PORT__ 9192
-#define __TELEMETRY_HEADER_PORT__ 9321
+#define __TELEMETRY_SERVER_IP__ "192.168.120.163" 
+///< Estabelece o IP default para onde os dados de telemetria são enviados.
+#define __TELEMETRY_SERVER_PORT__ 9192 
+///< Estabelece a porta default do servidor  para onde os dados de telemetria são enviados
+#define __TELEMETRY_HEADER_PORT__ 9321 
+///< Estabelece a porta default da Header, de onde os pacotes de telemetria são enviados.
+
+#define __VZ_HEADER_OFFSET__ 7 
+///< Indica o inicio dos dados recebidos efetivamente no pacote VZ.
+#define __CB_BUFFER_SIZE__ 300 
+///< Indica o numero máximo de bytes recebidos ( por pacote ) do CBx.
+#define __PROMPT_ETH_BUFFER_SIZE__ 1024 
+///< Representa o tamanho máximo do pacote recebido pelo prompt da Header.
+#define __CLOCK_SYNC_SIZE__ 14 
+///< Indica o numero de bytes ocupados pelo relogio no pacote transmitido.
+#define __SEQ_NUM_SIZE__ 1 
+///< Indica o numero de bytes ocupados para uso de sequence number.
+#define __TELEMETRY_SIZE__ __CB_BUFFER_SIZE__ - ( __VZ_HEADER_OFFSET__ + __CLOCK_SYNC_SIZE__ + __SEQ_NUM_SIZE__ ) 
+///< Indica o nro de bytes efetivos no envio de um pacote de telemetria
+#define __ETH_BUFFER_SIZE__ __CB_BUFFER_SIZE__ + __RTP_HEADER_SIZE__ + 1 // 313
+///< Indica o tamanho real do pacote que será enviado do CBx para o servidor via eth
+#define __CB_AUDIO_DATA_SIZE__ 240 
+///< Indica o numero de pacotes enviados pelo CBx referente a dados de audio.
+#define __CHECKSUM_OFFSET__ 7 
+///< Indica o deslocamento em relação ao começo do pacote enviado pelo CBx onde se encontra o cc.
+#define __TIMESLICE_PLACE__ 22 
+///< Indica o local ( em relação ao começo do pacote ) onde se encontra o timeslice.
 
 #define __MAX_CB_IN_A_BRANCH__ 40
-#define __READ__ 0x01
-#define __WAITING__ 0x00
+///< Estabelece o nro máximo de CBx em um mesmo ramo, não utilizado atualmente.
+
+#define __READ__ 0x01 
+///< Define o estado ( na main ) de que existe um dados disponivel para leitura.
+#define __WAITING__ 0x00 
+///< Define o estado ( na main ) de que esta apenas esperando por um novo pacote vindo dos CBx.
 
-// types
-#define __BOOT__ 0x00
-#define __REGISTRY__ 0x02
+#define __BOOT__ 0x00 
+///< Indica o tipo boot, enviado pelo CBx, assim que o mesmo liga ou sofre reboot.
+#define __REGISTRY__ 0x02 
+///< Tipo de registro, enviado pelo CBx, quando o mesmo quer se registrar, enviado pela Header para verificar se determinado CBx ainda esta ativo.
 #define __INVITE__ 0x04
+///< Representa o tipo de pedido de invite, enviado pelo CBx sempre quando o mesmo quer iniciar uma ligação com o server.
 #define __AUDIO__ 0x08
+///< Pacotes do tipo audio são trocados entre Header e CBx durante a ligação, representam os dados RTP.
 #define __TELEMETRY__ 0x10
+///< Define o tipo de pacote de telemetria enviado pelo CBx.
 #define __BOOTLOADER_CBX__ 0x12
+///< Define o tipo de pacote para a gravação do CBx
 #define __CB_BYE__ 0x20
+///< Representa o tipo de pacote que o CBx envia para a Header solicitando o final da ligação.
 #define __PROMPT__ 0x01
+///< Identifica o tipo de pacote responsavel por mandar comandos executáveis no Cbx.
 #define __FLOOD__ 0x40
+///< Representa os pacotes de flood, úteis para validação de comunicação Header-CBx.
 #define __SOMETHING_3__ 0x80
+///< Tipo ainda disponivel ( assim como todos os outros não listados ).
 #define __DO_NOTHING__ 0x99
+///< Representa o tipo de idle, importante para algumas comunicações.
 
 //#define __MY_IP__ "192.168.2.200"
 //#define __MY_IP__ "192.168.2.201"
 #define __MY_IP__ "192.168.120.171"
+///< Representa o IP default da Header.
 #define __MY_EXT__ 820
+///< Indica o ramal default da Header.
 #define __MY_PORT__ 5062
+///< Representa a porta default da Header.
 
 #define __SERVER_IP__ "192.168.120.120"
+///< Indica o IP defaut do servidor para onde a Header ira encaminhar pedidos de ligação.
 //#define __SERVER_IP__ "192.168.30.25"
 
+//FIXME pode dar inconssistencia.
+//#define __RTP_SEVER_IP__ "192.168.120.120"
+#define __RTP_SEVER_IP__ __SERVER_IP__
+///< Referencia ao envio de dados RTP
+
 #define __PEER_EXT__ 913
+///< Estabelece o ramal default para onde a Header ira direcionar os pedidos de ligações.
 //#define __PEER_EXT__ 812
 #define __SERVER_PORT__ 5075
+///< Indica a porta default do server para onde os pacotes eth serão enviados na negociação SIP.
 //#define __SERVER_PORT__ 5060
 
 #define __MY_MSK__ "255.255.255.0"
+///< Indica a mascara de rede onde a Header se encontra.
 //#define __MY_GTW__ "192.168.2.254" // colinas
 #define __MY_GTW__ "192.168.120.1"  // colinas
+///< Indica o IP do Gateway de rede
 
-extern uint16_t pkg_ckserr;
-extern uint16_t pkg_cksok;
+extern uint16_t pkg_ckserr; 
+///< Contador de pacotes em que o checksum resultou divergente do calculado/recebido
+extern uint16_t pkg_cksok; 
+///< Contador de pacotes em que o checksum resultou o mesmo calculado e o recebido
 
+/**
+ * @Synopsis Calcula o checksum do pacote.
+ *
+ * @param buffer Um ponteiro para a região de memória onde os dados de interesse estão localizados.
+ * @param length O numero de elementos que serão considerados no cálculo do checksum
+ *
+ * @return 0 - caso em que o vetor apontado por buffer estiver setado em NULL. O checksum propriamente
+ * calculado caso contrário.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  // onde cb_buffer contém os dados vindos do Call_Box, Obs. as posições 4 e 5 contém o MSB e LSB do CC calculado pelo Call_Box.
+ *  uint16_t cc = ( uint16_t )cb_buffer[ 4 ] << 8 | cb_buffer[ 5 ];
+ *  if( cc != __checksum__( cb_buffer, __CB_BUFFER_SIZE__ ) ){
+ *      //faça alguma coisa ...
+ *  }
+ * ...
+ * @endcode
+ */
 uint16_t __checksum__( uint8_t * buffer, size_t length );
 
 /* incorporar a parte de cc */
+/**
+ * @Synopsis Esta é a função responsável por, dado um pacote recebido dos CBx, quebra-lo em ramal( ext ), porta, type e dados.
+ *
+ * @param ext Um ponteiro para onde sera setado o ramal do CBx que enviou este pacote.
+ * @param port Um ponteiro para onde sera setado a porta do CBx que enviou este pacote.
+ * @param type Um ponteiro para onde sera setado o type de mensagem enviada pelo CBx.
+ * @param cb_buffer O pacote que se deseja decodificar.
+ *
+ * @return NULL, caso em que o checksum( cc ) calculado não bater com o cc recebido no pacote, retorna NULL também em pacotes do
+ * tipo flood, ou no caso em que o pacote recebido para processamento apontar para NULL; em todos esses casos os valores de ext,
+ * port e type devem ser desconsiderados para manter a integridade do processamento; retorna um ponteiro para o inicio dos dados
+ * enviados pelo CBx e seta ramal, porta e type nos casos em que o pacote recebido for válidado pelo protocolo.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  int ext, port, type;
+ *  uint8_t * data, buffer[ __CB_BUFFER_SIZE__ ];
+ *      //assumindo que os dados vindos do Call_Box estão armazenados em buffer;
+ *  data = __parse_vz_pkg__( &ext, &port, &type, buffer );
+ * ...
+ * @endcode
+ */
+
+/**
+ * \note Formato do pacote VZ :
+ *
+ * | E | E | P | P | C | C | T | [ Seq_num | Audio ] | 14[ Clock | Audio ] | [ TS | Audio ] |...|
+ *
+ * E = Ext = Ramal 
+ *
+ * P = Port = Porta
+ *
+ * C = Checksum 
+ *
+ * T = Type = Tipo 
+ *
+ * Seq_num = Sequence Number = Numero de sequencia 
+ *
+ * Clock = 14 bytes to sync 
+ *
+ * ...= demais __CB_BUFFER_SIZE__ - __VZ_HEADER_OFFSET__  bytes 
+ *
+ */
 uint8_t * __parse_vz_pkg__( int * ext, int * port, volatile uint8_t * type, uint8_t * cb_buffer );
+
+/**
+ * @Synopsis Função responsavel por montar o pacote para envio para o CBx seguindo o formato do protocolo VZ. 
+ *
+ * @param ext O ramal do CBx destino deste pacote.
+ * @param port A porta do CBx destino deste pacote.
+ * @param type O tipo do pacote que será enviado para o CBx.
+ * @param cb_buffer Os dados que serão colocados nesse pacote.
+ * @param seq_num O numero do sequência deste pacote.
+ * @param length O tamanho ( em bytes ) dos dados que serão enviados.
+ * @param pkg Um ponteiro que recebera o pacote montado e pronto para envio.
+ *
+ * @return O pacote montado e pronto para envio.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  int ext = 1011;
+ *  port = 1011;
+ *  type = __REGISTRY__;
+ *  __send_to_cb__( __build_cb_package__( ext, port, type, 
+ *              ( char * )data, cb->get_msg_id(), __CB_BUFFER_SIZE__ - __VZ_HEADER_OFFSET__, write_buffer ) ); 
+ * ...
+ * @endcode
+ */
 uint8_t * __build_cb_package__( int ext, int port, uint8_t type, char * cb_buffer, uint8_t seq_num, int length,  uint8_t * pkg );
+
+/**
+ * @Synopsis Função que seria responsavel pelo envio de pacotes eth, porém descontinuada, será removida no futuro.
+ *
+ * @return O pacote pronto para envio via protocolo eth.
+ *
+ * \note Não implementada.
+ */
 char * __build_eth__package__( void );
+
+/**
+ * @Synopsis Obtém uma referência de clock de um servidor.
+ *
+ * @param buffer Imprime a referência do relógio nesta posição de memória.
+ *
+ * \note Por definição de projeto, o relógio ocupa 14 bytes, seguindo o formato
+ *
+ * | ano | ano | ano | ano | mes | mes | dia | dia | hora | hora | minuto | minuto | segundo | segundo |
+ *
+ * Exemplo:
+ *
+ * 20141105101235
+ */
 void __print_clock__( uint8_t * buffer );
 
-extern void uart3_puts(uint8_t *src, uint16_t size);
+extern void uart3_puts( uint8_t *src, uint16_t size );
 
 /* mais pra frente isso vira os cpld_send and cpld_receive */
 uint8_t * __read_cb_buffer__( uint8_t * dest, uint8_t * src );
 uint8_t * __read_eth_buffer__( uint8_t * dest, uint8_t * src );
 uint8_t * __write_cb_buffer__( uint8_t * dest, uint8_t * src );
-void __send_to_cb__( uint8_t * buffer );
 uint8_t * __write_eth_buffer__( uint8_t * dest, uint8_t * src );
 
-
+//FIXME esta function deveria estar como extern
+extern void __send_to_cb__( uint8_t * buffer );
 #endif
\ No newline at end of file