world leader in high performance signal processing
This version (05 Sep 2012 14:08) was approved by mhennerich.The Previously approved version (08 Nov 2011 17:12) is available.Diff

ADP5588 Input Keyboard and GPIO Linux Driver

Supported Devices

Evaluation Boards

Description

The driver supports multiple key press detection and resolution.
It independently delivers key press and key release events in
chronological order to the Linux input device system.

This allows SHIFT + ANYKEY, ALT + F1 or CTRL + ALT + DEL sequences.

Since the ADP5588 buffers events in its internal FIFO,
it’s unlikely that events are lost due to heavy system
load and interrupt latencies.

Configuration

Software configurable features

  • Configurable keypad size matrix (rows, columns).
  • Support for switch events.
  • Enabling and disabling automatic key repeat feature.
  • Lock/Unlock key feature.
  • Unused row and column pins are exported general-purpose inputs/outputs to GPIOLIB

Source Code

Status

Source Mainlined?
git Yes

Files

Example platform device initialization

For compile time configuration, it’s common Linux practice to keep board- and application-specific configuration out of the main driver file, instead putting it into the board support file.

For devices on custom boards, as typical of embedded and SoC-(system-on-chip) based hardware, Linux uses platform_data to point to board-specific structures describing devices and how they are connected to the SoC. This can include available ports, chip variants, preferred modes, default initialization, additional pin roles, and so on. This shrinks the board-support packages (BSPs) and minimizes board and application specific #ifdefs in drivers.

21 Oct 2010 16:10 · Michael Hennerich

file: include/linux/i2c/adp5588.h

/* line 103 to 172 */
/* Put one of these structures in i2c_board_info platform_data */
 
#define ADP5588_KEYMAPSIZE	80
 
#define GPI_PIN_ROW0 97
#define GPI_PIN_ROW1 98
#define GPI_PIN_ROW2 99
#define GPI_PIN_ROW3 100
#define GPI_PIN_ROW4 101
#define GPI_PIN_ROW5 102
#define GPI_PIN_ROW6 103
#define GPI_PIN_ROW7 104
#define GPI_PIN_COL0 105
#define GPI_PIN_COL1 106
#define GPI_PIN_COL2 107
#define GPI_PIN_COL3 108
#define GPI_PIN_COL4 109
#define GPI_PIN_COL5 110
#define GPI_PIN_COL6 111
#define GPI_PIN_COL7 112
#define GPI_PIN_COL8 113
#define GPI_PIN_COL9 114
 
#define GPI_PIN_ROW_BASE GPI_PIN_ROW0
#define GPI_PIN_ROW_END GPI_PIN_ROW7
#define GPI_PIN_COL_BASE GPI_PIN_COL0
#define GPI_PIN_COL_END GPI_PIN_COL9
 
#define GPI_PIN_BASE GPI_PIN_ROW_BASE
#define GPI_PIN_END GPI_PIN_COL_END
 
#define ADP5588_GPIMAPSIZE_MAX (GPI_PIN_END - GPI_PIN_BASE + 1)
 
struct adp5588_gpi_map {
	unsigned short pin;
	unsigned short sw_evt;
};
 
struct adp5588_kpad_platform_data {
	int rows;			/* Number of rows */
	int cols;			/* Number of columns */
	const unsigned short *keymap;	/* Pointer to keymap */
	unsigned short keymapsize;	/* Keymap size */
	unsigned repeat:1;		/* Enable key repeat */
	unsigned en_keylock:1;		/* Enable Key Lock feature */
	unsigned short unlock_key1;	/* Unlock Key 1 */
	unsigned short unlock_key2;	/* Unlock Key 2 */
	const struct adp5588_gpi_map *gpimap;
	unsigned short gpimapsize;
	const struct adp5588_gpio_platform_data *gpio_data;
};
 
struct i2c_client; /* forward declaration */
 
struct adp5588_gpio_platform_data {
	int gpio_start;		/* GPIO Chip base # */
	const char *const *names;
	unsigned irq_base;	/* interrupt base # */
	unsigned pullup_dis_mask; /* Pull-Up Disable Mask */
	int	(*setup)(struct i2c_client *client,
				unsigned gpio, unsigned ngpio,
				void *context);
	int	(*teardown)(struct i2c_client *client,
				unsigned gpio, unsigned ngpio,
				void *context);
	void	*context;
};
 
#endif

file: arch/blackfin/mach-bf537/boards/stamp.c

static const unsigned short adp5588_keymap[ADP5588_KEYMAPSIZE] = {
	[0]	 = KEY_GRAVE,
	[1]	 = KEY_1,
	[2]	 = KEY_2,
	[3]	 = KEY_3,
	[4]	 = KEY_4,
	[5]	 = KEY_5,
	[6]	 = KEY_6,
	[7]	 = KEY_7,
	[8]	 = KEY_8,
	[9]	 = KEY_9,
	[10]	 = KEY_0,
	[11]	 = KEY_MINUS,
	[12]	 = KEY_EQUAL,
	[13]	 = KEY_BACKSLASH,
	[15]	 = KEY_KP0,
	[16]	 = KEY_Q,
	[17]	 = KEY_W,
	[18]	 = KEY_E,
	[19]	 = KEY_R,
	[20]	 = KEY_T,
	[21]	 = KEY_Y,
	[22]	 = KEY_U,
	[23]	 = KEY_I,
	[24]	 = KEY_O,
	[25]	 = KEY_P,
	[26]	 = KEY_LEFTBRACE,
	[27]	 = KEY_RIGHTBRACE,
	[29]	 = KEY_KP1,
	[30]	 = KEY_KP2,
	[31]	 = KEY_KP3,
	[32]	 = KEY_A,
	[33]	 = KEY_S,
	[34]	 = KEY_D,
	[35]	 = KEY_F,
	[36]	 = KEY_G,
	[37]	 = KEY_H,
	[38]	 = KEY_J,
	[39]	 = KEY_K,
	[40]	 = KEY_L,
	[41]	 = KEY_SEMICOLON,
	[42]	 = KEY_APOSTROPHE,
	[43]	 = KEY_BACKSLASH,
	[45]	 = KEY_KP4,
	[46]	 = KEY_KP5,
	[47]	 = KEY_KP6,
	[48]	 = KEY_102ND,
	[49]	 = KEY_Z,
	[50]	 = KEY_X,
	[51]	 = KEY_C,
	[52]	 = KEY_V,
	[53]	 = KEY_B,
	[54]	 = KEY_N,
	[55]	 = KEY_M,
	[56]	 = KEY_COMMA,
	[57]	 = KEY_DOT,
	[58]	 = KEY_SLASH,
	[60]	 = KEY_KPDOT,
	[61]	 = KEY_KP7,
	[62]	 = KEY_KP8,
	[63]	 = KEY_KP9,
	[64]	 = KEY_SPACE,
	[65]	 = KEY_BACKSPACE,
	[66]	 = KEY_TAB,
	[67]	 = KEY_KPENTER,
	[68]	 = KEY_ENTER,
	[69]	 = KEY_ESC,
	[70]	 = KEY_DELETE,
	[74]	 = KEY_KPMINUS,
	[76]	 = KEY_UP,
	[77]	 = KEY_DOWN,
	[78]	 = KEY_RIGHT,
	[79]	 = KEY_LEFT,
};

file: arch/blackfin/mach-bf537/boards/stamp.c

static struct adp5588_kpad_platform_data adp5588_kpad_data = {
	.rows		= 8,
	.cols		= 10,
	.keymap		= adp5588_keymap,
	.keymapsize	= ARRAY_SIZE(adp5588_keymap),
	.repeat		= 0,
};

Declaring I2C devices

Unlike PCI or USB devices, I2C devices are not enumerated at the hardware level. Instead, the software must know which devices are connected on each I2C bus segment, and what address these devices are using. For this reason, the kernel code must instantiate I2C devices explicitly. There are different ways to achieve this, depending on the context and requirements. However the most common method is to declare the I2C devices by bus number.

This method is appropriate when the I2C bus is a system bus, as in many embedded systems, wherein each I2C bus has a number which is known in advance. It is thus possible to pre-declare the I2C devices that inhabit this bus. This is done with an array of struct i2c_board_info, which is registered by calling i2c_register_board_info().

So, to enable such a driver one need only edit the board support file by adding an appropriate entry to i2c_board_info.

For more information see: Documentation/i2c/instantiating-devices

21 Oct 2010 16:10 · Michael Hennerich
static struct i2c_board_info __initdata bfin_i2c_board_info[] = {
#if defined(CONFIG_KEYBOARD_ADP5585) || defined(CONFIG_KEYBOARD_ADP5585_MODULE)
	{
		I2C_BOARD_INFO("adp5585-keys", 0x34),
		.irq = IRQ_PG0,
		.platform_data = (void *)&adp5585_kpad_data,
	},
#endif
}

Adding Linux driver support

Configure kernel with “make menuconfig” (alternatively use “make xconfig” or “make qconfig”)

<not e> The ADP5588 Driver depends on CONFIG_I2C </WRAP>

  --- Input Device Support
  <*> Generic input layer (needed for keyboard, mouse, ...)
  < >   Support for memoryless force-feedback devices
  ---   Userland interfaces
  < >   Mouse interface
  < >   Joystick interface
  < >   Touchscreen interface
  <M>   Event interface
  < >   Event debugging
  ---   Input Device Drivers
  [*]   Keyboards  —>

	  --- Keyboards
	  < >   AT keyboard
	  < >   Sun Type 4 and Type 5 keyboard
	  < >   DECstation/VAXstation LK201/LK401 keyboard
	  < >   XT keyboard
	  < >   Newton keyboard
	  < >   Stowaway keyboard
	  < >   GPIO Buttons
	  < >   OpenCores Keyboard Controller
	  <M>   ADP5588 I2C QWERTY Keypad and IO Expander

  [ ]   Mouse  --->
  [ ]   Joysticks  --->
  [ ]   Touchscreens  --->
  [ ]   Miscellaneous devices  --->
      Hardware I/O ports  --->

Make sure the I2C SCL Clock is in the range of 60-400 kHz!

Hardware configuration

There is no dedicated Blackfin STAMP evaluation board for the ADP5588. During test and driver development we used the ADP5588 Demo Mother/Daughter Board.

It can be easily wired to the Blackfin STAMP TWI/I2C header.

BF537-STAMP (P10) TWI/I2C header ADP5588 Daughter Board
PIN Function PIN/Function
2 (+3.3V) VCC
5 SCL SCL
6 SDA SDA
10 PORTG0 INTB
20 GND GND

On the ADP5588 Demo Mother Board replace R30 (10kOhm PULL-UP resistor on /INTB strobe) with a 1-3kOhm resistor. The 10kOhm resistor is too weak - Blackfin might see an additional falling edge interrupt on the rising edge of /INTB.

Driver testing

When the driver is loaded, you should see positive output that it found the ADP5588 device.

root:/> modprobe adp5588_keys
input: adp5588-keys as /class/input/input0
adp5588-keys 0-0034: Rev.2 keypad, irq 66
root:/> modprobe evdev
root:/> event_test /dev/input/event0
Input driver version is 1.0.0
Input device ID: bus 0x18 vendor 0x1 product 0x1 version 0x2
Input device name: "adp5588-keys"
Supported events:
  Event type 0 (Reset)
    Event code 0 (Reset)
    Event code 1 (Key)
  Event type 1 (Key)
    Event code 1 (Esc)
    Event code 2 (1)
    Event code 3 (2)
    Event code 4 (3)
    Event code 5 (4)
    Event code 6 (5)
    Event code 7 (6)
    Event code 8 (7)
    Event code 9 (8)
    Event code 10 (9)
    Event code 11 (0)
    Event code 12 (Minus)
    Event code 13 (Equal)
    Event code 14 (Backspace)
    Event code 15 (Tab)
    Event code 16 (Q)
    Event code 17 (W)
    Event code 18 (E)
    Event code 19 (R)
    Event code 20 (T)
    Event code 21 (Y)
    Event code 22 (U)
    Event code 23 (I)
    Event code 24 (O)
    Event code 25 (P)
    Event code 26 (LeftBrace)
    Event code 27 (RightBrace)
    Event code 28 (Enter)
    Event code 30 (A)
    Event code 31 (S)
    Event code 32 (D)
    Event code 33 (F)
    Event code 34 (G)
    Event code 35 (H)
    Event code 36 (J)
    Event code 37 (K)
    Event code 38 (L)
    Event code 39 (Semicolon)
    Event code 40 (Apostrophe)
    Event code 41 (Grave)
    Event code 43 (BackSlash)
    Event code 44 (Z)
    Event code 45 (X)
    Event code 46 (C)
    Event code 47 (V)
    Event code 48 (B)
    Event code 49 (N)
    Event code 50 (M)
    Event code 51 (Comma)
    Event code 52 (Dot)
    Event code 53 (Slash)
    Event code 57 (Space)
    Event code 71 (KP7)
    Event code 72 (KP8)
    Event code 73 (KP9)
    Event code 74 (KPMinus)
    Event code 75 (KP4)
    Event code 76 (KP5)
    Event code 77 (KP6)
    Event code 79 (KP1)
    Event code 80 (KP2)
    Event code 81 (KP3)
    Event code 82 (KP0)
    Event code 83 (KPDot)
    Event code 86 (102nd)
    Event code 96 (KPEnter)
    Event code 103 (Up)
    Event code 105 (Left)
    Event code 106 (Right)
    Event code 108 (Down)
    Event code 111 (Delete)
Testing ... (interrupt to exit)
Event: time 219561.256000, type 1 (Key), code 41 (Grave), value 1
Event: time 219561.256000, type 0 (Reset), code 0 (Reset), value 0
Event: time 219561.464000, type 1 (Key), code 41 (Grave), value 0
Event: time 219561.464000, type 0 (Reset), code 0 (Reset), value 0
Event: time 219561.968000, type 1 (Key), code 2 (1), value 1
Event: time 219561.968000, type 0 (Reset), code 0 (Reset), value 0
Event: time 219562.176000, type 1 (Key), code 2 (1), value 0
Event: time 219562.176000, type 0 (Reset), code 0 (Reset), value 0
Event: time 219562.608000, type 1 (Key), code 3 (2), value 1
Event: time 219562.608000, type 0 (Reset), code 0 (Reset), value 0
Event: time 219562.868000, type 1 (Key), code 3 (2), value 0
Event: time 219562.868000, type 0 (Reset), code 0 (Reset), value 0
Event: time 219563.628000, type 1 (Key), code 4 (3), value 1
Event: time 219563.628000, type 0 (Reset), code 0 (Reset), value 0
Event: time 219563.888000, type 1 (Key), code 4 (3), value 0
Event: time 219563.888000, type 0 (Reset), code 0 (Reset), value 0

More Information