Introducción

1.Resumen

1.1. ¿Por qué este documento?

1.2. ¿Qué es un "Controlador de Dispositivo Blindado?

1. Estabilidad y fiabilidad: El uso de prácticas de codificación bien conocidas en el controlador para detectar y comunicar condiciones de error (Nota del traductor: "errores errantes“) en el software y el hardware, para proteger el controlador, el kernel y otros componentes del software, de corrupción, para proporcionar pruebas de inducción de errores ("to provide for fault injection testing“), y para hacer el código limpio y fácil de leer para el mantenimiento de la calidad.
2. Instrumentación: Interfaces de comunicación para estadísticas, interfaces para pruebas de diagnóstico, y trazas de error conformes a POSIX para monitorizar y gestionar por sistemas de componentes de control de alto nivel.
3. Alta disponibilidad: Capacidades especiales, tales como redundancia de dispositivos, cambio en caliente, y recuperacion ante fallos, para incrementear la disponibilidad.

1.3. "Controladores de Dispositivo Robustos"

• Siguen el estilo de codificaciones de Linux, haciendolo fácil de mantener y consistente con el estilo de codificación del kernel.
  Referencia: <linux-kernel-source>/Documentation/CodingStyle
  Referencia: "http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/"
  
  Nota : no habrá más discusiones al respecto sobre este tema ya que las citadas referencias lo cubren todo.
• Eficiencia en la gestión y manejo de errores, comunicación y recuperación ante errores . (niveles printk , valores de retorno numéricos, etc.). Así como no panic() tontos. Los controladores de dispositivo no pueden dar 'panic' por pequeñas razones. Esto va de la mano con la correcta gestión de errores y la recuperación de los mismos.
• Cumplir con las últimas interfaces y API's del kernel Linux. Esto significa que es mantenido periódicamente y en diferentes plataformas hardware, estar al tanto de funciones ya viejas, macros e interfaces.
• Usar el nuevo modelo de controladores de dispositivo , kobjects y sysfs. Borrado de cli-sti.
• Manejo de recursos adecuado (memoria, semáforos, interrupciones, etc).
• Usar las funciones "C“ de E/S que el kernel proporciona en lugar del código en ensamblador (inb, outb, etc.)
• No tener código o variables no usadas. Si existe código que no se usa, pero que en el futuro se usará, entonces debe ser marcado como tal, de modo que no se compile y de esta forma no ocupe espacio.
• Optimizar el espacio una vez compilado (por ejemplo, usar funciones inline cuando sea apropiado).

2.0. ¿Dónde empezar?

3.0. Vale estoy preparado ...

3.1. Manejo eficiente, comunicación y recuperación de errores

• printk()
  
  De acuerdo con el TODO de la lista kernel-janitor, deberías siempre comprobar que las llamadas a printk() incluyen las constantes KERN_* apropiadas.
  
  
  int res;
...
if (res = register_chrdev(MAJOR, MOD_NAME, &fops)) {
        printk(KERN_ERR "Fallo al registrar el dispositovp <%s> con major <%d>\n",
                              MOD_NAME, MAJOR);
        return res;
}
...

  
  KERN_* están definidas en en linux/include/linux/kernel.h de la siguiente forma:
  
  
  #define KERN_EMERG  "<0>"  /* el sistema no es usable          */
#define KERN_ALERT  "<1>"  /* se debe hacer algo inmediatamente*/
#define KERN_CRIT  "<2>"  /* condiciones criticas            */
#define KERN_ERR    "<3>"  /* situacion de error              */
#define KERN_WARNING"<4>"  /* aviso                            */
#define KERN_NOTICE "<5>"  /* normal pero con condicion inmportante*/
#define KERN_INFO  "<6>"  /* informacion                      */
#define KERN_DEBUG  "<7>"  /* mesages de depuracion            */

  
  Nota: Usa printk sólo cuando sea necesario. Se informativo y evita llenar la consola con mensajes de error cuando se encuentren condiciones erróneas (controla la cantidad, "flood control“).
• goto
  
  Las instruciones goto están limitadas en la comunidad Linux para las siguientes situaciones:
  
  - Se usa menos código repetido.
  - Debe ser tan entendible como otras soluciones.
  - Debe ser menos susceptible de error.
  - Debe ser mas fácil de cambiar y mantener para el próximo que tenga que tocar el código.
  - Mantiene el código de manejo de errores lejos para mayor eficiencia en el uso de las cachés, teniendo (normalmente) el código de más frecuente éxito "cercano", quizá evitando saltos. [en gcc existen directivas likely/unlikely para elegir los caminos adecuados en caso de código repetido.]
  - Es usado a lo largo del código del kernel y usarlo hace uniforme el manejo de errores.
  
  
  int res;
...
res = tty_register_driver (&serial_driver);
if (res) {
        printk (KERN_ERR "serial.c: Error al registrar el controlador serie\n");
        goto out;
}

res = tty_register_driver (&callout_driver);
if (res) {
        printk(KERN_ERR "serial.c: Error al registrar el controlador de llamada\n");
        goto out_callout;
}
...
out_callout:
        tty_unregister_driver (&serial_driver);
out:
        return res;

  
  
• Códigos de retorno numéricos, devolver ELOQUESEA en vez de devolver -ELOQUESEA
  
  Tu controlador debe devolver siempre un estado si recibe una petición. Se recomienda devolver siempre códigos numéricos como valores normales de retorno. Devolver 0 = acertado, ó -1 = fallado, es vago y sin sentido.
  
  Todos los valores devueltos por un controlador deben ser los estándar que proporcionan los siguientes ficheros de cabecera del kernel de Linux:
  
  linux/include/linux/errno.h linux/include/asm/errno.h linux/include/asm-generic/errno-base.h linux/include/asm-generic/errno.h
  
  Además muchos controladores tienen sentencias de retorno como la siguiente:
  
  
  return EIO; /* Error de E/S */

  
  cuando deberia ser:
  
  
  return -EIO; /* Error de E/S */

  
  
• No se necesita llamar a panic()
  
  Un controlador de dispositivo debe hacer todo lo que esté en su mano para no llamar a panic(). El hecho de que un dispositivo hardware este roto, no responda y/o tenga un problema irresoluble no significa que haya que llamar a panic().
  
  Más aún, el controlador debería tratar de recuperar, reinicializar, o si todo lo anterior no es posible simplemente devolver el código de error apropiado, liberar los recursos que tuviera ocupados, grabar un mensaje y salir tranquilamente.
  
  Sólo en casos extremos, donde el sistema operativo y todo el sistema en general es irrecuperable se debería llamar a panic().
  
  Como regla general no se debe invocar a panic() y dejar a los subsistemas del kernel esa tarea como se muestra a continuacion:
  
  
  linux/drivers/char/watchdog/pcwd.c

Este es un ejemplo real de un controlador del dispositivo en el kernel linux-2.5.52:

if (revision == PCWD_REVISION_A) {
        if (cdat & WD_WDRST)
                rv |= WDIOF_CARDRESET;

        if (cdat & WD_T110) {
                rv |= WDIOF_OVERHEAT;

                if (temp_panic)
                        panic("pcwd: Temperature overheat trip!\n");
        }
}

  
  En este caso, la tarjeta watchdog esta llamando a panic() cuando detecta que la CPU está sobrecalentada.
  Si miras a la funcion panic() en linux/kernel/panic.c encontrarás que a no ser que la variable int panic_timeout > 0; donde la función panic() llamaría a machine_restart después de esperar la cantidad de tiempo panic_timeout; panic() podria poner el sistema en dead-lock (bucle infinito) que en este caso, podría perjudicar al sistema mas que ayudar.
  
  Una forma mas apropiada de manejar esta situación es simplemente apagar el sistema:
  
  
  if (revision == PCWD_REVISION_A) {
        if (cdat & WD_WDRST)
                rv |= WDIOF_CARDRESET;

        if (cdat & WD_T110) {
                rv |= WDIOF_OVERHEAT;

                if (temp_panic) {
                        printk (KERN_EMERG "pcwd: Temperature overheat trip!\n");
                        machine_power_off();
                }
        }
}

  
  Es importante no confundir los panic "lazy“ (nota del traductor: "suaves") con un uso apropiado de panic(). Contra lo que se advierte en este documento es contra los "lazy“ panic(), cuando el desarrollador no tiene un conocimiento completo de la situación y opta por llamar a panic() para simplificar.

3.2. Al día con las interfaces/Apis del kernel

3.2.1 Cambios en las interfaces de los módulos

• Inicialización y limpieza
  
  Antes del kernel 2.5 un controlador de dispositivo podia declarar lo siguiente:
  
  
  static int mi_funcion_de_inicializacion(void) { ...... }
static void mi_funcion_de_limpieza(void) { ........ }

module_init(mi_funcion_de_inicializacion);
module_exit mi_funcion_de_limpieza);

  
  La nueva forma es:
  
  
  static int __init mi_funcion_de_inicializacion(void) { ...... }
