doc/driver-model/UDM-gpio.txt

   1 The U-Boot Driver Model Project
   2 ===============================
   3 GPIO analysis
   4 =============
   5 Viktor Krivak <viktor.krivak@gmail.com>
   6 2012-02-24
   7
   8 I) Overview
   9 -----------
  10
  11   At this moment U-Boot provides standard API that consists of 7 functions.
  12
  13     int  gpio_request(unsigned gpio, const char *label)
  14     int  gpio_free(unsigned gpio)
  15     int  gpio_direction_input(unsigned gpio)
  16     int  gpio_direction_output(unsigned gpio, int value)
  17     int  gpio_get_value(unsigned gpio)
  18     void gpio_set_value(unsigned gpio, int value)
  19
  20   Methods "gpio_request()" and "gpio_free()" are used for claiming and releasing
  21   GPIOs. First one should check if the desired pin exists and if the pin wasn't
  22   requested already elsewhere. The method also has a label argument that can be
  23   used for debug purposes. The label argument should be copied into the internal
  24   memory, but only if the DEBUG macro is set. The "gpio_free()" is the exact
  25   opposite. It releases the particular pin. Other methods are used for setting
  26   input or output direction and obtaining or setting values of the pins.
  27
  28 II) Approach
  29 ------------
  30
  31   1) Request and free GPIO
  32   ------------------------
  33
  34     The "gpio_request()" implementation is basically the same for all boards.
  35     The function checks if the particular GPIO is correct and checks if the
  36     GPIO pin is still free. If the conditions are met, the method marks the
  37     GPIO claimed in it's internal structure. If macro DEBUG is defined, the
  38     function also copies the label argument to the structure. If the pin is
  39     already locked, the function returns -1 and if DEBUG is defined, certain
  40     debug output is generated, including the contents of the label argument.
  41     The "gpio_free()" function releases the lock and eventually deallocates
  42     data used by the copied label argument.
  43
  44   2) Internal data
  45   ----------------
  46
  47   Internal data are driver specific. They have to contain some mechanism to
  48   realise the locking though. This can be done for example using a bit field.
  49
  50   3) Operations provided by the driver
  51   ------------------------------------
  52
  53   The driver operations basically meet API that is already defined and used.
  54   Except for "gpio_request()" and "gpio_free()", all methods can be converted in
  55   a simple manner. The driver provides the following structure:
  56
  57   struct gpio_driver_ops {
  58     int  (*gpio_request)(struct instance *i, unsigned gpio,
  59                          const char *label);
  60     int  (*gpio_free)(struct instance *i, unsigned gpio);
  61     int  (*gpio_direction_input)(struct instance *i, unsigned gpio);
  62     int  (*gpio_direction_output)(struct instance *i, unsigned gpio,
  63                                   int value);
  64     int  (*gpio_get_value)(struct instance *i, unsigned gpio);
  65     void (*gpio_set_value)(struct instance *i, unsigned gpio, int value);
  66   }
  67
  68 III) Analysis of in-tree drivers
  69 --------------------------------
  70
  71   1) altera_pio.c
  72   ---------------
  73   Meets standard API. Implements gpio_request() properly. Simple conversion
  74   possible.
  75
  76   2) at91_gpio.c
  77   --------------
  78   Don't meet standard API. Need some other methods to implement.
  79
  80   3) da8xx_gpio.c
  81   ---------------
  82   Meets standard API. Implements gpio_request() properly. Simple conversion
  83   possible.
  84
  85   4) kw_gpio.c
  86   ------------
  87   Doesn't meet standard API. Needs some other methods to implement and move some
  88   methods to another file.
  89
  90   5) mpc83xx_gpio.c
  91   -----------------
  92   Meets standard API. Doesn't implement gpio_request() properly (only checks
  93   if the pin is valid). Simple conversion possible.
  94
  95   6) mvgpio.c
  96   -----------
  97   Meets standard API. Doesn't implement gpio_request() properly (only checks
  98   if the pin is valid). Simple conversion possible.
  99
 100   7) mvgpio.h
 101   -----------
 102   Wrong placement. Will be moved to another location.
 103
 104   8) mvmfp.c
 105   ----------
 106   Wrong placement. Will be moved to another location.