<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kcachegrind '<application
>KCachegrind</application
>'>
  <!ENTITY cachegrind "<application
>Cachegrind</application
>">
  <!ENTITY calltree "<application
>Calltree</application
>">
  <!ENTITY callgrind "<application
>Callgrind</application
>">
  <!ENTITY valgrind "<application
>Valgrind</application
>">
  <!ENTITY oprofile "<application
>OProfile</application
>">
  <!ENTITY kappname "&kcachegrind;">
  <!ENTITY package "kdesdk">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % Brazilian-Portuguese "INCLUDE">
]>

<!-- ................................................................ -->

<book lang="&language;">

<bookinfo>
<title
>O Manual do &kcachegrind;</title>

<authorgroup>
<author
><firstname
>Josef</firstname
> <surname
>Weidendorfer</surname
> <affiliation
> <address
><email
>Josef.Weidendorfer@gmx.de</email
></address>
</affiliation>
</author>

<othercredit role="translator"
><firstname
>Marcus</firstname
><surname
>Gama</surname
><affiliation
><address
><email
>marcus.gama@gmail.com</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 

</authorgroup>

<copyright>
<year
>2002-2004</year>
<holder
>&Josef.Weidendorfer;</holder
>	
</copyright>
<legalnotice
>&FDLNotice;</legalnotice>

<date
>2004-07-27</date>
<releaseinfo
>0.4.6</releaseinfo>

<abstract>
<para
>O &kcachegrind; é uma ferramenta de visualização de dados de auditoria, escrito usando o ambiente &kde;. </para>
</abstract>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>kdesdk</keyword>
<keyword
>Cachegrind</keyword>
<keyword
>Callgrind</keyword>
<keyword
>Valgrind</keyword>
<keyword
>Auditoria</keyword>
</keywordset>

</bookinfo>


<chapter id="introduction">
<title
>Introdução</title>

<para
>O &kappname; é um navegador para dados produzidos por ferramentas de auditoria. Este capítulo esclarece para que serve um auditoria, como ela é feita, e fornece alguns exemplos de ferramentas de auditoria disponíveis. </para>

<sect1 id="introduction-profiling">
<title
>Auditoria</title>

<para
>Quando você desenvolve um programa, um dos últimos passos muitas vezes envolve otimizações de desempenho. Como não faz sentido otimizar funções raramente usada, uma vez que elas não consumirão muito tempo de execução, você precisa saber em qual parte do seu programa a maior parte do tempo é consumido. </para>

<para
>Para o código sequencial, a coleta de dados estatísticos das características de execução dos programas, como os valores dos tempos dispendidos nas funções e linhas de código é normalmente o suficiente. Isto é chamado normalmente de Análise ou 'Profiling'. O programa é executado sob o controle de uma ferramenta de análise que fornece o resumo de uma execução no final. Em contraste, para o código paralelo, os problemas de performance são normalmente causados quando um processador fica à espera dos dados do outro. Uma vez que este tempo de espera normalmente é atribuído de forma simples, aqui será melhor gerar traços dos eventos com tempos marcados. O &kcachegrind; não consegue visualizar este tipo de dado. </para>

<para
>Após analisar os dados da auditoria produzida, deve ser fácil ver os trechos mais importantes e pontos de estrangulamento do código. Por exemplo, suposições sobre a contagem de chamadas podem ser verificadas, e identificadas regiões do código que pode ser otimizadas. Além disso,  sucesso da otimização pode ser verificado novamente com a execução de outra auditoria. </para>
</sect1>

<sect1 id="introduction-methods">
<title
>Métodos de Auditoria</title>

<para
>Uma medida exata do tempo que passou ou dos eventos que ocorrem durante a execução de uma determinada região de código (&eg; uma função) necessita da inserção de algum código de medida adicional, antes e depois da região indicada. Este código lê o tempo ou uma contagem de eventos global, calculando as diferenças. Assim, o código original terá que ser alterado antes da execução. Isto é chamado de instrumentação. Ela poderá ser criada pelo próprio programador, pelo compilador ou pelo sistema de execução. Uma vez que as regiões interessantes estão normalmente encadeadas, a sobrecarga da instrumentação influencia sempre a medida em si. Assim, a instrumentação deverá ser feita de forma seletiva e os resultados terão que ser interpretados com cuidado. Obviamente, isto torna a análise de performance por medida exata um processo bastante complexo.</para>

<para
>A medição exata é possível em função os contadores de hardware (incluindo contadores incrementados em um tique de tempo) fornecidos nos processadores modernos, que são incrementados sempre que um evento acontece. Como nós desejamos atribuir eventos para regiões de código, sem os contadores, nós teríamos que manipular cada evento incrementando um contador para a região de código atual por nós mesmos. Fazer isto no software é claramente impossível; mas na suposição que a distribuição do evento pelo código fonte é semelhante quando procuramos somente a cada enésimo evento ao invés de evento por evento, nós construímos um método de medição que é ajustável em função do todo. Isto é chamado Amostragem. Amostragem Baseada em Tempo (do inglês TBS) é feita usando um temporizador que regularmente verifica o contador do programa para criar um histograma ao longo do código do programa. Amostragem Baseada em Evento (do inglês EBS) é feita aproveitando os contadores de hardware dos modernos processadores, e é feita usando um modo onde um manipulador de interrupção é chamado em um contador abaixo do fluxo, gerando um histograma da distribuição do evento correspondente. No manipulador, o contador do evento está sempre reinicializado para o 'n' do método de amostragem. A vantagem da amostragem é que o código não precisa ser mudado, mas ela ainda deve atentar para uma restrição: a suposição acima será mais correta se n for pequeno, mas quanto menor o n, maior o todo do manipulador de interrupção.</para>

