X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Ftutorial%2Ftutorial.tex;h=5860ca888b20ca1a44a7b465372a69b9d8ae2d61;hb=e82def787e9b068059b622be21c8617ec2199e0b;hp=cef3632ac51a4cfefc36de88965c664dd3d0c78d;hpb=4a8fefed01935c3ede1a6bc272c13ea03a05cadb;p=fw%2Fstlink

diff --git a/doc/tutorial/tutorial.tex b/doc/tutorial/tutorial.tex
index cef3632..5860ca8 100644
--- a/doc/tutorial/tutorial.tex
+++ b/doc/tutorial/tutorial.tex
@@ -24,7 +24,7 @@
 \section{Overview}
 \paragraph{}
 This guide details the use of STMicroelectronics STM32 discovery kits in
-an opensource environment.
+an open source environment.
 
 
 \newpage
@@ -48,61 +48,80 @@ This documentation assumes the toolchains is installed in a \$TOOLCHAIN\_PATH.
 
 \section{Installing STLINK}
 \paragraph{}
-STLINK is an opensource software to program and debug the discovery kits. Those
+STLINK is open source software to program and debug ST's STM32 Discovery kits. Those
 kits have an onboard chip that translates USB commands sent by the host PC into
-JTAG commands. This chip is called STLINK, which is confusing since the software
-has the same name. It comes into 2 versions (STLINK v1 and v2). From a software
+JTAG/SWD commands. This chip is called STLINK, (yes, isn't that confusing? suggest a better
+name!)  and comes in 2 versions (STLINK v1 and v2). From a software
 point of view, those versions differ only in the transport layer used to communicate
-(v1 uses SCSI passthru commands, while v2 uses raw USB).
+(v1 uses SCSI passthru commands, while v2 uses raw USB).  From a user point of view, they 
+are identical. 
 
 \paragraph{}
-Before continuing, the following dependencies are required:
+Before continuing, the following dependencies must be met:
 \begin{itemize}
 \item libusb-1.0
-\item libsg2
+\item pkg-config
+\item autotools
 \end{itemize}
 
+\paragraph{}
+STLINK should run on any system meeting the above constraints.
+
 \paragraph{}
 The STLINK software source code is retrieved using:\\
 \begin{small}
 \begin{lstlisting}[frame=tb]
-git clone https://github.com/texane/stlink stlink.git
+$> git clone https://github.com/texane/stlink stlink.git
 \end{lstlisting}
 \end{small}
 
 \paragraph{}
-The GDB server is called st-util and is built using:\\
+Everything can be built from the top directory:\\
 \begin{small}
 \begin{lstlisting}[frame=tb]
-$> cd stlink.git;
-$> make ;
-$> cd gdbserver ;
-$> make ;
+$> cd stlink.git
+$> ./autogen.sh 
+$> ./configure
+$> make
 \end{lstlisting}
 \end{small}
+It includes:
+\begin{itemize}
+\item a communication library (stlink.git/libstlink.a),
+\item a GDB server (stlink.git/st-util),
+\item a flash manipulation tool (stlink.git/st-flash).
+\end{itemize}
 
 
 \newpage
+\section{Using the GDB server}
+\paragraph{}
+This assumes you have got the libopencm3 project downloaded in [ocm3].  The
+libopencm3 project has some good, reliable examples for each of the Discovery boards.
 
-\section{Building and running a program}
-A simple LED blinking example is provided in the example directory. It is built using:\\
-\begin{small}
-\begin{lstlisting}[frame=tb]
-cd stlink.git/example/blink ;
-PATH=$TOOLCHAIN_PATH/bin:$PATH make ;
-\end{lstlisting}
-\end{small}
+Even if you don't plan on using libopencm3, the examples they provide will help you 
+verify that:
+
+\begin{itemize}
+\item Your installed toolchain is capable of compiling for cortex M3/M4 targets
+\item stlink is functional
+\item Your arm-none-eabi-gdb is functional
+\item Your board is functional
+\end{itemize}
 
 \paragraph{}
-A GDB server must be start to interact with the STM32. Depending on the discovery kit you
+A GDB server must be started to interact with the STM32. Depending on the discovery kit you
 are using, you must run one of the 2 commands:\\
 \begin{small}
 \begin{lstlisting}[frame=tb]
-# STM32VL discovery kit
-$> sudo ./st-util /dev/sg2
+# STM32VL discovery kit (onboard ST-link)
+$> ./st-util --stlinkv1
+
+# STM32L or STM32F4 discovery kit (onboard ST-link/V2)
+$> ./st-util 
 
-# STM32L discovery kit
-$> sudo ./st-util
+# Full help for other options (listen port, version)
+$> ./st-util --help
 \end{lstlisting}
 \end{small}
 
@@ -110,7 +129,7 @@ $> sudo ./st-util
 Then, GDB can be used to interact with the kit:\\
 \begin{small}
 \begin{lstlisting}[frame=tb]
