Automatic merge of /spare/repo/linux-2.6/.git branch HEAD

S: USA

N: Randy Dunlap

E: rddunlap@osdl.org

E: rdunlap@xenotime.net

W: http://www.xenotime.net/linux/linux.html

W: http://www.linux-usb.org

D: Linux-USB subsystem, USB core/UHCI/printer/storage drivers

D: x86 SMP, ACPI, bootflag hacking

S: 12725 SW Millikan Way, Suite 400

S: Beaverton, Oregon 97005

S: (ask for current address)

S: USA

N: Bob Dunlop

  </authorgroup>

  <copyright>

   <year>2003</year>

   <year>2003-2005</year>

   <holder>Jeff Garzik</holder>

  </copyright>

<toc></toc>

  <chapter id="libataThanks">

     <title>Thanks</title>

  <para>

  The bulk of the ATA knowledge comes thanks to long conversations with

  Andre Hedrick (www.linux-ide.org).

  </para>

  <chapter id="libataIntroduction">

     <title>Introduction</title>

  <para>

  Thanks to Alan Cox for pointing out similarities 

  between SATA and SCSI, and in general for motivation to hack on

  libata.

  libATA is a library used inside the Linux kernel to support ATA host

  controllers and devices.  libATA provides an ATA driver API, class

  transports for ATA and ATAPI devices, and SCSI<->ATA translation

  for ATA devices according to the T10 SAT specification.

  </para>

  <para>

  libata's device detection

  method, ata_pio_devchk, and in general all the early probing was

  based on extensive study of Hale Landis's probe/reset code in his

  ATADRVR driver (www.ata-atapi.com).

  This Guide documents the libATA driver API, library functions, library

  internals, and a couple sample ATA low-level drivers.

  </para>

  </chapter>

  <chapter id="libataDriverApi">

     <title>libata Driver API</title>

     <para>

     struct ata_port_operations is defined for every low-level libata

     hardware driver, and it controls how the low-level driver

     interfaces with the ATA and SCSI layers.

     </para>

     <para>

     FIS-based drivers will hook into the system with ->qc_prep() and

     ->qc_issue() high-level hooks.  Hardware which behaves in a manner

     similar to PCI IDE hardware may utilize several generic helpers,

     defining at a bare minimum the bus I/O addresses of the ATA shadow

     register blocks.

     </para>

     <sect1>

        <title>struct ata_port_operations</title>

	<sect2><title>Disable ATA port</title>

	<programlisting>

void (*port_disable) (struct ata_port *);

	</programlisting>

	unplug).

	</para>

	</sect2>

	<sect2><title>Post-IDENTIFY device configuration</title>

	<programlisting>

void (*dev_config) (struct ata_port *, struct ata_device *);

	</programlisting>

	issue of SET FEATURES - XFER MODE, and prior to operation.

	</para>

	</sect2>

	<sect2><title>Set PIO/DMA mode</title>

	<programlisting>

void (*set_piomode) (struct ata_port *, struct ata_device *);

void (*set_dmamode) (struct ata_port *, struct ata_device *);

	->set_dma_mode() is only called if DMA is possible.

	</para>

	</sect2>

	<sect2><title>Taskfile read/write</title>

	<programlisting>

void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf);

void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf);

	taskfile register values.

	</para>

	</sect2>

	<sect2><title>ATA command execute</title>

	<programlisting>

void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf);

	</programlisting>

	->tf_load(), to be initiated in hardware.

	</para>

	</sect2>

	<sect2><title>Per-cmd ATAPI DMA capabilities filter</title>

	<programlisting>

int (*check_atapi_dma) (struct ata_queued_cmd *qc);

	</programlisting>

	<para>

Allow low-level driver to filter ATA PACKET commands, returning a status

indicating whether or not it is OK to use DMA for the supplied PACKET

command.

	</para>

	</sect2>

	<sect2><title>Read specific ATA shadow registers</title>

	<programlisting>

u8   (*check_status)(struct ata_port *ap);

void (*dev_select)(struct ata_port *ap, unsigned int device);

u8   (*check_altstatus)(struct ata_port *ap);