<para
>Outro método de medida é a simulação das coisas que ocorrem no sistema do computador enquanto executa um determinado código, &ie; uma simulação orientada pela execução. Obviamente, a simulação deriva sempre de um modelo de 'hardware' mais ou menos preciso. Para os modelos muito detalhados que se aproximam da realidade, o tempo de simulação poderá ser alto, de forma inaceitável para ser posto em prática. A vantagem é que o código de simulação/medida arbitrariamente complexo poderá ser introduzido num determinado código sem perturbar os resultados. Fazer isto diretamente antes da execução (chamado de instrumentação durante a execução), usando o binário original, é bastante confortável para o usuário. O método torna-se inútil quando se simula apenas partes de uma máquina com um modelo simples. Além disso, os resultados produzidos pelos modelos simples são normalmente muito mais fáceis de compreender: o problema frequente com o 'hardware' real é que os resultados incluem efeitos sobrepostos de diferentes partes do sistema.</para>
</sect1>

<sect1 id="introduction-tools">
<title
>Ferramentas de Auditoria</title>

<para
>A ferramenta de análise mais conhecida é o <application
>gprof</application
> do GCC: Você precisa compilar o seu programa com a opção <option
>-pg</option
>; rodar o programa, irá gerar um arquivo <filename
>gmon.out</filename
>, que poderá ser transformado num formato legível com o <command
>gprof</command
>. A desvantagem é o passo de compilação necessário para preparar o executável, que terá que ser compilado estaticamente. O método aqui usado é a instrumentação gerada pelo compilador, que consiste na medida dos arcos de chamadas entre funções, bem como contadores para as respectivas chamadas, juntamente com o TBS, que lhe fornece um histograma com a distribuição do tempo pelo código. Usando ambos os dados, é possível calcular de forma heurística o tempo inclusivo das funções, &ie; o tempo dispendido numa função, juntamente com todas as funções chamadas a partir dela. </para>

<para
>Para uma medida exata dos eventos que ocorrem, existem algumas bibliotecas com funções capazes de ler os contadores de performance do 'hardware'. As mais conhecidas são a atualização PerfCtr para o &Linux;, e as bibliotecas independentes da arquitectura PAPI e PCL. De qualquer forma, uma medida exata necessita de instrumentação no código, como dito anteriormente. Qualquer uma delas usa as próprias bibliotecas ou usa os sistemas de instrumentação automáticos como o ADAPTOR (para a instrumentação do código em FORTRAN) ou o DynaProf (injeção de código com o DynInst).</para>

<para
>O &oprofile; é uma ferramenta de análise a nível do sistema para &Linux; que usa a amostragem.</para>

<para
>Em vários aspectos, uma forma confortável de fazer uma Análise é com o &cachegrind; ou o &callgrind;, que são simuladores que usam a plataforma de instrumentação &valgrind; durante a execução. Uma vez que não existe necessidade de acessar os contadores do 'hardware' (o que é normalmente difícil com as instalações de &Linux; de hoje em dia) e os binários a serem analisados podem ser deixados sem modificações, é uma boa forma alternativa para as outras ferramentas de análise. A desvantagem da lentidão da simulação poderá ser reduzida fazendo a simulação apenas nas partes interessantes do programa e, talvez, só apenas em algumas iterações de um ciclo. Sem a instrumentação de medida/simulação, a utilização do Valgrind só terá um atraso num fator de 3 à 5. Além disso, quando apenas o gráfico de chamadas e as contagens de chamadas forem de interesse, o simulador da 'cache' poderá ser desligado. </para>

<para
>A simulação de cache é o primeiro passo na aproximação de tempos reais, uma vez que nos modernos sistemas, o tempo de execução é muito sensível à exploração das chamadas caches (pequenos e rápidos buffers que aceleram acessos repetitivos às mesmas células de memória). O &cachegrind; faz simulação de cache travando os acessos à memória. Os dados produzidos incluem número de instruções/acesso à dados na memória e perdas nas caches de nível 1 e 2, e relaciona-o às linhas de código e funções do programa executável. Através da combinação destas contagens de perdas, usando latências perdidas de processadores típicos, uma estimativa do tempo gasto pode ser fornecida. </para>

<para
>O Callgrind é uma extensão do &cachegrind; que constrói o gráfico de chamadas de um programa durante a execução, &ie; como as funções se chamam umas às outras e quantos eventos acontecem enquanto uma função é executada. Além disso, os dados da análise a serem recolhidos podem ser separados por tarefas ('threads') e por contextos de chamadas. Ele pode fornecer dados de análise a nível da instrução para permitir a anotação do código descodificado. </para>
</sect1>

<sect1 id="introduction-visualization">
<title
>Visualização</title>

<para
>As ferramentas de análise produzem tipicamente uma grande quantidade de dados. O desejo de navegar facilmente para baixo e para cima no gráfico de chamadas, em conjunto com uma alteração rápida do modo de ordenação das funções e a apresentação dos diferentes tipos de eventos, serve de motivo para criar um aplicativo &GUI; que desempenhe esta tarefa. </para>

<para
>O &kappname; é uma visualização para os dados de análise que preenche estes requisitos. Apesar de ser programada em primeiro lugar a partir da navegação dos dados do &cachegrind; com a &calltree; em mente, existem conversores disponíveis para apresentar os dados de análise produzidos pelas outras ferramentas. No apêndice, é dada uma descrição do formato do arquivo do &cachegrind;/&callgrind;. </para>

