aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2012-03-23 19:59:10 -0400
committerLinus Torvalds <torvalds@linux-foundation.org>2012-03-23 19:59:10 -0400
commit8e3ade251bc7c0a4f0777df4dd34343a03efadba (patch)
tree6c0b78731e3d6609057951d07660efbd90992ad0 /Documentation
parente317234975cb7463b8ca21a93bb6862d9dcf113f (diff)
parente075f59152890ffd7e3d704afc997dd686c8a781 (diff)
Merge branch 'akpm' (Andrew's patch-bomb)
Merge second batch of patches from Andrew Morton: - various misc things - core kernel changes to prctl, exit, exec, init, etc. - kernel/watchdog.c updates - get_maintainer - MAINTAINERS - the backlight driver queue - core bitops code cleanups - the led driver queue - some core prio_tree work - checkpatch udpates - largeish crc32 update - a new poll() feature for the v4l guys - the rtc driver queue - fatfs - ptrace - signals - kmod/usermodehelper updates - coredump - procfs updates * emailed from Andrew Morton <akpm@linux-foundation.org>: (141 commits) seq_file: add seq_set_overflow(), seq_overflow() proc-ns: use d_set_d_op() API to set dentry ops in proc_ns_instantiate(). procfs: speed up /proc/pid/stat, statm procfs: add num_to_str() to speed up /proc/stat proc: speed up /proc/stat handling fs/proc/kcore.c: make get_sparsemem_vmemmap_info() static coredump: add VM_NODUMP, MADV_NODUMP, MADV_CLEAR_NODUMP coredump: remove VM_ALWAYSDUMP flag kmod: make __request_module() killable kmod: introduce call_modprobe() helper usermodehelper: ____call_usermodehelper() doesn't need do_exit() usermodehelper: kill umh_wait, renumber UMH_* constants usermodehelper: implement UMH_KILLABLE usermodehelper: introduce umh_complete(sub_info) usermodehelper: use UMH_WAIT_PROC consistently signal: zap_pid_ns_processes: s/SEND_SIG_NOINFO/SEND_SIG_FORCED/ signal: oom_kill_task: use SEND_SIG_FORCED instead of force_sig() signal: cosmetic, s/from_ancestor_ns/force/ in prepare_signal() paths signal: give SEND_SIG_FORCED more power to beat SIGNAL_UNKILLABLE Hexagon: use set_current_blocked() and block_sigmask() ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/00-INDEX2
-rw-r--r--Documentation/backlight/lp855x-driver.txt78
-rw-r--r--Documentation/crc32.txt182
-rw-r--r--Documentation/leds/leds-lp5521.txt63
4 files changed, 325 insertions, 0 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index a1a643272883..2214f123a976 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -104,6 +104,8 @@ cpuidle/
104 - info on CPU_IDLE, CPU idle state management subsystem. 104 - info on CPU_IDLE, CPU idle state management subsystem.
105cputopology.txt 105cputopology.txt
106 - documentation on how CPU topology info is exported via sysfs. 106 - documentation on how CPU topology info is exported via sysfs.
107crc32.txt
108 - brief tutorial on CRC computation
107cris/ 109cris/
108 - directory with info about Linux on CRIS architecture. 110 - directory with info about Linux on CRIS architecture.
109crypto/ 111crypto/
diff --git a/Documentation/backlight/lp855x-driver.txt b/Documentation/backlight/lp855x-driver.txt
new file mode 100644
index 000000000000..f5e4caafab7d
--- /dev/null
+++ b/Documentation/backlight/lp855x-driver.txt
@@ -0,0 +1,78 @@
1Kernel driver lp855x
2====================
3
4Backlight driver for LP855x ICs
5
6Supported chips:
7 Texas Instruments LP8550, LP8551, LP8552, LP8553 and LP8556
8
9Author: Milo(Woogyom) Kim <milo.kim@ti.com>
10
11Description
12-----------
13
14* Brightness control
15
16Brightness can be controlled by the pwm input or the i2c command.
17The lp855x driver supports both cases.
18
19* Device attributes
20
211) bl_ctl_mode
22Backlight control mode.
23Value : pwm based or register based
24
252) chip_id
26The lp855x chip id.
27Value : lp8550/lp8551/lp8552/lp8553/lp8556
28
29Platform data for lp855x
30------------------------
31
32For supporting platform specific data, the lp855x platform data can be used.
33
34* name : Backlight driver name. If it is not defined, default name is set.
35* mode : Brightness control mode. PWM or register based.
36* device_control : Value of DEVICE CONTROL register.
37* initial_brightness : Initial value of backlight brightness.
38* pwm_data : Platform specific pwm generation functions.
39 Only valid when brightness is pwm input mode.
40 Functions should be implemented by PWM driver.
41 - pwm_set_intensity() : set duty of PWM
42 - pwm_get_intensity() : get current duty of PWM
43* load_new_rom_data :
44 0 : use default configuration data
45 1 : update values of eeprom or eprom registers on loading driver
46* size_program : Total size of lp855x_rom_data.
47* rom_data : List of new eeprom/eprom registers.
48
49example 1) lp8552 platform data : i2c register mode with new eeprom data
50
51#define EEPROM_A5_ADDR 0xA5
52#define EEPROM_A5_VAL 0x4f /* EN_VSYNC=0 */
53
54static struct lp855x_rom_data lp8552_eeprom_arr[] = {
55 {EEPROM_A5_ADDR, EEPROM_A5_VAL},
56};
57
58static struct lp855x_platform_data lp8552_pdata = {
59 .name = "lcd-bl",
60 .mode = REGISTER_BASED,
61 .device_control = I2C_CONFIG(LP8552),
62 .initial_brightness = INITIAL_BRT,
63 .load_new_rom_data = 1,
64 .size_program = ARRAY_SIZE(lp8552_eeprom_arr),
65 .rom_data = lp8552_eeprom_arr,
66};
67
68example 2) lp8556 platform data : pwm input mode with default rom data
69
70static struct lp855x_platform_data lp8556_pdata = {
71 .mode = PWM_BASED,
72 .device_control = PWM_CONFIG(LP8556),
73 .initial_brightness = INITIAL_BRT,
74 .pwm_data = {
75 .pwm_set_intensity = platform_pwm_set_intensity,
76 .pwm_get_intensity = platform_pwm_get_intensity,
77 },
78};
diff --git a/Documentation/crc32.txt b/Documentation/crc32.txt
new file mode 100644
index 000000000000..a08a7dd9d625
--- /dev/null
+++ b/Documentation/crc32.txt
@@ -0,0 +1,182 @@
1A brief CRC tutorial.
2
3A CRC is a long-division remainder. You add the CRC to the message,
4and the whole thing (message+CRC) is a multiple of the given
5CRC polynomial. To check the CRC, you can either check that the
6CRC matches the recomputed value, *or* you can check that the
7remainder computed on the message+CRC is 0. This latter approach
8is used by a lot of hardware implementations, and is why so many
9protocols put the end-of-frame flag after the CRC.
10
11It's actually the same long division you learned in school, except that
12- We're working in binary, so the digits are only 0 and 1, and
13- When dividing polynomials, there are no carries. Rather than add and
14 subtract, we just xor. Thus, we tend to get a bit sloppy about
15 the difference between adding and subtracting.
16
17Like all division, the remainder is always smaller than the divisor.
18To produce a 32-bit CRC, the divisor is actually a 33-bit CRC polynomial.
19Since it's 33 bits long, bit 32 is always going to be set, so usually the
20CRC is written in hex with the most significant bit omitted. (If you're
21familiar with the IEEE 754 floating-point format, it's the same idea.)
22
23Note that a CRC is computed over a string of *bits*, so you have
24to decide on the endianness of the bits within each byte. To get
25the best error-detecting properties, this should correspond to the
26order they're actually sent. For example, standard RS-232 serial is
27little-endian; the most significant bit (sometimes used for parity)
28is sent last. And when appending a CRC word to a message, you should
29do it in the right order, matching the endianness.
30
31Just like with ordinary division, you proceed one digit (bit) at a time.
32Each step of the division you take one more digit (bit) of the dividend
33and append it to the current remainder. Then you figure out the
34appropriate multiple of the divisor to subtract to being the remainder
35back into range. In binary, this is easy - it has to be either 0 or 1,
36and to make the XOR cancel, it's just a copy of bit 32 of the remainder.
37
38When computing a CRC, we don't care about the quotient, so we can
39throw the quotient bit away, but subtract the appropriate multiple of
40the polynomial from the remainder and we're back to where we started,
41ready to process the next bit.
42
43A big-endian CRC written this way would be coded like:
44for (i = 0; i < input_bits; i++) {
45 multiple = remainder & 0x80000000 ? CRCPOLY : 0;
46 remainder = (remainder << 1 | next_input_bit()) ^ multiple;
47}
48
49Notice how, to get at bit 32 of the shifted remainder, we look
50at bit 31 of the remainder *before* shifting it.
51
52But also notice how the next_input_bit() bits we're shifting into
53the remainder don't actually affect any decision-making until
5432 bits later. Thus, the first 32 cycles of this are pretty boring.
55Also, to add the CRC to a message, we need a 32-bit-long hole for it at
56the end, so we have to add 32 extra cycles shifting in zeros at the
57end of every message,
58
59These details lead to a standard trick: rearrange merging in the
60next_input_bit() until the moment it's needed. Then the first 32 cycles
61can be precomputed, and merging in the final 32 zero bits to make room
62for the CRC can be skipped entirely. This changes the code to:
63
64for (i = 0; i < input_bits; i++) {
65 remainder ^= next_input_bit() << 31;
66 multiple = (remainder & 0x80000000) ? CRCPOLY : 0;
67 remainder = (remainder << 1) ^ multiple;
68}
69
70With this optimization, the little-endian code is particularly simple:
71for (i = 0; i < input_bits; i++) {
72 remainder ^= next_input_bit();
73 multiple = (remainder & 1) ? CRCPOLY : 0;
74 remainder = (remainder >> 1) ^ multiple;
75}
76
77The most significant coefficient of the remainder polynomial is stored
78in the least significant bit of the binary "remainder" variable.
79The other details of endianness have been hidden in CRCPOLY (which must
80be bit-reversed) and next_input_bit().
81
82As long as next_input_bit is returning the bits in a sensible order, we don't
83*have* to wait until the last possible moment to merge in additional bits.
84We can do it 8 bits at a time rather than 1 bit at a time:
85for (i = 0; i < input_bytes; i++) {
86 remainder ^= next_input_byte() << 24;
87 for (j = 0; j < 8; j++) {
88 multiple = (remainder & 0x80000000) ? CRCPOLY : 0;
89 remainder = (remainder << 1) ^ multiple;
90 }
91}
92
93Or in little-endian:
94for (i = 0; i < input_bytes; i++) {
95 remainder ^= next_input_byte();
96 for (j = 0; j < 8; j++) {
97 multiple = (remainder & 1) ? CRCPOLY : 0;
98 remainder = (remainder >> 1) ^ multiple;
99 }
100}
101
102If the input is a multiple of 32 bits, you can even XOR in a 32-bit
103word at a time and increase the inner loop count to 32.
104
105You can also mix and match the two loop styles, for example doing the
106bulk of a message byte-at-a-time and adding bit-at-a-time processing
107for any fractional bytes at the end.
108
109To reduce the number of conditional branches, software commonly uses
110the byte-at-a-time table method, popularized by Dilip V. Sarwate,
111"Computation of Cyclic Redundancy Checks via Table Look-Up", Comm. ACM
112v.31 no.8 (August 1998) p. 1008-1013.
113
114Here, rather than just shifting one bit of the remainder to decide
115in the correct multiple to subtract, we can shift a byte at a time.
116This produces a 40-bit (rather than a 33-bit) intermediate remainder,
117and the correct multiple of the polynomial to subtract is found using
118a 256-entry lookup table indexed by the high 8 bits.
119
120(The table entries are simply the CRC-32 of the given one-byte messages.)
121
122When space is more constrained, smaller tables can be used, e.g. two
1234-bit shifts followed by a lookup in a 16-entry table.
124
125It is not practical to process much more than 8 bits at a time using this
126technique, because tables larger than 256 entries use too much memory and,
127more importantly, too much of the L1 cache.
128
129To get higher software performance, a "slicing" technique can be used.
130See "High Octane CRC Generation with the Intel Slicing-by-8 Algorithm",
131ftp://download.intel.com/technology/comms/perfnet/download/slicing-by-8.pdf
132
133This does not change the number of table lookups, but does increase
134the parallelism. With the classic Sarwate algorithm, each table lookup
135must be completed before the index of the next can be computed.
136
137A "slicing by 2" technique would shift the remainder 16 bits at a time,
138producing a 48-bit intermediate remainder. Rather than doing a single
139lookup in a 65536-entry table, the two high bytes are looked up in
140two different 256-entry tables. Each contains the remainder required
141to cancel out the corresponding byte. The tables are different because the
142polynomials to cancel are different. One has non-zero coefficients from
143x^32 to x^39, while the other goes from x^40 to x^47.
144
145Since modern processors can handle many parallel memory operations, this
146takes barely longer than a single table look-up and thus performs almost
147twice as fast as the basic Sarwate algorithm.
148
149This can be extended to "slicing by 4" using 4 256-entry tables.
150Each step, 32 bits of data is fetched, XORed with the CRC, and the result
151broken into bytes and looked up in the tables. Because the 32-bit shift
152leaves the low-order bits of the intermediate remainder zero, the
153final CRC is simply the XOR of the 4 table look-ups.
154
155But this still enforces sequential execution: a second group of table
156look-ups cannot begin until the previous groups 4 table look-ups have all
157been completed. Thus, the processor's load/store unit is sometimes idle.
158
159To make maximum use of the processor, "slicing by 8" performs 8 look-ups
160in parallel. Each step, the 32-bit CRC is shifted 64 bits and XORed
161with 64 bits of input data. What is important to note is that 4 of
162those 8 bytes are simply copies of the input data; they do not depend
163on the previous CRC at all. Thus, those 4 table look-ups may commence
164immediately, without waiting for the previous loop iteration.
165
166By always having 4 loads in flight, a modern superscalar processor can
167be kept busy and make full use of its L1 cache.
168
169Two more details about CRC implementation in the real world:
170
171Normally, appending zero bits to a message which is already a multiple
172of a polynomial produces a larger multiple of that polynomial. Thus,
173a basic CRC will not detect appended zero bits (or bytes). To enable
174a CRC to detect this condition, it's common to invert the CRC before
175appending it. This makes the remainder of the message+crc come out not
176as zero, but some fixed non-zero value. (The CRC of the inversion
177pattern, 0xffffffff.)
178
179The same problem applies to zero bits prepended to the message, and a
180similar solution is used. Instead of starting the CRC computation with
181a remainder of 0, an initial remainder of all ones is used. As long as
182you start the same way on decoding, it doesn't make a difference.
diff --git a/Documentation/leds/leds-lp5521.txt b/Documentation/leds/leds-lp5521.txt
index c4d8d151e0fe..0e542ab3d4a0 100644
--- a/Documentation/leds/leds-lp5521.txt
+++ b/Documentation/leds/leds-lp5521.txt
@@ -43,17 +43,23 @@ Format: 10x mA i.e 10 means 1.0 mA
43example platform data: 43example platform data:
44 44
45Note: chan_nr can have values between 0 and 2. 45Note: chan_nr can have values between 0 and 2.
46The name of each channel can be configurable.
47If the name field is not defined, the default name will be set to 'xxxx:channelN'
48(XXXX : pdata->label or i2c client name, N : channel number)
46 49
47static struct lp5521_led_config lp5521_led_config[] = { 50static struct lp5521_led_config lp5521_led_config[] = {
48 { 51 {
52 .name = "red",
49 .chan_nr = 0, 53 .chan_nr = 0,
50 .led_current = 50, 54 .led_current = 50,
51 .max_current = 130, 55 .max_current = 130,
52 }, { 56 }, {
57 .name = "green",
53 .chan_nr = 1, 58 .chan_nr = 1,
54 .led_current = 0, 59 .led_current = 0,
55 .max_current = 130, 60 .max_current = 130,
56 }, { 61 }, {
62 .name = "blue",
57 .chan_nr = 2, 63 .chan_nr = 2,
58 .led_current = 0, 64 .led_current = 0,
59 .max_current = 130, 65 .max_current = 130,
@@ -86,3 +92,60 @@ static struct lp5521_platform_data lp5521_platform_data = {
86 92
87If the current is set to 0 in the platform data, that channel is 93If the current is set to 0 in the platform data, that channel is
88disabled and it is not visible in the sysfs. 94disabled and it is not visible in the sysfs.
95
96The 'update_config' : CONFIG register (ADDR 08h)
97This value is platform-specific data.
98If update_config is not defined, the CONFIG register is set with
99'LP5521_PWRSAVE_EN | LP5521_CP_MODE_AUTO | LP5521_R_TO_BATT'.
100(Enable auto-powersave, set charge pump to auto, red to battery)
101
102example of update_config :
103
104#define LP5521_CONFIGS (LP5521_PWM_HF | LP5521_PWRSAVE_EN | \
105 LP5521_CP_MODE_AUTO | LP5521_R_TO_BATT | \
106 LP5521_CLK_INT)
107
108static struct lp5521_platform_data lp5521_pdata = {
109 .led_config = lp5521_led_config,
110 .num_channels = ARRAY_SIZE(lp5521_led_config),
111 .clock_mode = LP5521_CLOCK_INT,
112 .update_config = LP5521_CONFIGS,
113};
114
115LED patterns : LP5521 has autonomous operation without external control.
116Pattern data can be defined in the platform data.
117
118example of led pattern data :
119
120/* RGB(50,5,0) 500ms on, 500ms off, infinite loop */
121static u8 pattern_red[] = {
122 0x40, 0x32, 0x60, 0x00, 0x40, 0x00, 0x60, 0x00,
123 };
124
125static u8 pattern_green[] = {
126 0x40, 0x05, 0x60, 0x00, 0x40, 0x00, 0x60, 0x00,
127 };
128
129static struct lp5521_led_pattern board_led_patterns[] = {
130 {
131 .r = pattern_red,
132 .g = pattern_green,
133 .size_r = ARRAY_SIZE(pattern_red),
134 .size_g = ARRAY_SIZE(pattern_green),
135 },
136};
137
138static struct lp5521_platform_data lp5521_platform_data = {
139 .led_config = lp5521_led_config,
140 .num_channels = ARRAY_SIZE(lp5521_led_config),
141 .clock_mode = LP5521_CLOCK_EXT,
142 .patterns = board_led_patterns,
143 .num_patterns = ARRAY_SIZE(board_led_patterns),
144};
145
146Then predefined led pattern(s) can be executed via the sysfs.
147To start the pattern #1,
148# echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern
149(xxxx : i2c bus & slave address)
150To end the pattern,
151# echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern