Programación embebida no bloqueante mediante máquinas de estado en C++. Caso de uso con el chip de sonido SN76489 
El uso de máquinas de estado en un recurso casi obligatorio a la hora de implementar código no bloqueante, para dotar a los sistemas de algún tipo de funcionalidad multi-tarea o simplemente como mecanismo de ahorro de energía. En este post se estudiará un caso de uso: la programación del chip de sonido SN76489, mediante esta técnica de desarrollo y utilizando parte del potencial del lenguaje C++ moderno para ello.

Descripción funcional

El objetivo es hacer un pequeño montaje basado en el ARM Cortex-M3 STM32F103C8T6 como MCU y en el chip de sonido SN76489 (3 canales de tono más un canal de ruido, utilizado en las antiguas consolas de Sega y en algunas placas de recreativas de los años 80 y 90).



Dicho montaje incluye dos pulsadores externos: uno para generar un sonido de disparo "láser" y otro para generar un sonido de metralleta (o parecido, dentro de las limitaciones del SN76489).

Sonido

El SN76489 es un chip de sonido extremadamente sencillo de programar: un bus de 8 bits con señales /WE y /CE (que en este caso se han cortocircuitado) y una señal READY de salida. Como se puede ver en el circuito anterior, el SN76489 se alimenta a 5 voltios, mientras que el STM32 se alimenta a 3.3 voltios, lo que, a priori puede resultar un problema de cara a la señal READY. Dicho problema, sin embargo, no lo es tal ya que, según la hoja de datos del fabricante, el pin READY del SN76489 es una salida en colector abierto, por lo que puede atacar perfectamente a una entrada del STM32 siempre y cuando la resistencia de pull-up correspondiente esté a 3.3 voltios.

Como se puede ver en su hoja de datos, para enviarle un byte, es necesario hacer los siguiente pasos:

1. Esperar a que la salida READY se ponga a 1 (colector abierto), lo que indica que el chip puede recibir un comando.

2. Colocar el byte que se quiere enviar en el bus de 8 bits.

3. Poner /CE y /WE a 0.

4. Esperar a que la salida READY se ponga a 0 (a masa), lo que significa que está procesando el comando

5. Esperar a que la salida READY se ponga de nuevo a 1 (colector abierto), lo que significa que el comando ha sido procesado y el chip está preparado para recibir más comandos.

Esta secuencia hay que realizarla por cada comando (byte) que se le quiera enviar al SN76489.

A la hora de diseñar la máquina de estados se ha utilizado el formalismo de la máquina de Mealy. En este formalismo, los estados están caracterizados sólo por sus etiquetas, mientras que las transiciones están caracterizadas por el par (entrada | salida), en este caso, "entrada" será la condición de entrada para que el proceso tome por ese arco y la "salida" serán las operaciones a realizar en ese salto:



"condición" puede ser vacía, lo que significará que siempre se toma ese arco, y "operaciones" también podrá ser vacía, lo que significará que no se ejecuta ninguna operación al tomar ese arco.



En la máquina de estados se han introducido estados adicionales al final que permiten introducir retardos entre en envío de un comando y el siguiente. Esta funcionalidad es muy útil para controlar los tiempos: tiempo de caida de los tonos de "láser", tiempo entre "balas" de la metralleta, etc. "tc" es la variable miembro "tickCounter" usada para esperas forzosas (el STM32 va más rápido que el SN76489) mientras que "dt" se corresponde con la variable miembro "delayTicks", usada para hacer las esperas entre el envío de un comando y el envío del siguiente.

Cada objeto SN76489 incluye una cola de comandos: las funciones miembro que hacen de API se encargan de preparar y meter en la cola (push) los comandos que será posteriormente enviados por la función miembro "tick" (la encargada de ejecutar la máquina de estados):

void SN76489::setToneGeneratorFrequency(uint8_t index, uint16_t frequency, int16_t sweepFrequencyIncrement, int16_t sweepTicksPerIncrement, int16_t sweepNumIncrements) {
    if (index > 2)        // 0, 1 or 2
        index = 2;
    frequency &= 0x03FF;  // 10 bit value
    this->txQueue.push({(uint8_t) (0x80 | (index << 5) | (frequency & 0x0F))});
    this->txQueue.push({(uint8_t) ((frequency >> 4) & 0x3F), sweepTicksPerIncrement});
    while (sweepNumIncrements > 0) {
        frequency += sweepFrequencyIncrement;
        sweepNumIncrements--;
        this->txQueue.push({(uint8_t) ((frequency >> 4) & 0x3F), sweepTicksPerIncrement});
    }
}


void SN76489::setToneGeneratorAttenuation(uint8_t index, uint8_t attenuation) {
    if (index > 2)        // 0, 1 or 2
        index = 2;
    this->txQueue.push({(uint8_t) (0x80 | (index << 5) | 0x10 | (attenuation & 0x0F))});
}


void SN76489::setNoiseGeneratorFrequency(NoiseGeneratorFrequency frequency, NoiseGeneratorFeedback feedback) {
    this->txQueue.push({(uint8_t) (0xE0 | ((static_cast<uint8_t>(feedback) & 0x01) << 2) | (static_cast<uint8_t>(feedback) & 0x03))});
}


void SN76489::setNoiseGeneratorAttenuation(uint8_t attenuation, int32_t delayTicks) {
    this->txQueue.push({(uint8_t) (0xF0 | (attenuation & 0x0F)), delayTicks});
}

Mientras que la función miembro "tick" deberá ser invocada desde el SYSTICK del microcontrolador (que se ejecuta varios cientos de veces por segundo). Dicha función miembro "tick" es la encargada de ejecutar la máquina de estados y de enviar los comandos al SN76489 de forma correcta.

Para separar la implementación de esta máquina de estados del hardware se define una clase abstracta "SN76489Interface", que deberá ser implementada por el "usuario" y que es la que en última instancia escribe en el bus de datos del SN76489, escribe el bit /WE y lee el bit READY del SN76489.