-$> $TOOLCHAIN_PATH/bin/arm-none-eabi-gdb
+$> $TOOLCHAIN_PATH/bin/arm-none-eabi-gdb example_file.elf
 \end{lstlisting}
 \end{small}
 
@@ -118,75 +137,88 @@ $> $TOOLCHAIN_PATH/bin/arm-none-eabi-gdb
 From GDB, connect to the server using:\\
 \begin{small}
 \begin{lstlisting}[frame=tb]
-$> target extended localhost:4242
+(gdb) target extended localhost:4242
 \end{lstlisting}
 \end{small}
 
 \paragraph{}
-By default, the program was linked such that the base address is 0x20000000. From the architecture
-memory map, GDB knows this address belongs to SRAM. To load the program in SRAM, simply use:\\
+GDB has memory maps for as many chips as it knows about, and will load your project
+into either flash or SRAM based on how the project was linked.  Linking projects
+to boot from SRAM is beyond the scope of this document.
+
+Because of these built in memory maps, after specifying the .elf at the command line, now
+we can simply "load" the target:\\
 \begin{small}
 \begin{lstlisting}[frame=tb]
-$> load blink.elf
+(gdb) load
 \end{lstlisting}
 \end{small}
 
 \paragraph{}
-GDB automatically set the PC register to the correct value, 0x20000000 in this case. Then, you
-can run the program using:\\
+st-util will load all sections into their appropriate addresses, and "correctly" set the PC
+register.  So, to run your freshly loaded program, simply "continue"\\
 \begin{small}
 \begin{lstlisting}[frame=tb]
-$> continue
+(gdb) continue
 \end{lstlisting}
 \end{small}
 
 \paragraph{}
-The board BLUE and GREEN leds should be blinking (those leds are near the user and reset buttons).
-
+Your program should now be running, and, if you used one of the blinking examples from
+libopencm3, the LEDs on the board should be blinking for you.
 
 \newpage
-\section{Notes}
-
-\subsection{Disassembling THUMB code in GDB}
+\section{Building and flashing a program}
 \paragraph{}
-By default, the disassemble command in GDB operates in ARM mode. The programs running on CORTEX-M3
-are compiled in THUMB mode. To correctly disassemble them under GDB, uses an odd address. For instance,
-if you want to disassemble the code at 0x20000000, use:\\
+If you want to simply flash binary files to arbitrary sections of memory, or
+read arbitary addresses of memory out to a binary file, use the st-flash tool, 
+as shown below:\\
 \begin{small}
 \begin{lstlisting}[frame=tb]
-$> disassemble 0x20000001
-\end{lstlisting}
-\end{small}
 
+# stlinkv1 command to read 4096 from flash into out.bin
+$> ./st-flash read v1 out.bin 0x8000000 4096
 
-\subsection{libstm32l\_discovery}
-\paragraph{}
-The repository includes the STM32L discovery library source code from ST original firmware packages,
-available here:\\
-\begin{small}
-\begin{lstlisting}[frame=tb]
-http://www.st.com/internet/evalboard/product/250990.jsp#FIRMWARE
+# stlinkv2 command
+$> ./st-flash read out.bin 0x8000000 4096
+
+# stlinkv1 command to write the file in.bin into flash
+$> ./st-flash write v1 in.bin 0x8000000
+
+# stlinkv2 command
+$> ./st-flash write in.bin 0x8000000
 \end{lstlisting}
 \end{small}
 
 \paragraph{}
-It is built using:\\
+Of course, you can use this instead of the gdb server, if you prefer.  Just remember
+to use the ".bin" image, rather than the .elf file.\\
 \begin{small}
 \begin{lstlisting}[frame=tb]
-$> cd stlink.git/example/libstm32l_discovery/build
-$> make
+
+# write blink.bin into FLASH
+$> [sudo] ./st-flash write fancy_blink.bin 0x08000000
 \end{lstlisting}
 \end{small}
 
 \paragraph{}
-An example using the library can be built using:\\
+Upon reset, the board LEDs should be blinking.
+
+\newpage
+\section{Notes}
+
+\subsection{Disassembling THUMB code in GDB}
+\paragraph{}
+By default, the disassemble command in GDB operates in ARM mode. The programs running on CORTEX-M3
+are compiled in THUMB mode. To correctly disassemble them under GDB, uses an odd address. For instance,
+if you want to disassemble the code at 0x20000000, use:\\
 \begin{small}
 \begin{lstlisting}[frame=tb]
-$> cd stlink.git/example/lcd
-$> make
+(gdb) disassemble 0x20000001
 \end{lstlisting}
 \end{small}
 
+
 \newpage
 \section{References}
 \begin{itemize}
@@ -194,6 +226,9 @@ $> make
   documentation related to the STM32L mcu
 \item http://www.st.com/internet/evalboard/product/250990.jsp\\
   documentation related to the STM32L discovery kit
+\item http://www.libopencm3.org\\
+  libopencm3, a project providing a firmware library, with solid examples for Cortex
+  M3, M4 and M0 processors from any vendor.
 \end{itemize}
 
 \end{document}