<para
>Além de uma lista de funções ordenadas de acordo com medidas de custo exclusivas ou inclusivas, e opcionalmente agrupadas por arquivo fonte, biblioteca compartilhada ou classe C++, os recursos do &kappname; incluem diversas formas de visualização para uma função selecionada, quais sejam <itemizedlist>
<listitem
><para
>uma visão de gráfico de chamadas, que mostra uma seção do gráfico de chamadas ao redor da função selecionada,</para>
</listitem>
<listitem
><para
>uma visão de mapa em árvore, que permite visualizar chamadas aninhadas relacionadas juntas com métrica de custo inclusiva para rápida detecção visual de funções problemáticas,</para>
</listitem>
<listitem
><para
>código fonte e visões anotadas desassembladas, permitindo ver detalhes do custo relacionado às linhas de código e instruções assembler.</para>
</listitem>
</itemizedlist>

</para>
</sect1>
</chapter>

<chapter id="using-kcachegrind">
<title
>Usando o &kcachegrind;</title>

<sect1 id="using-profile">
<title
>Gerando Dados para Visualizar</title>

<para
>Primeiro, devemos gerar dados de desempenho medindo os aspectos das características em tempo de execução de um aplicativo, usando uma ferramenta de auditoria. O &kcachegrind; propriamente dito não inclui nenhuma ferramenta de auditoria, mas pode ser melhor aproveitado em conjunto com o &callgrind;, e usando um conversor, pode também ser usado para visualizar dados produzidos com o &oprofile;. Apesar do escopo deste manual não ser o de documentar como auditar com estas ferramentas, a próxima seção fornece um pequeno tutorial para início rápido que você pode tomar como base. </para>

<sect2>
<title
>&callgrind;</title>

<para
>O &callgrind; é uma parte do &valgrind;, <ulink url="http://valgrind.org"
>http://valgrind.org</ulink
>. Observe que ele era anteriormente chamado de &calltree;, mas o nome foi abandonado. </para>

<para
>O uso mais comum é anteceder a linha de comando para iniciar o seu aplicativo com o <application
>valgrind --tool=callgrind</application
>, como por exemplo <blockquote
><para
><command
>valgrind --tool=callgrind programa argumentos</command
></para
></blockquote
> Quando o programa terminar, será gerado um arquivo <filename
>callgrind.out.pid</filename
> e que poderá ser carregado no &kcachegrind;. </para>

<para
>Um uso mais avançado é gerar dados de auditoria sempre que uma determinada função de seu aplicativo é chamada. Por exemplo, para o <command
>konqueror</command
>, para ver dados de auditoria somente para renderização de uma página web, você pode decidir gerar os dados sempre que você selecionar o item de menu Ver/Recarregar. Isto corresponde a uma chamada ao <symbol
>KonqMainWindow::slotReload</symbol
>. Use <blockquote
><para
><command
> valgrind --tool=callgrind --dump-before=KonqMainWindow::slotReload konqueror </command
></para
></blockquote
> Isto produzirá múltiplos arquivos de dados de auditoria com uma sequência numérica crescente no final dos nomes de arquivo. Um arquivo sem um número no final (terminando somente no PID do processo) também será produzido. Carregando este arquivo no &kcachegrind;, todos os outros serão também carregados, e podem ser vistos na Visão Geral de Partes e Lista de Partes. </para>

</sect2>

<sect2>
<title
>&oprofile;</title>

<para
>O &oprofile; está disponível em <ulink url="http://oprofile.sf.net"
> http://oprofile.sf.net</ulink
>. Siga as instruções de instalação na página Web. Mas, antes disso, verifique se a sua distribuição não o oferece já como um pacote (como a &SuSE;). </para>

<para
>A análise ao nível do sistema só é permitida para o usuário 'root', uma vez que todas as ações do sistema poderão ser observadas. Assim, as seguintes ações terão que ser feitas como 'root'. Primeiro, configure o processo de análise, usando a &GUI; <command
>oprof_start</command
> ou a ferramenta da linha de comando <command
>opcontrol</command
>. A configuração normal seria o modo de temporização (TBS, ver a introdução). Para iniciar a medida, execute o <command
>opcontrol -s</command
>. Depois execute o aplicativo em que está interessado e, a seguir, invoque um <command
>opcontrol -d</command
>. Isto irá apresentar os resultados das medidas nos arquivos sob a pasta <filename
>/var/lib/oprofile/samples/</filename
>. Para ser capaz de visualizar os dados no &kcachegrind;, execute numa pasta vazia: <blockquote
><para
><command
> opreport -gdf | op2callgrind </command
></para
></blockquote
> Isto irá produzir uma quantidade de arquivos, um por cada programa que estava rodando no sistema. Cada um deles poderá ser carregado no &kcachegrind; por si só. </para>

</sect2>
</sect1>

<sect1 id="using-basics">
<title
>Fundamentos da Interface com o Usuário</title>

<para
>Ao iniciar o &kcachegrind; com um arquivo de dados de auditoria como argumento, ou após carregar um através do <menuchoice
><guimenu
>Arquivo</guimenu
><guimenuitem
>Abrir...</guimenuitem
> </menuchoice
>, você verá um painel de navegação contendo a lista de funções à esquerda, e na parte principal à direita, uma área com visualizações para a função selecionada. Esta área de visualização pode ser configurada arbitrariamente para mostrar múltiplas visualizações de uma vez. </para>

<para
>Na primeira inicialização, esta área será dividida em uma parte superior e inferior, cada uma com diferentes visualizações selecionáveis por abas. Para mover as visualizações, use o menu de contexto das abas, e ajuste os divisores entre as visualizações. Para alternar rapidamente entre as diferentes disposições de visualização, use Ver/Disposição/Duplicar, mude a disposição e alterne entre as disposições com Ver/Disposição/Próximo (ou melhor de acordo com os atalhos de teclado). </para>

