% Short manual that explains the end user how to use the simulator (pt).

\documentclass[11pt,a4paper,twoside,titlepage]{report}

\usepackage[utf8x]{inputenc}
\usepackage[portuguese]{babel}
\usepackage[T1]{fontenc}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{color}
\usepackage{siunitx}

\newcommand{\Author}{Bruno Nova}
\newcommand{\Title}{DrMIPS -- Manual de Utilizador}

\author{Bruno Nova}
\title{\Title}
\hypersetup{pdfauthor={Bruno Nova},pdftitle={\Title}}
\definecolor{cloudwhite}{cmyk}{0,0,0,0.025}
\graphicspath{{figures/}}

\lstset{
	extendedchars=\true,
	inputencoding=utf8x,
	literate={ç}{{\c{c}}}1,
	basicstyle=\footnotesize\ttfamily,
	keywordstyle=\bfseries,
	numbers=left,
	numberstyle=\scriptsize\texttt,
	stepnumber=1,
	numbersep=8pt,
	frame=tblr,
	float=htb,
	aboveskip=8mm,
	belowskip=4mm,
	backgroundcolor=\color{cloudwhite},
	showspaces=false,
	showstringspaces=false,
	showtabs=false,
	tabsize=2,	
	captionpos=b,
	breaklines=true,
	breakatwhitespace=false,
	escapeinside={\%*}{*)},
	morekeywords={*,var,template,new}
}

