Skip to content

Update hardware.md #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 10, 2025
Merged

Update hardware.md #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 91 additions & 102 deletions src/start/hardware.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,42 @@
# Hardware

By now you should be somewhat familiar with the tooling and the development
process. In this section we'll switch to real hardware; the process will remain
largely the same. Let's dive in.
A estas alturas, ya deberías estar familiarizado con las herramientas
y el proceso de desarrollo. En esta sección, hablaremos de hardware real;
el proceso se mantendrá prácticamente igual. Profundicemos.

## Know your hardware
## Conoce tu hardware

Before we begin you need to identify some characteristics of the target device
as these will be used to configure the project:
Antes de comenzar, es necesario identificar algunas características del dispositivo de destino,
ya que se utilizarán para configurar el proyecto:

- The ARM core. e.g. Cortex-M3.
- El núcleo ARM, Cortex-M3 por ejemplo.

- Does the ARM core include an FPU? Cortex-M4**F** and Cortex-M7**F** cores do.
- ¿El núcleo ARM incluye una FPU? Los núcleos Cortex-M4**F** y Cortex-M7**F** sí la incluyen.

- How much Flash memory and RAM does the target device have? e.g. 256 KiB of
Flash and 32 KiB of RAM.
- ¿Cuánta memoria Flash y RAM tiene el dispositivo de destino? Por ejemplo,
256 KiB de Flash y 32 KiB de RAM.

- Where are Flash memory and RAM mapped in the address space? e.g. RAM is
commonly located at address `0x2000_0000`.
- ¿Dónde se asignan la memoria flash y la RAM en el espacio de direcciones?
Por ejemplo, la RAM suele ubicarse en la dirección `0x2000_0000`.

You can find this information in the data sheet or the reference manual of your
device.
Puede encontrar esta información en la hoja de datos o en el manual de referencia de su dispositivo.

In this section we'll be using our reference hardware, the STM32F3DISCOVERY.
This board contains an STM32F303VCT6 microcontroller. This microcontroller has:
En esta sección, utilizaremos nuestro hardware de referencia, el STM32F3DISCOVERY.
Esta placa contiene un microcontrolador STM32F303VCT6. Este microcontrolador tiene:

- A Cortex-M4F core that includes a single precision FPU
- Un núcleo Cortex-M4F que incluye una única FPU de precisión

- 256 KiB of Flash located at address 0x0800_0000.
- 256 KiB de Flash ubicado en la dirección 0x0800_0000.

