A basic guide to start with the MSP430FR family and the GCC tools on Linux.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

334 lines
14 KiB

2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
  1. # Guía de usuario MSP430 GCC Toolchain
  2. Galván.A , Chávez.G , Julio,2022.
  3. ------
  4. [^]: Para usuarios de Linux
  5. **Abstract**
  6. This manual aims to describe the setup and basic operations of the MSP430 GCC toolchain to know how to use the open-source GCC compiler for microcontrollers to build an example for an MSP430 target device using the command terminal of Linux. It will also be shown how to debug software with the GDB Agent and the GNU Debugger tools so that the program that was built can be uploaded to the target device successfully.
  7. [^]: This user guide was approved in the following distributions of Linux: **Ubuntu 22.04LTS** and **Debian 11** using a **MSP430FR6989** microcontroller.
  8. ------
  9. [TOC]
  10. ------
  11. ## **Introducción**
  12. El paquete GCC de código abierto es un depurador completo y una cadena de herramientas de compilación C/C++ de código abierto para la creación y depuración de aplicaciones integradas basadas en microcontroladores MSP430. Este compilador soporta todos los dispositivos MSP430 sin limitaciones de tamaño de código y se puede utilizar de forma independiente desde la línea de comandos o dentro de Code Composer Studio v6.0 o posterior [1].
  13. *El paquete de instalación incluye lo siguiente:*
  14. 1. Binarios GCC y GDB para Windows y Linux.
  15. 2. Encabezado MSP430 y archivos de enlace.
  16. 3. Código fuente.
  17. 4. GBD Agent Configuration.
  18. #### Instalación de MSP430 GCC como paquete independiente
  19. El primer paso es bastante sencillo, consiste en abrir la terminal de comando y direccionarse a la carpeta en donde se guardará el archivo que contenga el programa a ejecutar.
  20. Con el comando **cd** se puede entrar a alguna carpeta en específico como lo puede ser la carpeta de **Descargas**, Ejemplo:
  21. ```bash
  22. $ cd Descargas
  23. ```
  24. Antes de continuar con el siguiente paso se debe dirigir a la página oficial de TI (Texas Instruments) yendo directamente a la siguiente página [https://www.ti.com/tool/MSP430\-GCC\-OPENSOURCE](). En la pestaña de *descargas* se debe seleccionar la opción más factible para su computadora en este caso **Mitto Systems GCC 64-bit Linux installer incl. support files**. Una vez descargada, en la carpeta de descargas se debe buscar el nombre del archivo y posteriormente, en la terminal de comando se debe colocar lo siguiente: "**sudo chmod +x <installer>.run** y el comando **./<installer>**", lo cual permitirá instalar el programa. A continuación se muestra un ejemplo, donde **msp430-gcc-full-linux-X64-installer-9.3.1.2.run**, es el nombre del archivo que se descargó (installer).
  25. ```bash
  26. $ sudo chmod +x msp430-gcc-full-linux-X64-installer-9.3.1.2.run
  27. $ ./msp430-gcc-full-linux-X64-installer-9.3.1.2.run
  28. ```
  29. Al ejecutar los comandos anteriormente mencionados se abrirá la siguiente ventana:
  30. ![1.png](https://i.postimg.cc/c4vD5DpJ/1.png)
  31. Se debe seleccionar el directorio de instalación y dar click en **Next** hasta finalizar como se muestra en la siguiente imagen:
  32. ![2.png](https://i.postimg.cc/44WBMXKZ/2.png)
  33. #### Creación de directorio
  34. Se debe crear una carpeta en donde se colocará el código y los archivos necesarios para compilar el programa, en este caso se creó la carpeta **Programa1** como ejemplo.
  35. > Comando para crear carpetas desde la terminal , el comando **mkdir** + el nombre del nuevo archivo.
  36. > Comando para encontrar carpetas dentro de la carpeta en la que se encuentra **dir**.
  37. > Comando para entrar en carpeta **cd**.
  38. ```bash
  39. $ mkdir Programa1
  40. $ dir
  41. $ cd Programa1
  42. ```
  43. El código que se muestra a continuación, hace parpadear el LED P1.1 del microcontrolador MSP430FR6989, este se utilizará como ejemplo a lo largo del documento. Para poder compilar y depurar el código, es necesario copiar dicho código en un archivo **.c**.
  44. ```c
  45. #include <msp430fr6989.h>
  46. void main(void)
  47. {
  48. WDTCTL = WDTPW | WDTHOLD; // stop watchdog timer
  49. PM5CTL0 = 0x0000; // disable high impedance mode
  50. P1DIR = 0x01; //set up bit 0 of P1 as output
  51. P1OUT = 0x00; //initialize bit 0 of P1 to 0
  52. for(;;){ //loop
  53. volatile unsigned int i;
  54. P1OUT ^= 0x01; //toggle bit 0 of P1
  55. //Delay
  56. for(i=40000; i>0;){
  57. i--;
  58. __no_operation();
  59. }
  60. }
  61. }
  62. ```
  63. #### Creación de un archivo .c
  64. Para crear un archivo **.c** se debe posicionar en el directorio en el que lo desea crear y se debe digitar el comando **pico filename.c**. Por fines explicativos, como ejemplo, se creará un archivo **.c** llamado **Ejemplo** en la carpeta **Programa1** (previamente creada). Una vez que se ejecuta el comando mencionado, se abrirá una ventana en la que se deberá copiar el códiogo del programa que se quiere subir a la tarjeta. En nuestro caso se copió el código mencionado anteriormente.
  65. Comando para editar/crear el archivo **.c**.
  66. [^]: Este ejemplo fue realizado con el editor de texto **pico**, pero se puede utilizar cualquier otro editor de su preferencia.
  67. ```bash
  68. $ pico Ejemplo.c
  69. ```
  70. Una vez copiado el código en el archivo **.c**, se teclea `Ctrl + X` para salir, posteriormente se guarda el archivo tecleando `S` y por último se teclea `Enter` para regresar a la terminal de comandos.
  71. #### Compilación de un programa desde la termial de Linux
  72. El programa se puede compilar manualmente desde la terminal indicando las rutas de instalación de las librerías, binarios y demás, o usando un método más sencillo implementando un archivo *Makefile* incluido en los ejemplos por defecto que el paquete contiene. En este documento se muestran los pasos a seguir empleando el segundo método comenzando con la creación de un nuevo proyecto; sin embargo, a continuación, se muestra un ejemplo de compilación manual desde la terminal.
  73. Ejemplo de compilación de un programa desde la terminal (primer método):
  74. ```bash
  75. $ ./msp430-elf-gcc -I ~/msp430-gcc/include -L ~/msp430-gcc/include -T ~/msp430-gcc/include/msp430fr6989.ld -mmcu=msp430fr6989 -O2 -g ~/Documentos/Programa1/Ejemplo.c -o ~/Documentos/Programa1/Ejemplo.o
  76. ```
  77. Primero se debe dirigir a la dirección en donde se encuentra instalado el paquete *MSP430- GCC* y redireccionarse a la carpeta *bin*.
  78. Para compilar se coloca ./ seguido de la dirección *msp430-elf-gcc* y después se colocan los parámetros de las banderas (flags) correspondientes a -I, -L, -T, -g, -o, -mmcu.
  79. Donde:
  80. - **-I**: se agrega el directorio a la lista de directorios para buscar archivos de encabezado.
  81. - **-L**: se agregan la ruta en las que ld buscará las bibliotecas del archivo.
  82. - **-T**: dirección donde se encuentran las librerías del microcontrolador especificando cuales se utilizarán .
  83. - **-g**: dirección donde se encuentra el archivo .c .
  84. - **-o**: se especifica la ruta donde se encuentra el archivo .c, con la diferencia que se cambia el .c por .o (output file).
  85. - **-mmcu**: especifica el microcontrolador que se utilizará.
  86. ## **Creación de un nuevo proyecto**
  87. ------
  88. #### Pasos para la creación de un nuevo proyecto
  89. 1. Crear un directorio para el nuevo proyecto.
  90. 2. Insertar el archivo .c que contiene el programa que se subirá a la tarjeta. Para crear un archivo .c vea el apartado **Creación de un archivo .c**.
  91. 3. Dentro de la carpeta que se instaló (msp430-gcc), hay un directorio llamado **examples** que contiene ejemplos predeterminados. Copiar uno de los archivos `Makefile` de los proyectos de ejemplo dentro del directorio de su nuevo proyecto, en este caso, dentro de la carpeta **Programa1**.
  92. 4. Abrir el archivo `Makefile` que copió y cambiar el formato de estructura actual por el que se muestra a continuación. En la variable **OBJECTS** se debe colocar el nombre del programa que se va a subir (archivo .c) respetando la terminación **.o**. En la variable **DEVICE** se debe colocar el nombre del microcontrolador que se usará.
  93. 5. Colocar las rutas de instalación correpondientes para las variables **GCC\_DIR** y **SUPPORT\_FILE\_DIRECTORY**. Las direcciones para las variables son **../../../bin** y **../../../include** respectivamente como se muestra en el siguiente ejemplo.
  94. Estructura de archivo Makefile:
  95. ```c
  96. OBJECTS=Ejemplo.o
  97. GCC_DIR = /home/usuario/msp430-gcc/bin
  98. SUPPORT_FILE_DIRECTORY = /home/usuario/msp430-gcc/include
  99. DEVICE = msp430fr6989
  100. CC = $(GCC_DIR)/msp430-elf-gcc
  101. GDB = $(GCC_DIR)/msp430-elf-gdb
  102. CFLAGS = -I $(SUPPORT_FILE_DIRECTORY) -mmcu=$(DEVICE) -O2 -g
  103. LFLAGS = -L $(SUPPORT_FILE_DIRECTORY) -T $(DEVICE).ld
  104. all: ${OBJECTS}
  105. $(CC) $(CFLAGS) $(LFLAGS) $? -o $(DEVICE).out
  106. debug: all
  107. $(GDB) $(DEVICE).out
  108. ```
  109. ## **Debugging**
  110. #### **Uso del agente GDB **
  111. ###### Introducción
  112. El agente GDB es una herramienta para conectar el GDB con el hardware de destino para depurar el software. El GDB Agent utiliza la pila de depuración MSP430 para conectarse al hardware y proporciona una interfaz al GDB.
  113. En Windows, se proporciona una consola y una versión de aplicación GUI del agente GDB. Solo la aplicación de consola (terminal de comandos) es compatible con Linux.
  114. #### Iniciando GDB Agent
  115. ###### Línea de comando
  116. Abra una terminal de comando y dirijase al directorio de instalación, una vez hecho, ejecute lo siguiente:
  117. ```bash
  118. $ ./bin/gdb\_agent\_console msp430.dat
  119. ```
  120. La aplicación de consola abre un puerto TCP/IP en el equipo local. Muestra el número de puerto en la consola, por defecto, este número de puerto es 55000.
  121. [^]: Es importante que se deje abierta esta consola hasta terminar de depurar el programa (debugging) para poder conectar el GDB con el GDB Agent.
  122. ```c
  123. $ ./bin/gdb\_agent\_console msp430.dat
  124. CPU Name Port
  125. -------- ----
  126. msp430 :55000
  127. Starting all cores
  128. CPU Name Status
  129. -------- ------
  130. msp430 Waiting for client
  131. ```
  132. #### Debugging con GDB
  133. ##### Ejecutar un programa en el debugger
  134. 1. Abra otra terminal de comando y dirijase a la ruta donde se encuentra el directorio con el archivo **.c** y el `Makefile` del programa que quiere cargar a la tarjeta.
  135. 2. Escriba el comando **make debug**. Este comando inicia el GDB y espera que se introduzcan comandos, esto es indicado por el puntero **(gdb)**.
  136. ```bash
  137. $ make debug
  138. /home/usuario/msp430-gcc/bin/msp430-elf-gcc -I /home/usuario/msp430-gcc/include -mmcu=msp430fr6989 -O2 -g -L /home/usuario/msp430-gcc/include -T msp430fr6989.ld Ejemplo.o -o msp430fr6989.out
  139. /home/usuario/msp430-gcc/bin/msp430-elf-gdb msp430fr6989.out
  140. GNU gdb (Mitto Systems Limited - msp430-gcc 9.3.1.11) 9.1
  141. Copyright (C) 2020 Free Software Foundation, Inc.
  142. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
  143. This is free software: you are free to change and redistribute it.
  144. There is NO WARRANTY, to the extent permitted by law.
  145. Type "show copying" and "show warranty" for details.
  146. This GDB was configured as "--host=x86_64-pc-linux-gnu --target=msp430-elf".
  147. Type "show configuration" for configuration details.
  148. For bug reporting instructions, please see:
  149. <http://www.gnu.org/software/gdb/bugs/>.
  150. Find the GDB manual and other documentation resources online at:
  151. <http://www.gnu.org/software/gdb/documentation/>.
  152. For help, type "help".
  153. Type "apropos word" to search for commands related to "word"...
  154. Reading symbols from msp430fr6989.out...
  155. (gdb)
  156. ```
  157. 3. Conecte el dispositivo.
  158. 4. Escriba el comando **target remote :55000** y presione enter para conectar el GDB con el GDB Agent que se encuentra en la otra terminal de comando que se dejó abierta. En la otra terminal se podrá observar en la consola del GDB Agent que se conectó un dispositivo/cliente.
  159. ```bash
  160. Reading symbols from msp430fr6989.out...
  161. (gdb) target remote :55000
  162. Remote debugging using :55000
  163. 0x00004402 in __crt0_start ()
  164. (gdb)
  165. ```
  166. Consola del GDB Agent:
  167. ```c
  168. $ ./bin/gdb\_agent\_console msp430.dat
  169. CPU Name Port
  170. -------- ----
  171. msp430 :55000
  172. Starting all cores
  173. CPU Name Status
  174. -------- ------
  175. msp430 Waiting for client
  176. msp430 Client connected...Connecting to Target
  177. Found USB FET at ttyACM0
  178. Target connected...Starting server
  179. ```
  180. 5. Escriba **load** y presione enter para cargar el programa binario al dispositivo MSP430 que esté usando.
  181. ```bash
  182. (gdb) load
  183. Loading section .upper.data, size 0x2 lma 0x4400
  184. Loading section .text, size 0x3c lma 0x4402
  185. Loading section __reset_vector, size 0x2 lma 0xfffe
  186. Start address 0x00004402, load size 64
  187. Transfer rate: 71 bytes/sec, 21 bytes/write.
  188. (gdb)
  189. ```
  190. 6. Escriba el comando **continue** para correr el programa o en su defecto escriba **step** para compilar el programa paso por paso.
  191. ```bash
  192. (gdb) continue
  193. Continuing.
  194. ```
  195. 7. Para parar la ejecución teclee `Ctrl + C` (^C), y para salir del GDB escriba `q`, presione enter y posteriormente escriba `y` y presione enter.
  196. ```bash
  197. ^C
  198. Program stopped.
  199. main () at Ejemplo.c:15
  200. 15 i--;
  201. (gdb) q
  202. A debugging session is active.
  203. Inferior 1 [Remote target] will be detached.
  204. Quit anyway? (y or n) y
  205. Detaching from program: /home/usuario/Escritorio/msp430_programs/Programa1/msp430fr6989.out, Remote target
  206. Ending remote debugging.
  207. [Inferior 1 (Remote target) detached]
  208. ```
  209. ### **Solución de problemas**
  210. [^]: En este apartado se muestran las posibles soluciones a los problemas más comunes.
  211. **Error Make debug*
  212. ```bash
  213. $ make debug
  214. Make: *** There is no rule to build the 'debug' target. Tall
  215. ```
  216. Instalar make para solucionar el problema mediante el comando :
  217. ```bash
  218. sudo apt-get install make
  219. ```
  220. ------
  221. **Error 127 makefile debug*
  222. ```bash
  223. /home/usuario/msp430-gcc/bin/msp430-elf-gdb:error while loading shared libraries: libncursesw.so.5: cannot open shared object file: No such file or directory
  224. make: *** [Makefile: debug] Error 127
  225. ```
  226. Instalar la libreria *libncursesw.so.5* para solucionar el problema, en caso de que continúe el problema, instalar *libncursesw5-dev* mediante el comando :
  227. ```bash
  228. sudo apt-get install libncursesw5
  229. sudo apt-get inatall libncursesw5-dev (opcional)
  230. ```
  231. ------
  232. ### **Referencias**
  233. [1] Texas Instruments. Msp430-gcc-opensource gcc-open source compiler for msp microcontrollers, 2017.