<para
>O importante para a visualização é o tipo de evento ativo: para o &callgrind;, isto é por exemplo Perdas de Cache ou Estimativa de Ciclo, para o &oprofile;, isto é "Temporizador" no caso mais simples. Você pode mudar o tipo de evento através da caixa combinada na barra de ferramentas ou na visão de Tipo de Evento. Uma primeira visão geral das características em tempo de execução deve ser fornecida quando você seleciona a função <symbol
>main</symbol
> na lista à esquerda, e observa a visualização do gráfico de chamadas. Nele, você vê as chamadas ocorrendo em seu programa. Observe que a visão do gráfico de chamadas somente mostra funções com alta contagem de eventos. Executar um duplo-clique em uma função no gráfico, mudará a representação para mostrar as funções ao redor da selecionada. </para>

<para
>Para explorar mais a &GUI;, além deste manual, dê uma olhada na seção de documentação na página Web <ulink url="http://kcachegrind.sf.net"
> http://kcachegrind.sf.net</ulink
>. Além disso, cada elemento gráfico do &kcachegrind; possui ajuda <quote
>O Que é Isto?</quote
>. </para>
</sect1>

</chapter>


<chapter id="kcachegrind-concepts">
<title
>Conceitos Básicos</title>

<para
>Este capítulo explana alguns conceitos do &kcachegrind; e introduz termos usados na interface. </para>

<sect1 id="concepts-model">
<title
>O Modelo de Dados para Dados de Auditoria</title>

<sect2>
<title
>Entidades de Custo</title>

<para
>Contagem de custos de eventos (como Perdas na L2) são atribuídas a entidades de custo, que são itens com relacionamentos com o código fonte ou estrutura de dados de um programa fornecido. Entidades de custo não somente podem ser código simples ou posições de dados, mas também posições de referência. Por exemplo, uma chamada tem uma fonte e um alvo, ou um endereço de dados pode ter um tipo de dado e uma posição do código onde sua alocação ocorreu. </para>

<para
>As entidades de custo conhecidas pelo &kcachegrind; estão indicadas a seguir. Posições Simples: <itemizedlist
> <listitem
><para
> Instrução. Uma instrução de Assembly num endereço indicado.</para
></listitem
> <listitem
><para
> Linha de Código de uma Função. Todas as instruções que o compilador (através da informação de depuração) mapeia numa determinada linha de código, identificada pelo nome do arquivo de código e pelo número de linha, e que são executadas sob o contexto de uma determinada função. A última é necessária, porque uma linha de código de uma função incorporada ('inline') poderá aparecer no contexto de várias funções. As instruções sem qualquer mapeamento numa linha de código são representadas pela linha 0 do arquivo  "???". </para
></listitem
> <listitem
><para
> Função. Todas as linhas de código de uma determinada função compõem a função em si. Uma função é identificada pelo seu nome e pela sua localização no arquivo-objeto binário, se estiver disponível. A última é necessária porque os objetos binários de um único programa poderão conter funções com o mesmo nome (elas poderão ser acessadas, &eg;, com o 'dlopen'/'dlsym'; o editor de ligações durante a execução resolve as funções numa determinada ordem de objetos binários). Se uma ferramenta de análise não conseguir detectar o nome do símbolo de uma função, &eg; porque a informação de depuração não está disponível, tanto é usado o endereço da primeira instrução executada, ou então o "???". </para
></listitem
> <listitem
><para
> Objeto Binário. Todas as funções cujo código esteja dentro do intervalo de um determinado objeto binário, seja ele o executável principal ou uma biblioteca dinâmica.</para
></listitem
> <listitem
><para
> Arquivo de Código. Todas as funções cuja primeira instrução esteja mapeada numa linha do arquivo de código indicado.</para
></listitem
> <listitem
><para
> Classe. Os nomes dos símbolos das funções estão tipicamente ordenados de forma hierárquica em espaços de nomes, &eg; os 'namespaces' de C++, ou as classes das linguagens orientadas por objetos. Como tal, uma classe poderá conter funções da classe ou outras classes embebidas nela.</para
></listitem
> <listitem
><para
> Parte de Análise. Alguma seção no tempo de uma execução da análise, com um dado ID de tarefa, ID de processo e uma linha de comandos executada.</para
></listitem
> </itemizedlist
> Tal como é visto na lista, um conjunto de entidades de custo define normalmente outra entidade de custo. Como tal, existe uma hierarquia de inclusão das entidade de custo que deverá ser óbvia a partir da descrição acima. </para>

<para
>Posições de referência: <itemizedlist
> <listitem
><para
> Chamada de um endereço de instrução para função alvo. </para
></listitem
> <listitem
><para
> Chamada de uma linha de código para função alvo. </para
></listitem
> <listitem
><para
> Chamada de código de função para função alvo. </para
></listitem
> <listitem
><para
> Salto (in)condicional do código para instrução alvo. </para
></listitem
> <listitem
><para
> Salto (in)condicional do código para linha alvo. </para
></listitem
> </itemizedlist
> Saltos entre funções não são permitidos, uma vez que isto não faz sentido em um gráfico de chamadas. Assim, construções como manipulação de exceções e saltos longos em C terão que ser traduzidas para aparecerem na pilha de chamadas se necessário. </para>

</sect2>



<sect2>
<title
>Tipos de Eventos</title>