- 40 KiB of RAM located at address 0x2000_0000. (There's another RAM region but
for simplicity we'll ignore it).
- 40 KiB de RAM ubicados en la dirección 0x2000_0000. (Hay otra región de RAM,
pero para simplificar, la ignoraremos).

## Configuring
## Configurando

We'll start from scratch with a fresh template instance. Refer to the
[previous section on QEMU] for a refresher on how to do this without
`cargo-generate`.
Empezaremos desde cero con una nueva instancia de plantilla.
Consulta la sección anterior sobre [QEMU] para repasar cómo hacerlo sin ``cargo-generate`.

[previous section on QEMU]: qemu.md
[QEMU]: qemu.md

``` text
$ cargo generate --git https://github.com/rust-embedded/cortex-m-quickstart
Expand All @@ -49,7 +47,7 @@ $ cargo generate --git https://github.com/rust-embedded/cortex-m-quickstart
$ cd app
```

Step number one is to set a default compilation target in `.cargo/config.toml`.
El paso número uno es establecer un destino de compilación predeterminado en `.cargo/config.toml`.

``` console
tail -n5 .cargo/config.toml
Expand All @@ -63,13 +61,12 @@ tail -n5 .cargo/config.toml
target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)
```

We'll use `thumbv7em-none-eabihf` as that covers the Cortex-M4F core.
> **NOTE**: As you may remember from the previous chapter, we have to install
> all targets and this is a new one. So don't forget to run the installation
> process `rustup target add thumbv7em-none-eabihf` for this target.
Usaremos `thumbv7em-none-eabihf` ya que cubre el núcleo Cortex-M4F.
> **NOTA**: Como recordarás del capítulo anterior, debemos instalar todos los objetivos,
> y este es uno nuevo. Así que no olvides ejecutar el proceso de instalación `
> rustup target add thumbv7em-none-eabihf` para este objetivo.

The second step is to enter the memory region information into the `memory.x`
file.
El segundo paso es ingresar la información de la región de memoria en el archivo `memory.x`.

``` text
$ cat memory.x
Expand All @@ -81,80 +78,74 @@ MEMORY
RAM : ORIGIN = 0x20000000, LENGTH = 40K
}
```
> **NOTE**: If you for some reason changed the `memory.x` file after you had made
> the first build of a specific build target, then do `cargo clean` before
> `cargo build`, because `cargo build` may not track updates of `memory.x`.
> **NOTA**: Si por alguna razón modificó el archivo `memory.x` después de haber realizado
> la primera compilación de un objetivo de compilación específico, ejecute `cargo clean`
> antes de `cargo build`, ya que `cargo build` podría no rastrear las actualizaciones de `memory.x`.

We'll start with the hello example again, but first we have to make a small
change.
Comenzaremos nuevamente con el ejemplo de hola, pero primero tenemos que hacer un pequeño cambio.

In `examples/hello.rs`, make sure the `debug::exit()` call is commented out or
removed. It is used only for running in QEMU.
En `examples/hello.rs`, asegúrese de que la llamada `debug::exit()` esté comentada o eliminada. Solo se usa para ejecutarse en QEMU.

```rust,ignore
#[entry]
fn main() -> ! {
hprintln!("Hello, world!").unwrap();

// exit QEMU
// NOTE do not run this on hardware; it can corrupt OpenOCD state
// salir de QEMU
// NOTA no ejecute esto en el hardware; puede dañar el estado de OpenOCD
// debug::exit(debug::EXIT_SUCCESS);

loop {}
}
```

You can now cross compile programs using `cargo build`
and inspect the binaries using `cargo-binutils` as you did before. The
`cortex-m-rt` crate handles all the magic required to get your chip running,
as helpfully, pretty much all Cortex-M CPUs boot in the same fashion.
Ahora puedes compilar programas de forma cruzada usando `cargo build`
e inspeccionar los binarios con `cargo-binutils`, como antes. El paquete `cortex-m-rt`
gestiona todo el proceso necesario para que tu chip funcione, ya que, afortunadamente,
prácticamente todas las CPU Cortex-M arrancan de la misma manera.

``` console
cargo build --example hello
```

## Debugging
## Depuración
La depuración será un poco diferente. De hecho, los primeros pasos pueden variar según el dispositivo de destino.
En esta sección, mostraremos los pasos necesarios para depurar un programa que se ejecuta en el STM32F3DISCOVERY.
Esto sirve como referencia; para obtener información específica sobre la depuración del dispositivo, consulte [el Debugonomicon](https://github.com/rust-embedded/debugonomicon).

Debugging will look a bit different. In fact, the first steps can look different
depending on the target device. In this section we'll show the steps required to
debug a program running on the STM32F3DISCOVERY. This is meant to serve as a
reference; for device specific information about debugging check out [the
Debugonomicon](https://github.com/rust-embedded/debugonomicon).
Como antes, realizaremos depuración remota y el cliente será un proceso GDB.
1Sin embargo, esta vez, el servidor será OpenOCD.

As before we'll do remote debugging and the client will be a GDB process. This
time, however, the server will be OpenOCD.

As done during the [verify] section connect the discovery board to your laptop /
PC and check that the ST-LINK header is populated.
Como se hizo durante la sección [verify], conecte la placa de descubrimiento a su computadora portátil/PC y verifique que el encabezado ST-LINK esté completo.

[verify]: ../intro/install/verify.md

On a terminal run `openocd` to connect to the ST-LINK on the discovery board.
Run this command from the root of the template; `openocd` will pick up the
`openocd.cfg` file which indicates which interface file and target file to use.
En una terminal, ejecute `openocd` para conectarse al ST-LINK en la placa Discovery.
Ejecute este comando desde el root del template; `openocd` recuperará el archivo `openocd.cfg`,
que indica qué archivo de interfaz y archivo de destino usar.

``` console
cat openocd.cfg
```

``` text
# Sample OpenOCD configuration for the STM32F3DISCOVERY development board
# Muestra de configuración OpenOCD para la placa de desarrollo STM32F3DISCOVERY.

