printer-driver/PROGRESO.md

Progreso

Estado actual

• Fase 2: buffer dinámico. La Fase 1 está cerrada en Fedora y en Windows (2026-10-05).
• 2026-10-06 (Fedora): antes del 2.3b, repaso de punteros. Le costaba qué viaja a una función, * frente a ->, la pila frente al montón y restar en hex. Se creó docs/02-pointers-visual.html (interactivo). Pendiente de que conteste: A) por qué &buffer_a - &buffer da 4; B) cuántos bytes copia su append actual con data_b.
• Paso actual: 2.3b. hello.c ya usa bien goto cleanup (punteros a NULL uno por línea, result, un solo return), sin avisos con gcc ni clang, y Valgrind limpio. Falta escpos_buffer_append: el parámetro con la cantidad, const, reservar len + cantidad, memcpy y el comentario de la cabecera. Ahora copia 1 byte (sizeof *byte).
• Máquinas: sobremesa con Windows (MSYS2 UCRT64) y portátil con Fedora 42 (gcc 15.2, clang 20, make 4.4, gdb 17, valgrind 3.26). Ver "Pendiente por máquina".

Pendiente por máquina

Windows (sobremesa)

• Hay gcc, gdb y make en C:\msys64. Faltan clang y xxd (opcionales: pacman -S mingw-w64-ucrt-x86_64-clang vim; mientras, hexdump -C).
• Fase 1 cerrada: make, make run y Nothing to be done funcionan sin EXE gracias a la emulación de .exe de MSYS2 (ver docs/06-make.md). El ifeq ($(OS),Windows_NT) se pospone a la Fase 4, cuando haga falta -lws2_32.
• Probar en VS Code: terminal nueva (debe abrir UCRT64), Ctrl+Shift+B y F5.
• El 2.3b se puede avanzar aquí; la comprobación de memoria queda para Fedora.

Fedora (portátil)

• Validar con valgrind el 2.3b cuando esté hecho (y con ASan/UBSan antes de cerrar la Fase 2).
• Tras el git pull del 2026-10-05, comprobar que make y F5 siguen igual (se ha tocado .vscode/ y se han añadido .gitattributes y .gitignore). Los binarios de Go ya no se versionan: recompilarlos con go build si hacen falta.

Hecho

• include/escpos.h + src/escpos.c con escpos_version(), y hello.c que la usa. Compila y enlaza a mano en Windows y en Fedora.
• samples/hello_world.bin: ESC @, texto, LF, ESC d 5, GS V 0.
• Emulador ESC/POS en Go (emulator/) para probar sin gastar papel.
• Makefile con regla patrón, clean y .PHONY. Compila desde un clon limpio y sin avisos con gcc y con clang.
• 2.1: escpos_buffer_new / escpos_buffer_free con tipo opaco. Valgrind limpio, y fuga provocada a propósito para leer el informe.
• 2.2: escpos_buffer_append_byte con realloc: 64 bytes al principio, luego el doble. Comprobado con 100 bytes (crece de 64 a 128). Valgrind limpio. Sin el free, Valgrind da 24 definitely + 128 indirectly.
• 2.3a: crecimiento extraído a static int buffer_reserve(buffer, min_cap): arranca en 64 o en cap y dobla hasta que cabe; un único realloc.

Conceptos de C aprendidos

• Etapas de compilación, unidades de traducción, cabeceras, include guards, static para encapsular, nm y errores del enlazador.
• Cadenas terminadas en '\0', const char *, 'A' frente a "A".
• Memoria virtual de un proceso, modo usuario y modo núcleo. VmSize frente a VmRSS, overcommit y OOM killer.
• Make: reglas, dependencias por fechas, variables, regla patrón con $@ $< $^, .PHONY.
• Pila y montón, malloc/free/realloc, NULL, propiedad de punteros, tipo opaco, typedef, ->, uint8_t/size_t, qué tipo usar.
• Liberar en caminos de error sin defer: patrón goto cleanup.
• Depuración: segfault (139), free(): invalid pointer (134), gdb básico, y leer errores e informes de fugas en Valgrind.

Forma de trabajar

• Desde el 2026-10-02: sin vibecoding. Enunciado y pruebas, predicción antes de compilar, y pistas por niveles solo si las pide. Ante un error, primero su diagnóstico.

Decisiones de diseño

• Prefijo escpos_ para toda la API pública.
• escpos_buffer es un tipo opaco: declarado en escpos.h y definido en src/buffer.c. Campos uint8_t *data, size_t len y size_t cap.
• Crecimiento del buffer: 64 bytes al principio y luego el doble.
• Por ahora, las funciones que pueden fallar devuelven int: 0 si va bien y -1 si no hay memoria. Pendiente de cambiar a códigos de error propios.
• Estilo: nombres en snake_case y llave de apertura en línea aparte (estilo Allman) en funciones, structs y bloques.
• Lo generado va en build/, que se crea en las recetas con mkdir -p y no se versiona. Tampoco se versionan ejecutables ni volcados (vgcore.*).
• Dos máquinas transparentes: .gitattributes fuerza LF en todo y marca *.bin como binario (git no toca los bytes ESC/POS). En Windows, VS Code usa la shell UCRT64 de MSYS2 para la terminal y las tareas, así que make, mkdir -p y rm -rf funcionan igual que en Fedora.

Pendiente / puntos débiles

• Fase 1: probar el Makefile en Windows (MSYS2), con el sufijo .exe.
• Make: le costó entender que va hacia atrás desde el objetivo y que una regla patrón es una plantilla. Repasar con docs/06-make.md.
• Punteros: le cuesta saber cuándo hace falta * y cuándo no, y distinguir la dirección del bloque (data) de una casilla (data[i]). Le funciona la analogía de papel y casa. Reforzar con ejemplos de su propio código.
• Tipos: usó uint8_t para un código de retorno. Repasar la tabla "Qué tipo usar" de docs/08-structs.md.
• Valorar añadir -Wconversion a CFLAGS: detecta conversiones con pérdida que gcc no avisa por defecto.
• Bucles: en buffer_reserve calculaba cada vuelta a partir de un valor que no cambiaba (buffer->cap) o que empezaba en 0, y eso daba bucles infinitos. Lo resolvió siguiendo los valores vuelta a vuelta. Seguir pidiéndole trazas a mano.
• Declaraciones múltiples: escribió escpos_buffer *a, *b, *c = NULL; creyendo que las tres valían NULL (solo la última). Lo detectó clang con -Wsometimes-uninitialized. Ahora declara una variable por línea.
• Variables locales sin inicializar: creía que valían NULL como en Go.
• sizeof: el 2026-10-06 dijo que sizeof buffer (un puntero) da 1 byte; da 8 en 64 bits. Y lo veía como algo que "va a la casa" mientras se ejecuta, cuando se calcula al compilar a partir del tipo.
• Hexadecimal: no sabe restar direcciones (0xd210 - 0xd1f0). Se le enseñó a hacerlo con p en gdb y con las potencias de 16. Pide ayuda con "ni idea": darle herramientas para medir, no la cuenta hecha.
• Se salta la predicción: el 2026-10-06 miró gdb sin predecir tres veces seguidas. Insistir en que la escriba antes de ejecutar.
• Impresoras físicas: sin registrar marca y modelo.
• Confunde puntero colgante ("se pierde") con fuga. Tampoco tenía claro por qué el slice viejo es seguro en Go tras append (el GC no libera el array viejo, no es por la copia). Repasar con la tabla de docs/07-dynamic-memory.md.

Otros

• goescpos/: equivalente en Go idiomático (bytes.Buffer) de lo hecho hasta ahora, para comparar.