class SN76489Interface {
    public:
        virtual void sn76489SetByte(uint8_t v) = 0;
        virtual void sn76489SetWE(uint8_t v) = 0;
        virtual bool sn76489GetReady() = 0;
};

Cuando se invoca la función miembro "init" del objeto "SN76489", se le pasa un puntero a un objeto de tipo "SN76489Interface", para que el objeto "SN76489" pueda comunicarse con un hardware real a través de este interface.

Cada elemento de la cola de comandos es un par (comando, ticksRetardo), de tal manera que la máquina de estados (la función miembro "tick") envía el comando y espera una cantidad de ticks equivalente a "ticksRetardo" antes de enviar el siguiente comando de la cola (si lo hubiese). De esta manera es muy sencillo hacer los sonidos propuestos:

- Láser: Se configura el generador de tono 0 con una frecuencia alta, se espera un par de ticks, se envía una frecuencia más baja, se espera otro par de ticks, se envía otra fecuencia más baja, etc. Esta caida de frecuencia en el tiempo genera un efecto psicoacústico "percutido", como de disparo. Al final de la secuencia se pone el volumen el mínimo del generator tono 0.

- Metralleta: Se configura el generador de ruido y se manda 17 veces la secuencia: volumen máximo con espera de 20 ticks y silencio con espera de 30 ticks. Esta alternancia de ruido/silencio repetidas veces genera el sonido de "metralleta".

Nótese que los comandos descritos para cada sonido se empujan en la cola de comandos de forma simultánea uno detrás de otro, es la máquina de estados (función miembro "tick" de la clase "SN76489") la que se encarga de enviar los comandos y realizar la espera entre comando y comando a medida que va sacando comandos de la cola.

Teclado

De forma adicional, es necesario implementar un pequeño teclado de dos botones, de manera de un botón dispare el "láser" y el otro la "metralleta". Para este menester creamos también una clase Keyboard pero en este caso, como dicha clase sí va a estar vinculada directamente con un recurso hardware (esta es una decisión arbitraria), será una clase estática (con todas sus funciones miembro estáticas).

La función miembro "init" configurará dos pines GPIO y el controlador de interrupciones externas ETXI del STM32 para que genere una interrupción cada vez que se produzca un flanco de bajada en esos dos pines del microcontrolador. Como se puede comprobar en la declaración de la clase Keyboard, la función miembro estática "interrupt" se coloca en la sección ".exti" dentro del código objeto: esto hará que el linker script la coloque en el lugar adecuado para que se invoque al producirse una interrupción de GPIO.

#ifndef  __KEYBOARD_H__
#define  __KEYBOARD_H__


#include <stdint.h>


extern "C++" {
    namespace avelino {
        using namespace std;

        class KeyboardListener {
            public:
                virtual void buttonPressed(int8_t key) = 0;
        };

        class Keyboard {
            protected:
                static KeyboardListener *listener;
                static int8_t currentKey;
                static int32_t tickCounter;
                enum class Status : int8_t { IDLE, WAIT_AFTER_PRESSED };
                static Status status;
            public:
                static void init(KeyboardListener *listener);
                static void interrupt()  __attribute__ ((section(".exti")));
                static void tick();
        };
    }
}


#endif  // __KEYBOARD_H__

La función miembro "interrupt" hace muy poco: simplemente actualiza la variable miembro "key" y limpia los "pending bits" del microcontrolador para que la interrupción pueda volver a dispararse en el futuro. Uno puede pensar que con esto ya sería, de por sí, suficiente pero lo cierto es que no es así, ya que al tratarse de entradas desde el exterior, son propensas a experimentar rebotes y ruido, por lo que se hace necesario hacer "limpieza" de esa señal mediante una sencilla máquina de estados. Es la función miembro "tick" (invocada, como su homónima de SN76489, periódicamente desde el SYSTICK del microcontrolador) la encargada de ejecutar la máquina de estados que procesa los valores de esta variable "key".



Como la interrupción se dispara sólo ante flancos de bajada, lo único que hace la máquina de estados es simplemente esperar un tiempo prudencial (200 ejecuciones de ticks) antes de volver al estado de espera a que se detecte una nueva pulsación. De esta forma se eliminan las pulsaciones espúreas que saldrían su hubiese rebote mecánico.

La función miembro "buttonPressed" de la clase "ButtonListener" (que hereda de "KeyboardListener") es invocada cada vez que se detecta la pulsación de uno de los botones y el parámetro "key" indica qué botón se ha pulsado. Es aquí donde se realizan las llamadas a la API del objeto de clase "SN76489" para encolar los comandos que generan el sonido "láser" o encolar los comandos que generan el sonido de "metralleta", en función de la tecla pulsada.

void systick() __attribute__ ((section(".systick")));


void systick() {
    sn76489.tick();
    Keyboard::tick();
}


class ButtonListener : public KeyboardListener {
    public:
        virtual void buttonPressed(int8_t key);
};


void ButtonListener::buttonPressed(int8_t key) {
    if (key == 1) {   // láser
        sn76489.setToneGeneratorAttenuation(0, 0);   // full volume
        sn76489.setToneGeneratorFrequency(0, 477, 100, 5, 10);
        sn76489.setToneGeneratorAttenuation(0, 0x0F);   // min volume
    }
    else if (key == 2) {   // metralleta
        sn76489.setNoiseGeneratorFrequency(SN76489::NoiseGeneratorFrequency::N_512, SN76489::NoiseGeneratorFeedback::WHITE);
        for (int i = 0; i < 17; i++) {
            sn76489.setNoiseGeneratorAttenuation(0, 20);
            sn76489.setNoiseGeneratorAttenuation(0xFF, 30);
        }
    }
}

Como se puede apreciar, la función global "systick", que es invocada de forma periódica por el timer SYSTICK del microcontrolador, es la encargada a su vez de invocar las funciones miembro "tick" de "SN76489" y "Keyboard".

El hecho de que todo el software esté basado en interrupciones permite generar un código más elegante y más eficiente desde un punto de vista energético: la función main sólo tiene que inicializar los objetos y variables y dormirse a la espera de que se produzcan interrupciones (ya sea por GPIO como de SYSTICK):