# Depending on the hardware revision you got you'll have to pick ONE of these
# interfaces. At any time only one interface should be commented out.
# Dependiendo de la revisión de hardware que tengas, tendrás que elegir UNO de estas
# Interfaces. En cualquier momento solo se debe comentar una interfaz.

# Revision C (newer revision)
# Revisión C (revisión mas nueva)
source [find interface/stlink.cfg]

# Revision A and B (older revisions)
# Revisión A y B (revisiones viejas)
# source [find interface/stlink-v2.cfg]

source [find target/stm32f3x.cfg]
```

> **NOTE** If you found out that you have an older revision of the discovery
> board during the [verify] section then you should modify the `openocd.cfg`
> file at this point to use `interface/stlink-v2.cfg`.
> **NOTA** Si descubrió que tiene una revisión anterior de la
> placa de descubrimiento durante la sección [verificar], debe modificar el
> 1archivo `openocd.cfg` en este punto para usar `interface/stlink-v2.cfg`.

``` text
$ openocd
Expand All @@ -176,26 +167,26 @@ Info : Target voltage: 2.913879
Info : stm32f3x.cpu: hardware has 6 breakpoints, 4 watchpoints
```

On another terminal run GDB, also from the root of the template.
En otra terminal ejecute GDB, también desde el root de la template.

``` text
gdb-multiarch -q target/thumbv7em-none-eabihf/debug/examples/hello
```

**NOTE**: like before you might need another version of gdb instead of `gdb-multiarch` depending
on which one you installed in the installation chapter. This could also be
`arm-none-eabi-gdb` or just `gdb`.
**NOTA**: Al igual que antes, podría necesitar otra versión de gdb en lugar de `gdb-multiarch`,
dependiendo de la que haya instalado en el capítulo de instalación.
También podría ser `arm-none-eabi-gdb` o simplemente `gdb`.

Next connect GDB to OpenOCD, which is waiting for a TCP connection on port 3333.
A continuación, conecte GDB a OpenOCD, que está esperando una conexión TCP en el puerto 3333.

``` console
(gdb) target remote :3333
Remote debugging using :3333
0x00000000 in ?? ()
```

Now proceed to *flash* (load) the program onto the microcontroller using the
`load` command.
Ahora proceda a *cargar* el programa en el microcontrolador usando el
comando `load`.

``` console
(gdb) load
Expand All @@ -206,19 +197,18 @@ Start address 0x08000400, load size 7468
Transfer rate: 13 KB/sec, 2489 bytes/write.
```

The program is now loaded. This program uses semihosting so before we do any
semihosting call we have to tell OpenOCD to enable semihosting. You can send
commands to OpenOCD using the `monitor` command.
El programa ya está cargado. Este programa usa semihosting, así que antes de realizar cualquier llamada a semihosting,
debemos indicarle a OpenOCD que lo habilite. Puedes enviar comandos a OpenOCD usando el comando `monitor`.

``` console
(gdb) monitor arm semihosting enable
semihosting is enabled
```

> You can see all the OpenOCD commands by invoking the `monitor help` command.
> Puede ver todos los comandos de OpenOCD invocando el comando `monitor help`.

Like before we can skip all the way to `main` using a breakpoint and the
`continue` command.
Como antes, podemos saltar directamente a `main` usando un punto de interrupción y el
comando `continue`.

``` console
(gdb) break main
Expand All @@ -232,12 +222,12 @@ Breakpoint 1, hello::__cortex_m_rt_main_trampoline () at examples/hello.rs:11
11 #[entry]
```

> **NOTE** If GDB blocks the terminal instead of hitting the breakpoint after
> you issue the `continue` command above, you might want to double check that
> the memory region information in the `memory.x` file is correctly set up
> for your device (both the starts *and* lengths).
> **NOTA** Si GDB bloquea la terminal en lugar de alcanzar el punto de interrupción después
> de emitir el comando `continue` anterior, es posible que desee verificar que la información de la región de
> memoria en el archivo `memory.x` esté configurada correctamente
> para su dispositivo (tanto los inicios *como* las longitudes).

Step into the main function with `step`.
Ingrese a la función principal con `step`.

``` console
(gdb) step
Expand All @@ -246,8 +236,8 @@ hello::__cortex_m_rt_main () at examples/hello.rs:13
13 hprintln!("Hello, world!").unwrap();
```

After advancing the program with `next` you should see "Hello, world!" printed on the OpenOCD console,
among other stuff.
Después de avanzar el programa con `siguiente` deberías ver "¡Hola, mundo!" impreso en la consola OpenOCD,
entre otras cosas.

``` console
$ openocd
Expand All @@ -261,9 +251,9 @@ Info : halted: PC: 0x080004b4
Info : halted: PC: 0x080004b8
Info : halted: PC: 0x080004bc
```
The message is only displayed once as the program is about to enter the infinite loop defined in line 19: `loop {}`
El mensaje solo se muestra una vez porque el programa está a punto de ingresar al bucle infinito definido en la línea 19: `loop {}`

You can now exit GDB using the `quit` command.
Ahora puedes salir de GDB usando el comando `quit`.

``` console
(gdb) quit
Expand All @@ -274,8 +264,8 @@ A debugging session is active.
Quit anyway? (y or n)
```

Debugging now requires a few more steps so we have packed all those steps into a
single GDB script named `openocd.gdb`. The file was created during the `cargo generate` step, and should work without any modifications. Let's have a peek:
La depuración ahora requiere algunos pasos adicionales, por lo que los hemos agrupado en un solo script de GDB llamado `openocd.gdb`.
El archivo se creó durante el paso `cargo generate` y debería funcionar sin modificaciones. Echemos un vistazo:

``` console
cat openocd.gdb
Expand All @@ -284,10 +274,10 @@ cat openocd.gdb
``` text
target extended-remote :3333

# print demangled symbols
# imprimir símbolos desenredados
set print asm-demangle on

# detect unhandled exceptions, hard faults and panics
# Detectar excepciones no controladas, fallos graves y pánicos
break DefaultHandler
break HardFault
break rust_begin_unwind
Expand All @@ -296,29 +286,28 @@ monitor arm semihosting enable

load

# start the process but immediately halt the processor
# Iniciar el proceso pero detener inmediatamente el procesador
stepi
```