u8   (*check_err)(struct ata_port *ap);

	</programlisting>

	<para>

	Reads the Status ATA shadow register from hardware.  On some

	hardware, this has the side effect of clearing the interrupt

	condition.

	Reads the Status/AltStatus/Error ATA shadow register from

	hardware.  On some hardware, reading the Status register has

	the side effect of clearing the interrupt condition.

	</para>

	</sect2>

	<sect2><title>Select ATA device on bus</title>

	<programlisting>

void (*dev_select)(struct ata_port *ap, unsigned int device);

	</programlisting>

	<para>

	Issues the low-level hardware command(s) that causes one of N

	hardware devices to be considered 'selected' (active and

	available for use) on the ATA bus.

	available for use) on the ATA bus.  This generally has no

meaning on FIS-based devices.

	</para>

	</sect2>

	<sect2><title>Reset ATA bus</title>

	<programlisting>

void (*phy_reset) (struct ata_port *ap);

	</programlisting>

	functions ata_bus_reset() or sata_phy_reset() for this hook.

	</para>

	</sect2>

	<sect2><title>Control PCI IDE BMDMA engine</title>

	<programlisting>

void (*bmdma_setup) (struct ata_queued_cmd *qc);

void (*bmdma_start) (struct ata_queued_cmd *qc);

void (*bmdma_stop) (struct ata_port *ap);

u8   (*bmdma_status) (struct ata_port *ap);

	</programlisting>

	<para>

When setting up an IDE BMDMA transaction, these hooks arm

	(->bmdma_setup) and fire (->bmdma_start) the hardware's DMA

	engine.

(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop)

the hardware's DMA engine.  ->bmdma_status is used to read the standard

PCI IDE DMA Status register.

	</para>

	<para>

These hooks are typically either no-ops, or simply not implemented, in

FIS-based drivers.

	</para>

	</sect2>

	<sect2><title>High-level taskfile hooks</title>

	<programlisting>

void (*qc_prep) (struct ata_queued_cmd *qc);

int (*qc_issue) (struct ata_queued_cmd *qc);

	->qc_issue is used to make a command active, once the hardware

	and S/G tables have been prepared.  IDE BMDMA drivers use the

	helper function ata_qc_issue_prot() for taskfile protocol-based

	dispatch.  More advanced drivers roll their own ->qc_issue

	implementation, using this as the "issue new ATA command to

	hardware" hook.

	dispatch.  More advanced drivers implement their own ->qc_issue.

	</para>

	</sect2>

	<sect2><title>Timeout (error) handling</title>

	<programlisting>

void (*eng_timeout) (struct ata_port *ap);

	</programlisting>

	<para>

This is a high level error handling function, called from the

	error handling thread, when a command times out.

error handling thread, when a command times out.  Most newer

hardware will implement its own error handling code here.  IDE BMDMA

drivers may use the helper function ata_eng_timeout().

	</para>

	</sect2>

	<sect2><title>Hardware interrupt handling</title>

	<programlisting>

irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);

void (*irq_clear) (struct ata_port *);

	is quiet.

	</para>

	</sect2>

	<sect2><title>SATA phy read/write</title>

	<programlisting>

u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg);