int main() {
    // keyboard
    Keyboard::init(&buttonListener);
    // enable systick timer
    SYST_RVR = 0x0001FFFF;
    SYST_CVR = 0;
    SYST_CSR = 7;
    // sn76489
    sn76489GPIOInterface.init();
    sn76489.init(&sn76489GPIOInterface);
    sn76489.setToneGeneratorAttenuation(0, 0xFF); // min volume for tone generator 0
    sn76489.setToneGeneratorAttenuation(1, 0x0F); // min volume for tone generator 1
    sn76489.setToneGeneratorAttenuation(2, 0x0F); // min volume for tone generator 2
    sn76489.setNoiseGeneratorAttenuation(0x0F);   // min volume for noise generator
    while (true) {
        // WFI (wait for interrupt) instruction, enters low power mode
        asm volatile ("wfi");
    }
}

Nótese el bucle infinito con la instrucción que duerme la CPU "wfi" (Wait For Interrupt).

Características de C++ aprovechadas

- Plantillas estáticas en lugar de memoria dinámica: En sistemas embebidos hay que evitar el uso de memoria dinámica y es por ello que se ha creado la plantilla "StaticQueue" que define una cola circular estática cuyos parámetros de plantilla son el tipo base y la cantidad de elementos: Esta cola estática es la utilizada para almacenar los pares (comando, ticksRetardo) que utiliza la clase SN76489.

- Enumeradores fuertemente tipados ("enum class"): Los estados en las máquinas de estado no están definidos como constantes enteras sino como tipos "enum class" que es un tipo de enumerado fuertemente tipado introducido en C++11. El uso de este tipo de datos impide, por ejemplo, que se le asigne un entero aunque su tipo base sea un entero. Además, el código generado es igual de eficiente que si se utilizasen constantes enteras y se gana mucho en claridad en el código.

A continuación puede verse un vídeo del montaje en acción (con sonido):


Todo el código fuente está disponible en la sección soft.

[ añadir comentario ] ( 2411 visualizaciones )   |  [ 0 trackbacks ]   |  enlace permanente  |   ( 2.9 / 1223 )
Implementación no bloqueante de un driver LCD 
A la hora de controlador un display LCD mediante el conocido adaptador I2C la gran mayoría de ejemplos disponibles por ahí implementan los estados de espera necesarios mediante retardos explícitos ("delays"). Dichas implementaciones están bien como prueba de concepto, pero no son deseables en entornos multitarea donde no podemos desperdiciar ciclos sólo esperando. En entornos reales se precisa de implementaciones no bloqueantes que hagan uso de timers e interrupciones.

El circuito

La interfaz de un display LCD estándar de caracteres es una interfaz paralelo de 8 bits, con 3 líneas de control adicionales (RS, EN y RW). Del bus paralelo de 8 bits pueden usarse sólo los 4 bits más significativos enviando de forma adecuada los comandos. Los circuitos de conversión a I2C que se venden habitualmente por AliExpress, Ebay y demás están basados en el conversor I2C/paralelo de 8 bits PCF8574 de Texas Instruments: del bus paralelo de dicho conversor se sacan los 4 bits más significativos para el bus paralelo del LCD y las tres señales de control para RS, EN y RW.



La configuración habitual en este tipo de módulos es esta:

PCF8574bit 7bit 6bit 5bit 4bit 3bit 2bit 1bit 0
LCDD7D6D5D4BLENRWRS

En la tabla se puede apreciar una cuarta señal de control etiquetada como BL (backlight) que controla el encendido del led de la luz trasera. Dicho led no forma parte de la circuitería estándar del display y ha sido introducido en versiones más recientes.

El problema

Los displays baratos de caracteres LCD que se encuentran en el mercado están basados en en un chip de Hitachi que no se caracteriza precisamente por su velocidad (probablemente debe ser uno de los chips más rentabilizados de toda la historia de Hitachi) y normalmente cada acceso debe estar seguido por una espera de uno a varios microsegundos, dependiendo del acceso realizado. A continuación puede verse la tabla de comandos de referencia del display, nótese la columna de la derecha ("Execution Time"):


