From 09f6e9d6b6c45b164188c8cdcc75e9628e531bfa Mon Sep 17 00:00:00 2001
From: Robert Baruch <robert.c.baruch@gmail.com>
Date: Wed, 25 Nov 2020 09:53:39 -0800
Subject: [PATCH] Clarifies use of integers, and character set.

---
 manual/CHAPTER_TextRtlil.tex | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex
index ee77a987d..12b90a7f7 100644
--- a/manual/CHAPTER_TextRtlil.tex
+++ b/manual/CHAPTER_TextRtlil.tex
@@ -23,6 +23,10 @@ Finally, note that all statements (rules ending in \texttt{-stmt}) terminate in
 
 \section{Lexical elements}
 
+\subsection{Characters}
+
+The characters accepted in an RTLIL file are those encodable in 8 bits. Unicode is not supported. For maximum safety, limit characters to the 7-bit ASCII range $[0,127]$.
+
 \subsection{Identifiers}
 
 There are two types of identifiers in RTLIL:
@@ -33,13 +37,15 @@ There are two types of identifiers in RTLIL:
 \end{itemize}
 
 \begin{indentgrammar}{<autogen-id>}
-<id> ::= <public-id> | <autogen-id> | <dotted-id>
+<id> ::= <public-id> | <autogen-id>
 
 <public-id> ::= "\textbackslash" <nonws>$+$
 
 <autogen-id> ::= "\textdollar" <nonws>$+$
 \end{indentgrammar}
 
+A \texttt{nonws} character is any character other than a space (ASCII 32), tab (ASCII 9), newline (ASCII 10), or carriage return (ASCII 13).
+
 \subsection{Values}
 
 A \textit{value} consists of a width in bits and a bit representation, most significant bit first. Bits may be any of:
@@ -52,11 +58,13 @@ A \textit{value} consists of a width in bits and a bit representation, most sign
     \item \texttt{-}: A don't care value
 \end{itemize}
 
-An \textit{integer} is simply a signed integer value in decimal format.
+An \textit{integer} is simply a signed integer value in decimal format. \textbf{Warning:} Integer constants are limited to 32 bits. That is, they may only be in the range $[-2147483648, 2147483648)$. Integers outside this range will result in an error.
 
 \begin{indentgrammar}{<binary-digit>}
 <value> ::= <decimal-digit>$+$ \texttt{\textbf{'}} <binary-digit>$*$
 
+<decimal-digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
+
 <binary-digit> ::= "0" | "1" | "x" | "z" | "m" | "-"
 
 <integer> ::= "-"$?$ <decimal-digit>$+$
@@ -128,8 +136,6 @@ Declares a module, with zero or more attributes, consisting of zero or more wire
 
 Declares an attribute with the given identifier and value.
 
-\textbf{Warning:} Integer constants greater than 32 bits are silently truncated to 32 bits and treated as unsigned.
-
 \begin{indentgrammar}{<attr-stmt>}
 <attr-stmt> ::= "attribute" <id> <constant> <eol>
 \end{indentgrammar}
@@ -138,6 +144,8 @@ Declares an attribute with the given identifier and value.
 
 A signal is anything that can be applied to a cell port, i.e. a constant value, all bits or a selection of bits from a wire, or concatenations of those.
 
+\textbf{Warning:} When an integer constant is a sigspec, it is always 32 bits wide, 2's complement. For example, a constant of $-1$ is the same as \texttt{32'11111111111111111111111111111111}, while a constant of $1$ is the same as \texttt{32'1}.
+
 See Sec.~\ref{sec:rtlil_sigspec} for an overview of signal specifications.
 
 \begin{indentgrammar}{<sigspec>}
-- 
2.30.2