void (*scr_write) (struct ata_port *ap, unsigned int sc_reg,

	if ->phy_reset hook called the sata_phy_reset() helper function.

	</para>

	</sect2>

	<sect2><title>Init and shutdown</title>

	<programlisting>

int (*port_start) (struct ata_port *ap);

void (*port_stop) (struct ata_port *ap);

	tasks.  

	</para>

	<para>

	->host_stop() is called when the rmmod or hot unplug process

	begins.  The hook must stop all hardware interrupts, DMA

	engines, etc.

	</para>

	<para>

	->port_stop() is called after ->host_stop().  It's sole function

	is to release DMA/memory resources, now that they are no longer

	actively being used.

	</para>

	<para>

	->host_stop() is called after all ->port_stop() calls

have completed.  The hook must finalize hardware shutdown, release DMA

and other resources, etc.

	</para>

	</sect2>

     </sect1>

  </chapter>

!Idrivers/scsi/sata_sil.c

  </chapter>

  <chapter id="libataThanks">

     <title>Thanks</title>

  <para>

  The bulk of the ATA knowledge comes thanks to long conversations with

  Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA

  and SCSI specifications.

  </para>

  <para>

  Thanks to Alan Cox for pointing out similarities 

  between SATA and SCSI, and in general for motivation to hack on

  libata.

  </para>

  <para>

  libata's device detection

  method, ata_pio_devchk, and in general all the early probing was

  based on extensive study of Hale Landis's probe/reset code in his

  ATADRVR driver (www.ata-atapi.com).

  </para>

  </chapter>

</book>

     CPU frequency and voltage scaling statictics in the Linux(TM) kernel

             L i n u x    c p u f r e q - s t a t s   d r i v e r

                       - information for users -

             Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>

Contents

1. Introduction

2. Statistics Provided (with example)

3. Configuring cpufreq-stats

1. Introduction

cpufreq-stats is a driver that provices CPU frequency statistics for each CPU.

This statistics is provided in /sysfs as a bunch of read_only interfaces. This

interface (when configured) will appear in a seperate directory under cpufreq

in /sysfs (<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/) for each CPU.

Various statistics will form read_only files under this directory.

This driver is designed to be independent of any particular cpufreq_driver

that may be running on your CPU. So, it will work with any cpufreq_driver.

2. Statistics Provided (with example)

cpufreq stats provides following statistics (explained in detail below).

-  time_in_state

-  total_trans

-  trans_table

All the statistics will be from the time the stats driver has been inserted 

to the time when a read of a particular statistic is done. Obviously, stats 

driver will not have any information about the the frequcny transitions before

the stats driver insertion.

--------------------------------------------------------------------------------

<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l

total 0

drwxr-xr-x  2 root root    0 May 14 16:06 .

drwxr-xr-x  3 root root    0 May 14 15:58 ..

-r--r--r--  1 root root 4096 May 14 16:06 time_in_state

-r--r--r--  1 root root 4096 May 14 16:06 total_trans

-r--r--r--  1 root root 4096 May 14 16:06 trans_table

--------------------------------------------------------------------------------

-  time_in_state

This gives the amount of time spent in each of the frequencies supported by

this CPU. The cat output will have "<frequency> <time>" pair in each line, which

will mean this CPU spent <time> usertime units of time at <frequency>. Output

will have one line for each of the supported freuencies. usertime units here 

is 10mS (similar to other time exported in /proc).

--------------------------------------------------------------------------------

<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state 

3600000 2089

3400000 136

3200000 34

3000000 67

2800000 172488

--------------------------------------------------------------------------------

-  total_trans

This gives the total number of frequency transitions on this CPU. The cat 

output will have a single count which is the total number of frequency

transitions.

--------------------------------------------------------------------------------

<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans

20

--------------------------------------------------------------------------------

-  trans_table

This will give a fine grained information about all the CPU frequency

transitions. The cat output here is a two dimensional matrix, where an entry

<i,j> (row i, column j) represents the count of number of transitions from 

Freq_i to Freq_j. Freq_i is in descending order with increasing rows and 

Freq_j is in descending order with increasing columns. The output here also 

contains the actual freq values for each row and column for better readability.

--------------------------------------------------------------------------------

<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table

   From  :    To

         :   3600000   3400000   3200000   3000000   2800000 

  3600000:         0         5         0         0         0 

  3400000:         4         0         2         0         0 

  3200000:         0         1         0         2         0 

  3000000:         0         0         1         0         3 

  2800000:         0         0         0         2         0 

--------------------------------------------------------------------------------

3. Configuring cpufreq-stats

To configure cpufreq-stats in your kernel

Config Main Menu

	Power management options (ACPI, APM)  --->

		CPU Frequency scaling  --->

			[*] CPU Frequency scaling

			<*>   CPU frequency translation statistics 

			[*]     CPU frequency translation statistics details

"CPU Frequency scaling" (CONFIG_CPU_FREQ) should be enabled to configure

cpufreq-stats.

"CPU frequency translation statistics" (CONFIG_CPU_FREQ_STAT) provides the

basic statistics which includes time_in_state and total_trans.

"CPU frequency translation statistics details" (CONFIG_CPU_FREQ_STAT_DETAILS)

provides fine grained cpufreq stats by trans_table. The reason for having a

seperate config option for trans_table is:

- trans_table goes against the traditional /sysfs rule of one value per

  interface. It provides a whole bunch of value in a 2 dimensional matrix

  form.

Once these two options are enabled and your CPU supports cpufrequency, you

will be able to see the CPU frequency statistics in /sysfs.

There is an exception to the above.  If hotplug funtionality is used

to remove all the CPUs that are currently assigned to a cpuset,

then the kernel will automatically update the cpus_allowed of all

tasks attached to CPUs in that cpuset with the online CPUs of the

nearest parent cpuset that still has some CPUs online.  When memory

tasks attached to CPUs in that cpuset to allow all CPUs.  When memory

hotplug functionality for removing Memory Nodes is available, a

similar exception is expected to apply there as well.  In general,

the kernel prefers to violate cpuset placement, over starving a task

This README escorted the skystar2-driver rewriting procedure. It describes the

state of the new flexcop-driver set and some internals are written down here

too.

This document hopefully describes things about the flexcop and its

device-offsprings. Goal was to write an easy-to-write and easy-to-read set of

drivers based on the skystar2.c and other information.

Remark: flexcop-pci.c was a copy of skystar2.c, but every line has been

touched and rewritten.

History & News

==============

  2005-04-01 - correct USB ISOC transfers (thanks to Vadim Catana)

General coding processing

=========================

We should proceed as follows (as long as no one complains):

0) Think before start writing code!