(imagen extraida de https://learningmsp430.wordpress.com/2013/11/13/16x2-lcd-interfacing-in-8bit-mode/)

Cuando uno realiza una búsqueda en internet sobre códigos de ejemplo para control de displays LCD, la gran mayoría de los mismos (no digo todos porque considero que no los he visto todos, pero al menos todos los que yo he visto), implementan las esperas mediante retardos utilizando funciones "delay" o similares. Esta forma de implementación, aunque resulta simple, supone un desperdicio de ciclos e impide que el microcontrolador realice otras tareas de forma concurrente.

La solución no bloqueante

La solución ideal pasaría por una implementación basada en colas y en interrupciones. En este caso se ha implementado una máquina de estados que controla el flujo de datos I2C, el troceado de los bytes en dos nibbles y las esperas que hay que realizar entre un envío y el siguiente. Grosso modo, la solución sería la siguiente:

- Cada vez que se quiere escribir en el display, lo que se hace es escribir lo que se quiere mandar al display en una cola de datos, por lo que la función encargada de escribir regresa inmediatamente (no es bloqueante).

- El systick del microcontrolador cuando detecta que hay algún dato en la cola de datos inicia una máquina de estados que se encarga de trocear en byte en dos nibbles y enviarlos en tiempos diferentes, así hasta que la cola de datos quede vacía, en cuyo momento la máquina de estados pasa a modo "IDLE" y queda a la espera que de haya más datos en la cola.

- La capa I2C también está implementada como una cola de bytes de tal manera que si la capa LCD quiere escribir N bytes seguidos por I2C, los escribe de forma no bloqueante en la cola I2C (la función de escritura I2C también regresa inmediatamente) y se va vaciando a medida que la interrupción de callback de transmisión es llamada por el microcontrolador.

A continuación puede verse cómo ha quedado la máquina de estados del controlador LCD:



El código no queda tan sencillo a simple vista pero se trata, sin duda, de una implementación más eficiente.

#include "LCD.H"

using namespace avelino;
using namespace std;

void LCD::init(uint8_t address) {
    this->address = address;
    this->timerCounter = 5;
    this->status = LCD::Status::WAIT_AFTER_INIT;
    this->queue.push(LCD::QueueItem(0x33, LCD::IsCommand::YES));
    this->queue.push(LCD::QueueItem(0x32, LCD::IsCommand::YES));
    this->queue.push(LCD::QueueItem(0x28, LCD::IsCommand::YES));
    this->queue.push(LCD::QueueItem(0x08, LCD::IsCommand::YES));
    this->queue.push(LCD::QueueItem(0x01, LCD::IsCommand::YES));
    this->queue.push(LCD::QueueItem(0x06, LCD::IsCommand::YES));
    this->queue.push(LCD::QueueItem(0x0C, LCD::IsCommand::YES));
}

void LCD::tick() {
    Status localStatus = this->status;
    do {
        this->status = localStatus;
        if (localStatus == LCD::Status::WAIT_AFTER_INIT) {
            if (this->timerCounter > 0)
                this->timerCounter--;
            else
                localStatus = LCD::Status::IDLE;
        }
        else if (localStatus == LCD::Status::IDLE) {
            if (!this->queue.empty()) {
                I2CManager::deviceAddress = this->address << 1;
                localStatus = LCD::Status::SEND_FIRST_NIBBLE;
            }
        }
        else if (localStatus == LCD::Status::SEND_FIRST_NIBBLE) {
            uint8_t byte = this->queue.head().byte;
            LCD::IsCommand isCommand = this->queue.head().isCommand;
            I2CManager::txQueue.push((byte & 0xF0) | ((isCommand == LCD::IsCommand::YES) ? LCD::RS_0 : LCD::RS_1) | LCD::RW_0 | LCD::EN_1 | LCD::BL_1);
            I2CManager::txQueue.push((byte & 0xF0) | ((isCommand == LCD::IsCommand::YES) ? LCD::RS_0 : LCD::RS_1) | LCD::RW_0 | LCD::EN_0 | LCD::BL_1);
            I2CManager::send();
            localStatus = LCD::Status::WAIT_FIRST_NIBBLE_SENT;
        }
        else if (localStatus == LCD::Status::WAIT_FIRST_NIBBLE_SENT) {
            if (I2CManager::txDone) {
                this->timerCounter = 1;
                localStatus = LCD::Status::WAIT_TICK_AFTER_FIRST_NIBBLE_SENT;
            }
        }
        else if (localStatus == LCD::Status::WAIT_TICK_AFTER_FIRST_NIBBLE_SENT) {
            if (this->timerCounter > 0)
                this->timerCounter--;
            else
                localStatus = LCD::Status::SEND_SECOND_NIBBLE;
        }
        else if (localStatus == LCD::Status::SEND_SECOND_NIBBLE) {
            uint8_t byte = this->queue.head().byte << 4;
            LCD::IsCommand isCommand = this->queue.head().isCommand;
            this->queue.pop();
            I2CManager::txQueue.push((byte & 0xF0) | ((isCommand == LCD::IsCommand::YES) ? LCD::RS_0 : LCD::RS_1) | LCD::RW_0 | LCD::EN_1 | LCD::BL_1);
            I2CManager::txQueue.push((byte & 0xF0) | ((isCommand == LCD::IsCommand::YES) ? LCD::RS_0 : LCD::RS_1) | LCD::RW_0 | LCD::EN_0 | LCD::BL_1);
            I2CManager::send();
            localStatus = LCD::Status::WAIT_SECOND_NIBBLE_SENT;
        }
        else if (localStatus == LCD::Status::WAIT_SECOND_NIBBLE_SENT) {
            if (I2CManager::txDone) {
                this->timerCounter = 1;
                localStatus = LCD::Status::WAIT_TICK_AFTER_SECOND_NIBBLE_SENT;
            }
        }
        else if (localStatus == LCD::Status::WAIT_TICK_AFTER_SECOND_NIBBLE_SENT) {
            if (this->timerCounter > 0)
                this->timerCounter--;
            else
                localStatus = LCD::Status::IDLE;
        }
    } while (localStatus != this->status);
}


void LCD::write(const char *s, int16_t size, LCD::IsCommand isCommand) {
    while ((*s != 0) && ((size < 0) || (size > 0))) {
        this->queue.push(QueueItem(*s, isCommand));
        s++;
        if (size > 0)
            size--;
    }
}

La función miembro "tick" es invocada desde la interrupción systick del microcontrolador en "main.cc":

LCD lcd;

void systick() __attribute__ ((section(".systick")));

void systick() {
    lcd.tick();
}

Nótese que las colas (tanto la cola I2C como la cola LCD) están implementadas usando colas circulares estáticas a través de una plantilla ("StaticQueue.H").

#ifndef  __STATICQUEUE_H__
#define  __STATICQUEUE_H__

#include <stdint.h>

extern "C++" {
    namespace avelino {
        using namespace std;

        template <typename T, int32_t N>
        class StaticQueue {
            public:
                T data[N];
                int32_t headIndex;
                int32_t tailIndex;
                void push(const T &v);
                const T &head() { return this->data[this->headIndex]; };
                void pop();
                bool empty() { return (this->headIndex == this->tailIndex); };
                StaticQueue() : headIndex(0), tailIndex(0) { };
        };

        template <typename T, int32_t N>
        void StaticQueue<T, N>::push(const T &v) {
            this->data[this->tailIndex] = v;
            this->tailIndex++;
            if (this->tailIndex == N)
                this->tailIndex = 0;
        }

        template <typename T, int32_t N>
        void StaticQueue<T, N>::pop() {
            this->headIndex++;
            if (this->headIndex == N)
                this->headIndex = 0;
        }
    }
}

#endif  // __STATICQUEUE_H__

Se ha utilizado en varios sitios el "enum class", que permite trabajar con enumerados fuertemente tipados (introducido en el estándar C++11).

En la sección soft puede descargarse todo el código fuente.



[ añadir comentario ] ( 1522 visualizaciones )   |  [ 0 trackbacks ]   |  enlace permanente  |   ( 3 / 11080 )
Implementación de un dispositivo USB en STM32 desde cero 
El STM32F103 es un microcontrolador muy asequible que incluye interfaz USB 2.0. La mayoría de desarrollos USB realizados para esta serie de microcontroladores utiliza la librería STM32Cube, desarrollada por el propio fabricante, de libre uso y que abstrae de los entresijos del protocolo al programador. Abordar, sin embargo, el desarrollo de esta funcionalidad desde cero en este o en otros microcontroladores permite profundizar y mejorar en el conocimiento del propio protocolo USB.



Un repaso rápido del protocolo USB

Aunque aquí intentaré desgranar a grandes rasgos el protocolo, recomiendo siempre las dos grandes y mejores fuentes de información sobre el mismo:

USB made simple
USB in a nutshell

Es de lo mejorcito que hay al respecto por la red ya que el documento oficial es un poco infumable. A nivel eléctrico, se trata de un protocolo serie asíncrono que utiliza dos hilos de señal balanceada. El protocolo consiste en una serie de "endpoints" multiplexados en tiempo y enumerados. Hay tres tipos de endpoint:

Control: usado para transferencias de control del dispositivo. Identificación, configuración, etc.

Bulk: usado para transferencias masivas de datos con control de errores (menos ancho de banda).

Interrupt: usado para transferencias pequeñas de datos pero con tiempo mínimo de entrega garantizado.

Isochronous: usado para transferencias masivas de datos sin control de errores (máximo ancho de banda).

Cada endpoint tiene un número asociado y un tipo. El estándar USB reserva el endpoint 0 como un endpoint de control sobre el que el host (ordenador) envía los mensajes de configuración iniciales al dispositivo que acaba de conectarse.

La secuencia ya se describió en un post anterior en el que se abordó el mismo proyecto pero utilizando el microcontrolador ATmega32u4 de AVR pero la volvemos a indicar a continuación:

1. El host detecta que hay un dispositivo conectado (detecta una resistencia pull up en D+ o en D-)

2. El host inicia una secuencia de reset poniendo a nivel bajo las líneas D- y D+ durante al menos 2.5 us.

3. El host envía un paquete de SETUP para pedir el descriptor de dispositivo al dispositivo. Este descriptor indica el tipo de dispositivo, el código de fabricante, código de producto, etc. Esta primera petición se realiza siempre indicando en el campo longitud la longitud máxima y en la respuesta proveniente del dispositivo, el host es capaz de deducir el tamaño máximo de buffer con el que trabaja el dispositivo. Hay que tener en cuenta que en el caso de dospisitivos low-speed los paquetes son siempre de 8 bytes de datos mientras que en dispositivos full-speed los paquetes pueden ser de 8, 16, 32 o 64 bytes.

4. Tras esta primera petición de descripción de dispositivo el host suele iniciar de nuevo una condición de reset y, a continuación vuelve a pedir el descriptor de dispositivo pero con el tamaño ajustado al tamaño indicado por el dispositivo en la primera petición.

5. Cada dispositivo tiene asignada una dirección en el bus que, tras es reset, es siempre 0. En este instante lo habitual es que el host envíe un paquete de SETUP de tipo SET_ADDRESS para indicarle al dispositivo que a partir de ahora el host se va a comunicar con el dispositivo usando una dirección concreta diferente a 0 y que el dispositivo debe recordar para posteriores paquetes que se transmitan.

6. Ya con la nueva dirección de bus configurada, el host envía otro paquete de SETUP para solicitar el descriptor de configuración. Este descriptor es más grande que el anterior e incluye información sobre la clase de dipositivo y los endpoints que utiliza. El descriptor de dispositivo indica en un campo cuántas configuraciones posee el dispositivo, que suele ser siempre 1, por lo que el host normalmente sólo pide un descriptor de configuración.

7. El host (normalmente el driver instalado en el host) decide qué configuración quiere activar (que suele ser la única) en el dispositivo enviando un paquete de SETUP de tipo SET_CONFIGURATION. A partir de este instante el dispositivo queda conectado y con sus endpoints preparados para recibir y enviar datos propios de la funcionalidad del dispositivo.

La secuencia puede variar ligeramente en función del sistema operativo del host. Hay que recordar que en el protocolo USB el host es siempre el que envía "tokens" al dispositivo, incluso para traer datos desde el dispositivo. Cuando el host quiere enviar datos a un dispositivo hace transferencias de tipo SETUP y OUT mientras que cuando quiere recibir datos del dispositivo, el host hace transferencias de tipo IN pero siempre es el host el que pregunta. Un dispositivo no puede enviar datos a un host hasta que el host mande un token de tipo IN al dispositivo.

Implementación en el STM32F103

La serie STM32F103 es la serie más sencilla y baratita de toda la familia STM32 con soporte USB 2.0 full-speed (en el momento que escribo esto se puede conseguir una placa mínima de desarrollo con STM32F103 por menos de 3 ¤ en AliExpress). La documentación de referencia para programar el módulo USB es algo oscura y no está pensada para que te sumerjas mucho en ella, sino para que utilices la librería STM32Cube que, aunque es open source y permite un uso sin restricciones, su uso le quita toda la gracia al concepto de programar un microcontrolador desde cero :-).