static void __exit mi_funcion_de_limpieza(void) { ...... }

module_init(mi_funcion_de_inicializacion);
module_exit(mi_funcion_de_limpieza);

MODULE_LICENSE("license_type"); /* Esto ahora se pide en la mayoria de los casos */
                                /* Puede ser GPL, BSD o cualquier otra          */

  
  
• Macros de módulos para cuenta de referencias:
  
  Referencia: linux/include/linux/module.h
  Referencia: "ftp.us.kernel.org/pub/linux/kernel/people/rusty/modules/FAQ"
  
  Estas macros no están ya soportadas en 2.5.x y 2.6. En su lugar inicializa el campo .owner como parte de la estructura file_operations. En el kernel 2.4 se solía tener que ajustar la cuenta de referencias a los módulos para saber qué hacer en el caso de que el módulo se mueriera o se descargara mientras era usado, normalmente esto se hacía en la función open:
  
  
  static int mi_funcion_open (struct inode *inode, struct file *file) {
    ........
    MOD_INC_USE_COUNT;
    ........
}

  
  Ahora ya no se necesita ajustar uno mismo las referencias a su propio módulo
• Cuenta de referencia de/desde otros módulos:
  
  Un regla dorada: si estás llamando desde un puntero a función a un módulo diferente, debes guardar una referencia a ese módulo. Sino, te arriesgas a quedarte esperando si ese modulo se descarga. Puedes obtener una referencia a ese modulo usando:
  
  
  try_module_get(owner);

  
  y no tienes que comprobar si OWNER != NULL, porque esto lo hace try_module_get. Para devolver/guardar la referencia:
  
  
  module_put(owner);  // Para FAQ, si owner == NULL es correcto

  
  De igual forma si obtienes un punto de de entrada a otro módulo a través de symbol_get(), u obtienes un puntero a función, o el módulo exporta con EXPORT_SYMBOL una función, entonces necesitas llamar a try_module_get(owner) primero y no llamar al módulo si esto falla.
  
  Evita usar GET_USE_COUNT(module) especialmente si la descarga del modulo está deshabilitada en el kernel. Entonces no hay cuenta de las referencias y nada a lo que asignar.
  
  Es seguro llamar a try_module_get y module_put desde una interrupción o una softirq. (Fixme: example)
  
  Los controladores de red deberían llamar a SET_MODULE_OWNER en lugar de MOD_*_USE_COUNT.
  
  No es necesario tener toda la informacion del módulo en tu código: MODULE_AUTHOR, MODULE_DESCRIPTION, SUPPORTED_DEVICE, PARM_DESC, ...
  
  Ejemplo:
  
  
  MODULE_AUTHOR("The Linux Kernel Team");
MODULE_DESCRIPTION("Digital 21*4* Tulip ethernet driver");
MODULE_LICENSE("GPL");

  
  Nota: MODULE_PARM fue reemplazado con module_param y está definido en linux/include/linux/moduleparam.h de la siguiente forma: module_param(name, type, perm), que trabaja si el controlador esta empotrado o si el módulo no requere un #ifndef MODULE para tratar los argumentos de la línea de comandos del kernel.
• Modulos, Kobjects y sysfs
  
  Mirar "3.2.2 Sysfs y el nuevo modelo de controladores" a continuación.