<para
>Tipos de eventos arbitrários podem ser especificados nos dados de auditoria fornecendo-lhes um nome. Seu custo relacionado a uma entidade de custo é um inteiro de 64 bits. </para>
<para
>Tipos de eventos os quais os custos são especificados em um arquivo de dados de auditoria são chamados eventos reais. Além disso, tipos podem especificar fórmulas para tipos de eventos calculados a partir de eventos reais, sendo chamados de eventos herdados. </para>
</sect2>

</sect1>

<sect1 id="concepts-state">
<title
>Visualização de Estado</title>

<para
>O estado da visualização de uma janela do &kcachegrind; inclui: <itemizedlist
> <listitem
><para
> o tipo primário e secundário dos eventos selecionados para mostrar, </para
></listitem
> <listitem
><para
> o agrupamento de funções (usado na lista da Análise da Função e na cor da entidade), </para
></listitem
> <listitem
><para
> as partes da análise cujos custos serão incluídos na visualização, </para
></listitem
> <listitem
><para
> uma entidade de custo ativa (&eg; uma função selecionada a partir da barra de análise da função), </para
></listitem
> <listitem
><para
> uma entidade de custo selecionada. </para
></listitem
> </itemizedlist
> Este estado influencia as visualizações. </para>
<para
>As visualizações são sempre apresentadas apenas para a entidade de custo atualmente ativa. Quando uma determinada visualização não é apropriada para uma entidade de custo, ela fica desativada (p.ex., ao selecionar um objeto &ELF; na lista de grupos através de um duplo-clique, a anotação de código para um objeto &ELF; não faz sentido). </para>
<para
>Por exemplo para uma função ativa, a lista de chamadas mostra todas as funções chamadas a partir da ativa. Aguém pode selecionar uma destas funções sem torná-la ativa. Se o gráfico de chamada é mostrado logo ao lado, ele automaticamente selecionará a mesma função. </para>

</sect1>

<sect1 id="concepts-guiparts">
<title
>Partes da &GUI;</title>

<sect2>
<title
>Abas Laterais</title>
<para
>As barras laterais são janelas laterais que poderão ser colocadas em qualquer extremo de uma janela do &kcachegrind;. Elas contêm sempre uma lista das entidades de custo, ordenadas de uma determinada forma. <itemizedlist>
<listitem
><para
>Auditoria de Função. A Auditoria de Função é uma lista de funções mostrando custo inclusivo e exclusivo, contagem de chamadas, nome e posição de funções. </para
></listitem>
<listitem
><para
>Visão Geral das Partes </para
></listitem>
<listitem
><para
>Pilha de Chamadas </para
></listitem>
</itemizedlist>
</para>
</sect2>

<sect2>
<title
>Área de Visualização</title>
<para
>A área de visualização, tipicamente do lado direito da janela principal do &kcachegrind;, é composta por uma (a padrão) ou mais páginas, quer alinhadas na horizontal quer na vertical. Cada página contém diferentes áreas de visualização com apenas uma entidade de custo de cada vez. O nome desta entidade é indicado no topo da página. Se existirem várias páginas, só uma estará ativa. O nome da entidade da página ativa é mostrado em negrito e determina a entidade de custo ativa da janela do &kcachegrind;. </para>
</sect2>

<sect2>
<title
>Áreas de uma Visão em Aba</title>
<para
>Cada visão em aba pode conter quatro áreas de visão, nomeadas Superior, Direita, Esquerda e Inferior. Cada área pode conter múltiplas visualizações empilhadas. A parte visível de uma área é selecionada por uma barra de abas. Barras de abas da área superior e direita estão no topo, barras de abas da área inferior e esquerda estão na base. Você pode especificar que tipo de visualização deve ser colocado em qual área usando o menu de contexto das abas. </para>
</sect2>

<sect2>
<title
>Visualização Sincronizada através da Entidade Selecionada na Visão em Abas</title>
<para
>Além de uma entidade ativa, cada visão em aba tem uma entidade selecionada. Como a maioria dos tipos de visualização mostram múltiplas entidades com a ativa centrada, você muda o item selecionado navegando dentro de uma visualização (clicando com o mouse ou usando o teclado). Tipicamente, itens selecionados são mostrado em um estado destacado. Mudando a entidade selecionada em uma visualização de uma visão em aba, todas as outras visualizações na visão em abas destacarão a nova entidade selecionada. </para>
</sect2>

<sect2>
<title
>Sincronização entre Visões em Abas</title>
<para
>Se existirem múltiplas visões em abas, uma mudança de seleção em uma visão em aba faz um mudança de ativação na visão em aba seguinte (à direita/abaixo). Este tipo de ligação por exemplo deve permitir uma rápida navegação nos gráficos de chamadas. </para>
</sect2>

<sect2>
<title
>Disposições</title>
<para
>A disposição de todas as páginas de uma janela poderá ser salva (veja o item do menu Ver/Disposição). Depois de duplicar a disposição atual (Ctrl+Mais ou o menu) e alterar alguns tamanhos ou mudar uma área de visualização de posição para outra área de uma página, você poderá mudar rapidamente entre a disposição antiga e a nova com as combinações Ctrl+Esquerda/Direita. O conjunto de disposições será salvo entre sessões do &kcachegrind; do mesmo comando analisado. Você poderá tornar o conjunto de disposições o padrão para as novas sessões do &kcachegrind; ou restaurar o conjunto de disposições padrão. </para>
</sect2>
</sect1>

<sect1 id="concepts-sidedocks">
<title
>Abas Laterais</title>

<sect2>
<title
>Auditoria Plana</title>
<para
>A auditoria plana contém uma lista de grupos e uma lista de funções. A lista de grupos contém todos os grupos onde o custo ocorre, dependendo do tipo de grupo escolhido. A lista de grupos é oculta quando o agrupamento é desligado. </para>
<para
>A lista de funções contém as funções do grupo selecionado (ou todas as funções se o agrupamento estiver desligado), ordenadas por uma determinada coluna, &eg; os custos da própria ou os custos inclusos dispendidos até então. Existe um número máximo de funções apresentado na lista que é configurável na opção Configurações/Configurar o &kcachegrind;. </para>
</sect2>