A continuación puede verse la implementación de un dispositivo USB consistente en dos endpoints sencillos de tipo bulk (uno de entrada y otro de salida). La razón para implementar un dispositivo así es el hecho de que desde Linux el driver "usbserial" permite intercambiar datos con cualquier dispositivo USB que cumpla que tenga un endpoint bulk de salida y otro de entrada sin importar su clase, ni el código de fabricante ni de producto. Es un driver ideal para depurar dispositivos USB y que instancia un "/dev/ttyUSB0". Escribiendo en "/dev/ttyUSB0" se envían bytes a través del endpoint de salida mediante paquetes OUT mientras que leyendo de "/dev/ttyUSB0" se reciben bytes desde el dispositivo a través del endpoint de entrada mediante paquetes IN que envía el host.

La función usbDeviceInit se encarga de inicializar los tranceptores y de activar la interrupción de "USB Reset":

void usbDeviceInit() {
    // enable USB clock
    RCC_APB1ENR |= (((uint32_t) 1) << 23);
    // enable USB interrupts
    NVIC_ENABLE_IRQ(20);
    NVIC_SET_PRIORITY(20, 0);   // highest priority
    // enable analog transceivers
    USB_CNTR &= ~(((uint16_t) 1) << 1);
    for (uint32_t i = 0; i < 20000; i++)
        ;
    USB_CNTR &= ~(((uint16_t) 1) << 0);
    USB_ISTR = 0;
    // enable and wait for USB RESET interrupt
    USB_CNTR |= (((uint16_t) 1) << 10);
}