3.2.2 Sysfs y el nuevo modelo de controladores

3.2.3 Cli() y Sti()

• proc_register están muerto, en su lugar usa create_proc_entry().
• La nueva API de PCI tiene los siguientes cambios:
  - Antes de leer del dispositivos utilizando pdev->irq or pdev->resource[] , pci_enable_device se debe llamar dado que sino esos punteros tendrán valores incorrectos.
  - Llama a pci_set_drvdata() para inicializar dev->driver_data, de la misma forma para pci_get_drvdata() en lugar de leer directamente.
  - Se debe inicializar PCI_CACHE_LINE_SIZE durante la inicialización de PCI.
• Debes cambiar Replace check_region por request_region y comprobar el valor de retorno:
  
  Ejemplo: [extraído del parche enviado a KJP]
  
  
      if ((state->type != PORT_UNKNOWN) && state->port) {
-      request_region(state->port,8,"serial(set)");
+      if(!request_region(state->port,8,"serial(set)")) {
+          printk(KERN_WARNING "serial port request region %d failed.\n", state->port);
+          return -EBUSY;
+  }
}

  
  
• La función sleep_on() desaparecerá en las series de kernels 2.5/2.6 .

3.3. Gestionando recursos

3.3.1. Funciones de cadenas

• La función strtok() no es segura para programación de hilos y multi-procesdor en su lugar se debe utilizar strsep():
  
  
  -      for (opt = strtok(options, ",");
-          opt != NULL;
-          opt = strtok(NULL, ",")) {
+      while (opt = strsep(&options, ",")) {
+              if (!*opt)
+                      continue;

  
  
• Las funciones strlen y sprintf se deben evitar en la programación de controladores, especialmente desde que sysfs especifica en linux/Documentation/filesystems/sysfs.txt, que la función show() debe usar siempre snprintf para devolver el número de bytes impresos en el buffer. Lo mismo para la funciçon store(), debe devolver el número de bytes usados del buffer usando strnlen().

3.3.2. Declaración e inicialización de variables

• Para generar un código optimo en ensamblador:
  
  [const] char foo[] = "blah";
  
  es mejor que
  
  [const] char *foo = "blah";
  
  dado que el segundo ejemplo podría generar dos variables al generar el código en ensamblador, una cadena estática y un puntero apuntando a ella.
• Es mejor "Unsigned int" que "int" ya que genera mejor código en ensamblador en todas las plataformas excepto en sh5. Aunque, si se necesita para recoger codigos de error negativos "int" está bien.
• Si tienes un puntero a una estructura y necesitas utilizar “sizeof” es mejor usar “sizeof(*var)” que “sizeof(type)” ya que frente a un cambio de tipo no necesitarás ir por todo el código adaptandolo.

3.3.3. Funciones de balanceo/reparto

• pci_alloc_consistent() y pci_free_consistent().
• La llamada a ioremap() se debe balancear con iounmap(). Este es un punto de perdida de memoria habitual.
• Las funciones con nombre *_lock_* se deben balancear con sus correspondientes *_unlock_* para evitar bloqueos infinitos (dead-locks).

3.4. Operaciones de E/S

3.4.1. Acceso al espacio de E/S

3.4.2. Acceso a la memoria mapeada de E/S

3.5. Lo que obviamente no debes

• Los controladores de dispositivos nunca deben añadir una "syscall". Las llamadas al sistema (syscall) se deciden por los mantenedores del kernel e implica código en ensamblador, manejo de software de interrupciones (int 0x80), que es algo que los desarrolladores de controladores de dispositivo nunca deben hacer.
• Por supuesto nunca debes tratar con la BIOS a no ser que sepas exactamente lo que haces.
• No accedas a ningún recurso sin haberlo reservado y chequedado.
• No añadas IOCTLs que dupliquen las existentes.
• No elimines los mesajes de aviso (warnings) en los makefiles. Esto esconde mensajes de aviso que pueden terminar resultando fatales.
• No uses __SMP__ nunca más, ya no existe o no existirá.
• No mezcles tipos o hagas conversión de tipos en el espacio del kernel.
• No añadas nuevas APIs sin estar seguro de que ya existen, investiga.