<sect2>
<title
>Visão Geral das Partes</title>
<para
>Na execução de uma análise, poderão ser produzidos vários arquivos de dados de análise que poderão ser carregados juntamente no &kcachegrind;. A barra de Visão Geral das Partes mostra estes arquivos, ordenados na horizontal de acordo com a hora de criação; os tamanhos dos retângulo são proporcionais ao custo dispendido nas partes. Você poderá selecionar uma ou várias partes para restringir os custos apresentados nas outras zonas do &kcachegrind; apenas para estas partes. </para>
<para
>As partes são posteriormente subdivididas: existe um modo e particionamento e um de divisão de custo inclusivo: <itemizedlist>
<listitem
><para
>Partição: O usuário vê a repartição em grupos para uma parte de dados de análise, de acordo com o tipo de grupo selecionado. Por exemplo, se forem selecionados os grupos de objetos &ELF;, você irá ver retângulos coloridos para cada objeto &ELF; usado (biblioteca dinâmica ou executável), dimensionado de acordo com o custo nele dispendido. </para
></listitem>
<listitem
><para
>Divisão de Custo Inclusivo: Um retângulo mostrando o custo inclusivo da função ativa atual na parte é mostrado. Ele divide-se novamente para mostrar os custos inclusivos de suas chamadas. </para
></listitem>
</itemizedlist>
</para>
</sect2>

<sect2>
<title
>Pilha de Chamadas</title>
<para
>Isto é uma pilha de chamadas 'mais provável' puramente fictícia. Ela é construída iniciando com a função ativa atual e adicionar as chamadas/chamados com custo mais alto de cima para baixo. </para>
<para
>As colunas 'Custo' e 'Chamadas' mostram o custo usado para todas as chamadas a partir da função na linha acima. </para>
</sect2>
</sect1>

<sect1 id="concepts-visualizations">
<title
>Visualizações</title>

<sect2>
<title
>Tipos de Eventos</title>
<para
>Esta lista mostra todos os tipos de custo disponíveis e o custo próprio correspondente e inclusivo da função ativa atual para o tipo de evento especificado. </para>
<para
>Se escolher um tipo de evento na lista, você poderá alterar o tipo de custos apresentados em todo o &kcachegrind;, de modo a ser o tipo selecionado. </para>
</sect2>

<sect2>
<title
>Lista de Chamadas</title>
<para
>Estas listas mostram chamadas para/da função ativa atual. Com 'todas' funções chamadoras/chamadas significando que podem ser alcançadas na direção chamadora/chamada, mesmo se outras funções estiverem interpostas. </para>
<para
>Visões de lista de chamada incluem: <itemizedlist>
<listitem
><para
>Chamadores Diretos </para
></listitem>
<listitem
><para
>Chamados Diretos </para
></listitem>
<listitem
><para
>Todos os Chamadores </para
></listitem>
<listitem
><para
>Todas as Chamadas </para
></listitem>
</itemizedlist>
</para>
</sect2>

<sect2>
<title
>Mapas</title>
<para
>Uma visualização de mapa em árvore do tipo de evento primário, acima e abaixo da hierarquia de chamadas. Cada retângulo colorido representa uma função; seu tamanho tenta ser proporcional ao custo gasto nela enquanto a função ativa estiver em execução (no entanto, existem restrições de desenho). </para>
<para
>Para o Mapa de Chamador, o gráfico mostra a hierarquia aninhada de todos os chamadores da função ativa atual; para o Mapa de Chamados, ele mostra a hierarquia aninhada de todas os chamados da função ativa atual. </para>
<para
>Opções de aparência podem ser encontradas no menu de contexto. Para obter proporções exatas de tamanho, escolha 'Ocultar bordas incorretas'. Como este modo pode consumir muito tempo, você pode querer limitar o nível de aninhamento de desenho máximo antes. 'O Melhor' determina a direção de divisão para filhos a partir da proporção do pai. 'Sempre O Melhor' decide sobre o espaço remanescente para cada irmão. 'Ignorar Proporções' toma o espaço para desenhar o nome da função antes de desenhar o filho. Observe que as proporções de tamanho podem ficar bastante incorretas. </para>
<para
>A navegação pelo teclado está disponível com as teclas de set esquerda/direita para navegar por irmãos, e teclas de seta acima/abaixo para ir um nível aninhado acima/abaixo. 'Return' ativa o item atual. </para>
</sect2>

<sect2>
<title
>Gráfico de Chamadas</title>
<para
>Esta janela mostra o gráfico de chamadas em torno da função ativa. O custo apresentado é apenas o custo dispendido enquanto a função estava de fato rodando; &ie;, o custo mostrado para o main() - se for visível - deverá ser o mesmo que o custo da função ativa, uma vez que faz parte do custo inclusivo do main() dispendido enquanto a função ativa estava em execução. </para>
<para
>Para ciclos, setas de chamadas em azul indicam que esta é uma chamada artificial adicionada para corrigir o desenho e que na verdade nunca ocorre. </para>
<para
>Se o gráfico é maior que a área do widget, um painel de visão geral é mostrado em um dos lados. Existem opções de visualização similares as do Mapa em Árvore de Chamadas; a função selecionada é destacada. </para>
</sect2>

<sect2>
<title
>Anotações</title>
<para
>A lista de código/assembler anotado mostra as instruções da linha de código/desassembladas da função ativa atual junto com o custo (próprio) gasto ao executar o código de uma linha fonte/instrução. Se existir uma chamada, linhas com detalhes sobre a chamada serão inseridas na fonte: o custo (inclusivo) gasto dentro de uma chamada, o número de chamadas que ocorreram, e o destino da chamada. </para>
<para
>Selecione uma linha de informação de chamada para ativar o destino da chamada. </para>
</sect2>
</sect1>

</chapter>


<chapter id="commands">
<title
>Referência de Comandos</title>

<sect1 id="kcachegrind-mainwindow">
<title
>A janela principal do &kcachegrind;</title>

<sect2>
<title
>O Menu <guimenu
>Arquivo</guimenu
></title>
<para>
<variablelist>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Ctrl;<keycap
>N</keycap
></keycombo
> </shortcut
> <guimenu
>Arquivo</guimenu
> <guimenuitem
>Novo</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
> Abre uma nova janela de nível superior de onde você pode carregar dados de perfil. </action
> Esta ação não é realmente necessária, uma vez que <menuchoice
><guimenu
>Arquivo</guimenu
> <guimenuitem
>Abrir... </guimenuitem
> </menuchoice
> lhe fornecerá uma nova janela de nível superior quando a atual já estiver exibindo algum dado. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Ctrl;<keycap
>O</keycap
></keycombo
> </shortcut
> <guimenu
>Arquivo</guimenu
> <guimenuitem
>Abrir</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
> Exibe o Diálogo de Abertura de Arquivo para escolher um arquivo de dados de auditoria a ser carregado. </action
> Se já existir algum dado sendo mostrado na janela de nível superior atual, ele abrirá uma nova janela. Se você deseja abrir dados de auditoria adicionais na janela atual, use <menuchoice
><guimenu
>Arquivo</guimenu
> <guimenuitem
>Adicionar...</guimenuitem
> </menuchoice
>. </para>
<para
>Os nomes dos arquivos de dados de auditoria normalmente terminam em .'.pid.part-threadID', onde o 'part' e 'threadID' são opcionais e 'pid' e 'part' são usados para arquivos de dados de auditoria múltiplos ao longo da execução de um aplicativo. Ao carregar um arquivo terminando somente com '.pid', eventualmente existindo outros arquivos de dados para esta execução, mas com pontos adicionais, eles serão também carregados também. </para>
<para
>Exemplo: Se existir arquivos de dados de auditoria cachegrind.out.123 e cachegrind.out.123.1, carregando o primeiro, o segundo será automaticamente carregado também. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Arquivo</guimenu
> <guimenuitem
>Adicionar...</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
> Adiciona uma arquivo de dados de auditoria à janela atual. </action
> Com isto, você pode forçar que arquivos de dados múltiplos sejam carregados em uma mesma janela de nível superior mesmo se eles não vierem da mesma execução fornecida por uma convenção de nomeação de arquivos de dados de auditoria. Por exemplo, use-o para comparações lado a lado. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Arquivo</guimenu
> <guimenuitem
>Recarregar</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
> Recarrega os dados de auditoria. </action
> Isto é mais interessante após outro arquivo de dados de auditoria ter sido gerado pela execução de um aplicativo já carregado. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Ctrl;<keycap
>S</keycap
></keycombo
> </shortcut
> <guimenu
>Arquivo</guimenu
> <guimenuitem
>Sair</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Sai</action
> do &kappname;</para
></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

<sect2>
<title
>O Menu <guimenu
>Ver</guimenu
></title>
<para>
<variablelist>

<varlistentry>
<term
><menuchoice
><guimenu
>Ver</guimenu
> <guimenuitem
>Tipo de Evento Primário</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>(A ser feito)</action
></para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ver</guimenu
> <guimenuitem
>Tipo de Evento Sevundário</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>(A ser feito)</action
></para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ver</guimenu
> <guimenuitem
>Agrupamento</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>(A ser feito)</action
></para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ver</guimenu
> <guimenuitem
>Disposição</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>(A ser feito)</action
></para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ver</guimenu
> <guimenuitem
>Dividir</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>(A ser feito)</action
></para
></listitem>
</varlistentry>

</variablelist>
</para>

</sect2>


</sect1>
</chapter>

<chapter id="faq">
<title
>Perguntas e Respostas</title>
&reporting.bugs; &updating.documentation; <qandaset id="faqlist">


<qandaentry>
<question>
<para
>Para que serve o &kcachegrind;? Eu não faço a mínima ideia. </para>
</question>
<answer>
<para
>O &kcachegrind; é útil no último estágio de desenvolvimento de software, chamado Auditoria. Se você não desenvolve aplicativos, você não precisa do &kcachegrind;. </para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para
>Qual a diferença entre 'Inclusivo' e 'Próprio'? </para>
</question>
<answer>
<para
>Estes são atributos de custo para funções relativos a algum tipo de evento. Como funções podem chamar outras, faz sentido distinguir o custo da função propriamente dita ('Custo Próprio') e o cuso incluindo todas as chamadas de funções ('Custo Inclusivo'). 'Próprio' é algumas vezes também referenciado como custo 'Exclusivo'. </para>
<para
>Assim, por exemplo para o main(), você sempre terá um custo inclusivo de cerca de 100%, visto que o custo próprio e negligenciado quando o trabalho real é feito em outra função. </para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para
>A barra de ferramentas/menu do meu &kcachegrind; está tão esquisita. Isto é normal?</para>
</question>
<answer>
<para
>Obviamente, o &kcachegrind; está mal instalado no seu sistema. Recomenda-se que o compile com o prefixo de instalação igual à sua pasta base do sistema &kde;, como por exemplo o comando <command
>configure --prefix=/opt/kde4; make install</command
>. Se escolher outra pasta, como a $HOME/kde, você deverá apontar a variável de ambiente KDEDIR para esta pasta antes de executar o &kcachegrind;. </para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para
>Se eu der um duplo-clique em uma função abaixo da Visão do Gráfico de Chamadas, ele mostra para a função principal o mesmo custo da função selecionada. Isto não é supostamente um 100% costante? </para>
</question>
<answer>
<para
>Você terá ativado uma função abaixo do main() com custo menor que o main(). Para qualquer função, somente esta parte do custo total da função é mostrado, que é gasta enquanto a função ativada está rodando. Isto é, o custo mostrado para qualquer função nunca pode ser maior que o custo da função ativada. </para>
</answer>
</qandaentry>


</qandaset>
</chapter>

<chapter id="glossary">
<title
>Glossário</title>

<para
>A seguir está uma lista mesclada de termos. <itemizedlist>
<listitem
><para
>Auditoria: O processo de coletar informações estatísticas sobre as características de tempo de execução de um programa. </para
></listitem>
<listitem
><para
>Rastreamento: O processo de supervisionar a execução de um programa e armazenar eventos ocorridos ordenados por uma estampa de tempo em um arquivo de saída, para Rastreio. </para
></listitem>
<listitem
><para
>Rastreio: Uma sequência de eventos com estampas de tempo que ocorreram durante o rastreamento da execução de um programa. Seu tamanho é tipicamente linear em função do tempo de execução de um programa. </para
></listitem>
<listitem
><para
>Arquivo de Dados de Auditoria: Um arquivo contendo dados medidos em um experimento de auditoria (ou parte de) ou produzidos por processamento posterior de um rastreio. Seu tamanho é tipicamente linear em função do tamanho do código do programa. </para
></listitem>
<listitem
><para
>Parte da Dados de Auditoria (incorretamente também usado: Parte de Rastreio): Dados de um arquivo de dados de auditoria. </para
></listitem>
<listitem
><para
>Experimento de Auditoria: Um programa executado sob supervisão de uma ferramenta de auditoria, produzindo possivelmente múltiplos arquivos de dados de auditoria a partir de partes e/ou linhas de execução. </para
></listitem>
<listitem
><para
>Projeto de Auditoria: Uma configuração para experimentos de auditoria usados para um programa que será auditado, talvez em versões múltiplas. Comparações de dados auditados tipicamente só fazem sentido entre dados auditados produzidos em experimentos de um projeto de auditoria. </para
></listitem>
<listitem
><para
>Entidade de Custo: Um item abstrato relacionado com o código-fonte, para o qual poderão ser atribuídas as contagens de eventos. As dimensões das entidades de custo são a localização no código (&eg;, linha de código, função), a localização dos dados (&eg; tipo dos dados acedidos, o objeto de dados), a localização da execução (&eg;, a tarefa ou processo) e os tuplos das posições acima indicadas (&eg;, as chamadas, o acesso aos objetos pela instrução, os dados obtidos a partir da 'cache'). </para
></listitem>
<listitem
><para
>Tipo de Evento: O tipo de evento do qual custos podem ser atribuídos para uma entidade de custo. Aqui existem tipos de eventos reais e tipos de eventos herdados. </para
></listitem>
<listitem
><para
>Tipo de Evento Real: Um tipo de evento que pode ser medido por uma ferramenta. Ele precisa da existência de um sensor para o tipo de evento fornecido. </para
></listitem>
<listitem
><para
>Tipo de Evento Herdado: Um tipo de evento virtual somente visível na visualização que é definido por uma fórmula a ser calculada a partir de tipos de eventos reais. </para
></listitem>
<listitem
><para
>Custos de Evento: Soma de eventos de algum tipo de evento ocorrido durante a execução é relacionada a alguma entidade de custo. O custo é atribuído à entidade. </para
></listitem>
</itemizedlist>
</para>
</chapter>

<chapter id="credits">


<title
>Créditos e Licença</title>

<para
>&kappname; </para>
<para
>Obrigado ao Julian Seward pelo seu excelente &valgrind;, e ao Nicholas Nethercote pela adição do &cachegrind;. Sem estes programas, o &kcachegrind; não existiria. Algumas das ideias para esta &GUI; foram dadas por eles, também. </para>
<para
>E agradecimentos a todos os diferentes usuários que reportaram erros/sugestões. </para>

<para
>Tradução de Marcus Gama <email
>marcus.gama@gmail.com</email
></para
> 
&underFDL; </chapter>

<appendix id="installation">
<title
>Instalação</title>

<sect1 id="getting-kcachegrind">
<title
>Como obter o &kcachegrind;</title>

<para
>O &kcachegrind; é parte do pacote &package; do &kde;. Para versões menos suportadas, &callgrind; e documentação adicional, veja a página web em <ulink url="http://kcachegrind.sf.net"
>http://kcachegrind.sf.net</ulink
>. Lá você obterá instruções completas para instalação e compilação. </para>
</sect1>

<sect1 id="requirements">
<title
>Requisitos</title>

<para
>Para usar com sucesso o &kcachegrind;, você precisa do &kde; 4.x. Para gerar dados de auditoria, o &cachegrind; ou o &calltree;/&callgrind; é recomendável. </para>
</sect1>

<sect1 id="compilation">
<title
>Compilação e Instalação</title>
&install.compile.documentation; </sect1>

<sect1 id="configuration">
<title
>Configuração</title>

<para
>itens as opções de configuração estão tanto no diálogo de configuração como nos menus de contexto das visualizações. </para>

</sect1>

</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->