A continuación definimos los diferentes descriptores del dispositivo (descriptor de dispositivo, descriptor de configuración y descriptor de cadena 0 que indica los idiomas disponibles en el dispositivo):

const UsbDeviceDescriptor MyUsbDeviceDescriptor = {
    0x12,      // descriptor size
    0x01,      // descriptor type (device)
    0x0110,    // USB protocol version 1.10
    0x00,
    0x00,
    0x00,
    0x08,      // max packet size for control endpoint 0 = 8 bytes
    0xF055,    // vendor id
    0x0001,    // product id
    0x0100,
    0x00,
    0x00,
    0x00,
    0x01       // num configurations
};

...

const UsbConfigurationDescriptor MyUsbConfigurationDescriptor = {
    0x09,    // descriptor size
    0x02,    // descriptor type (configuration)
    0x0020,  // configuration (9) + interface (9) + endpoint (7) + endpoint (7) = 32
    0x01,    // num interfaces = 1
    0x01,    // this configuration number = 1
    0x00,
    0x80,    // bus powered (not self powered)
    0x20,    // 32 * 2 = 64 mA
    {           // interface descriptor
        0x09,   // descriptor size
        0x04,   // descriptor type (interface)
        0x00,   // interface number (zero based)
        0x00,
        0x02,   // num endpoints = 2
        0xFF,   // class = vendor defined
        0xFF,   // subclass = vendor defined
        0x00,
        0x00
    },
    {             // in endpoint descriptor
        0x07,     // descriptor size
        0x05,     // descriptor type (endpoint)
        0x81,     // in endpoint 1
        0x02,     // bulk endpoint
        0x0008,   // max packet size = 8 bytes
        0x0A      // 10 ms for polling interval
    },
    {             // out endpoint descriptor
        0x07,     // descriptor size
        0x05,     // descriptor type (endpoint)
        0x02,     // out endpoint 2
        0x02,     // bulk endpoint
        0x0008,   // max packet size = 8 bytes
        0x0A      // 10 ms for polling interval
    }
};

...

const UsbString0Descriptor MyUsbString0Descriptor = {
    0x04,            // descriptor size
    0x03,            // descriptor type (string descriptor)
    0x0409           // 'en_US' language id
};


const uint16_t MyUsbStatus = 0x0000;

Los buffers de recepción y transmisión USB en el caso de STM32 deben ser direccionados y accedidos de forma particular. Desde el punto de vista del subsistema USB, la anchura del bus de datos es de 16 bits, en lugar de 32 bits aunque los datos están alineados a 32 bits. Gráficamente se ve mejor:

Offset desde el punto de     Offset desde el punto de
vista del controlador USB vista del programa (CPU)
0 0
1 1
2 4
3 5
4 8
5 9
6 12


Como se puede ver, por cada palabra de 32 bits direccionada desde la CPU sólo se puede acceder a los 16 bits menos significativos. Para leer los 2 primeros bytes de la memoria USB desde la CPU hay que acceder a los 4 primeros bytes de dicha memoria (como si fuese un entero de 32 bits) y quedarnos con los 16 bits menos significativos. Los siguientes 2 bytes no están en los 16 bits más significativos de la primera palabra de 32 bits, sino en los 16 bits menos significativos de la siguiente palabra de 32 bits y así sucesivamente. Teniendo en cuenta esta particularidad se implementan dos funciones de acceso a esta memoria USB para copiar hacia y desde ella:

void usbCopyFromPacketSRAM(volatile uint32_t *packetSRAMSource, volatile uint16_t *destination, uint16_t bytes) {
    volatile uint32_t *p = (volatile uint32_t *) packetSRAMSource;
    volatile uint16_t *q = destination;
    uint16_t n = bytes >> 1;
    if (bytes & 1)
        n++;
    for (uint16_t i = 0; i < n; i++, p++, q++)
        *q = (uint16_t) (*p & 0x0000FFFF);
}


void usbCopyToPacketSRAM(volatile uint16_t *source, volatile uint32_t *packetSRAMDestination, uint16_t bytes) {
    volatile uint32_t *p = (volatile uint32_t *) packetSRAMDestination;
    volatile uint16_t *q = source;
    uint16_t n = bytes >> 1;
    if (bytes & 1)
        n++;
    for (uint16_t i = 0; i < n; i++, p++, q++)
        *p = (uint32_t) *q;
}

A continuación definimos las rutinas de interrupción correspondientes. Primero escribimos la rutina usbDeviceISRReset, que se ejecuta en caso de que se genere una interrupción de "USB Reset" provocada por una condición de reset en el bus USB. Dicha condición de reset es iniciada por el host en cuanto detecta un nuevo dispositivo conectado a una de sus bocas USB (es el paso 2 de la secuencia descrita anteriormente):

void usbDeviceISR()  __attribute__ ((section(".usblp")));

...