\newcommand{\menupath}[1]{\textbf{\emph{#1}}}



\begin{document}

\maketitle
\tableofcontents


\chapter{Introdução}

O DrMIPS é um simulador do processador MIPS.
Ele permite seguir a execução de um programa em \emph{assembly}
passo-a-passo. Uma representação gráfica do caminho de dados permite ver
como o processador funciona internamente.

Este manual é um curto guia de como usar o simulador, focando-se
na versão para PC.
O Capítulo~\ref{ch:composition} fornece uma visão geral da interface gráfica.
O Capítulo~\ref{ch:tabs_windows} explica a interface dos separadores/janelas
do simulador e como os utilizar.


\chapter{Composição da Interface Gráfica} \label{ch:composition}

A interface gráfica do simulador DrMIPS é composta pela barra de menus, pela
barra de ferramentas e pela área onde os conteúdos principais do simulador são
mostrados.
Os ícones na barra de ferramentas são atalhos para algumas acções usadas
frequentemente nos menus. Pode pairar o cursor do rato sobre cada ícone para
descobrir o que ele faz.

A interface é mostrada com um tema claro, por omissão. Mas pode mudar para o
tema escuro ao seleccionar \menupath{Ver > Tema escuro} no menu.
O DrMIPS suporta múltiplos idiomas, portanto estes nomes podem ser diferentes.
Pode escolher outro idioma no menu \menupath{Ver > Idioma}.

Os conteúdos principais do simulador são divididos em separadores, por omissão.
Cada separador pode ser posicionado no lado esquerdo da janela ou no lado 
direito.
Pode mover um separador para o outro lado se clicar com o botão direito do rato
no separador e seleccionar \menupath{Mudar de lado} no menu que aparece.
Se, em vez disso, preferir ver os conteúdos divididos em janelas, pode fazê-lo
seleccionando \menupath{Ver > Janelas internas} no menu.
As posições e tamanhos dos separadores/janelas são recordadas ao sair.

Os separadores ou janelas mostrados são:
\begin{itemize}
	\item \textbf{Código}: o editor de código, onde pode criar ou editar um
		programa em \emph{assembly} para ser executado pelo simulador.
	\item \textbf{Código máquina}: após o código máquina ser gerado com sucesso,
		este mostra as instruções máquina resultantes.
	\item \textbf{Registos}: lista todos os registos e seus valores.
	\item \textbf{Memória de dados}: mostra todos os valores na memória de 
		dados.
	\item \textbf{Caminho de dados}: a representação gráfica do caminho de
		dados, e o seu estado, é mostrada aqui.
\end{itemize}


\chapter{Separadores/Janelas} \label{ch:tabs_windows}

\section{Código}

Este é o editor de código, onde pode escrever um programa em \emph{assembly}.
O editor mostra os números das linhas e realça a sintaxe válida.

Pode desfazer/refazer alterações, cortar/copiar/colar texto e 
procurar/substituir palavras no código. Estas acções podem ser acedidas pelo
menu \menupath{Editar} ou com um clique com o botão direito do rato no editor.
O código pode ser gravado para ou lido de um ficheiro. Estas acções estão
disponíveis no menu \menupath{Ficheiro}.

Pode premir \emph{Ctrl+Espaço} para auto-completar a palavra que está a escrever.
Ao fazer isso será mostrada uma lista de instruções, pseudo-instruções,
directivas e etiquetas que podem completar essa palavra.
Também será mostrada uma janela que explica o que a palavra seleccionada na lista
faz e como é usada.
Ao premir \emph{Ctrl+Espaço} num espaço vazio serão listadas todas as instruções,
pseudo-instruções, directivas e etiquetas disponíveis.
Também pode ver esta informação no menu \menupath{CPU > Instruções suportadas}.

Após escrever um programa em \emph{assembly}, terá de o converter em código máquina
(i.e., ``assemblar'' o programa).
Isto é feito seleccionando \menupath{Executar > Gerar o código máquina} no menu ou
pressionando o respectivo botão na barra de ferramentas.
Se o programa tiver erros, uma mensagem irá indicar o primeiro erro e um ícone de
exclamação irá aparecer ao lado dos números das linhas que têm um erro.
Pode pairar o cursor do rato sobre estes ícones para descobrir qual é o erro.
Se o programa estiver correcto, nenhuma mensagem será mostrada e pode prosseguir
para o executar.


\section{Código Máquina} \label{sec:assembled}

Após o código máquina ser gerado com sucesso, as instruções máquina
resultantes serão mostradas aqui numa tabela.

Cada linha da tabela corresponde a uma instrução máquina, contendo o seu
endereço, código máquina e instrução original.
A instrução a ser executada no momento é realçada.

Se estiver a simular um processador pipeline, todas as instruções que estão no
pipeline são realçadas com diferentes cores, cada uma representando uma uma etapa
diferente.
As diferentes cores significam:
\begin{itemize}
	\item \textbf{Azul}: Etapa \textbf{I}nstruction \textbf{F}etch (\textbf{IF}).
	\item \textbf{Verde}: Etapa \textbf{I}nstruction \textbf{D}ecode (\textbf{ID}).
	\item \textbf{Amarelo}: Etapa \textbf{Ex}ecute (\textbf{EX}).
	\item \textbf{Vermelho}: Etapa \textbf{Mem}ory access (\textbf{MEM}).
	\item \textbf{Magenta}: Etapa \textbf{W}rite \textbf{B}ack (\textbf{WB}).
\end{itemize}

Ao pairar o cursor do rato sobre uma instrução na tabela irá exibir uma dica.
Esta dica mostra o tipo da instrução e os valores dos seus campos. \footnote{Na
versão para Android, toque na instrução para ver a sua dica.}

Os valores são mostrados em formato decimal, por omissão.
Pode alterar esse formato para binário ou hexadecimal usando a caixa de 
combinação no fundo do separador/janela.
Esta caixa de combinação está disponível em todos os separadores/janelas, 
excepto no separador/janela de código.

Para controlar a simulação, pode usar o menu \menupath{Executar} ou a barra de
ferramentas. Prima \menupath{Passo} para executar uma instrução, 
\menupath{Passo atrás} para reverter uma instrução, \menupath{Executar} para
executar o programa inteiro e \menupath{Reiniciar} para reverter para a primeira
instrução.


\section{Registos e Memória de Dados}

Estes dois separadores/janelas são bastante semelhantes.
O separador/janela dos registos mostra os valores dos registos e do contador do
programa, enquanto que o separador/janela da memória de dados mostra os valores
na memória de dados.

Os valores que estão actualmente a ser acedidos são realçados em diferentes 
cores. As cores significam:
\begin{itemize}
	\item \textbf{Verde}: o registo/endereço está a ser lido no banco de
		registos/memória de dados.
	\item \textbf{Vermelho}: o registo/endereço está a ser escrito no banco de
		registos/memória de dados.
	\item \textbf{Amarelo}: o registo/endereço está a ser lido e escrito no mesmo
		ciclo no banco de registos/memória de dados.
\end{itemize}

Pode editar o valor de qualquer registo ou endereço de memória fazendo 
duplo-clique nele na respectiva tabela. Isto inclui o contador do programa.
Registos constantes (como o registo \verb+$zero+) não podem ser editados.
\footnote{Na versão para Android, toque durante alguns segundos no
registo/endereço para o editar.}

Por omissão, os valores dos registos e da memória de dados são reiniciados
sempre que o código máquina é gerado.
Se não quiser que isto aconteça, desmarque 
\menupath{Executar > Reiniciar dados antes de gerar cód. máquina} no menu.


\section{Caminho de Dados}

A representação gráfica do caminho de dados do processador é exibida aqui.
É aqui que pode ver como o CPU funciona internamente.

O DrMIPS pode simular vários caminhos de dados uniciclo e pipeline diferentes.
O nome do caminho de dados a ser usado actualmente é mostrado no fundo deste
separador/janela. Pode escolher outro caminho de dados seleccionando
\menupath{CPU > Carregar} no menu.
Note que caminhos de dados diferentes podem suportar instruções diferentes.

Os caminhos de dados fornecidos por omissão são:
\begin{itemize}
	\item \textbf{Caminhos de dados uniciclo}
	\begin{itemize}
		\item \textbf{unicycle.cpu}: O caminho de dados uniciclo por omissão.
		\item \textbf{unicycle-no-jump.cpu}: Variante mais simples do caminho
			de dados uniciclo que não suporta a instrução \verb+j+
			(\emph{jump}).
		\item \textbf{unicycle-no-jump-branch.cpu}: Uma variante ainda mais
			simples do caminho de dados uniciclo que não suporta \emph{jumps}
			nem \emph{branches}.
		\item \textbf{unicycle-extended.cpu}: Uma variante os caminho de dados
			uniciclo que suporta algumas instruções adicionais, como
			multiplicações e divisões.
	\end{itemize}
	
	\item \textbf{Caminhos de dados pipeline}
	\begin{itemize}
		\item \textbf{pipeline.cpu}: O caminho de dados pipeline por omissão,
			que implementa resolução de conflitos. Os caminhos de dados 
			pipeline não suportam a instrução \verb+j+ (\emph{jump}).
		\item \textbf{pipeline-only-forwarding.cpu}: Variante do caminho de 
			dados pipeline que, em termos de resolução de conflitos, só
			implementa atalhos (dando resultados errados).
		\item \textbf{pipeline-no-hazard-detection.cpu}: Uma variante do
			caminho de dados pipeline que não implementa nenhum tipo de
			resolução de conflitos (dando resultados errados).
		\item \textbf{pipeline-extended.cpu}: Uma variante que suporta algumas
			instruções adicionais, tal como o \emph{unicycle-extended.cpu}.
	\end{itemize}
\end{itemize}

No topo do separador/janela, a instrução ou instruções actualmente a serem
executadas são mostradas. Elas são realçadas com as mesmas cores explicadas
na secção~\ref{sec:assembled}.

O caminho de dados é mostrado por baixo das instruções.
Os componentes são representados por rectângulos ou quadrados, e os fios por
linhas que terminam em setas.
Os fios que estão no caminho de controlo são mostrados em azul.
O caminho de controlo pode ser ocultado se desmarcar
\menupath{Caminho de dados > Caminho de controlo} no menu.

Fios que são considerados irrelevantes no ciclo de relógio actual são 
mostrados em cinzento.
Um fio é considerado irrelevante se for um sinal de controlo colocado a
\verb+0+, se o seu valor for ignorado por um componente, se for a saída da
\emph{unidade de detecção de conflitos} e não estiver a ocorrer um
protelamento, etc.
Pode ocultar as setas no fim dos fios desmarcando
\menupath{Caminho de dados > Setas nos fios} no menu.

Os valores em algumas entradas e saídas importantes de alguns componentes são
mostrados no caminho de dados como umas pequenas ``dicas'' com 
fundo amarelo.
Pode pairar o cursor do rato sobre estas ``dicas'' para descobrir qual é o
identificador da entrada/saída.
O menu \menupath{Caminho de dados > Dados nas entradas e saídas} contém algumas
opções para controlar estas ``dicas'': \menupath{Activar} para as mostrar/ocultar,
\menupath{Mostrar os nomes} para mostrar os nomes das entradas/saídas e
\menupath{Mostrar para todos os componentes} para mostrar as ``dicas'' em todos
os componentes.

Ao pairar o cursor do rato sobre um componente, uma dica com alguns detalhes
sobre o mesmo será mostrada \footnote{Na versão para Android, toque no
componente para ver a sua dica.}.
A dica apresenta o nome do componente, uma descrição do que faz e os valores
em todas as entradas e saídas.

O caminho de dados pode ser ampliado e reduzido. Isto pode ser feito pelas
opções \menupath{Caminho de dados > Ampliar},
\menupath{Caminho de dados > Reduzir} e \menupath{Caminho de dados > Normal}
no menu ou pelos respectivos botões na barra de ferramentas.
O nível de ampliação pode também ser ajustado automaticamente para ocupar todo
o espaço disponível ao usar a opção
\menupath{Caminho de dados > Ajustar automaticamente}.

\bigskip

O caminho de dados também pode ser mostrado num ``modo de desempenho''.
Pode mudar para este modo seleccionando 
\menupath{Caminho de dados > Modo de desempenho} no menu.
Neste modo, o desempenho do processador é simulado, e o caminho crítico
é mostrado a vermelho.

Pode ver ou o caminho crítico da instrução que está actualmente a ser
executada ou o caminho crítico global do CPU (independente da instrução).
A caixa de combinação no fundo do separador/janela é usada para escolher
entre estas duas opções.

Cada componente tem uma latência, que pode ser consultada na sua dica.
A dica também mostra as latências acumuladas nas entradas (o tempo que
demora para a entrada receber o valor correcto após a transição do relógio)
e nas saídas (o tempo que o componente demora a gerar o valor correcto para
a saída).

As latências dos componentes podem ser alteradas fazendo um duplo-clique
neles no modo de desempenho \footnote{Na versão para Android, toque durante
alguns segundos no componente no modo de desempenho para editar a sua
latência.}.
Para além disso, pode seleccionar 
\menupath{Caminho de dados > Restaurar latências} no menu para restaurar as
latências de todos os componentes para os seus valores originais, e
\menupath{Caminho de dados > Remover latências} para colocar todas as
latências a \verb+0+.

Também pode ver algumas estatísticas sobre a simulação, como a frequência de
relógio e o CPI (\emph{Ciclos Por Instrução}), seleccionando
\menupath{Caminho de dados > Estatísticas} no menu.


\end{document}
