mirror of
https://github.com/t2linux/kernel.git
synced 2026-04-30 13:48:59 -07:00
Merge branch 'master' of /home/trondmy/kernel/linux-2.6/
Conflicts: net/sunrpc/auth_gss/gss_krb5_crypto.c net/sunrpc/auth_gss/gss_spkm3_token.c net/sunrpc/clnt.c Merge with mainline and fix conflicts.
This commit is contained in:
Trond Myklebust
@@ -2571,6 +2571,16 @@ S: Subiaco, 6008
|
||||
S: Perth, Western Australia
|
||||
S: Australia
|
||||
|
||||
N: Miguel Ojeda Sandonis
|
||||
E: maxextreme@gmail.com
|
||||
D: Author: Auxiliary LCD Controller driver (ks0108)
|
||||
D: Author: Auxiliary LCD driver (cfag12864b)
|
||||
D: Author: Auxiliary LCD framebuffer driver (cfag12864bfb)
|
||||
D: Maintainer: Auxiliary display drivers tree (drivers/auxdisplay/*)
|
||||
S: C/ Mieses 20, 9-B
|
||||
S: Valladolid 47009
|
||||
S: Spain
|
||||
|
||||
N: Greg Page
|
||||
E: gpage@sovereign.org
|
||||
D: IPX development and support
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
What: /debug/pktcdvd/pktcdvd[0-7]
|
||||
Date: Oct. 2006
|
||||
KernelVersion: 2.6.19
|
||||
KernelVersion: 2.6.20
|
||||
Contact: Thomas Maier <balagi@justmail.de>
|
||||
Description:
|
||||
|
||||
@@ -11,8 +11,7 @@ The pktcdvd module (packet writing driver) creates
|
||||
these files in debugfs:
|
||||
|
||||
/debug/pktcdvd/pktcdvd[0-7]/
|
||||
info (0444) Lots of human readable driver
|
||||
statistics and infos. Multiple lines!
|
||||
info (0444) Lots of driver statistics and infos.
|
||||
|
||||
Example:
|
||||
-------
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
What: /sys/class/pktcdvd/
|
||||
Date: Oct. 2006
|
||||
KernelVersion: 2.6.19
|
||||
KernelVersion: 2.6.20
|
||||
Contact: Thomas Maier <balagi@justmail.de>
|
||||
Description:
|
||||
|
||||
|
||||
@@ -482,13 +482,13 @@ slightly.
|
||||
<para>Gadget drivers
|
||||
rely on common USB structures and constants
|
||||
defined in the
|
||||
<filename><linux/usb_ch9.h></filename>
|
||||
<filename><linux/usb/ch9.h></filename>
|
||||
header file, which is standard in Linux 2.6 kernels.
|
||||
These are the same types and constants used by host
|
||||
side drivers (and usbcore).
|
||||
</para>
|
||||
|
||||
!Iinclude/linux/usb_ch9.h
|
||||
!Iinclude/linux/usb/ch9.h
|
||||
</sect1>
|
||||
|
||||
<sect1 id="core"><title>Core Objects and Methods</title>
|
||||
|
||||
@@ -316,6 +316,9 @@ X!Earch/i386/kernel/mca.c
|
||||
<sect1><title>DMI Interfaces</title>
|
||||
!Edrivers/firmware/dmi_scan.c
|
||||
</sect1>
|
||||
<sect1><title>EDD Interfaces</title>
|
||||
!Idrivers/firmware/edd.c
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
<chapter id="security">
|
||||
|
||||
@@ -4,4 +4,5 @@
|
||||
<param name="funcsynopsis.style">ansi</param>
|
||||
<param name="funcsynopsis.tabular.threshold">80</param>
|
||||
<!-- <param name="paper.type">A4</param> -->
|
||||
<param name="generate.section.toc.level">2</param>
|
||||
</stylesheet>
|
||||
|
||||
@@ -187,13 +187,13 @@
|
||||
|
||||
<chapter><title>USB-Standard Types</title>
|
||||
|
||||
<para>In <filename><linux/usb_ch9.h></filename> you will find
|
||||
<para>In <filename><linux/usb/ch9.h></filename> you will find
|
||||
the USB data types defined in chapter 9 of the USB specification.
|
||||
These data types are used throughout USB, and in APIs including
|
||||
this host side API, gadget APIs, and usbfs.
|
||||
</para>
|
||||
|
||||
!Iinclude/linux/usb_ch9.h
|
||||
!Iinclude/linux/usb/ch9.h
|
||||
|
||||
</chapter>
|
||||
|
||||
@@ -574,7 +574,7 @@ for (;;) {
|
||||
#include <asm/byteorder.h></programlisting>
|
||||
The standard USB device model requests, from "Chapter 9" of
|
||||
the USB 2.0 specification, are automatically included from
|
||||
the <filename><linux/usb_ch9.h></filename> header.
|
||||
the <filename><linux/usb/ch9.h></filename> header.
|
||||
</para>
|
||||
|
||||
<para>Unless noted otherwise, the ioctl requests
|
||||
|
||||
@@ -30,6 +30,7 @@ are not a good substitute for a solid C education and/or years of
|
||||
experience, the following books are good for, if anything, reference:
|
||||
- "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
|
||||
- "Practical C Programming" by Steve Oualline [O'Reilly]
|
||||
- "C: A Reference Manual" by Harbison and Steele [Prentice Hall]
|
||||
|
||||
The kernel is written using GNU C and the GNU toolchain. While it
|
||||
adheres to the ISO C89 standard, it uses a number of extensions that are
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
===================================
|
||||
cfag12864b LCD Driver Documentation
|
||||
===================================
|
||||
|
||||
License: GPLv2
|
||||
Author & Maintainer: Miguel Ojeda Sandonis <maxextreme@gmail.com>
|
||||
Date: 2006-10-27
|
||||
|
||||
|
||||
|
||||
--------
|
||||
0. INDEX
|
||||
--------
|
||||
|
||||
1. DRIVER INFORMATION
|
||||
2. DEVICE INFORMATION
|
||||
3. WIRING
|
||||
4. USERSPACE PROGRAMMING
|
||||
|
||||
|
||||
---------------------
|
||||
1. DRIVER INFORMATION
|
||||
---------------------
|
||||
|
||||
This driver support one cfag12864b display at time.
|
||||
|
||||
|
||||
---------------------
|
||||
2. DEVICE INFORMATION
|
||||
---------------------
|
||||
|
||||
Manufacturer: Crystalfontz
|
||||
Device Name: Crystalfontz 12864b LCD Series
|
||||
Device Code: cfag12864b
|
||||
Webpage: http://www.crystalfontz.com
|
||||
Device Webpage: http://www.crystalfontz.com/products/12864b/
|
||||
Type: LCD (Liquid Crystal Display)
|
||||
Width: 128
|
||||
Height: 64
|
||||
Colors: 2 (B/N)
|
||||
Controller: ks0108
|
||||
Controllers: 2
|
||||
Pages: 8 each controller
|
||||
Addresses: 64 each page
|
||||
Data size: 1 byte each address
|
||||
Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
|
||||
|
||||
|
||||
---------
|
||||
3. WIRING
|
||||
---------
|
||||
|
||||
The cfag12864b LCD Series don't have official wiring.
|
||||
|
||||
The common wiring is done to the parallel port as shown:
|
||||
|
||||
Parallel Port cfag12864b
|
||||
|
||||
Name Pin# Pin# Name
|
||||
|
||||
Strobe ( 1)------------------------------(17) Enable
|
||||
Data 0 ( 2)------------------------------( 4) Data 0
|
||||
Data 1 ( 3)------------------------------( 5) Data 1
|
||||
Data 2 ( 4)------------------------------( 6) Data 2
|
||||
Data 3 ( 5)------------------------------( 7) Data 3
|
||||
Data 4 ( 6)------------------------------( 8) Data 4
|
||||
Data 5 ( 7)------------------------------( 9) Data 5
|
||||
Data 6 ( 8)------------------------------(10) Data 6
|
||||
Data 7 ( 9)------------------------------(11) Data 7
|
||||
(10) [+5v]---( 1) Vdd
|
||||
(11) [GND]---( 2) Ground
|
||||
(12) [+5v]---(14) Reset
|
||||
(13) [GND]---(15) Read / Write
|
||||
Line (14)------------------------------(13) Controller Select 1
|
||||
(15)
|
||||
Init (16)------------------------------(12) Controller Select 2
|
||||
Select (17)------------------------------(16) Data / Instruction
|
||||
Ground (18)---[GND] [+5v]---(19) LED +
|
||||
Ground (19)---[GND]
|
||||
Ground (20)---[GND] E A Values:
|
||||
Ground (21)---[GND] [GND]---[P1]---(18) Vee · R = Resistor = 22 ohm
|
||||
Ground (22)---[GND] | · P1 = Preset = 10 Kohm
|
||||
Ground (23)---[GND] ---- S ------( 3) V0 · P2 = Preset = 1 Kohm
|
||||
Ground (24)---[GND] | |
|
||||
Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
|
||||
|
||||
|
||||
------------------------
|
||||
4. USERSPACE PROGRAMMING
|
||||
------------------------
|
||||
|
||||
The cfag12864bfb describes a framebuffer device (/dev/fbX).
|
||||
|
||||
It has a size of 1024 bytes = 1 Kbyte.
|
||||
Each bit represents one pixel. If the bit is high, the pixel will
|
||||
turn on. If the pixel is low, the pixel will turn off.
|
||||
|
||||
You can use the framebuffer as a file: fopen, fwrite, fclose...
|
||||
Although the LCD won't get updated until the next refresh time arrives.
|
||||
|
||||
Also, you can mmap the framebuffer: open & mmap, munmap & close...
|
||||
which is the best option for most uses.
|
||||
|
||||
Check Documentation/auxdisplay/cfag12864b-example.c
|
||||
for a real working userspace complete program with usage examples.
|
||||
@@ -0,0 +1,282 @@
|
||||
/*
|
||||
* Filename: cfag12864b-example.c
|
||||
* Version: 0.1.0
|
||||
* Description: cfag12864b LCD userspace example program
|
||||
* License: GPLv2
|
||||
*
|
||||
* Author: Copyright (C) Miguel Ojeda Sandonis <maxextreme@gmail.com>
|
||||
* Date: 2006-10-31
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License version 2 as
|
||||
* published by the Free Software Foundation.
|
||||
*
|
||||
* This program is distributed in the hope that it will be useful,
|
||||
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
* GNU General Public License for more details.
|
||||
*
|
||||
* You should have received a copy of the GNU General Public License
|
||||
* along with this program; if not, write to the Free Software
|
||||
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
||||
*
|
||||
*/
|
||||
|
||||
/*
|
||||
* ------------------------
|
||||
* start of cfag12864b code
|
||||
* ------------------------
|
||||
*/
|
||||
|
||||
#include <string.h>
|
||||
#include <fcntl.h>
|
||||
#include <unistd.h>
|
||||
#include <sys/types.h>
|
||||
#include <sys/stat.h>
|
||||
#include <sys/mman.h>
|
||||
|
||||
#define CFAG12864B_WIDTH (128)
|
||||
#define CFAG12864B_HEIGHT (64)
|
||||
#define CFAG12864B_SIZE (128 * 64 / 8)
|
||||
#define CFAG12864B_BPB (8)
|
||||
#define CFAG12864B_ADDRESS(x, y) ((y) * CFAG12864B_WIDTH / \
|
||||
CFAG12864B_BPB + (x) / CFAG12864B_BPB)
|
||||
#define CFAG12864B_BIT(n) (((unsigned char) 1) << (n))
|
||||
|
||||
#undef CFAG12864B_DOCHECK
|
||||
#ifdef CFAG12864B_DOCHECK
|
||||
#define CFAG12864B_CHECK(x, y) ((x) < CFAG12864B_WIDTH && \
|
||||
(y) < CFAG12864B_HEIGHT)
|
||||
#else
|
||||
#define CFAG12864B_CHECK(x, y) (1)
|
||||
#endif
|
||||
|
||||
int cfag12864b_fd;
|
||||
unsigned char * cfag12864b_mem;
|
||||
unsigned char cfag12864b_buffer[CFAG12864B_SIZE];
|
||||
|
||||
/*
|
||||
* init a cfag12864b framebuffer device
|
||||
*
|
||||
* No error: return = 0
|
||||
* Unable to open: return = -1
|
||||
* Unable to mmap: return = -2
|
||||
*/
|
||||
int cfag12864b_init(char *path)
|
||||
{
|
||||
cfag12864b_fd = open(path, O_RDWR);
|
||||
if (cfag12864b_fd == -1)
|
||||
return -1;
|
||||
|
||||
cfag12864b_mem = mmap(0, CFAG12864B_SIZE, PROT_READ | PROT_WRITE,
|
||||
MAP_SHARED, cfag12864b_fd, 0);
|
||||
if (cfag12864b_mem == MAP_FAILED) {
|
||||
close(cfag12864b_fd);
|
||||
return -2;
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
/*
|
||||
* exit a cfag12864b framebuffer device
|
||||
*/
|
||||
void cfag12864b_exit(void)
|
||||
{
|
||||
munmap(cfag12864b_mem, CFAG12864B_SIZE);
|
||||
close(cfag12864b_fd);
|
||||
}
|
||||
|
||||
/*
|
||||
* set (x, y) pixel
|
||||
*/
|
||||
void cfag12864b_set(unsigned char x, unsigned char y)
|
||||
{
|
||||
if (CFAG12864B_CHECK(x, y))
|
||||
cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] |=
|
||||
CFAG12864B_BIT(x % CFAG12864B_BPB);
|
||||
}
|
||||
|
||||
/*
|
||||
* unset (x, y) pixel
|
||||
*/
|
||||
void cfag12864b_unset(unsigned char x, unsigned char y)
|
||||
{
|
||||
if (CFAG12864B_CHECK(x, y))
|
||||
cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] &=
|
||||
~CFAG12864B_BIT(x % CFAG12864B_BPB);
|
||||
}
|
||||
|
||||
/*
|
||||
* is set (x, y) pixel?
|
||||
*
|
||||
* Pixel off: return = 0
|
||||
* Pixel on: return = 1
|
||||
*/
|
||||
unsigned char cfag12864b_isset(unsigned char x, unsigned char y)
|
||||
{
|
||||
if (CFAG12864B_CHECK(x, y))
|
||||
if (cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] &
|
||||
CFAG12864B_BIT(x % CFAG12864B_BPB))
|
||||
return 1;
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
/*
|
||||
* not (x, y) pixel
|
||||
*/
|
||||
void cfag12864b_not(unsigned char x, unsigned char y)
|
||||
{
|
||||
if (cfag12864b_isset(x, y))
|
||||
cfag12864b_unset(x, y);
|
||||
else
|
||||
cfag12864b_set(x, y);
|
||||
}
|
||||
|
||||
/*
|
||||
* fill (set all pixels)
|
||||
*/
|
||||
void cfag12864b_fill(void)
|
||||
{
|
||||
unsigned short i;
|
||||
|
||||
for (i = 0; i < CFAG12864B_SIZE; i++)
|
||||
cfag12864b_buffer[i] = 0xFF;
|
||||
}
|
||||
|
||||
/*
|
||||
* clear (unset all pixels)
|
||||
*/
|
||||
void cfag12864b_clear(void)
|
||||
{
|
||||
unsigned short i;
|
||||
|
||||
for (i = 0; i < CFAG12864B_SIZE; i++)
|
||||
cfag12864b_buffer[i] = 0;
|
||||
}
|
||||
|
||||
/*
|
||||
* format a [128*64] matrix
|
||||
*
|
||||
* Pixel off: src[i] = 0
|
||||
* Pixel on: src[i] > 0
|
||||
*/
|
||||
void cfag12864b_format(unsigned char * matrix)
|
||||
{
|
||||
unsigned char i, j, n;
|
||||
|
||||
for (i = 0; i < CFAG12864B_HEIGHT; i++)
|
||||
for (j = 0; j < CFAG12864B_WIDTH / CFAG12864B_BPB; j++) {
|
||||
cfag12864b_buffer[i * CFAG12864B_WIDTH / CFAG12864B_BPB +
|
||||
j] = 0;
|
||||
for (n = 0; n < CFAG12864B_BPB; n++)
|
||||
if (matrix[i * CFAG12864B_WIDTH +
|
||||
j * CFAG12864B_BPB + n])
|
||||
cfag12864b_buffer[i * CFAG12864B_WIDTH /
|
||||
CFAG12864B_BPB + j] |=
|
||||
CFAG12864B_BIT(n);
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* blit buffer to lcd
|
||||
*/
|
||||
void cfag12864b_blit(void)
|
||||
{
|
||||
memcpy(cfag12864b_mem, cfag12864b_buffer, CFAG12864B_SIZE);
|
||||
}
|
||||
|
||||
/*
|
||||
* ----------------------
|
||||
* end of cfag12864b code
|
||||
* ----------------------
|
||||
*/
|
||||
|
||||
#include <stdio.h>
|
||||
#include <string.h>
|
||||
|
||||
#define EXAMPLES 6
|
||||
|
||||
void example(unsigned char n)
|
||||
{
|
||||
unsigned short i, j;
|
||||
unsigned char matrix[CFAG12864B_WIDTH * CFAG12864B_HEIGHT];
|
||||
|
||||
if (n > EXAMPLES)
|
||||
return;
|
||||
|
||||
printf("Example %i/%i - ", n, EXAMPLES);
|
||||
|
||||
switch (n) {
|
||||
case 1:
|
||||
printf("Draw points setting bits");
|
||||
cfag12864b_clear();
|
||||
for (i = 0; i < CFAG12864B_WIDTH; i += 2)
|
||||
for (j = 0; j < CFAG12864B_HEIGHT; j += 2)
|
||||
cfag12864b_set(i, j);
|
||||
break;
|
||||
|
||||
case 2:
|
||||
printf("Clear the LCD");
|
||||
cfag12864b_clear();
|
||||
break;
|
||||
|
||||
case 3:
|
||||
printf("Draw rows formatting a [128*64] matrix");
|
||||
memset(matrix, 0, CFAG12864B_WIDTH * CFAG12864B_HEIGHT);
|
||||
for (i = 0; i < CFAG12864B_WIDTH; i++)
|
||||
for (j = 0; j < CFAG12864B_HEIGHT; j += 2)
|
||||
matrix[j * CFAG12864B_WIDTH + i] = 1;
|
||||
cfag12864b_format(matrix);
|
||||
break;
|
||||
|
||||
case 4:
|
||||
printf("Fill the lcd");
|
||||
cfag12864b_fill();
|
||||
break;
|
||||
|
||||
case 5:
|
||||
printf("Draw columns unsetting bits");
|
||||
for (i = 0; i < CFAG12864B_WIDTH; i += 2)
|
||||
for (j = 0; j < CFAG12864B_HEIGHT; j++)
|
||||
cfag12864b_unset(i, j);
|
||||
break;
|
||||
|
||||
case 6:
|
||||
printf("Do negative not-ing all bits");
|
||||
for (i = 0; i < CFAG12864B_WIDTH; i++)
|
||||
for (j = 0; j < CFAG12864B_HEIGHT; j ++)
|
||||
cfag12864b_not(i, j);
|
||||
break;
|
||||
}
|
||||
|
||||
puts(" - [Press Enter]");
|
||||
}
|
||||
|
||||
int main(int argc, char *argv[])
|
||||
{
|
||||
unsigned char n;
|
||||
|
||||
if (argc != 2) {
|
||||
printf(
|
||||
"Sintax: %s fbdev\n"
|
||||
"Usually: /dev/fb0, /dev/fb1...\n", argv[0]);
|
||||
return -1;
|
||||
}
|
||||
|
||||
if (cfag12864b_init(argv[1])) {
|
||||
printf("Can't init %s fbdev\n", argv[1]);
|
||||
return -2;
|
||||
}
|
||||
|
||||
for (n = 1; n <= EXAMPLES; n++) {
|
||||
example(n);
|
||||
cfag12864b_blit();
|
||||
while (getchar() != '\n');
|
||||
}
|
||||
|
||||
cfag12864b_exit();
|
||||
|
||||
return 0;
|
||||
}
|
||||
@@ -0,0 +1,55 @@
|
||||
==========================================
|
||||
ks0108 LCD Controller Driver Documentation
|
||||
==========================================
|
||||
|
||||
License: GPLv2
|
||||
Author & Maintainer: Miguel Ojeda Sandonis <maxextreme@gmail.com>
|
||||
Date: 2006-10-27
|
||||
|
||||
|
||||
|
||||
--------
|
||||
0. INDEX
|
||||
--------
|
||||
|
||||
1. DRIVER INFORMATION
|
||||
2. DEVICE INFORMATION
|
||||
3. WIRING
|
||||
|
||||
|
||||
---------------------
|
||||
1. DRIVER INFORMATION
|
||||
---------------------
|
||||
|
||||
This driver support the ks0108 LCD controller.
|
||||
|
||||
|
||||
---------------------
|
||||
2. DEVICE INFORMATION
|
||||
---------------------
|
||||
|
||||
Manufacturer: Samsung
|
||||
Device Name: KS0108 LCD Controller
|
||||
Device Code: ks0108
|
||||
Webpage: -
|
||||
Device Webpage: -
|
||||
Type: LCD Controller (Liquid Crystal Display Controller)
|
||||
Width: 64
|
||||
Height: 64
|
||||
Colors: 2 (B/N)
|
||||
Pages: 8
|
||||
Addresses: 64 each page
|
||||
Data size: 1 byte each address
|
||||
Memory size: 8 * 64 * 1 = 512 bytes
|
||||
|
||||
|
||||
---------
|
||||
3. WIRING
|
||||
---------
|
||||
|
||||
The driver supports data parallel port wiring.
|
||||
|
||||
If you aren't building LCD related hardware, you should check
|
||||
your LCD specific wiring information in the same folder.
|
||||
|
||||
For example, check Documentation/auxdisplay/cfag12864b.
|
||||
@@ -93,7 +93,7 @@ Notes
|
||||
Using the pktcdvd sysfs interface
|
||||
---------------------------------
|
||||
|
||||
Since Linux 2.6.19, the pktcdvd module has a sysfs interface
|
||||
Since Linux 2.6.20, the pktcdvd module has a sysfs interface
|
||||
and can be controlled by it. For example the "pktcdvd" tool uses
|
||||
this interface. (see http://people.freenet.de/BalaGi#pktcdvd )
|
||||
|
||||
|
||||
@@ -193,6 +193,7 @@ Original developers of the crypto algorithms:
|
||||
Kartikey Mahendra Bhatt (CAST6)
|
||||
Jon Oberheide (ARC4)
|
||||
Jouni Malinen (Michael MIC)
|
||||
NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
|
||||
|
||||
SHA1 algorithm contributors:
|
||||
Jean-Francois Dive
|
||||
@@ -246,6 +247,9 @@ Tiger algorithm contributors:
|
||||
VIA PadLock contributors:
|
||||
Michal Ludvig
|
||||
|
||||
Camellia algorithm contributors:
|
||||
NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
|
||||
|
||||
Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
|
||||
|
||||
Please send any credits updates or corrections to:
|
||||
|
||||
@@ -0,0 +1,268 @@
|
||||
Devres - Managed Device Resource
|
||||
================================
|
||||
|
||||
Tejun Heo <teheo@suse.de>
|
||||
|
||||
First draft 10 January 2007
|
||||
|
||||
|
||||
1. Intro : Huh? Devres?
|
||||
2. Devres : Devres in a nutshell
|
||||
3. Devres Group : Group devres'es and release them together
|
||||
4. Details : Life time rules, calling context, ...
|
||||
5. Overhead : How much do we have to pay for this?
|
||||
6. List of managed interfaces : Currently implemented managed interfaces
|
||||
|
||||
|
||||
1. Intro
|
||||
--------
|
||||
|
||||
devres came up while trying to convert libata to use iomap. Each
|
||||
iomapped address should be kept and unmapped on driver detach. For
|
||||
example, a plain SFF ATA controller (that is, good old PCI IDE) in
|
||||
native mode makes use of 5 PCI BARs and all of them should be
|
||||
maintained.
|
||||
|
||||
As with many other device drivers, libata low level drivers have
|
||||
sufficient bugs in ->remove and ->probe failure path. Well, yes,
|
||||
that's probably because libata low level driver developers are lazy
|
||||
bunch, but aren't all low level driver developers? After spending a
|
||||
day fiddling with braindamaged hardware with no document or
|
||||
braindamaged document, if it's finally working, well, it's working.
|
||||
|
||||
For one reason or another, low level drivers don't receive as much
|
||||
attention or testing as core code, and bugs on driver detach or
|
||||
initilaization failure doesn't happen often enough to be noticeable.
|
||||
Init failure path is worse because it's much less travelled while
|
||||
needs to handle multiple entry points.
|
||||
|
||||
So, many low level drivers end up leaking resources on driver detach
|
||||
and having half broken failure path implementation in ->probe() which
|
||||
would leak resources or even cause oops when failure occurs. iomap
|
||||
adds more to this mix. So do msi and msix.
|
||||
|
||||
|
||||
2. Devres
|
||||
---------
|
||||
|
||||
devres is basically linked list of arbitrarily sized memory areas
|
||||
associated with a struct device. Each devres entry is associated with
|
||||
a release function. A devres can be released in several ways. No
|
||||
matter what, all devres entries are released on driver detach. On
|
||||
release, the associated release function is invoked and then the
|
||||
devres entry is freed.
|
||||
|
||||
Managed interface is created for resources commonly used by device
|
||||
drivers using devres. For example, coherent DMA memory is acquired
|
||||
using dma_alloc_coherent(). The managed version is called
|
||||
dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except
|
||||
for the DMA memory allocated using it is managed and will be
|
||||
automatically released on driver detach. Implementation looks like
|
||||
the following.
|
||||
|
||||
struct dma_devres {
|
||||
size_t size;
|
||||
void *vaddr;
|
||||
dma_addr_t dma_handle;
|
||||
};
|
||||
|
||||
static void dmam_coherent_release(struct device *dev, void *res)
|
||||
{
|
||||
struct dma_devres *this = res;
|
||||
|
||||
dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle);
|
||||
}
|
||||
|
||||
dmam_alloc_coherent(dev, size, dma_handle, gfp)
|
||||
{
|
||||
struct dma_devres *dr;
|
||||
void *vaddr;
|
||||
|
||||
dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp);
|
||||
...
|
||||
|
||||
/* alloc DMA memory as usual */
|
||||
vaddr = dma_alloc_coherent(...);
|
||||
...
|
||||
|
||||
/* record size, vaddr, dma_handle in dr */
|
||||
dr->vaddr = vaddr;
|
||||
...
|
||||
|
||||
devres_add(dev, dr);
|
||||
|
||||
return vaddr;
|
||||
}
|
||||
|
||||
If a driver uses dmam_alloc_coherent(), the area is guaranteed to be
|
||||
freed whether initialization fails half-way or the device gets
|
||||
detached. If most resources are acquired using managed interface, a
|
||||
driver can have much simpler init and exit code. Init path basically
|
||||
looks like the following.
|
||||
|
||||
my_init_one()
|
||||
{
|
||||
struct mydev *d;
|
||||
|
||||
d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL);
|
||||
if (!d)
|
||||
return -ENOMEM;
|
||||
|
||||
d->ring = dmam_alloc_coherent(...);
|
||||
if (!d->ring)
|
||||
return -ENOMEM;
|
||||
|
||||
if (check something)
|
||||
return -EINVAL;
|
||||
...
|
||||
|
||||
return register_to_upper_layer(d);
|
||||
}
|
||||
|
||||
And exit path,
|
||||
|
||||
my_remove_one()
|
||||
{
|
||||
unregister_from_upper_layer(d);
|
||||
shutdown_my_hardware();
|
||||
}
|
||||
|
||||
As shown above, low level drivers can be simplified a lot by using
|
||||
devres. Complexity is shifted from less maintained low level drivers
|
||||
to better maintained higher layer. Also, as init failure path is
|
||||
shared with exit path, both can get more testing.
|
||||
|
||||
|
||||
3. Devres group
|
||||
---------------
|
||||
|
||||
Devres entries can be grouped using devres group. When a group is
|
||||
released, all contained normal devres entries and properly nested
|
||||
groups are released. One usage is to rollback series of acquired
|
||||
resources on failure. For example,
|
||||
|
||||
if (!devres_open_group(dev, NULL, GFP_KERNEL))
|
||||
return -ENOMEM;
|
||||
|
||||
acquire A;
|
||||
if (failed)
|
||||
goto err;
|
||||
|
||||
acquire B;
|
||||
if (failed)
|
||||
goto err;
|
||||
...
|
||||
|
||||
devres_remove_group(dev, NULL);
|
||||
return 0;
|
||||
|
||||
err:
|
||||
devres_release_group(dev, NULL);
|
||||
return err_code;
|
||||
|
||||
As resource acquision failure usually means probe failure, constructs
|
||||
like above are usually useful in midlayer driver (e.g. libata core
|
||||
layer) where interface function shouldn't have side effect on failure.
|
||||
For LLDs, just returning error code suffices in most cases.
|
||||
|
||||
Each group is identified by void *id. It can either be explicitly
|
||||
specified by @id argument to devres_open_group() or automatically
|
||||
created by passing NULL as @id as in the above example. In both
|
||||
cases, devres_open_group() returns the group's id. The returned id
|
||||
can be passed to other devres functions to select the target group.
|
||||
If NULL is given to those functions, the latest open group is
|
||||
selected.
|
||||
|
||||
For example, you can do something like the following.
|
||||
|
||||
int my_midlayer_create_something()
|
||||
{
|
||||
if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL))
|
||||
return -ENOMEM;
|
||||
|
||||
...
|
||||
|
||||
devres_close_group(dev, my_midlayer_something);
|
||||
return 0;
|
||||
}
|
||||
|
||||
void my_midlayer_destroy_something()
|
||||
{
|
||||
devres_release_group(dev, my_midlayer_create_soemthing);
|
||||
}
|
||||
|
||||
|
||||
4. Details
|
||||
----------
|
||||
|
||||
Lifetime of a devres entry begins on devres allocation and finishes
|
||||
when it is released or destroyed (removed and freed) - no reference
|
||||
counting.
|
||||
|
||||
devres core guarantees atomicity to all basic devres operations and
|
||||
has support for single-instance devres types (atomic
|
||||
lookup-and-add-if-not-found). Other than that, synchronizing
|
||||
concurrent accesses to allocated devres data is caller's
|
||||
responsibility. This is usually non-issue because bus ops and
|
||||
resource allocations already do the job.
|
||||
|
||||
For an example of single-instance devres type, read pcim_iomap_table()
|
||||
in lib/iomap.c.
|
||||
|
||||
All devres interface functions can be called without context if the
|
||||
right gfp mask is given.
|
||||
|
||||
|
||||
5. Overhead
|
||||
-----------
|
||||
|
||||
Each devres bookkeeping info is allocated together with requested data
|
||||
area. With debug option turned off, bookkeeping info occupies 16
|
||||
bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded
|
||||
up to ull alignment). If singly linked list is used, it can be
|
||||
reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit).
|
||||
|
||||
Each devres group occupies 8 pointers. It can be reduced to 6 if
|
||||
singly linked list is used.
|
||||
|
||||
Memory space overhead on ahci controller with two ports is between 300
|
||||
and 400 bytes on 32bit machine after naive conversion (we can
|
||||
certainly invest a bit more effort into libata core layer).
|
||||
|
||||
|
||||
6. List of managed interfaces
|
||||
-----------------------------
|
||||
|
||||
IO region
|
||||
devm_request_region()
|
||||
devm_request_mem_region()
|
||||
devm_release_region()
|
||||
devm_release_mem_region()
|
||||
|
||||
IRQ
|
||||
devm_request_irq()
|
||||
devm_free_irq()
|
||||
|
||||
DMA
|
||||
dmam_alloc_coherent()
|
||||
dmam_free_coherent()
|
||||
dmam_alloc_noncoherent()
|
||||
dmam_free_noncoherent()
|
||||
dmam_declare_coherent_memory()
|
||||
dmam_pool_create()
|
||||
dmam_pool_destroy()
|
||||
|
||||
PCI
|
||||
pcim_enable_device() : after success, all PCI ops become managed
|
||||
pcim_pin_device() : keep PCI device enabled after release
|
||||
|
||||
IOMAP
|
||||
devm_ioport_map()
|
||||
devm_ioport_unmap()
|
||||
devm_ioremap()
|
||||
devm_ioremap_nocache()
|
||||
devm_iounmap()
|
||||
pcim_iomap()
|
||||
pcim_iounmap()
|
||||
pcim_iomap_table() : array of mapped addresses indexed by BAR
|
||||
pcim_iomap_regions() : do request_region() and iomap() on multiple BARs
|
||||
@@ -339,7 +339,21 @@ Device Symlink:
|
||||
|
||||
'device'
|
||||
|
||||
Symlink to the memory controller device
|
||||
Symlink to the memory controller device.
|
||||
|
||||
Sdram memory scrubbing rate:
|
||||
|
||||
'sdram_scrub_rate'
|
||||
|
||||
Read/Write attribute file that controls memory scrubbing. The scrubbing
|
||||
rate is set by writing a minimum bandwith in bytes/sec to the attribute
|
||||
file. The rate will be translated to an internal value that gives at
|
||||
least the specified rate.
|
||||
|
||||
Reading the file will return the actual scrubbing rate employed.
|
||||
|
||||
If configuration fails or memory scrubbing is not implemented, the value
|
||||
of the attribute file will be -1.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
|
||||
s3fb - fbdev driver for S3 Trio/Virge chips
|
||||
===========================================
|
||||
|
||||
|
||||
Supported Hardware
|
||||
==================
|
||||
|
||||
S3 Trio32
|
||||
S3 Trio64 (and variants V+, UV+, V2/DX, V2/GX)
|
||||
S3 Virge (and variants VX, DX, GX and GX2+)
|
||||
S3 Plato/PX (completely untested)
|
||||
S3 Aurora64V+ (completely untested)
|
||||
|
||||
- only PCI bus supported
|
||||
- only BIOS initialized VGA devices supported
|
||||
- probably not working on big endian
|
||||
|
||||
I tested s3fb on Trio64 (plain, V+ and V2/DX) and Virge (plain, VX, DX),
|
||||
all on i386.
|
||||
|
||||
|
||||
Supported Features
|
||||
==================
|
||||
|
||||
* 4 bpp pseudocolor modes (with 18bit palette, two variants)
|
||||
* 8 bpp pseudocolor mode (with 18bit palette)
|
||||
* 16 bpp truecolor modes (RGB 555 and RGB 565)
|
||||
* 24 bpp truecolor mode (RGB 888) on (only on Virge VX)
|
||||
* 32 bpp truecolor mode (RGB 888) on (not on Virge VX)
|
||||
* text mode (activated by bpp = 0)
|
||||
* interlaced mode variant (not available in text mode)
|
||||
* doublescan mode variant (not available in text mode)
|
||||
* panning in both directions
|
||||
* suspend/resume support
|
||||
* DPMS support
|
||||
|
||||
Text mode is supported even in higher resolutions, but there is limitation
|
||||
to lower pixclocks (maximum between 50-60 MHz, depending on specific hardware).
|
||||
This limitation is not enforced by driver. Text mode supports 8bit wide fonts
|
||||
only (hardware limitation) and 16bit tall fonts (driver limitation).
|
||||
|
||||
There are two 4 bpp modes. First mode (selected if nonstd == 0) is mode with
|
||||
packed pixels, high nibble first. Second mode (selected if nonstd == 1) is mode
|
||||
with interleaved planes (1 byte interleave), MSB first. Both modes support
|
||||
8bit wide fonts only (driver limitation).
|
||||
|
||||
Suspend/resume works on systems that initialize video card during resume and
|
||||
if device is active (for example used by fbcon).
|
||||
|
||||
|
||||
Missing Features
|
||||
================
|
||||
(alias TODO list)
|
||||
|
||||
* secondary (not initialized by BIOS) device support
|
||||
* big endian support
|
||||
* Zorro bus support
|
||||
* MMIO support
|
||||
* 24 bpp mode support on more cards
|
||||
* support for fontwidths != 8 in 4 bpp modes
|
||||
* support for fontheight != 16 in text mode
|
||||
* composite and external sync (is anyone able to test this?)
|
||||
* hardware cursor
|
||||
* video overlay support
|
||||
* vsync synchronization
|
||||
* feature connector support
|
||||
* acceleration support (8514-like 2D, Virge 3D, busmaster transfers)
|
||||
* better values for some magic registers (performance issues)
|
||||
|
||||
|
||||
Known bugs
|
||||
==========
|
||||
|
||||
* cursor disable in text mode doesn't work
|
||||
|
||||
--
|
||||
Ondrej Zajicek <santiago@crfreenet.org>
|
||||
@@ -50,22 +50,6 @@ Who: Dan Dennedy <dan@dennedy.org>, Stefan Richter <stefanr@s5r6.in-berlin.de>
|
||||
|
||||
---------------------------
|
||||
|
||||
What: ieee1394 core's unused exports (CONFIG_IEEE1394_EXPORT_FULL_API)
|
||||
When: January 2007
|
||||
Why: There are no projects known to use these exported symbols, except
|
||||
dfg1394 (uses one symbol whose functionality is core-internal now).
|
||||
Who: Stefan Richter <stefanr@s5r6.in-berlin.de>
|
||||
|
||||
---------------------------
|
||||
|
||||
What: ieee1394's *_oui sysfs attributes (CONFIG_IEEE1394_OUI_DB)
|
||||
When: January 2007
|
||||
Files: drivers/ieee1394/: oui.db, oui2c.sh
|
||||
Why: big size, little value
|
||||
Who: Stefan Richter <stefanr@s5r6.in-berlin.de>
|
||||
|
||||
---------------------------
|
||||
|
||||
What: Video4Linux API 1 ioctls and video_decoder.h from Video devices.
|
||||
When: December 2006
|
||||
Why: V4L1 AP1 was replaced by V4L2 API. during migration from 2.4 to 2.6
|
||||
@@ -186,18 +170,6 @@ Who: Greg Kroah-Hartman <gregkh@suse.de>
|
||||
|
||||
---------------------------
|
||||
|
||||
What: find_trylock_page
|
||||
When: January 2007
|
||||
Why: The interface no longer has any callers left in the kernel. It
|
||||
is an odd interface (compared with other find_*_page functions), in
|
||||
that it does not take a refcount to the page, only the page lock.
|
||||
It should be replaced with find_get_page or find_lock_page if possible.
|
||||
This feature removal can be reevaluated if users of the interface
|
||||
cannot cleanly use something else.
|
||||
Who: Nick Piggin <npiggin@suse.de>
|
||||
|
||||
---------------------------
|
||||
|
||||
What: Interrupt only SA_* flags
|
||||
When: Januar 2007
|
||||
Why: The interrupt related SA_* flags are replaced by IRQF_* to move them
|
||||
@@ -243,6 +215,13 @@ Who: Jean Delvare <khali@linux-fr.org>,
|
||||
|
||||
---------------------------
|
||||
|
||||
What: drivers depending on OBSOLETE_OSS
|
||||
When: options in 2.6.22, code in 2.6.24
|
||||
Why: OSS drivers with ALSA replacements
|
||||
Who: Adrian Bunk <bunk@stusta.de>
|
||||
|
||||
---------------------------
|
||||
|
||||
What: IPv4 only connection tracking/NAT/helpers
|
||||
When: 2.6.22
|
||||
Why: The new layer 3 independant connection tracking replaces the old
|
||||
@@ -274,6 +253,7 @@ Who: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>
|
||||
|
||||
---------------------------
|
||||
|
||||
<<<<<<< test:Documentation/feature-removal-schedule.txt
|
||||
What: ACPI hotkey driver (CONFIG_ACPI_HOTKEY)
|
||||
When: 2.6.21
|
||||
Why: hotkey.c was an attempt to consolidate multiple drivers that use
|
||||
@@ -306,11 +286,18 @@ Why: The ACPI namespace is effectively the symbol list for
|
||||
the BIOS can be extracted and disassembled with acpidump
|
||||
and iasl as documented in the pmtools package here:
|
||||
http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils
|
||||
|
||||
Who: Len Brown <len.brown@intel.com>
|
||||
|
||||
---------------------------
|
||||
|
||||
What: ACPI procfs interface
|
||||
When: July 2007
|
||||
Why: After ACPI sysfs conversion, ACPI attributes will be duplicated
|
||||
in sysfs and the ACPI procfs interface should be removed.
|
||||
Who: Zhang Rui <rui.zhang@intel.com>
|
||||
|
||||
---------------------------
|
||||
|
||||
What: /proc/acpi/button
|
||||
When: August 2007
|
||||
Why: /proc/acpi/button has been replaced by events to the input layer
|
||||
@@ -325,3 +312,25 @@ Why: Unmaintained for years, superceded by JFFS2 for years.
|
||||
Who: Jeff Garzik <jeff@garzik.org>
|
||||
|
||||
---------------------------
|
||||
|
||||
What: sk98lin network driver
|
||||
When: July 2007
|
||||
Why: In kernel tree version of driver is unmaintained. Sk98lin driver
|
||||
replaced by the skge driver.
|
||||
Who: Stephen Hemminger <shemminger@osdl.org>
|
||||
|
||||
---------------------------
|
||||
|
||||
What: Compaq touchscreen device emulation
|
||||
When: Oct 2007
|
||||
Files: drivers/input/tsdev.c
|
||||
Why: The code says it was obsolete when it was written in 2001.
|
||||
tslib is a userspace library which does anything tsdev can do and
|
||||
much more besides in userspace where this code belongs. There is no
|
||||
longer any need for tsdev and applications should have converted to
|
||||
use tslib by now.
|
||||
The name "tsdev" is also extremely confusing and lots of people have
|
||||
it loaded when they don't need/use it.
|
||||
Who: Richard Purdie <rpurdie@rpsys.net>
|
||||
|
||||
---------------------------
|
||||
|
||||
@@ -157,7 +157,7 @@ TBD(curr. line MT:/API/)
|
||||
channel management functions:
|
||||
|
||||
relay_open(base_filename, parent, subbuf_size, n_subbufs,
|
||||
callbacks)
|
||||
callbacks, private_data)
|
||||
relay_close(chan)
|
||||
relay_flush(chan)
|
||||
relay_reset(chan)
|
||||
@@ -251,7 +251,7 @@ static struct rchan_callbacks relay_callbacks =
|
||||
|
||||
And an example relay_open() invocation using them:
|
||||
|
||||
chan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks);
|
||||
chan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks, NULL);
|
||||
|
||||
If the create_buf_file() callback fails, or isn't defined, channel
|
||||
creation and thus relay_open() will fail.
|
||||
@@ -289,6 +289,11 @@ they use the proper locking for such a buffer, either by wrapping
|
||||
writes in a spinlock, or by copying a write function from relay.h and
|
||||
creating a local version that internally does the proper locking.
|
||||
|
||||
The private_data passed into relay_open() allows clients to associate
|
||||
user-defined data with a channel, and is immediately available
|
||||
(including in create_buf_file()) via chan->private_data or
|
||||
buf->chan->private_data.
|
||||
|
||||
Channel 'modes'
|
||||
---------------
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ ufstype=type_of_ufs
|
||||
supported as read-write
|
||||
|
||||
ufs2 used in FreeBSD 5.x
|
||||
supported as read-only
|
||||
supported as read-write
|
||||
|
||||
5xbsd synonym for ufs2
|
||||
|
||||
@@ -50,12 +50,11 @@ ufstype=type_of_ufs
|
||||
POSSIBLE PROBLEMS
|
||||
=================
|
||||
|
||||
There is still bug in reallocation of fragment, in file fs/ufs/balloc.c,
|
||||
line 364. But it seems working on current buffer cache configuration.
|
||||
See next section, if you have any.
|
||||
|
||||
|
||||
BUG REPORTS
|
||||
===========
|
||||
|
||||
Any ufs bug report you can send to daniel.pirkl@email.cz (do not send
|
||||
partition tables bug reports.)
|
||||
Any ufs bug report you can send to daniel.pirkl@email.cz or
|
||||
to dushistov@mail.ru (do not send partition tables bug reports).
|
||||
|
||||
@@ -0,0 +1,271 @@
|
||||
GPIO Interfaces
|
||||
|
||||
This provides an overview of GPIO access conventions on Linux.
|
||||
|
||||
|
||||
What is a GPIO?
|
||||
===============
|
||||
A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
|
||||
digital signal. They are provided from many kinds of chip, and are familiar
|
||||
to Linux developers working with embedded and custom hardware. Each GPIO
|
||||
represents a bit connected to a particular pin, or "ball" on Ball Grid Array
|
||||
(BGA) packages. Board schematics show which external hardware connects to
|
||||
which GPIOs. Drivers can be written generically, so that board setup code
|
||||
passes such pin configuration data to drivers.
|
||||
|
||||
System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every
|
||||
non-dedicated pin can be configured as a GPIO; and most chips have at least
|
||||
several dozen of them. Programmable logic devices (like FPGAs) can easily
|
||||
provide GPIOs; multifunction chips like power managers, and audio codecs
|
||||
often have a few such pins to help with pin scarcity on SOCs; and there are
|
||||
also "GPIO Expander" chips that connect using the I2C or SPI serial busses.
|
||||
Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
|
||||
firmware knowing how they're used).
|
||||
|
||||
The exact capabilities of GPIOs vary between systems. Common options:
|
||||
|
||||
- Output values are writable (high=1, low=0). Some chips also have
|
||||
options about how that value is driven, so that for example only one
|
||||
value might be driven ... supporting "wire-OR" and similar schemes
|
||||
for the other value.
|
||||
|
||||
- Input values are likewise readable (1, 0). Some chips support readback
|
||||
of pins configured as "output", which is very useful in such "wire-OR"
|
||||
cases (to support bidirectional signaling). GPIO controllers may have
|
||||
input de-glitch logic, sometimes with software controls.
|
||||
|
||||
- Inputs can often be used as IRQ signals, often edge triggered but
|
||||
sometimes level triggered. Such IRQs may be configurable as system
|
||||
wakeup events, to wake the system from a low power state.
|
||||
|
||||
- Usually a GPIO will be configurable as either input or output, as needed
|
||||
by different product boards; single direction ones exist too.
|
||||
|
||||
- Most GPIOs can be accessed while holding spinlocks, but those accessed
|
||||
through a serial bus normally can't. Some systems support both types.
|
||||
|
||||
On a given board each GPIO is used for one specific purpose like monitoring
|
||||
MMC/SD card insertion/removal, detecting card writeprotect status, driving
|
||||
a LED, configuring a transceiver, bitbanging a serial bus, poking a hardware
|
||||
watchdog, sensing a switch, and so on.
|
||||
|
||||
|
||||
GPIO conventions
|
||||
================
|
||||
Note that this is called a "convention" because you don't need to do it this
|
||||
way, and it's no crime if you don't. There **are** cases where portability
|
||||
is not the main issue; GPIOs are often used for the kind of board-specific
|
||||
glue logic that may even change between board revisions, and can't ever be
|
||||
used on a board that's wired differently. Only least-common-denominator
|
||||
functionality can be very portable. Other features are platform-specific,
|
||||
and that can be critical for glue logic.
|
||||
|
||||
Plus, this doesn't define an implementation framework, just an interface.
|
||||
One platform might implement it as simple inline functions accessing chip
|
||||
registers; another might implement it by delegating through abstractions
|
||||
used for several very different kinds of GPIO controller.
|
||||
|
||||
That said, if the convention is supported on their platform, drivers should
|
||||
use it when possible:
|
||||
|
||||
#include <asm/gpio.h>
|
||||
|
||||
If you stick to this convention then it'll be easier for other developers to
|
||||
see what your code is doing, and help maintain it.
|
||||
|
||||
|
||||
Identifying GPIOs
|
||||
-----------------
|
||||
GPIOs are identified by unsigned integers in the range 0..MAX_INT. That
|
||||
reserves "negative" numbers for other purposes like marking signals as
|
||||
"not available on this board", or indicating faults.
|
||||
|
||||
Platforms define how they use those integers, and usually #define symbols
|
||||
for the GPIO lines so that board-specific setup code directly corresponds
|
||||
to the relevant schematics. In contrast, drivers should only use GPIO
|
||||
numbers passed to them from that setup code, using platform_data to hold
|
||||
board-specific pin configuration data (along with other board specific
|
||||
data they need). That avoids portability problems.
|
||||
|
||||
So for example one platform uses numbers 32-159 for GPIOs; while another
|
||||
uses numbers 0..63 with one set of GPIO controllers, 64-79 with another
|
||||
type of GPIO controller, and on one particular board 80-95 with an FPGA.
|
||||
The numbers need not be contiguous; either of those platforms could also
|
||||
use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders.
|
||||
|
||||
Whether a platform supports multiple GPIO controllers is currently a
|
||||
platform-specific implementation issue.
|
||||
|
||||
|
||||
Using GPIOs
|
||||
-----------
|
||||
One of the first things to do with a GPIO, often in board setup code when
|
||||
setting up a platform_device using the GPIO, is mark its direction:
|
||||
|
||||
/* set as input or output, returning 0 or negative errno */
|
||||
int gpio_direction_input(unsigned gpio);
|
||||
int gpio_direction_output(unsigned gpio);
|
||||
|
||||
The return value is zero for success, else a negative errno. It should
|
||||
be checked, since the get/set calls don't have error returns and since
|
||||
misconfiguration is possible. (These calls could sleep.)
|
||||
|
||||
Setting the direction can fail if the GPIO number is invalid, or when
|
||||
that particular GPIO can't be used in that mode. It's generally a bad
|
||||
idea to rely on boot firmware to have set the direction correctly, since
|
||||
it probably wasn't validated to do more than boot Linux. (Similarly,
|
||||
that board setup code probably needs to multiplex that pin as a GPIO,
|
||||
and configure pullups/pulldowns appropriately.)
|
||||
|
||||
|
||||
Spinlock-Safe GPIO access
|
||||
-------------------------
|
||||
Most GPIO controllers can be accessed with memory read/write instructions.
|
||||
That doesn't need to sleep, and can safely be done from inside IRQ handlers.
|
||||
|
||||
Use these calls to access such GPIOs:
|
||||
|
||||
/* GPIO INPUT: return zero or nonzero */
|
||||
int gpio_get_value(unsigned gpio);
|
||||
|
||||
/* GPIO OUTPUT */
|
||||
void gpio_set_value(unsigned gpio, int value);
|
||||
|
||||
The values are boolean, zero for low, nonzero for high. When reading the
|
||||
value of an output pin, the value returned should be what's seen on the
|
||||
pin ... that won't always match the specified output value, because of
|
||||
issues including wire-OR and output latencies.
|
||||
|
||||
The get/set calls have no error returns because "invalid GPIO" should have
|
||||
been reported earlier in gpio_set_direction(). However, note that not all
|
||||
platforms can read the value of output pins; those that can't should always
|
||||
return zero. Also, these calls will be ignored for GPIOs that can't safely
|
||||
be accessed wihtout sleeping (see below).
|
||||
|
||||
Platform-specific implementations are encouraged to optimise the two
|
||||
calls to access the GPIO value in cases where the GPIO number (and for
|
||||
output, value) are constant. It's normal for them to need only a couple
|
||||
of instructions in such cases (reading or writing a hardware register),
|
||||
and not to need spinlocks. Such optimized calls can make bitbanging
|
||||
applications a lot more efficient (in both space and time) than spending
|
||||
dozens of instructions on subroutine calls.
|
||||
|
||||
|
||||
GPIO access that may sleep
|
||||
--------------------------
|
||||
Some GPIO controllers must be accessed using message based busses like I2C
|
||||
or SPI. Commands to read or write those GPIO values require waiting to
|
||||
get to the head of a queue to transmit a command and get its response.
|
||||
This requires sleeping, which can't be done from inside IRQ handlers.
|
||||
|
||||
Platforms that support this type of GPIO distinguish them from other GPIOs
|
||||
by returning nonzero from this call:
|
||||
|
||||
int gpio_cansleep(unsigned gpio);
|
||||
|
||||
To access such GPIOs, a different set of accessors is defined:
|
||||
|
||||
/* GPIO INPUT: return zero or nonzero, might sleep */
|
||||
int gpio_get_value_cansleep(unsigned gpio);
|
||||
|
||||
/* GPIO OUTPUT, might sleep */
|
||||
void gpio_set_value_cansleep(unsigned gpio, int value);
|
||||
|
||||
Other than the fact that these calls might sleep, and will not be ignored
|
||||
for GPIOs that can't be accessed from IRQ handlers, these calls act the
|
||||
same as the spinlock-safe calls.
|
||||
|
||||
|
||||
Claiming and Releasing GPIOs (OPTIONAL)
|
||||
---------------------------------------
|
||||
To help catch system configuration errors, two calls are defined.
|
||||
However, many platforms don't currently support this mechanism.
|
||||
|
||||
/* request GPIO, returning 0 or negative errno.
|
||||
* non-null labels may be useful for diagnostics.
|
||||
*/
|
||||
int gpio_request(unsigned gpio, const char *label);
|
||||
|
||||
/* release previously-claimed GPIO */
|
||||
void gpio_free(unsigned gpio);
|
||||
|
||||
Passing invalid GPIO numbers to gpio_request() will fail, as will requesting
|
||||
GPIOs that have already been claimed with that call. The return value of
|
||||
gpio_request() must be checked. (These calls could sleep.)
|
||||
|
||||
These calls serve two basic purposes. One is marking the signals which
|
||||
are actually in use as GPIOs, for better diagnostics; systems may have
|
||||
several hundred potential GPIOs, but often only a dozen are used on any
|
||||
given board. Another is to catch conflicts between drivers, reporting
|
||||
errors when drivers wrongly think they have exclusive use of that signal.
|
||||
|
||||
These two calls are optional because not not all current Linux platforms
|
||||
offer such functionality in their GPIO support; a valid implementation
|
||||
could return success for all gpio_request() calls. Unlike the other calls,
|
||||
the state they represent doesn't normally match anything from a hardware
|
||||
register; it's just a software bitmap which clearly is not necessary for
|
||||
correct operation of hardware or (bug free) drivers.
|
||||
|
||||
Note that requesting a GPIO does NOT cause it to be configured in any
|
||||
way; it just marks that GPIO as in use. Separate code must handle any
|
||||
pin setup (e.g. controlling which pin the GPIO uses, pullup/pulldown).
|
||||
|
||||
|
||||
GPIOs mapped to IRQs
|
||||
--------------------
|
||||
GPIO numbers are unsigned integers; so are IRQ numbers. These make up
|
||||
two logically distinct namespaces (GPIO 0 need not use IRQ 0). You can
|
||||
map between them using calls like:
|
||||
|
||||
/* map GPIO numbers to IRQ numbers */
|
||||
int gpio_to_irq(unsigned gpio);
|
||||
|
||||
/* map IRQ numbers to GPIO numbers */
|
||||
int irq_to_gpio(unsigned irq);
|
||||
|
||||
Those return either the corresponding number in the other namespace, or
|
||||
else a negative errno code if the mapping can't be done. (For example,
|
||||
some GPIOs can't used as IRQs.) It is an unchecked error to use a GPIO
|
||||
number that hasn't been marked as an input using gpio_set_direction(), or
|
||||
to use an IRQ number that didn't originally come from gpio_to_irq().
|
||||
|
||||
These two mapping calls are expected to cost on the order of a single
|
||||
addition or subtraction. They're not allowed to sleep.
|
||||
|
||||
Non-error values returned from gpio_to_irq() can be passed to request_irq()
|
||||
or free_irq(). They will often be stored into IRQ resources for platform
|
||||
devices, by the board-specific initialization code. Note that IRQ trigger
|
||||
options are part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are
|
||||
system wakeup capabilities.
|
||||
|
||||
Non-error values returned from irq_to_gpio() would most commonly be used
|
||||
with gpio_get_value().
|
||||
|
||||
|
||||
|
||||
What do these conventions omit?
|
||||
===============================
|
||||
One of the biggest things these conventions omit is pin multiplexing, since
|
||||
this is highly chip-specific and nonportable. One platform might not need
|
||||
explicit multiplexing; another might have just two options for use of any
|
||||
given pin; another might have eight options per pin; another might be able
|
||||
to route a given GPIO to any one of several pins. (Yes, those examples all
|
||||
come from systems that run Linux today.)
|
||||
|
||||
Related to multiplexing is configuration and enabling of the pullups or
|
||||
pulldowns integrated on some platforms. Not all platforms support them,
|
||||
or support them in the same way; and any given board might use external
|
||||
pullups (or pulldowns) so that the on-chip ones should not be used.
|
||||
|
||||
There are other system-specific mechanisms that are not specified here,
|
||||
like the aforementioned options for input de-glitching and wire-OR output.
|
||||
Hardware may support reading or writing GPIOs in gangs, but that's usually
|
||||
configuration dependednt: for GPIOs sharing the same bank. (GPIOs are
|
||||
commonly grouped in banks of 16 or 32, with a given SOC having several such
|
||||
banks.) Code relying on such mechanisms will necessarily be nonportable.
|
||||
|
||||
Dynamic definition of GPIOs is not currently supported; for example, as
|
||||
a side effect of configuring an add-on board with some GPIO expanders.
|
||||
|
||||
These calls are purely for kernel space, but a userspace API could be built
|
||||
on top of it.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user