void usbDeviceISRReset() {
    // prepare buffer descriptor table for endpoint 0 (control)
    USB_BTABLE = 0;
    // endpoint 0 (bidireccional)
    USB_ADDR0_TX = 24;
    USB_COUNT0_TX = 0;   // 8
    USB_ADDR0_RX = 32;
    USB_COUNT0_RX = (((uint16_t) 4) << 10);   // 2 * 4 = 8 bytes
    // endpoint 1 (in, tx)
    USB_ADDR1_TX = 40;
    USB_COUNT1_TX = 0;   // 8
    USB_ADDR1_RX = 40;
    USB_COUNT1_RX = (((uint16_t) 4) << 10);   // 2 * 4 = 8 bytes
    // endpoint 2 (out, rx)
    USB_ADDR2_TX = 48;
    USB_COUNT2_TX = 0;   // 8
    USB_ADDR2_RX = 48;
    USB_COUNT2_RX = (((uint16_t) 4) << 10);   // 2 * 4 = 8 bytes
    // device address = 0
    USB_DADDR = ((uint16_t) 1) << 7;   // enable usb function
    usbNextAddress = 0;
    // prepare endpoint 0 for rx setup packets
    USB_EP0R = (((uint16_t) 1) << 9);
    usbDeviceEPRSetRxStat(USB_EP0R, STAT_NAK);
    usbDeviceEPRSetTxStat(USB_EP0R, STAT_NAK);
    usbDeviceEPRSetDtogRx(USB_EP0R, 0);
    usbDeviceEPRSetDtogTx(USB_EP0R, 0);
    // prepare endpoint 1 and endpoint 2
    USB_EP1R = 1;
    usbDeviceEPRSetRxStat(USB_EP1R, STAT_NAK);
    usbDeviceEPRSetTxStat(USB_EP1R, STAT_VAL);
    usbDeviceEPRSetDtogRx(USB_EP1R, 0);
    usbDeviceEPRSetDtogTx(USB_EP1R, 0);
    USB_EP2R = 2;
    usbDeviceEPRSetRxStat(USB_EP2R, STAT_VAL);
    usbDeviceEPRSetTxStat(USB_EP2R, STAT_NAK);
    usbDeviceEPRSetDtogRx(USB_EP2R, 0);
    usbDeviceEPRSetDtogTx(USB_EP2R, 0);
    // enable complete transfer interrupt
    USB_CNTR |= (((uint16_t) 1) << 15);
}

A continuación se define la rutina principal que atiende las interrupciones USB, usbDeviceISR. Esta función llama, en caso de darse una condición de reset a la función usbDeviceISRReset definida arriba:

void usbDeviceISR() {
    uint16_t istr = USB_ISTR;
    if (istr & (((uint16_t) 1) << 10)) {
        usbDeviceISRReset();
        USB_ISTR = 0;
    }
    else if (istr & (((uint16_t) 1) << 15)) {   // correct transfer interrupt
        USB_ISTR = 0;
        uint16_t epNum = istr & 0x000F;
        if (epNum == 0) {
            if (istr & 0x0010) {
                // out/setup packet
                if (USB_EP0R & (((uint16_t) 1) << 11)) {
                    // setup packet
                    usbCopyFromPacketSRAM((uint32_t *) USB_EP0RXBUF, usbRxBuffer, USB_COUNT0_RX & 0x03FF);
                    UsbSetupPacket *setupPacket = (UsbSetupPacket *) usbRxBuffer;
                    if ((setupPacket->bmRequestType == 0x80) && (setupPacket->bRequest == 0x06)) {
                        bool stall = false;
                        if ((setupPacket->wValue >> 8) == 1) {
                            ep0DataPtr = (uint8_t *) &MyUsbDeviceDescriptor;           // get_descriptor (device)
                            ep0DataCount = (sizeof(MyUsbDeviceDescriptor) < setupPacket->wLength) ? sizeof(MyUsbDeviceDescriptor) : setupPacket->wLength;
                        }
                        else if ((setupPacket->wValue >> 8) == 2) {
                            ep0DataPtr = (uint8_t *) &MyUsbConfigurationDescriptor;    // get_descriptor (configuration)
                            ep0DataCount = (sizeof(MyUsbConfigurationDescriptor) < setupPacket->wLength) ? sizeof(MyUsbConfigurationDescriptor) : setupPacket->wLength;
                        }
                        else if ((setupPacket->wValue >> 8) == 3) {
                            ep0DataPtr = (uint8_t *) &MyUsbString0Descriptor;    // get_descriptor (string)
                            ep0DataCount = (sizeof(MyUsbString0Descriptor) < setupPacket->wLength) ? sizeof(MyUsbString0Descriptor) : setupPacket->wLength;
                        }
                        else {
                            usart1SendString("\tg?");
                            usart1SendHexValue(setupPacket->wValue >> 8);
                            usart1SendString("\r\n");
                            ep0DataCount = 0;
                            stall = true;
                        }
                        if (stall)
                            usbDeviceEPRSetTxStat(USB_EP0R, STAT_STA);
                        else {
                            uint16_t size = (ep0DataCount > 8) ? 8 : ep0DataCount;     // copy bytes to packet SRAM
                            usbCopyToPacketSRAM((uint16_t *) ep0DataPtr, (uint32_t *) USB_EP0TXBUF, size);
                            USB_COUNT0_TX = size;
                            ep0DataCount -= size;
                            ep0DataPtr += size;
                            usbDeviceEPRSetTxStat(USB_EP0R, STAT_VAL);
                        }
                        usbDeviceEPRSetRxStat(USB_EP0R, STAT_STA);
                    }
                    else if ((setupPacket->bmRequestType == 0x00) && (setupPacket->bRequest == 0x05)) {
                        usbNextAddress = setupPacket->wValue;
                        USB_COUNT0_TX = 0;
                        usbDeviceEPRSetTxStat(USB_EP0R, STAT_VAL);
                        usbDeviceEPRSetRxStat(USB_EP0R, STAT_STA);
                    }
                    else if ((setupPacket->bmRequestType == 0x00) && (setupPacket->bRequest == 0x09)) {
                        USB_COUNT0_TX = 0;
                        usbDeviceEPRSetTxStat(USB_EP0R, STAT_VAL);
                        usbDeviceEPRSetRxStat(USB_EP0R, STAT_STA);
                    }
                    else if ((setupPacket->bmRequestType == 0x80) && (setupPacket->bRequest == 0x00)) {
                        usbCopyToPacketSRAM((uint16_t *) &MyUsbStatus, (uint32_t *) USB_EP0TXBUF, 2);
                        USB_COUNT0_TX = 2;
                        usbDeviceEPRSetTxStat(USB_EP0R, STAT_VAL);
                        usbDeviceEPRSetRxStat(USB_EP0R, STAT_STA);
                    }
                    else {
                        usart1SendString("\tother setup packet\r\n");
                        usart1SendString("x: ");
                        usart1SendHexValue(setupPacket->bmRequestType);
                        usart1SendString(" ");
                        usart1SendHexValue(setupPacket->bRequest);
                        usart1SendString("\r\n");
                    }
                }
                else {
                    // out packet
                    usbCopyFromPacketSRAM((uint32_t *) USB_EP0RXBUF, usbRxBuffer, USB_COUNT0_RX & 0x03FF);
                    // TODO process data
                }
            }
            else {
                // in packet
                if (usbNextAddress != 0) {
                    USB_DADDR = (((uint16_t) 1) << 7) | (usbNextAddress & 0x007F);
                    usbNextAddress = 0;
                }
                else {
                    uint16_t size = (ep0DataCount > 8) ? 8 : ep0DataCount;
                    usbCopyToPacketSRAM((uint16_t *) ep0DataPtr, (uint32_t *) USB_EP0TXBUF, size);
                    USB_COUNT0_TX = size;
                    ep0DataCount -= size;
                    ep0DataPtr += size;
                    usbDeviceEPRSetTxStat(USB_EP0R, STAT_VAL);
                    usbDeviceEPRSetRxStat(USB_EP0R, STAT_VAL);
                }
            }
            USB_EP0R &= 0x0F0F;    // ctr_rx = 0, ctr_tx = 0
        }
        else if (epNum == 1) {
            if (istr & 0x0010) {
                // out packet
            }
            else {
                // in packet 
            }
            usbDeviceEPRSetTxStat(USB_EP1R, STAT_VAL);
            usbDeviceEPRSetRxStat(USB_EP1R, STAT_NAK);
            USB_EP1R &= 0x0F0F;    // ctr_rx = 0, ctr_tx = 0
        }
        else if (epNum == 2) {
            if (istr & 0x0010) {
                // out packet
                usbCopyFromPacketSRAM((uint32_t *) USB_EP2RXBUF, usbRxBuffer, USB_COUNT2_RX & 0x03FF);
                usart1SendString("rx '");
                usart1SendBytes((uint8_t *) usbRxBuffer, USB_COUNT2_RX & 0x03FF);
                usart1SendString("'\r\n");
            }
            else {
                // in packet 
            }
            usbDeviceEPRSetTxStat(USB_EP2R, STAT_NAK);
            usbDeviceEPRSetRxStat(USB_EP2R, STAT_VAL);
            USB_EP2R &= 0x0F0F;    // ctr_rx = 0, ctr_tx = 0
        }
        //USB_ISTR = 0;
    }
}