Now running `<gdb> -x openocd.gdb target/thumbv7em-none-eabihf/debug/examples/hello` will immediately connect GDB to
OpenOCD, enable semihosting, load the program and start the process.
Ahora, al ejecutar `<gdb> -x openocd.gdb target/thumbv7em-none-eabihf/debug/examples/hello` se conectará inmediatamente GDB a
OpenOCD, habilitará el semihosting, cargará el programa e iniciará el proceso.

Alternatively, you can turn `<gdb> -x openocd.gdb` into a custom runner to make
`cargo run` build a program *and* start a GDB session. This runner is included
in `.cargo/config.toml` but it's commented out.
Como alternativa, puedes convertir `<gdb> -x openocd.gdb` en un ejecutor personalizado para que
`cargo run` cree un programa *e* inicie una sesión de GDB. Este ejecutor está incluido en `.cargo/config.toml`, pero está comentado.

``` console
head -n10 .cargo/config.toml
```

``` toml
[target.thumbv7m-none-eabi]
# uncomment this to make `cargo run` execute programs on QEMU
# Descomente esto para hacer que `cargo run` ejecute programas en QEMU
# runner = "qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config enable=on,target=native -kernel"

[target.'cfg(all(target_arch = "arm", target_os = "none"))']
# uncomment ONE of these three option to make `cargo run` start a GDB session
# which option to pick depends on your system
# Descomente UNA de estas tres opciones para hacer que `cargo run` inicie una sesión GDB
# La opción a elegir depende de su sistema.
runner = "arm-none-eabi-gdb -x openocd.gdb"
# runner = "gdb-multiarch -x openocd.gdb"
# runner = "gdb -x openocd.gdb"
Expand Down
Loading