1) rewriting the skystar2.c with the help of the flexcop register descriptions

and splitting up the files to a pci-bus-part and a flexcop-part.

The new driver will be called b2c2-flexcop-pci.ko/b2c2-flexcop-usb.ko for the

device-specific part and b2c2-flexcop.ko for the common flexcop-functions.

2) Search for errors in the leftover of flexcop-pci.c (compare with pluto2.c

and other pci drivers)

3) make some beautification (see 'Improvements when rewriting (refactoring) is

done')

4) Testing the new driver and maybe substitute the skystar2.c with it, to reach

a wider tester audience.

5) creating an usb-bus-part using the already written flexcop code for the pci

card.

Idea: create a kernel-object for the flexcop and export all important

functions. This option saves kernel-memory, but maybe a lot of functions have

to be exported to kernel namespace.

Current situation

=================

0) Done :)

1) Done (some minor issues left)

2) Done

3) Not ready yet, more information is necessary

4) next to be done (see the table below)

5) USB driver is working (yes, there are some minor issues)

What seems to be ready?

-----------------------

1) Rewriting

1a) i2c is cut off from the flexcop-pci.c and seems to work

1b) moved tuner and demod stuff from flexcop-pci.c to flexcop-tuner-fe.c

1c) moved lnb and diseqc stuff from flexcop-pci.c to flexcop-tuner-fe.c

1e) eeprom (reading MAC address)

1d) sram (no dynamic sll size detection (commented out) (using default as JJ told me))

1f) misc. register accesses for reading parameters (e.g. resetting, revision)

1g) pid/mac filter (flexcop-hw-filter.c)

1i) dvb-stuff initialization in flexcop.c (done)

1h) dma stuff (now just using the size-irq, instead of all-together, to be done)

1j) remove flexcop initialization from flexcop-pci.c completely (done)

1l) use a well working dma IRQ method (done, see 'Known bugs and problems and TODO')

1k) cleanup flexcop-files (remove unused EXPORT_SYMBOLs, make static from

non-static where possible, moved code to proper places)

2) Search for errors in the leftover of flexcop-pci.c (partially done)

5a) add MAC address reading

5c) feeding of ISOC data to the software demux (format of the isochronous data

and speed optimization, no real error) (thanks to Vadim Catana)

What to do in the near future?

--------------------------------------

(no special order here)

5) USB driver

5b) optimize isoc-transfer (submitting/killing isoc URBs when transfer is starting)

Testing changes

---------------

O             = item is working

P             = item is partially working

X             = item is not working

N             = item does not apply here

<empty field> = item need to be examined

       | PCI                               | USB

item   | mt352 | nxt2002 | stv0299 | mt312 | mt352 | nxt2002 | stv0299 | mt312

-------+-------+---------+---------+-------+-------+---------+---------+-------

1a)    | O     |         |         |       | N     | N       | N       | N

1b)    | O     |         |         |       |       |         | O       |

1c)    | N     | N       |         |       | N     | N       | O       |

1d)    |                 O                 |                 O

1e)    |                 O                 |                 O

1f)    |                                   P

1g)    |                                   O

1h)    |                 P                 |

1i)    |                 O                 |                 N

1j)    |                 O                 |                 N

1l)    |                 O                 |                 N

2)     |                 O                 |                 N

5a)    |                 N                 |                 O

5b)*   |                 N                 |

5c)    |                 N                 |                 O

* - not done yet

Known bugs and problems and TODO

--------------------------------

1g/h/l) when pid filtering is enabled on the pci card

DMA usage currently:

  The DMA is splitted in 2 equal-sized subbuffers. The Flexcop writes to first

  address and triggers an IRQ when it's full and starts writing to the second

  address. When the second address is full, the IRQ is triggered again, and

  the flexcop writes to first address again, and so on.

  The buffersize of each address is currently 640*188 bytes.

  Problem is, when using hw-pid-filtering and doing some low-bandwidth

  operation (like scanning) the buffers won't be filled enough to trigger

  the IRQ. That's why:

  When PID filtering is activated, the timer IRQ is used. Every 1.97 ms the IRQ

  is triggered.  Is the current write address of DMA1 different to the one

  during the last IRQ, then the data is passed to the demuxer.

  There is an additional DMA-IRQ-method: packet count IRQ. This isn't

  implemented correctly yet.

  The solution is to disable HW PID filtering, but I don't know how the DVB

  API software demux behaves on slow systems with 45MBit/s TS.

Solved bugs :)

--------------

1g) pid-filtering (somehow pid index 4 and 5 (EMM_PID and ECM_PID) aren't

working)

SOLUTION: also index 0 was affected, because net_translation is done for

these indexes by default

5b) isochronous transfer does only work in the first attempt (for the Sky2PC

USB, Air2PC is working) SOLUTION: the flexcop was going asleep and never really

woke up again (don't know if this need fixes, see

flexcop-fe-tuner.c:flexcop_sleep)

NEWS: when the driver is loaded and unloaded and loaded again (w/o doing

anything in the while the driver is loaded the first time), no transfers take

place anymore.

Improvements when rewriting (refactoring) is done

=================================================

- split sleeping of the flexcop (misc_204.ACPI3_sig = 1;) from lnb_control

  (enable sleeping for other demods than dvb-s)

- add support for CableStar (stv0297 Microtune 203x/ALPS) (almost done, incompatibilities with the Nexus-CA)

Debugging

---------

- add verbose debugging to skystar2.c (dump the reg_dw_data) and compare it

  with this flexcop, this is important, because i2c is now using the

  flexcop_ibi_value union from flexcop-reg.h (do you have a better idea for

  that, please tell us so).

Everything which is identical in the following table, can be put into a common

flexcop-module.

                  PCI                  USB

-------------------------------------------------------------------------------

Different:

Register access:  accessing IO memory  USB control message

I2C bus:          I2C bus of the FC    USB control message

Data transfer:    DMA                  isochronous transfer

EEPROM transfer:  through i2c bus      not clear yet

Identical:

Streaming:                 accessing registers

PID Filtering:             accessing registers

Sram destinations:         accessing registers

Tuner/Demod:                     I2C bus

DVB-stuff:            can be written for common use

Acknowledgements (just for the rewriting part)

================

Bjarne Steinsbo thought a lot in the first place of the pci part for this code

sharing idea.

Andreas Oberritter for providing a recent PCI initialization template

(pluto2.c).

Boleslaw Ciesielski for pointing out a problem with firmware loader.

Vadim Catana for correcting the USB transfer.

comments, critics and ideas to linux-dvb@linuxtv.org.