Lo primero que hace la rutina es identificar el endpoint por el que se ha producido la transacción. En caso de que la transacción se haya producido a través del endpoint 0 se comprueba si es un token SETUP u OUT y, si es un token SETUP, se parsea y se mira a ver si el host está mandando algo (configuraciones) o si lo está pidiendo (descriptores). Si el host está pidiendo algo, hay que rellenar el buffer de transmisión con los datos que necesita, pues la siguiente transacción que realizará el host a través del endpoint 0 será utilizando uno o varios tokens IN y para entonces los datos tienen que estar ya preparados en dicho búffer.

Recordemos algunos elementos básicos sobre cómo son las transferencias USB a través del endpoint 0:

Control: Es un endpoint que debe ser siempre configurado como de tipo "Control" y es bidireccional. Un dispositivo puede definir endpoints de control adicionales pero el endpoint 0 de control siempre debe estar disponible.

Transacciones SETUP: Los endpoints configurados como de control permiten transferir un tipo especial de token denominado SETUP. Este token puede ser de entrada o de salida (siempre desde el punto de vista del host).

Transacciones SETUP de salida: El host manda un token SETUP, a continuación envía cero o más tokens OUT con datos anexos y por último manda un token IN para que el dispositivo mande 0 bytes a modo de ACK.

Transacciones SETUP de entrada: El host manda un token SETUP, a continuación envía cero o más tokens IN para recibir datos del dispositivo y al final el host manda un token OUT con 0 bytes anexos a modo de ACK hacia el dispositivo.

Si la transacción se ha producido en el endpoint 1 o 2, se asume que es una transacción simple de tipo bulk:

Endpoint 1: Es un endpoint configurado como de tipo IN y en esta implementación no hace nada, pues el STM32 no manda ningún dato cuando es leido a través del USB.
Endpoint 2: Es un endpoint configurado como de tipo OUT. Por lo tanto, el STM32 recibe por aquí los datos que son enviados desde el host y los manda formateados a través de la USART.

Nos limitamos a mandar por la USART1 todo lo que entra a través del endpoint de tipo "bulk out", mientras que las lecturas desde el host al endpoint de tipo "bulk in" devuelven siempre 0 bytes.

Para cargar el módulo "usbserial" en el kernel simplemente hay que hacer:
modprobe usbserial vendor=0xf055 product=0x0001

Esto nos permite comunicarnos con el dispositivo desde la misma shell:
echo "Hola, caracola" > /dev/ttyUSB1

Partiendo de este código se pueden implementar multitud de dispositivos USB en este microcontrolador (Mass storage, HID, DFU, etc.). Todo el código fuente puede descargarse desde la sección soft.

Quiero agradecer a Jian Jiao (mculabs.net) la ayuda prestada a la hora de comprender algunos entresijos en la programación del módulo USB del microcontrolador STM32.

[ añadir comentario ] ( 2422 visualizaciones )   |  [ 0 trackbacks ]   |  enlace permanente  |   ( 3 / 4630 )

| 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |